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