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

145 lines
9.1 KiB
Markdown

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