Caelum 0d7f3e4a26
feat: product expansion + production hardening (16 components, 4 langs) (#4)
* feat(prod): fail-fast on missing live creds + client hardening

No more silent mock fallback — the defining hackathon→product fix.

- agent-runtime: build_data_source/build_executor now return Result and
  refuse to run on mock data in LIVE mode (missing CMC_API_KEY/mcp_url,
  use_mock=true, twak.mode="mock", or a network transport without base_url
  all error instead of silently trading on fake data from a fake wallet).
  Paper mode still degrades to mock. +3 deterministic fail-fast tests.
- twak-client: REST and MCP transports now use a 20s request timeout
  (was reqwest's no-timeout default — a hung TWAK endpoint could stall
  the trading loop forever).
- cmc-client: a missing/non-positive quote price now skips the asset with
  a warning instead of feeding a $0 price into the strategy/risk engine.
- agent-runtime: run-report dir create failure is logged, not swallowed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(prod): doc truth, strip hackathon scaffolding, observability (chunks 2-4)

Chunk 2 — doc↔code truth:
- Fix stale counts: 69 routes (README/API/ARCHITECTURE), 64 dashboard pages
  (ARCHITECTURE), and mark the route/page tables as representative subsets.

Chunk 3 — strip hackathon scaffolding:
- Archive pure prize/judge docs to docs/archive/hackathon/ (SUBMISSION,
  HACKATHON, PRIZE_MAP, PITCH, JUDGE_DEMO, TRACK2, DEMO_SCRIPT) and judge
  scripts to scripts/archive/. Reframe README "Hackathon tracks" -> "Capabilities"
  and fix the now-archived links. Product-relevant docs (architecture, risk,
  strategy, runbook, proof/identity, CMC hub) stay.

Chunk 4 — observability + tests:
- agent-runtime: build_data_source/build_executor return a transport label;
  AgentStarted payload now carries cmc_transport + twak_transport, plus a
  "transports resolved" structured log — operators can see live-vs-mock at a glance.
- cmc-client: extract parse_quotes pure helper + 6 tests for the price-skip behavior.

Workspace builds green, clippy clean, tests pass, paper run verified.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(product): orderbook + ta-signals crates + /ta API route

Two real, pure-Rust product crates (no mocks), integrated into the workspace,
plus a real API surface exposing the indicators.

- crates/orderbook: in-memory limit order book with a price-time-priority
  matching engine — limit/market orders, partial fills, multi-level market
  sweeps, FIFO time priority, cancel, best bid/ask, spread, aggregated depth.
  8 unit tests + a doctest.
- crates/ta-signals: technical-analysis library — SMA, EMA, RSI (Wilder),
  MACD, Bollinger Bands, ATR, Stochastic, OBV, ADX (full Wilder directional
  system), VWAP. Each returns an input-aligned Vec with NaN warmup; correct
  algorithms with known-value tests. 24 unit tests + a doctest.
- apps/guardrail-api GET /ta: compute sma/ema/rsi/macd/bollinger over a
  caller-supplied close series via ta-signals (NaN -> JSON null). Route count
  -> 70; docs synced.

Workspace builds green, clippy clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(product): price-oracle Go microservice + README count sync

services/price-oracle: a real read-only Go microservice serving live USD
prices for the BSC universe from the free CoinGecko public API, cached behind
a TTL. No key, no chain, no writes.
- oracle/coingecko.go: real HTTP client (timeout, UA, error handling) over
  /simple/price for 10 tracked symbols.
- oracle/cache.go: thread-safe TTL cache; stale-on-error graceful degradation.
- oracle/server.go: net/http (go1.22 method+path patterns) — GET /health,
  /prices, /prices/{symbol}, /prices/refresh; JSON; access logging.
- main.go: PORT/ORACLE_TTL/ORACLE_HTTP_TIMEOUT env, read-header timeout.
- go vet clean, go build ok; verified live: /prices/BTC returned a real price.

docs: sync README "What's inside" counts to reality (24 crates, 70 routes,
64 pages).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(product): risk-analytics service (metrics engine + API + CLI)

services/risk-analytics: portfolio risk/performance metrics over the agent's
NAV curve. Pure-stdlib engine + CLI (run anywhere, no numpy); optional FastAPI
HTTP surface.
- risk_analytics/metrics.py: total/annualized return, annualized vol, max
  drawdown, Sharpe, Sortino, Calmar, historical + parametric VaR (Acklam
  inverse-normal), Pearson correlation matrix. Doctested formulas.
- store.py: reads the NAV series from portfolio_reconciled events in the
  SQLite log. api.py: import-guarded FastAPI (POST /metrics, /correlation,
  GET /metrics/live, /health). cli.py: metrics/live/demo subcommands.
- Verified: doctests pass; CLI demo + live (over the real event log) produce
  correct metrics.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(product): 3 new dashboard pages (market-oracle, transports, journal-pro)

Real Next.js server components over the read-only API; nav links added.
- /market-oracle: renders the CMC data->capability lineage from
  GET /cmc/capabilities (datasets + capabilities tables, summary).
- /transports: surfaces the running agent's resolved cmc/twak transports +
  mode from the latest agent_started event, flagging live-with-mock.
- /journal-pro: GET /events with a client-side event-type filter (a small
  "use client" JournalTable component).
- src/lib/types-expansion.ts holds the new types (existing types.ts untouched).
- tsc --noEmit clean. Dashboard pages -> 67.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(product): grctl read-only operator CLI (Go)

clients/go-cli: a dependency-free Go CLI over the read-only API.
- internal/client: net/http client (10s timeout, non-2xx errors, JSON decode).
- internal/commands: status/regime/portfolio/trades/risk/signals/proof/verify/
  events/cockpit + watch (polls /regime); clean tabwriter summaries or --json.
- main.go: --api/$GUARDRAIL_API base, --json flag, help.
- go vet clean, go build ok.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(product): guardrail-term terminal client (TypeScript)

clients/ts-terminal: a typed, dependency-free Node CLI over the read-only API.
Uses built-in fetch; DOM lib + a tiny process shim so it typechecks with zero
deps (no @types/node).
- src/api.ts: read-only client (AbortController 10s timeout, non-2xx errors).
- src/render.ts: ANSI color + aligned kv/table helpers (no deps).
- src/index.ts: status/regime/portfolio/trades/risk/signals/proof/verify/
  events/cockpit/watch; --api/$GUARDRAIL_API, --json; colored verify table.
- tsc --noEmit clean; built + ran help to verify.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(product): strategy parameter optimizer (Python)

python-lab/optimizer: grid + random search over the agent's strategy params,
maximizing Calmar or Sharpe. Pure stdlib (no numpy/requests).
- objective.py: calmar/sharpe/max_drawdown/annualized_return over an equity curve.
- model.py: deterministic synthetic equity surface with a hidden optimum.
- grid.py: grid_search + seeded random_search.
- runner.py: offline scorer (synthetic) + api_backtest scorer (urllib over
  GET /skills/{skill}/backtest?preset=).
- cli.py: --offline/--api, --metric, --random N, --csv, --top.
- Verified: offline grid rediscovers the hidden ideal params as the top Calmar.

8/8 product-expansion components shipped (orderbook, ta-signals+/ta, price-oracle,
risk-analytics, dashboard pages, grctl, ts-terminal, optimizer).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(whats-new): Phase 3 product-expansion entry + fix archived companion links

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(product): batch 2 — position-sizer, fee-model, notification-relay, reporting, ta-studio

Five more real components (workflow-built, integrated + verified). Workspace
builds green; new Rust crates carry unit tests.

- crates/position-sizer (Rust): fixed-fractional, vol-target, Kelly (fractional
  + cap), equal-risk-contribution weights. 39 tests + 5 doctests. forbid(unsafe).
- crates/fee-model (Rust): all-in swap cost — gas, constant-product price impact
  + linear slippage, protocol fee; CostBreakdown w/ effective price. 16 tests + doctest.
- services/notification-relay (Go): concurrent webhook fan-out (POST /notify ->
  goroutine per target, per-attempt timeout + retry, 200/207/502, delivery
  report), GET /health, graceful shutdown. vet + build clean.
- python-lab/reporting (Python, stdlib): reads the event log read-only + run
  report, computes drawdown/return/sharpe, renders a self-contained HTML (or
  text) report. Verified against the real DB.
- dashboard /ta-studio: page driving the new GET /ta endpoint (searchParams ->
  indicator/series/period), NaN warmup rendered as "—"; nav link added. tsc clean.

Both new crates registered in the workspace; cargo build --workspace green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(product): expose fee-model + position-sizer via GET /fees and /sizer

Two real API routes over the new crates, wiring crate -> API.
- GET /fees: all-in swap cost (gas + price-impact/slippage + protocol fee) from
  fee-model; query params with sensible defaults, buy/sell side.
- GET /sizer: position sizing from position-sizer — method=fixed_fractional|
  vol_target|kelly with their params; returns input + output (or a typed error).
- guardrail-api deps + modules + routes wired; build + clippy clean.
- Route count -> 72; README/API/ARCHITECTURE synced.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(product): /fees + /sizer dashboard pages (crate -> API -> page verticals)

Two new Next.js pages closing the verticals for the fee-model and
position-sizer crates:
- /fees: renders GET /fees cost breakdown; ?notional_usd/quantity/side drive it.
- /sizer: renders GET /sizer input+output; ?method=fixed_fractional|vol_target|
  kelly + params.
Nav links added; inline types; tsc --noEmit clean. Dashboard pages -> 70;
README/ARCHITECTURE synced.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(product): Monte Carlo outcome simulator (Python)

python-lab/montecarlo: simulate strategy equity outcomes — terminal-value
distribution, max-drawdown risk, prob of loss, prob of ruin. Pure stdlib.
- sim.py: bootstrap (resample a historical return series) + GBM engines;
  per-path max drawdown; percentile/ruin summary.
- cli.py: --demo/--bootstrap/--gbm, reads NAV from the event log (read-only)
  with --db, configurable paths/horizon/mu/sigma/ruin.
- Verified: demo + gbm produce sensible distributions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(sdk): TypeScript SDK methods for /ta, /fees, /sizer, /cmc/capabilities

Make the new quant endpoints consumable from the typed client:
- ta(params): compute an indicator over a close-price series.
- fees(params): all-in swap cost (camelCase -> snake_case query mapping).
- sizer(params): position sizing by method.
- cmcCapabilities(): CMC data->capability lineage.
Typed param interfaces (TaParams/FeesParams/SizerParams); tsc --noEmit clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(sdk): Python client methods for /ta, /fees, /sizer, /cmc/capabilities

Parity with the TS SDK — ta(indicator, series, ...), fees(**params),
sizer(method, **params), cmc_capabilities(). Stdlib urllib; imports clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: README clients count 9->11 (grctl, guardrail-term) + services list

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-16 14:05:15 +03:00
..

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.