> ## 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.

# Explainability and Self-Tuning

> 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 theme={null}
fund = FundManager(FundConfig(
    total_capital=100_000,
    adaptive_thresholds_enabled=True,
))
```

### Precision Tracking

```python theme={null}
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 theme={null}
# 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 theme={null}
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                                                                            |