---
title: "Explainability and Self-Tuning"
description: "Rich structured explanations for MCP tools, adaptive confidence thresholds, and built-in backtesting."
---

Three subsystems that make the fund self-aware: explainability surfaces everything the LLM needs in a single call, adaptive thresholds tune decision confidence from outcomes, and the backtest runner validates strategies before deployment.

## Explainability

The Explainer reads from every fund subsystem and returns structured dictionaries that give the LLM a complete picture. Each section is wrapped in error handling so a failure in one subsystem does not break the entire response.

### Fund State Explanation

```
fund_explain()
```

Returns everything about the fund in one call:

| Section | Contents |
|---|---|
| `overview` | NAV, drawdown, running strategies, kill switch status, universe size |
| `regime` | Current market regime with confidence and recent transitions |
| `risk` | Tail risk (VaR/CVaR), portfolio Greeks, correlation flags |
| `strategies` | Per-strategy status with P&L, drawdown, uptime, orders, positions |
| `decisions` | Recent autonomous decisions with reasoning and outcomes |
| `alerts` | Recent alerts with counts by category |
| `hypotheses` | Active trading hypotheses with lifecycle state and confidence |
| `alpha_factors` | Per-factor information coefficients and weights |

### Strategy Explanation

```
fund_explain_strategy(name="political_mm")
```

Deep dive into a single strategy:

| Section | Contents |
|---|---|
| `performance` | NAV, P&L, drawdown, open orders, active positions, uptime |
| `execution` | Fill rates, slippage, adverse selection, market impact |
| `alpha_decay` | Current edge, half-life, predicted zero crossing, retirement recommendation |
| `promotion` | Current stage (paper/shadow/live), days in stage |
| `hypotheses` | Active hypotheses for this strategy's markets |

### Risk Explanation

```
fund_explain_risk()
```

Full risk breakdown:

| Section | Contents |
|---|---|
| `tail_risk` | Historical and Cornish-Fisher VaR/CVaR, skewness, kurtosis |
| `greeks` | Portfolio-level delta, gamma, theta, vega |
| `correlations` | Cross-strategy correlation matrix with high-correlation flags |
| `stress` | Stress test results (10/20% drawdown, correlation spike, liquidity crisis, black swan) |
| `var_budget` | Per-strategy VaR utilization vs. budget |
| `dynamic_limits` | Regime-adjusted position limits |
| `attribution` | Alpha/beta decomposition, information ratio |

### Full Snapshot

```
fund_full_snapshot()
```

Everything combined: status, strategies, NAV history, risk dashboard, stress test, P&L attribution, correlation matrix, execution report, hypotheses, regime, alpha model, decisions, decay report, alerts, ledger, and promotion status. Use this when the LLM needs a complete picture to make a decision.

### Design

The Explainer is stateless. It holds a reference to the FundManager and reads from subsystems on demand. If a subsystem is not enabled or throws an error, that section returns `"unavailable"` instead of failing the entire call.

## Adaptive Thresholds

Self-tuning confidence thresholds that learn from decision outcomes. Over time, the fund raises thresholds for actions that produce bad outcomes and lowers them for actions that consistently succeed.

### How It Works

1. After each autonomous decision, the outcome (profitable or not) is recorded
2. Every 120 oversight ticks, the tuner computes precision (profitable / total) per action type
3. Thresholds are adjusted:
  - Precision < 0.6: raise threshold by 0.05 (be more conservative)
  - Precision > 0.8: lower threshold by 0.02 (allow more actions)
4. Updated thresholds are injected into the DecisionFramework

### Bounds

Thresholds are clamped to `[0.2, 0.95]` to prevent the system from becoming either reckless or paralyzed. A minimum of 10 samples per action type is required before any adjustment.

### Configuration

```python
fund = FundManager(FundConfig(
    total_capital=100_000,
    adaptive_thresholds_enabled=True,
))
```

### Precision Tracking

```python
stats = fund.threshold_tuner.stats()
# {
#     "deploy": {"total": 25, "profitable": 18, "precision": 0.72},
#     "scale_up": {"total": 12, "profitable": 10, "precision": 0.83},
#     "retire": {"total": 8, "profitable": 6, "precision": 0.75},
# }
```

## Built-in Backtester

The BacktestRunner generates synthetic prediction market data and runs strategies through it. It produces callables that plug directly into the Autopilot's `evaluate()` method, so every strategy is backtested before deployment.

### Synthetic Price Data

Generates bounded random walks that simulate prediction market price movement:

- Prices stay within `[0.02, 0.98]` (valid probability range)
- Drift is proportional to the edge estimate (positive edge = upward drift)
- Bid/ask spread and volume are included in each tick
- Default: 500 ticks per backtest run

### Integration with Autopilot

When the fund is configured, the BacktestRunner provides two callables:

```python
# These are wired automatically in the oversight loop
backtest_fn = fund.backtest_runner.as_backtest_fn()
robustness_fn = fund.backtest_runner.as_robustness_fn()

# Autopilot uses them to validate candidates before deployment
autopilot.evaluate(
    candidate,
    backtest_fn=backtest_fn,
    robustness_fn=robustness_fn,
)
```

The backtest function returns a results dict with `sharpe`, `trades`, `max_drawdown_pct`, and `walk_forward_consistency`. The robustness function returns a dict with `p_value` indicating statistical significance.

### Direct Usage

```python
from horizon.fund import BacktestRunner

runner = BacktestRunner()
results = runner.run(
    pipeline=[signal_fn, quote_fn],
    markets=["will-x-win"],
    edge=0.05,
    n_ticks=1000,
)
```

## MCP Tools Summary

| Tool | Description |
|---|---|
| `fund_explain` | Full fund state: overview, regime, risk, strategies, decisions, alerts, hypotheses, alpha factors |
| `fund_explain_strategy` | Single strategy deep dive: performance, execution, decay, promotion, hypotheses |
| `fund_explain_risk` | Full risk analysis: tail risk, Greeks, correlations, stress, VaR, limits, attribution |
| `fund_hypotheses` | Active trading hypotheses with lifecycle state, confidence, edge estimates |
| `fund_regime` | Current market regime with confidence and recent transitions |
| `fund_alpha_model` | Alpha model factor report: per-factor ICs, significance, weights |
| `fund_decisions` | Recent autonomous decisions with reasoning, confidence, outcome, guardrail status |
| `fund_decay_report` | Alpha decay tracking: edge erosion, half-life estimates, retirement recommendations |
| `fund_full_snapshot` | Everything in one call |
