* 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-reporting
A self-contained HTML (and plain-text) report generator for the Guardrail agent. It reads the agent's SQLite event log and JSON run report, computes summary risk metrics from the NAV series, and renders a clean report with no external assets and no third-party dependencies — standard library only.
What it reads
data/guardrail_alpha.db— a singleeventstable with columns(id, run_id, timestamp, event_type, payload_json). The generator extracts:- event counts by
event_type - the NAV series from
portfolio_reconciledevents (payload.nav_usd) - confirmed trades from
tx_confirmedevents (tx_hash,competition_tx,block,status) The database is opened read-only so the agent's log is never mutated.
- event counts by
data/run_report.json— flat run summary (run_id,mode,regime,kill_switch,nav_usd,starting_nav_usd,positions,trades, ...). Optional: if absent the report still renders from the event log alone.
Metrics (computed inline, stdlib only)
All math uses decimal.Decimal for exactness — see reporting/metrics.py.
- Total return —
(last NAV / first NAV) − 1. - Max drawdown — largest peak-to-trough decline over the NAV series, as a non-negative ratio.
- Simple Sharpe —
mean(period return) / stdev(period return)over the simple returns between successive NAV observations. Risk-free rate is assumed zero and the ratio is reported un-annualised. - Volatility — sample standard deviation (n−1) of the period returns.
Usage
# from python-lab/reporting/
python -m reporting.cli --db ../../data/guardrail_alpha.db --out report.html
# text summary to stdout
python -m reporting.cli --db ../../data/guardrail_alpha.db --format text
# explicit run report, single run, custom title
python -m reporting.cli \
--db ../../data/guardrail_alpha.db \
--report ../../data/run_report.json \
--run-id run_0485d42cebfd45a79219ec8bc2219f09 \
--title "Guardrail Alpha" \
--out report.html
CLI options
| Option | Description |
|---|---|
--db |
Path to the SQLite event log (required). |
--report |
Path to run_report.json. Defaults to a sibling of --db. |
--no-report |
Ignore any run report, even one beside --db. |
--run-id |
Restrict the event log to one run_id. |
--format |
html (default) or text. |
--out |
Output file path. Defaults to stdout. |
--title |
Document title for HTML output. |
An installed entry point guardrail-report mirrors python -m reporting.cli.
Layout
reporting/
├── pyproject.toml # no dependencies
├── README.md
└── reporting/
├── __init__.py
├── data.py # sqlite + json readers (read-only, validated)
├── metrics.py # inline risk metrics (Decimal, stdlib)
├── format.py # shared value formatting helpers
├── html.py # self-contained HTML template + inline SVG chart
├── text.py # plain-text summary renderer
└── cli.py # python -m reporting.cli
Notes
- The HTML report embeds an inline SVG NAV chart and inline CSS; there are no
http/httpsreferences and no JavaScript, so it opens correctly offline. - All user-derived values are HTML-escaped before rendering.
- Pure standard library:
sqlite3,json,decimal,html,argparse.