> ## Documentation Index
> Fetch the complete documentation index at: https://artemiscity.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Hebbian routing

> Blend static composite scores with learned Hebbian weights so the kernel routes tasks to the agents that have actually succeeded at them.

The Hebbian router is the production agent-selection layer in Artemis City. It biases routing toward agents that have *learned* to succeed at a capability, not just the agents whose static profile looks strong. It is the production wiring of the adaptive selection rule prototyped in the Hebbian notebooks.

## When to use this

Use the Hebbian router when:

* You have more than one agent that advertises the same capability and want the kernel to prefer the one with the best track record.
* You want a single general-purpose agent (for example, the LLM agent) to absorb tasks that no specialist advertises.
* You want governance state (quarantined, suspended) to remove an agent from routing without un-registering it.

You do not need to change anything if you only run a single agent per capability and never quarantine agents — the router still works, it just collapses to the registry's composite-score ranking.

## How it scores candidates

Among the agents that advertise the requested capability and are not blocked by governance, the router blends each agent's static composite score with its average Hebbian connection weight:

$$
\text{score}(a) = (1 - \alpha) \cdot \text{composite}(a) + \alpha \cdot \text{hebbian\_norm}(a)
$$

* `composite(a)` comes from the agent registry (trust, capability match, recency).
* `hebbian_norm(a)` is the agent's average Hebbian weight, normalised to `[0, 1]` across the current candidates.
* `alpha` controls how much learned weight overrides the static score.

With no Hebbian history (cold start), every candidate gets a neutral prior, so ranking collapses to the composite score. As the orchestrator strengthens (`+1`) or weakens (`-1`) agent → task connections after each run, proven performers are increasingly preferred.

### Tuning alpha

`alpha` is clamped to `[0, 1]`. Common settings:

| `alpha`         | Behaviour                                                           |
| --------------- | ------------------------------------------------------------------- |
| `0.0`           | Pure composite. Legacy registry behaviour, ignores Hebbian weights. |
| `0.3` (default) | Composite-led, with learned weight as a tiebreaker and slow drift.  |
| `0.5`           | Balanced. Learned success can overturn a mid-rank composite agent.  |
| `1.0`           | Pure Hebbian. Only learned weight matters; composite is ignored.    |

Raise `alpha` once you have enough completed runs for Hebbian weights to be meaningful. Drop it back toward `0` if you are debugging a misbehaving agent and want the registry's static scoring to dominate.

## Fallback capability

`fallback_capability` makes a general-purpose agent reachable when no specialist advertises the requested capability — or when the task omits one entirely.

* If a task has `required_capability` but no eligible agent advertises it, the router retries with `fallback_capability`.
* If a task has no `required_capability` at all, the router routes directly to the fallback.
* If `fallback_capability` is `None`, capability matching is strict and the router raises `ValueError` on no match.

A typical setting is `fallback_capability="llm_chat"`, so the LLM agent absorbs anything no specialist owns.

## Governance gating

Agents in the following governance states are removed from the candidate set before scoring:

* `quarantined`
* `suspended`

This means you can quarantine a misbehaving agent through the governance layer and the router stops selecting it immediately, without changes to its registry record or capabilities.

## Configuration

The router is constructed against an `AgentRegistry` and a `HebbianWeightManager`:

```python theme={null}
from src.integration.hebbian_router import HebbianRouter

router = HebbianRouter(
    registry=agent_registry,
    hebbian=hebbian_weights,
    alpha=0.3,                       # blend factor; default 0.3
    fallback_capability="llm_chat",  # optional; None = strict matching
)

decision = router.route({"required_capability": "summarize_legal"})

print(decision.agent_name)     # selected agent
print(decision.alpha)          # blend factor used
print(decision.fallback_from)  # set if routed via fallback, else None

for candidate in decision.candidates:
    print(
        candidate.name,
        candidate.composite,
        candidate.hebbian_weight,
        candidate.hebbian_norm,
        candidate.blended,
    )
```

`route()` returns a `RoutingDecision` with the chosen agent and a per-candidate breakdown (composite, raw and normalised Hebbian weight, blended score). The decision serialises with `to_dict()` for the run logger or API responses.

For callers that only need the selected name:

```python theme={null}
agent_name = router.route_name(task)
```

## Failure modes

The router is intentionally defensive: any failure reading a weight or score is treated as the neutral prior, so a missing or mocked Hebbian source never breaks routing — it falls back to composite-only behaviour. The only paths that raise `ValueError` are:

* A task with no `required_capability` *and* no `fallback_capability` configured.
* A `required_capability` that no eligible agent advertises *and* no usable fallback.

## Related

* [Routing modes](/Documentation/architecture/routing-modes) — sequential, concurrent, and adaptive orchestration shapes that sit above the router.
* [Hebbian learning and controlled decay](/Documentation/memory/hebbian-learning) — how the weights the router consumes are reinforced and decayed.
* [Trust scoring](/Documentation/governance/trust-scoring) — how composite scores and governance state are produced.


## Related topics

- [Changelog](/Changelog/changelog.md)
- [Artemiscity (Hebbian Agents) Whitepaper V.3](/Documentation/concepts/whitepaper.md)
- [Routing Modes](/Documentation/architecture/routing-modes.md)
- [API Reference](/api/api-reference.md)
- [What Is Artemis City?](/Documentation/Introduction/what-is-artemis-city.md)