- Rust engine: real bootstrap/wiring preflight (guardrail-agent), execution layer (retry/router/pre-trade/post-trade/reconciliation), guardrail-doctor diagnostics with allowlist-drift guard. - guardrail-cli: extracted pure helpers into util.rs (split in progress). - 6 Track-2 skills + ensemble; python-lab analytics (regime/drawdown/montecarlo/dossier/ensemble/journal/seed); clients (ts/py/go/mcp/langchain/web-lite/proof-verifier); alert relay; scenarios; helm/k8s/compose; docs. - dashboard/vercel.json + docs/VERCEL_DEPLOY.md for Vercel deployment. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
9.1 KiB
Guardrail Alpha — Python Analytics Lab
Offline analytics layer for the Guardrail Alpha trading agent. It reads the agent's SQLite event log plus its JSON run report and produces metrics, charts, CSV exports, and Markdown reports.
Everything is standard-library only. matplotlib is the single optional
dependency: when it is installed, chart scripts emit PNGs; when it is absent they
fall back to CSV, so every script always succeeds. The packages listed in
requirements.txt / pyproject.toml are for the notebooks, not for the export
pipeline.
# No install required for the export pipeline:
python3 python-lab/scripts/verify.py # smoke check
python3 python-lab/scripts/export_all.py # full pipeline
All scripts bootstrap sys.path so they run from either the repository root or
from python-lab/. Paths below are written as run from the repository root.
Data Sources
1. SQLite event log — data/guardrail_alpha.db
Single events table, one row per agent event:
| Column | Type | Notes |
|---|---|---|
id |
TEXT | Primary key. |
run_id |
TEXT | Run identifier (not null). |
timestamp |
TEXT | ISO-8601 / sortable timestamp (not null). |
event_type |
TEXT | Event kind (not null) — see table below. |
payload_json |
TEXT | JSON object string (not null), parsed to payload. |
Event types and their key payload fields (one cycle, in timestamp order):
event_type |
Key payload fields |
|---|---|
agent_started |
agent_id, mode, policy_hash, wallet |
market_snapshot_received |
assets, ts |
regime_classified |
regime (e.g. risk_on) |
portfolio_target_computed |
headline, orders |
order_proposed |
from, to, amount_usd (decimal string) |
twak_quote_received |
route, slippage_pct |
risk_approved / risk_clipped |
amount_usd (final executed amount, decimal string) |
twak_swap_submitted |
amount_usd |
tx_confirmed |
tx_hash, status, block (one confirmed on-chain swap) |
daily_trade_requirement_satisfied |
trades |
portfolio_reconciled |
nav_usd (high-precision decimal string), positions |
agent_report_published |
agent_id, wallet_address, policy_hash, report_hash, run_id, final_nav_usd, total_drawdown_pct, cycles, events, address_url |
amount_usd / nav_usd are stored as high-precision decimal strings and are
parsed to float best-effort; unparseable values degrade to 0.0 / are skipped
rather than raising.
2. Run report — data/run_report.json
JSON object summarizing the run. Keys:
| Key | Meaning |
|---|---|
run_id |
Run identifier. |
mode |
paper / live. |
regime |
Latest regime classification. |
kill_switch |
Boolean — whether the kill switch triggered. |
nav_usd |
Current NAV (decimal string). |
starting_nav_usd |
NAV at the start of the run. |
total_drawdown_pct |
Reported drawdown as a fraction (e.g. 0.0432). |
trades |
Confirmed trade count. |
events |
Event count. |
policy_hash |
Policy hash. |
wallet_address |
Agent wallet address. |
updated_ms |
Last-update timestamp (ms). |
positions |
Array of { symbol, value_usd, weight_pct }. |
guardrail_lab package
Each module is stdlib-only and tolerates missing / malformed data.
| Module | Purpose | Key functions |
|---|---|---|
db.py |
SQLite event-log access | load_events(db_path) → list[dict] (parses payload_json to payload); event_counts(events) → dict by type; database_path() |
loaders.py |
JSON run-report access | load_run_report(path) → dict | None (None when missing/invalid) |
metrics.py |
NAV / drawdown / counts | nav_series(events) → list[(ts, nav)]; drawdown_series(events) → list[(ts, pct)]; max_drawdown(values) → float; trade_count(events) → int |
attribution.py |
Trade attribution & regimes | trade_attribution(events) → list[{symbol, count, total_amount_usd}] (descending); regime_timeline(events) → list[{timestamp, regime}] |
charts.py |
Charts (PNG) + CSV fallback | plot_equity_curve, plot_drawdown, plot_allocation, plot_attribution (return path or None); write_equity_curve_csv, write_allocation_csv, write_attribution_csv, write_drawdown_csv; PLOTTING_AVAILABLE flag |
reports.py |
Markdown reports | build_daily_report(db_path, report_path) → str; build_submission_report(...) → str (judge-facing) |
trade_attribution correlates each tx_confirmed swap with the most recent
preceding order_proposed (for the destination symbol) and the latest
risk_approved / risk_clipped decision (for the final executed amount).
Scripts (scripts/)
Each script accepts an optional positional [db_path] (and, where noted,
[report_path]) and is safe to run when the database is missing.
| Script | Run command (from repo root) | Artifact written |
|---|---|---|
verify.py |
python3 python-lab/scripts/verify.py |
None — prints a PASS/FAIL smoke-check checklist (exits non-zero on failure) |
export_equity_curve.py |
python3 python-lab/scripts/export_equity_curve.py |
data/exports/equity_curve.csv (timestamp, nav_usd) + summary stats |
export_drawdown_chart.py |
python3 python-lab/scripts/export_drawdown_chart.py |
data/exports/drawdown.png (matplotlib) or data/exports/drawdown.csv |
export_trade_attribution.py |
python3 python-lab/scripts/export_trade_attribution.py |
data/exports/trade_attribution.csv (symbol, count, total_amount_usd) |
export_signal_heatmap.py |
python3 python-lab/scripts/export_signal_heatmap.py |
data/exports/signal_summary.csv (regime timeline + final weights) |
export_charts.py |
python3 python-lab/scripts/export_charts.py |
data/exports/{equity_curve,allocation,attribution}.png or .csv fallbacks |
generate_daily_report.py |
python3 python-lab/scripts/generate_daily_report.py |
python-lab/reports/daily/<date>.md (or data/exports/daily_report.md when no run report) |
generate_submission_report.py |
python3 python-lab/scripts/generate_submission_report.py |
python-lab/reports/final_submission/submission.md |
export_all.py |
python3 python-lab/scripts/export_all.py |
Runs the full pipeline (equity, allocation, drawdown, attribution, signal summary, daily report) and prints a manifest |
Output locations
data/exports/— CSV/PNG export artifacts.python-lab/reports/daily/<date>.md— daily Markdown reports.python-lab/reports/final_submission/submission.md— submission report.
PNG vs CSV
Chart scripts (export_charts.py, export_drawdown_chart.py, export_all.py)
write PNG when matplotlib is importable and CSV otherwise. The plotting
functions return None when plotting is unavailable or there is no data, which
is the signal the scripts use to fall back to CSV. Pure-data exports
(export_equity_curve.py, export_trade_attribution.py, export_signal_heatmap.py)
are always CSV.
Verification
python3 python-lab/scripts/verify.py # exit 0 on success
verify.py imports every module, checks the key functions are callable, runs
each pipeline function against an empty event log, runs the full pipeline against
data/guardrail_alpha.db when it exists, and writes a sample artifact to a temp
directory. When the database is absent it runs import-only checks and still
passes with a notice.