io.github.Hlobo-dev/tengu-firm

Cache hit-rate statistics for the data layer. Call when the user asks whether the system/data pipeline is healthy or why data looks stale or slow.

REVIEW A TRACKED DECISION. Pass the decision_id returned by decision_track. FIRM re-fetches the same verdict shape (ticker_full) and computes a structured DELTA against the original snapshot. Returns thesis_status in {intact, weakening, broken, n/a} based on the score delta projected into the user's side direction. Includes a narrative the chat can render verbatim. Returns 404 if the decision expired (90-day TTL) or was never recorded. Use this for the 'your AAPL position you opened Tuesday is up X% — thesis is tracking' callback shape.

Live IC drift status — comparison of realised live IC vs training-time IC. The canonical alpha-decay early warning. CALL THIS when the user asks 'is the model still working?', 'any drift?', 'should we trust today's predictions?'. Returns ic_ratio (live / training) per horizon, drift status (green / yellow / red), and a plain-English narrative. Sub-second; refreshed daily after the close. ic_ratio < 0 = sign flip (halt new positions); ic_ratio < 0.3 = severe (retrain ASAP); ic_ratio > 1.0 = model outperforming training expectation.

Current macro regime + plain-English interpretation of how strong the model's edge is in this regime. CALL THIS when the user asks about market conditions, regime, 'is it a good time to invest', or how confident the model is right now.

Full per-ticker quant analysis. CALL THIS when the user asks about any specific stock (e.g. 'should I buy NVDA', 'what do you think of TSLA'). Returns blended_score, decile, conformal expected-return interval (90% band), 12-voter breakdown, factor tier, regime context, suggested position size, and a self-contained narrative. Use the narrative as a quotable summary; use the structured fields for follow-up questions. NAMESPACE: FIRM's universe is US EQUITIES. Nine tickers (BTC ETH LINK LTC COMP ARB NEAR APT ATOM) are ALSO crypto symbols; for those the response carries a `ticker_collision` block stating the score describes the US-listed EQUITY. If the user means the CRYPTO asset pass asset_class=crypto, which 404s (no FIRM crypto model yet). NEVER present an equity score as a crypto view.

CONTRACT C2 — is the alpha signal fit to trade, and do we actually know? CALL THIS BEFORE acting on /top-picks or /score. Returns a closed-vocabulary `status` (healthy | degraded | do_not_trade | unknown), a `tradeable` boolean to branch on, `decile_convention` (10_is_best), the per-horizon live IC, and prose guidance. Fail CLOSED on anything other than `healthy` — treat it as an empty candidate list. `unknown` is a real verdict, not a placeholder: it means no BELIEVABLE current measurement exists, which carries the same instruction as red. The contract checks whether the measurement is trustworthy, not merely recent — a drift job that re-stamps a frozen input publishes today's date over old numbers, and this refuses to grade that as fresh.

OMNIBUS aggregation for one ticker — Brain's primary single-stock verdict path. Pulls BOTH the 5-layer transparency cluster AND the 7-layer smartmoney cluster in ONE call (up to 12 underlying tools in parallel inside FIRM). Replaces Brain's 24-72 HTTP-burst fan-out with a single call. Use for 'should I buy X?' / 'what do you think of Y?' / 'verdict on Z' shapes. `include_smartmoney` and `include_transparency` flags let comparison views skip clusters they don't need. Cache TTL 60s. Pass `cache_max_age_s=0` to bypass cache.

Smart-money aggregation for one ticker — collapses 7 individual tools (sec13f_changes, institutional_ownership, insider_trades, options_flow, darkpool, max_pain, gex) into ONE call. Use when Brain's verdict needs positioning context ('who's accumulating?', 'what is the options market saying?'). Saves 6 HTTP calls per verdict. Same `degraded` / `missing_layers` contract as ticker_transparency. Cache TTL 180s — positioning doesn't tick at chat cadence.

ML-transparency aggregation for one ticker — collapses 5 individual tools (ml_drivers, ml_prediction, model_calibration, voter_ic_drift, voter_coverage) into a SINGLE call. Use when Brain's verdict needs the model-transparency layer ('why is the model saying this?'). Saves 4 HTTP calls per verdict. Returns a 5-layer payload + `degraded:bool` + `missing_layers:[...]` so partial failures still produce usable output. Cache TTL 60s. Pass `cache_max_age_s=0` to bypass cache.

Today's top N picks (long or short side). CALL THIS when the user asks 'what should I buy', 'give me trade ideas', 'top picks today', 'daily briefing', or similar list-of-ideas queries. Each pick comes with the same full quant analysis as score_ticker (score, interval, voter breakdown, narrative).

Out-of-sample model performance — Sharpe, IC, conformal coverage, factor-decomp alpha. CALL THIS when the user asks 'how do I know this works', 'what's your track record', 'is this real alpha vs factor exposure'. Covers out-of-sample backtest, strict-OOS, conformal-validation and factor-decomposition metrics, refreshed weekly.

The ENTIRE scored universe in one call (limit=0 = all ~13k names), ranked, each with the model's absolute suggested_position_pct AND a relative normalized_weight that sums to ~100% across the returned set. Pass tickers=AAPL,NVDA,… to score+SIZE a specific holdings basket (the per-holding rebalance path); omit it to screen/rank the universe (limit/min_decile/side). Use normalized_weight for rebalance targets.

Per-voter IC drift breakdown — pinpoints WHICH of the 12 voters in the ensemble is decaying. The blended-IC drift tool tells you IF the ensemble is decaying; this tells you WHICH voter. CALL THIS when the user asks 'which voter is the problem?', 'why did the model decay?', 'should we re-weight?'. Critically distinguishes 'data_silent' (voter source offline → not the voter's fault) from 'real decay' (voter producing scores that no longer predict). Returns per-voter live IC, causal-marginal-ATE baseline, ic_ratio, drift severity, current weight, and operator-suggested weight delta (capped ±0.05 absolute per cycle).

Live crypto quote from the market-data feed (real-time entitlement, 439 pairs): last-trade price, 24h change/volume (UTC-day basis), day + prev-day OHLC, optional last-7 daily bars, honest as_of. PRIMARY tool for 'what is BTC at?' — accepts BTC/BTCUSD/X:BTCUSD plus a vs currency (e.g. EUR); unknown symbols return a structured 404.

The tradeable crypto universe, ranked by 24h dollar volume across the WHOLE book (~419 pairs) in one call. Stablecoins (USDT/USDC/UST...) are excluded — huge volume, no directional tradeability. Call this to get the liquid crypto candidate set instead of a hand-picked list. IMPORTANT: this is a LIQUIDITY ranking, NOT a conviction ranking — `rank` orders by tradeability, never by expected return. FIRM has no validated crypto edge, so these are candidates by tradeability only; never present `rank` as a signal.

Clusters of insider buying across companies: names where multiple distinct insiders bought around the same time. Call it when the user asks 'where are insiders buying?' or wants market-wide insider conviction rather than one company's filings.

Recent service log lines. Call when the user asks whether the system/data pipeline is healthy or why data looks missing/stale and status alone doesn't explain it.

One-call macro dashboard: VIX, DXY, treasury spreads, fear-greed, and the current regime read. Call it FIRST for any 'how is the overall market / macro backdrop?' question, or to frame a single-name view against market conditions.

ML pipeline freshness probe: has_predictions, has_weights_history, latest_as_of_ts, n_tickers. Call when the user asks whether the ML pipeline is healthy or why predictions look missing/stale.

Latest ML ensemble prediction for one ticker: blended_score, conviction, decile rank, and per-voter sub-scores. Call this when the user asks 'what does the model think of X' or wants a quantitative score to weigh against fundamentals.

Top-N ranked tickers from the latest ML ensemble scoring snapshot, optionally floored by min_conviction. PRIMARY tool for 'what are the model's top picks / best-ranked stocks right now'; use tengu_ml_predict for one ticker's detail.

Current live ML ensemble voter weights (latest history row, broken out per market regime). Call it to know how the ensemble is blending its voters before interpreting a prediction; use tengu_ml_weights_history for drift over time.

Time series of ML ensemble voter weights (per regime, newest first; days=1-365, default 30). Call this when the user asks how the model's weighting has drifted or shifted across regimes; use tengu_ml_weights for the current row.

Readiness flags showing which subsystems are up and serving. Call when the user asks whether the system/data pipeline is healthy or why data looks missing/stale.

Current market regime label plus the model's regime probabilities. Call it when the user asks 'what regime are we in?' or before positioning advice that depends on the prevailing regime; use tengu_v2_regime_forecast for the forward view and tengu_v2_regime_history for the past.

Research knowledge base

Live price snapshot for one ticker: latest price plus basic trading stats. Call it when the user asks 'where is X trading right now?' or needs a current quote before any single-name analysis. Heavy endpoint — fetch one ticker per call.

System status for the service. Call when the user asks whether the system/data pipeline is healthy or why data looks missing/stale.

Mined alpha expressions from the research pipeline, filtered to a minimum information ratio (min_ir, default 0.5) and capped at `limit` (default 25). Call this when the user asks what alpha signals or factor expressions the research engine has actually discovered.

Historical crash replay through past market crash episodes. Call it when the user asks 'how would this have held up in previous crashes?' or wants tail risk anchored to real historical events; use tengu_v2_stress for hypothetical scenarios.

Feature and prediction drift over a rolling window (default 30 days). Call it when the user asks whether the models are still well calibrated, why predictions look off, or whether model inputs have shifted recently.

IC/IR half-life per factor — how fast each factor's predictive power decays. Call it when the user asks which signals are going stale, how long a factor's edge lasts, or before weighting factors in a strategy.

Top-N feature importances for the prediction models (default top 50, optionally filtered to one model). Call it when the user asks 'what is the model actually looking at?' or which inputs are driving current predictions.

Conformal prediction intervals for one ticker's forecast: a calibrated lower/upper band at the requested miscoverage alpha (default 0.1 = 90% interval). Call it when the user asks 'how confident is the model?' or wants an uncertainty range around a prediction rather than just a point estimate.

Forecast regime probabilities N days ahead (default 21-day horizon). Call it when the user asks 'is the regime about to change?' or wants the forward market-state outlook rather than today's label — use tengu_regime for the current read.

Historical regime labels over the last N days (default 180). Call it when the user asks how long the current regime has lasted, when the last regime shift happened, or wants past behavior broken out by regime.

Discover the 39 licensed research datasets servable via the research-dataset reader — equity prices (daily/monthly/delistings/distributions/mutual funds), fundamentals (annual/quarterly/segments/customers/supply-chain), analyst estimates (summary/detail/guidance/price-targets/actuals/recs), implied volatility, securities-finance (full-history CDS + short interest), transcripts/ratings/key-developments, board relationships, forensic-audit filings, syndicated loans, ESG ratings, crowd estimates, TRACE bond trades and Fama-French factors. Call FIRST when unsure of a slug; not_ingested lists any slug awaiting a table (currently empty).

Read any licensed research dataset by slug (discover via tengu_v2_research_datasets). ?ticker= pushes an exact server-side filter down the dataset's own symbol column when it has one; datasets keyed by an internal security id instead state explicitly that ticker was ignored. The `implied_vol_by_ticker` slug REQUIRES ?ticker= and resolves the symbol to that id automatically before pushdown. The `cds_composites` slug serves the FULL 2005–2025 spread history. Unfiltered reads are capped at 5000 rows.

Short interest for one ticker: shares short, days-to-cover (DTC), and fails-to-deliver (FTD). Call it FIRST for any 'is X heavily shorted / squeeze candidate?' question or before evaluating short-side risk in a position.

Correlation matrix across the voter signals feeding the ensemble. Call it when the user asks whether the model's signals are independent or redundant — high pairwise correlation means the vote count overstates conviction.

Strategy genealogy with out-of-sample (OOS) scores — how each evolved strategy variant descends from its parents and how it validated OOS, up to `limit` entries (default 50). Call this when the user asks how strategies were developed, mutated, or which generations survived validation.

Stress-test scenarios from the risk engine. Call it when the user asks 'what happens if things go bad?' before sizing risk; use tengu_v2_crash_scenarios to replay specific historical crashes.

Portfolio VaR and CVaR at a chosen horizon and confidence (defaults: 1-day, 99%). Call it when the user asks 'how much could the portfolio lose?' or needs a tail-risk number before sizing or hedging decisions.

Forensic accounting red flags with plain-language reasons, from the forensic-audit dataset: fraud/SEC-investigation/adverse restatements, auditor resignations, going-concern or disagreement auditor changes, auditor churn, audit-fee swings >50% yoy, and non-audit-fee dominance (independence risk). Each flag carries severity + reason with the evidence rows attached. Call it before trusting reported financials on any name with earnings-quality doubts (e.g. SMCI returns the 2024 EY-resignation cluster); an empty flags list on a covered name is a genuinely clean record.

Realised-vs-predicted accuracy over a rolling window (window_days, default 90) — how well predictions matched what actually happened. Call this when the user asks how accurate the system has been or wants a track record before trusting a new call; use prediction_tracker for individual predictions.

Recent outputs from a named agent

Latest heartbeat + stats for one agent

Catalogue of every agent in the swarm — one entry per agent. Call this when the user asks which agents exist, what the swarm is composed of, or to resolve an agent's name before drilling into its output.

Currently-active alerts

Per-feed external API quota usage and cap status (news, news-analytics, market-data, alt-data). Call when the user asks whether the system/data pipeline is healthy or why data looks missing/stale.