> ## Documentation Index
> Fetch the complete documentation index at: https://mathematicalcompany.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Pipeline
> Agent lifecycle from spawning to retirement. 9 archetype templates, paper-to-shadow-to-live promotion, fitness-based selection pressure.
Each agent in the Hive follows a structured lifecycle managed by the compiled Rust subsystems. The **AgentFactory** spawns agents from 9 archetype templates. The **SwarmCoordinator** applies selection pressure, culling underperformers and promoting winners through paper, shadow, and live stages. The **ReputationSystem** tracks trust with Bayesian scoring. Every order goes through the same compiled Rust risk pipeline.
## Phases
Agent is spawned but hasn't started work. Waiting for capital allocation from the Hive.
Discover markets, gather data, check the knowledge graph for what other agents have found. Uses `discover_markets`, `market_detail`, `get_orderbook`, `query_knowledge`.
Compute Kelly sizing, check parity across exchanges, estimate edge, compute Hurst exponent for mean-reversion signals. Tools: `kelly_sizing`, `check_parity`, `compute_hurst_exponent`, `build_signals`.
Simulate the strategy on historical data. Collect equity curves, compute Sharpe, max drawdown, win rate. Tools: `simulate_portfolio`, `bootstrap_sharpe_tool`, `backtest`.
Run all 5 anti-overfitting gates. Every gate must pass. The agent can't move to proposing until all 5 return passing results. This is the filter that separates curve-fit garbage from strategies with real edge.
Package the hypothesis, market, side, edge estimate, Kelly fraction, backtest results, and all 5 gate results into a proposal. Submit to the Hive. Wait for a verdict.
Hive approved. Place orders within the capital allocation. The Rust engine enforces position limits and notional caps. Tools: `submit_order`, `cancel_order`, `amend_order`.
Track open positions, read live feeds, detect regime changes. If the market shifts, the agent can evolve or retire. Tools: `list_positions`, `get_feed_snapshot`, `portfolio_summary`.
Adjust strategy parameters based on live performance. Re-run partial backtests if needed. Can go back to monitoring or forward to retiring.
Close all positions, write a post-mortem to the knowledge graph, report final P\&L to the Hive, stop.
Transitions happen when the agent calls `transition_phase(new_phase, reason)`. The reason is logged to the event bus. The system prompt tells the agent which tools to use in each phase, but all tools are always available. Phase filtering is prompt-guided so agents have flexibility when they need it.
## Anti-Overfitting Gates
Five statistical tests. All must pass during the Robustness phase. The Hive also verifies gate results when reviewing a proposal. If any gate is missing or failed, the proposal is auto-rejected in code.
Harvey et al. 2016 correction for multiple testing. Adjusts the observed Sharpe ratio for how many strategies were tested. Gate: p-value below 0.05.
Rolling train/test splits. Train on historical data, test on out-of-sample. Gate: OOS Sharpe above 0.5 and OOS/IS ratio above 0.5.
Combinatorial purged cross-validation. Computes the probability of backtest overfitting across all path combinations. Gate: PBO below 0.30.
Bootstrap Sharpe distribution: P(Sharpe > 0) must exceed 0.95. Monte Carlo timing permutation: profitable in 80%+ of shuffles. Stress test at 2x volatility and -20% crash: max drawdown below 2x normal.
The strategy must have a non-trivial economic hypothesis. Must be profitable across at least 2 market regimes. Capacity must exceed the requested capital.
Implemented as tool calls: `run_deflated_sharpe`, `run_walk_forward`, `run_cpcv_pbo`, `run_bootstrap_robustness`, `run_structural_validation`. Each returns a structured result with a `passed` boolean and supporting metrics.
## Agent Archetypes
The Rust **AgentFactory** provides 9 archetype templates:
| Archetype | Strategy Style |
| ---------------- | -------------------------------------------------------- |
| `momentum` | Trend following, breakout detection |
| `mean_reversion` | Statistical reversion to fair value |
| `market_maker` | Two-sided quoting, inventory management |
| `arbitrage` | Cross-venue price discrepancies |
| `volatility` | Vol surface, straddles, calendar spreads |
| `event_driven` | News, earnings, resolution catalysts |
| `macro` | Rate expectations, yield curve, inflation |
| `copy` | Behavioral cloning of operator style (via ImprintSystem) |
| `liquidation` | Forced liquidation flow detection |
Agents can also be spawned from 5 additional sources: **evolution** (bred by the EvolutionEngine), **clone** (copy of a high-performing agent), **user** (manually spawned), **imprint** (learned from operator behavior), and **opportunistic** (spawned in response to detected opportunities).
```python theme={null}
# Spawn from template
agent = hive.spawn_agent("momentum", markets=["BTC-YES"], capital=5000.0)
# The AgentFactory creates the genome, the SwarmCoordinator registers it
```
## Promotion Pipeline
Agents don't go straight to live trading. The SwarmCoordinator manages a 3-stage promotion pipeline:
| Stage | What Happens | Graduation Criteria |
| ---------- | ------------------------------------- | ------------------------------------------ |
| **Paper** | Simulated execution only | Sharpe > `min_sharpe_paper` (default 1.0) |
| **Shadow** | Real market data, simulated fills | Sharpe > `min_sharpe_shadow` (default 1.2) |
| **Live** | Real execution with allocated capital | Promoted by SwarmCoordinator tick |
Each tick of the SwarmCoordinator evaluates all agents: updates fitness scores, culls underperformers past `age_cull_days`, promotes qualified agents, and rebalances capital using fitness-weighted allocation.
## Engine Integration
Each agent gets its own `Engine` instance with risk limits derived from its capital allocation. When an agent calls `submit_order`, the 8-point risk pipeline runs in Rust. If the order is rejected, the agent gets an error message and can adjust.
The SwarmCoordinator enforces that total capital across all agents can't exceed `total_capital`. When it rebalances, agents with higher fitness scores receive proportionally more capital. `max_capital_per_agent_pct` (default 15%) prevents any single agent from dominating.
One agent's risk breach doesn't affect another agent's engine. Portfolio-wide limits are handled by the CriticalityMonitor and KillChain.
## Tools
Each agent gets access to all Horizon SDK tools plus swarm-specific tools:
Auto-wrapped from `tools.py`. Discovery, analytics, execution, fund management, wallet analysis, and feeds across all 8 exchanges.
`transition_phase`, `submit_proposal`, `share_insight`, `get_hive_directives`, `report_status`, `query_knowledge`.
`run_deflated_sharpe`, `run_walk_forward`, `run_cpcv_pbo`, `run_bootstrap_robustness`, `run_structural_validation`.
`query_knowledge` and `share_insight` connect to the shared SQLite knowledge graph. Agents read what other agents found and write their own findings.
## Selection Pressure
The SwarmCoordinator applies Darwinian selection pressure every tick:
1. **Fitness scoring**: Each agent's fitness is a composite of Sharpe ratio, profit factor, drawdown, and diversity contribution (via the MAPElitesArchive).
2. **Diversity tax**: Agents whose behavioral fingerprint is too similar to existing agents (correlation > `diversity_tax_threshold`, default 0.7) get a fitness penalty. Prevents the swarm from converging to one strategy.
3. **Age culling**: Agents past `age_cull_days` (default 30) that haven't earned promotion are culled.
4. **Reputation weighting**: The Bayesian ReputationSystem weights capital allocation and pheromone deposits. Higher reputation = more influence on the swarm.
```python theme={null}
# The SwarmCoordinator tick returns a summary
result = hive.coordinator.tick()
# {"tick": 142, "fitness_updated": 12, "culled": 2, "promoted": 1,
# "scaled": 3, "rebalanced": True, "total_agents": 15}
```
## Pheromone Communication
Agents don't message each other. They communicate through the **PheromoneField**: 9 channels of environmental signals that evaporate over time and diffuse to related markets.
Before trading, an agent senses the field:
```python theme={null}
readings = hive.pheromone.sense("BTC-YES")
# High crowding? Too many agents on this market. Look elsewhere.
# High toxicity? Adverse selection detected. Widen spreads or avoid.
# High opportunity? Untapped edge. Consider entering.
```
After trading, an agent deposits pheromone weighted by its fitness:
```python theme={null}
hive.pheromone.deposit("BTC-YES", PheromoneChannel.Bullish, amount=0.8, agent_fitness=1.5)
```
No central planner tells agents where to go. The pheromone landscape guides them. Same mechanism ant colonies use.
## Building Custom Agents
Multiple customization paths:
* **Archetype templates**: 9 built-in strategy styles with pre-tuned parameters.
* **Evolution**: The EvolutionEngine breeds new strategy genomes via NSGA-II across 5 islands.
* **Imprint**: The ImprintSystem learns from your trading actions and can spawn agents that replicate your style.
* **MAPElites**: The quality-diversity archive keeps the swarm diverse by construction.
* **Hive directives**: The ReACT research agent can redirect agents based on causal graph analysis and regime detection.
```python theme={null}
from horizon.hive import HiveController, HiveConfig, AutonomyMode
config = HiveConfig(
total_capital=50_000,
max_agents=20,
initial_mode=AutonomyMode.Observe,
)
hive = HiveController(config)
# Spawn specific archetypes
hive.spawn_agent("momentum", markets=["BTC-YES"], capital=5000.0)
hive.spawn_agent("mean_reversion", markets=["ETH-YES"], capital=3000.0)
hive.spawn_agent("arbitrage", markets=["BTC-YES", "ETH-YES"], capital=8000.0)
# Let evolution breed new strategies
hive.evolve(generations=100)
# Or run offline dream state for accelerated evolution
hive.dream(generations=10_000)
```