Mycelium

Small-world agent network infrastructure. Build graphs of AI agents where edges represent cognitive similarity, then traverse them to select diverse agent ensembles.

Like the fungal networks that connect trees underground — agents cluster by how they think, with shortcut connections bridging distant cognitive styles.

What it does

1. Personality embedding — each agent is scored on 6 cognitive axes (analytical↔intuitive, convergent↔divergent, abstract↔concrete, critical↔generative, individual↔systemic, conservative↔innovative)
2. 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
3. Graph traversal — three walk strategies (random, diversity-biased, cluster-bridging) explore the network from a seed node
4. Agent selection — visited nodes are filtered to a diverse subset via furthest-point sampling
5. Budget-aware activation — optional iterator mode where the consumer reports actual costs and Mycelium stops yielding agents when the budget is exhausted
6. Event system — opt-in observer callbacks that stream every internal decision (walk steps, selections, budget updates) for monitoring or visualization
7. Real-time viz dashboard — a built-in web UI that visualizes your agent network, walk paths, selections, and budget in real time

Install

npm install @anagnole/mycelium

Quick start

import { buildGraph, activate, activateIterative, createBudgetTracker } from '@anagnole/mycelium';
import type { AgentNode } from '@anagnole/mycelium';

// 1. Define agents with personality embeddings
const agents: AgentNode[] = [
  {
    id: 'analyst',
    name: 'The Analyst',
    embedding: {
      analytical_intuitive: -0.9,
      convergent_divergent: -0.6,
      abstract_concrete: 0.3,
      critical_generative: -0.7,
      individual_systemic: 0.2,
      conservative_innovative: -0.3,
    },
  },
  // ... more agents
];

// 2. Build the small-world graph
const graph = buildGraph(agents, { k: 6, beta: 0.15, seed: 42 });

// 3a. One-shot activation (returns all selected agents at once)
const subgraph = await activate('my query', graph, myEntryPointSelector, {
  walkLength: 8,
  walkStrategy: 'diversity-biased',
  selectionMode: 'top-k-diverse',
  maxAgents: 5,
});
console.log(subgraph.selectedNodes); // 5 diverse agents

// 3b. Budget-aware activation (yields agents one at a time)
const budget = createBudgetTracker(0.50); // e.g., $0.50 USD
const iterator = await activateIterative('my query', graph, myEntryPointSelector, {
  walkLength: 8,
  walkStrategy: 'diversity-biased',
  selectionMode: 'top-k-diverse',
  maxAgents: 10,
}, budget);

let agent = iterator.next();
while (agent !== null) {
  const result = await runMyAgent(agent); // your LLM call
  budget.report(result.cost);             // report actual cost
  agent = iterator.next();                // stops when budget exhausted
}
const finalSubgraph = iterator.finalize();

Viz dashboard

Mycelium ships with a real-time visualization dashboard. Import it from @anagnole/mycelium/viz and point it at your graph:

import { buildGraph, activate } from '@anagnole/mycelium';
import { startViz } from '@anagnole/mycelium/viz';

const graph = buildGraph(agents, { k: 6, beta: 0.15 });
const viz = await startViz(graph, { port: 3000 });
// opens http://localhost:3000

// Pass viz.observer to stream events to the dashboard
const result = await activate(query, graph, selector, {
  walkLength: 10,
  walkStrategy: 'diversity-biased',
  selectionMode: 'top-k-diverse',
  maxAgents: 5,
  observer: viz.observer,
});

// When done
await viz.stop();

The dashboard shows:

• Force-directed graph — nodes colored by state (grey = idle, purple = walked, amber = selected), rewired edges in red
• Walk animation — play/pause/step through the walk path with adjustable speed
• Agent detail — click any node to see a radar chart and bar visualization of its 6 personality axes
• Selection list — ordered list of agents chosen by the activation
• Budget gauge — donut chart tracking spend vs. limit (when using createBudgetTracker)
• Event log — scrolling feed of every event with timestamps

startViz options:

• port — server port (default: 4200)
• open — auto-open browser (default: true)

Events are buffered on the server, so the dashboard shows the full state even if you open the browser after an activation has run.

Event system

Every core function accepts an optional observer via the propagation config. The observer receives typed events as they happen:

import type { MyceliumEvent, MyceliumObserver } from '@anagnole/mycelium';

const observer: MyceliumObserver = (event) => {
  console.log(event.type, event);
};

await activate(query, graph, selector, {
  walkLength: 8,
  walkStrategy: 'diversity-biased',
  selectionMode: 'top-k-diverse',
  maxAgents: 5,
  observer, // opt-in — zero overhead if omitted
});

Event types:

| Event | Emitted by | Payload | |---|---|---| | activation:start | activate, activateIterative | query, entry node ID | | walk:step | walk | from/to node, step index, edge weight, rewired flag | | walk:complete | walk | full path, strategy | | selection:complete | selectFromWalk | selected IDs, mode | | budget:update | BudgetTracker.report | spent, limit, remaining | | activation:agent-yielded | activateIterative.next | agent ID/name, embedding, round | | agent:run:complete | runActivation | agent ID/name, cost |

API

Graph

• buildGraph(agents, config?) — build a SmallWorldGraph from embedded agents
• SmallWorldGraph — graph class with getNeighbors(), getNHopNeighbors(), inducedSubgraph(), etc.

Activation

• activate(query, graph, entryPointSelector, config?) — one-shot: returns ActivatedSubgraph with all selected agents
• activateIterative(query, graph, entryPointSelector, config?, budgetTracker?) — returns ActivationIterator that yields agents one at a time

Budget

• createBudgetTracker(limit, observer?) — create a tracker with a spending limit
• runActivation(iterator, runner, query, tracker?, observer?) — convenience loop: pulls agents, runs them, reports costs, stops on budget

Viz

• startViz(graph, options?) — start the visualization server, returns VizHandle with observer, url, and stop()

Walk strategies

| Strategy | Behavior | |---|---| | random | Uniform random neighbor selection, prefers unvisited | | diversity-biased | Picks the most cognitively different neighbor at each step | | cluster-bridging | Prefers rewired (shortcut) edges to cross cluster boundaries |

Selection modes

| Mode | Behavior | |---|---| | all-visited | First N unique agents from the walk path | | top-k-diverse | Greedy furthest-point sampling for maximum personality diversity |

Personality axes

| Axis | Low (-1) | High (+1) | |---|---|---| | analytical_intuitive | Systematic decomposition | Pattern recognition, holistic leaps | | convergent_divergent | Narrows to one answer | Expands possibilities | | abstract_concrete | Theoretical frameworks | Specific, grounded examples | | critical_generative | Finds flaws, stress-tests | Builds, creates, synthesizes | | individual_systemic | Focuses on parts | Focuses on wholes, feedback loops | | conservative_innovative | Works within paradigms | Breaks paradigms |

License

MIT