{"_id":"@anagnole/mycelium","_rev":"2-c80ed66d448ebb708b0cf43c4e5a33f1","name":"@anagnole/mycelium","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@anagnole/mycelium","version":"0.1.0","_id":"@anagnole/mycelium@0.1.0","maintainers":[{"name":"anagnole","email":"anagnole@outlook.com.gr"}],"dist":{"shasum":"5d7a2607e34422b34f5cea22046333649d32e8b7","tarball":"https://registry.npmjs.org/@anagnole/mycelium/-/mycelium-0.1.0.tgz","fileCount":57,"integrity":"sha512-HzJahQq6d42nF2SwC9F09HqbHk7eYsB6l+f+LWwt8xxbPlmZC/bvsPgLhwAD5lCS85GuZL0THsz6bkUncRWpMA==","signatures":[{"sig":"MEUCIHL8HhSw1EEGSmTDlJpF1buXenjxDQX6XSeselCEWMh3AiEA7LeFo1gH/+wBQvmfFXBvbZ9Zds8ldj69au5Q6o6cCI0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":76234},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"5684089f7740f3b4fb1b02e920dd5680d77b2578","scripts":{"test":"vitest --run","build":"tsc","test:watch":"vitest"},"_npmUser":{"name":"anagnole","email":"anagnole@outlook.com.gr"},"_npmVersion":"11.6.2","description":"Small-world agent network infrastructure — graph construction, personality embedding, and topology-driven propagation for multi-agent systems","directories":{},"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.7.0"},"_npmOperationalInternal":{"tmp":"tmp/mycelium_0.1.0_1775129514062_0.43825792646222794","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@anagnole/mycelium","version":"0.2.0","type":"module","description":"Small-world agent network infrastructure — graph construction, personality embedding, and topology-driven propagation for multi-agent systems","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./viz":{"import":"./dist/viz/index.js","types":"./dist/viz/index.d.ts"}},"scripts":{"build":"tsc && vite build -c src/viz/client/vite.config.ts","build:core":"tsc","build:viz-client":"vite build -c src/viz/client/vite.config.ts","test":"vitest --run","test:watch":"vitest"},"devDependencies":{"@types/react":"^19.2.14","@types/react-dom":"^19.2.3","@types/ws":"^8.18.1","@vitejs/plugin-react":"^5.2.0","react":"^19.2.4","react-dom":"^19.2.4","react-force-graph-2d":"^1.29.1","recharts":"^3.8.1","typescript":"^5.7.0","vitest":"^3.0.0","zustand":"^5.0.12"},"dependencies":{"ws":"^8.20.0"},"gitHead":"9da23893ae92589d02b3cf9a29d5b550fed64a07","_id":"@anagnole/mycelium@0.2.0","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-KJJ7UiSQ5On2N0jFGWy5n+vzAW4ajM3KFBUi7/AxfRyuClnfKX8jnLKu6HWXQEF8fa9OXpqc4y2QaPVsxuCAjw==","shasum":"d2d1f728016dee05a653e3d5c4b13f0980c8cb45","tarball":"https://registry.npmjs.org/@anagnole/mycelium/-/mycelium-0.2.0.tgz","fileCount":89,"unpackedSize":865036,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAWFgig9DPlSaT7+S7Nenet7iguo9JnEQxfOJQoZtKpIAiEAtck6yn0uKw68jg7AlcaI5S+mAp6eSsfeJlh1fbwcriY="}]},"_npmUser":{"name":"anagnole","email":"anagnole@outlook.com.gr"},"directories":{},"maintainers":[{"name":"anagnole","email":"anagnole@outlook.com.gr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mycelium_0.2.0_1775233163636_0.25247026690743835"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-02T11:31:53.948Z","modified":"2026-04-03T16:19:23.892Z","0.1.0":"2026-04-02T11:31:54.349Z","0.2.0":"2026-04-03T16:19:23.792Z"},"description":"Small-world agent network infrastructure — graph construction, personality embedding, and topology-driven propagation for multi-agent systems","maintainers":[{"name":"anagnole","email":"anagnole@outlook.com.gr"}],"readme":"# Mycelium\n\nSmall-world agent network infrastructure. Build graphs of AI agents where edges represent cognitive similarity, then traverse them to select diverse agent ensembles.\n\nLike the fungal networks that connect trees underground — agents cluster by how they think, with shortcut connections bridging distant cognitive styles.\n\n## What it does\n\n1. **Personality embedding** — each agent is scored on 6 cognitive axes (analytical↔intuitive, convergent↔divergent, abstract↔concrete, critical↔generative, individual↔systemic, conservative↔innovative)\n2. **Small-world graph** — Watts-Strogatz construction: agents sorted by similarity form a ring lattice, then edges are randomly rewired to create shortcut bridges between distant clusters\n3. **Graph traversal** — three walk strategies (random, diversity-biased, cluster-bridging) explore the network from a seed node\n4. **Agent selection** — visited nodes are filtered to a diverse subset via furthest-point sampling\n5. **Budget-aware activation** — optional iterator mode where the consumer reports actual costs and Mycelium stops yielding agents when the budget is exhausted\n6. **Event system** — opt-in observer callbacks that stream every internal decision (walk steps, selections, budget updates) for monitoring or visualization\n7. **Real-time viz dashboard** — a built-in web UI that visualizes your agent network, walk paths, selections, and budget in real time\n\n## Install\n\n```\nnpm install @anagnole/mycelium\n```\n\n## Quick start\n\n```typescript\nimport { buildGraph, activate, activateIterative, createBudgetTracker } from '@anagnole/mycelium';\nimport type { AgentNode } from '@anagnole/mycelium';\n\n// 1. Define agents with personality embeddings\nconst agents: AgentNode[] = [\n  {\n    id: 'analyst',\n    name: 'The Analyst',\n    embedding: {\n      analytical_intuitive: -0.9,\n      convergent_divergent: -0.6,\n      abstract_concrete: 0.3,\n      critical_generative: -0.7,\n      individual_systemic: 0.2,\n      conservative_innovative: -0.3,\n    },\n  },\n  // ... more agents\n];\n\n// 2. Build the small-world graph\nconst graph = buildGraph(agents, { k: 6, beta: 0.15, seed: 42 });\n\n// 3a. One-shot activation (returns all selected agents at once)\nconst subgraph = await activate('my query', graph, myEntryPointSelector, {\n  walkLength: 8,\n  walkStrategy: 'diversity-biased',\n  selectionMode: 'top-k-diverse',\n  maxAgents: 5,\n});\nconsole.log(subgraph.selectedNodes); // 5 diverse agents\n\n// 3b. Budget-aware activation (yields agents one at a time)\nconst budget = createBudgetTracker(0.50); // e.g., $0.50 USD\nconst iterator = await activateIterative('my query', graph, myEntryPointSelector, {\n  walkLength: 8,\n  walkStrategy: 'diversity-biased',\n  selectionMode: 'top-k-diverse',\n  maxAgents: 10,\n}, budget);\n\nlet agent = iterator.next();\nwhile (agent !== null) {\n  const result = await runMyAgent(agent); // your LLM call\n  budget.report(result.cost);             // report actual cost\n  agent = iterator.next();                // stops when budget exhausted\n}\nconst finalSubgraph = iterator.finalize();\n```\n\n## Viz dashboard\n\nMycelium ships with a real-time visualization dashboard. Import it from `@anagnole/mycelium/viz` and point it at your graph:\n\n```typescript\nimport { buildGraph, activate } from '@anagnole/mycelium';\nimport { startViz } from '@anagnole/mycelium/viz';\n\nconst graph = buildGraph(agents, { k: 6, beta: 0.15 });\nconst viz = await startViz(graph, { port: 3000 });\n// opens http://localhost:3000\n\n// Pass viz.observer to stream events to the dashboard\nconst result = await activate(query, graph, selector, {\n  walkLength: 10,\n  walkStrategy: 'diversity-biased',\n  selectionMode: 'top-k-diverse',\n  maxAgents: 5,\n  observer: viz.observer,\n});\n\n// When done\nawait viz.stop();\n```\n\nThe dashboard shows:\n- **Force-directed graph** — nodes colored by state (grey = idle, purple = walked, amber = selected), rewired edges in red\n- **Walk animation** — play/pause/step through the walk path with adjustable speed\n- **Agent detail** — click any node to see a radar chart and bar visualization of its 6 personality axes\n- **Selection list** — ordered list of agents chosen by the activation\n- **Budget gauge** — donut chart tracking spend vs. limit (when using `createBudgetTracker`)\n- **Event log** — scrolling feed of every event with timestamps\n\n`startViz` options:\n- `port` — server port (default: `4200`)\n- `open` — auto-open browser (default: `true`)\n\nEvents are buffered on the server, so the dashboard shows the full state even if you open the browser after an activation has run.\n\n## Event system\n\nEvery core function accepts an optional `observer` via the propagation config. The observer receives typed events as they happen:\n\n```typescript\nimport type { MyceliumEvent, MyceliumObserver } from '@anagnole/mycelium';\n\nconst observer: MyceliumObserver = (event) => {\n  console.log(event.type, event);\n};\n\nawait activate(query, graph, selector, {\n  walkLength: 8,\n  walkStrategy: 'diversity-biased',\n  selectionMode: 'top-k-diverse',\n  maxAgents: 5,\n  observer, // opt-in — zero overhead if omitted\n});\n```\n\nEvent types:\n\n| Event | Emitted by | Payload |\n|---|---|---|\n| `activation:start` | `activate`, `activateIterative` | query, entry node ID |\n| `walk:step` | `walk` | from/to node, step index, edge weight, rewired flag |\n| `walk:complete` | `walk` | full path, strategy |\n| `selection:complete` | `selectFromWalk` | selected IDs, mode |\n| `budget:update` | `BudgetTracker.report` | spent, limit, remaining |\n| `activation:agent-yielded` | `activateIterative.next` | agent ID/name, embedding, round |\n| `agent:run:complete` | `runActivation` | agent ID/name, cost |\n\n## API\n\n### Graph\n\n- **`buildGraph(agents, config?)`** — build a SmallWorldGraph from embedded agents\n- **`SmallWorldGraph`** — graph class with `getNeighbors()`, `getNHopNeighbors()`, `inducedSubgraph()`, etc.\n\n### Activation\n\n- **`activate(query, graph, entryPointSelector, config?)`** — one-shot: returns `ActivatedSubgraph` with all selected agents\n- **`activateIterative(query, graph, entryPointSelector, config?, budgetTracker?)`** — returns `ActivationIterator` that yields agents one at a time\n\n### Budget\n\n- **`createBudgetTracker(limit, observer?)`** — create a tracker with a spending limit\n- **`runActivation(iterator, runner, query, tracker?, observer?)`** — convenience loop: pulls agents, runs them, reports costs, stops on budget\n\n### Viz\n\n- **`startViz(graph, options?)`** — start the visualization server, returns `VizHandle` with `observer`, `url`, and `stop()`\n\n### Walk strategies\n\n| Strategy | Behavior |\n|---|---|\n| `random` | Uniform random neighbor selection, prefers unvisited |\n| `diversity-biased` | Picks the most cognitively different neighbor at each step |\n| `cluster-bridging` | Prefers rewired (shortcut) edges to cross cluster boundaries |\n\n### Selection modes\n\n| Mode | Behavior |\n|---|---|\n| `all-visited` | First N unique agents from the walk path |\n| `top-k-diverse` | Greedy furthest-point sampling for maximum personality diversity |\n\n### Personality axes\n\n| Axis | Low (-1) | High (+1) |\n|---|---|---|\n| `analytical_intuitive` | Systematic decomposition | Pattern recognition, holistic leaps |\n| `convergent_divergent` | Narrows to one answer | Expands possibilities |\n| `abstract_concrete` | Theoretical frameworks | Specific, grounded examples |\n| `critical_generative` | Finds flaws, stress-tests | Builds, creates, synthesizes |\n| `individual_systemic` | Focuses on parts | Focuses on wholes, feedback loops |\n| `conservative_innovative` | Works within paradigms | Breaks paradigms |\n\n## License\n\nMIT\n","readmeFilename":"README.md"}