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-optimizer

A strategy-parameter optimizer: grid and random search over the parameters the agent exposes (min_score_to_enter, min_score_to_hold, max_positions, rebalance_threshold_pct, target_stable_reserve_pct), maximizing a chosen objective (Calmar or Sharpe). Pure standard library — no numpy, no requests.

Two modes:

  • offline (default): searches a deterministic synthetic objective surface whose optimum is hidden in model.py; the search rediscovers it. Runs with no API.
  • api: ranks the named presets (conservative/balanced/aggressive) by calling the live backtest endpoint GET /skills/{skill}/backtest?preset=.

Run

cd python-lab/optimizer
python3 -m optimizer.cli --offline --metric calmar
python3 -m optimizer.cli --offline --random 40 --metric sharpe
python3 -m optimizer.cli --offline --csv /tmp/grid.csv
python3 -m optimizer.cli --api --skill momentum-volatility-blend --metric calmar

--top N controls how many ranked results print; --api-url / $GUARDRAIL_API sets the API base.