caelum0x 2d2b15c7fe feat: full guardrail-alpha system + CLI modularization + Vercel deploy config
- 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>
2026-06-15 11:02:22 +03:00

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.