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