io.github.Hlobo-dev/tengu-firm

Options-chain snapshot for a ticker: every contract with Greeks (delta/gamma/theta/vega), implied volatility, open interest, last quote/trade; filter by expiry or call/put side. PRIMARY tool for 'where's the gamma / IV smile / max pain by strike'. Pair with options_volume (flow) and gex (dealer positioning). 60s cache.

Recent unusual options-flow alerts across the whole market from the options-flow feed, filtered to trades above min_premium (default $50k). Call this when the user asks 'what is the smart money buying today?' or wants market-wide unusual options activity; use tengu_v3_intel_options_flow_ticker for a single name.

Historical options-flow aggregates for one ticker — the ~60s warehouse capture behind the live /intel/options_flow tool. Call when you need how flow EVOLVED (e.g. 'was NVDA flow bullish before the earnings pop?') rather than the current snapshot. Rows: as_of_ts, polarity (-1..1 net bullish/bearish score), n_alerts, premium_total (USD) + a window summary (total premium, avg polarity, bullish/bearish snapshot counts). REQUIRES date OR start(+end), max 7 days per request (422 otherwise); warehouse coverage begins 2026-05-10. 5-min cache.

Unusual options-flow alerts for one ticker from the options-flow feed (default 25). Call this when the user asks 'any unusual options activity in X?' or wants the large options bets hitting a specific name; use tengu_v3_intel_options_flow for the cross-market view.

Daily options volume and put/call ratio per day for one ticker from the options-flow feed (default 30 days). Call this when the user asks whether options activity or put/call skew is elevated versus recent days, or how bullish/bearish the options tape has been trending.

Issued USPTO patents tagged to one ticker — date, title, IPC class, claim count, and abstract for each (default 25). Call this when the user asks what a company is patenting or wants an innovation-velocity read on its R&D pipeline.

Daily PnL track record for the paper book, Carhart 4-factor-decomposed. Snapshotted nightly. Returns `rows[]` of trading days with per-row gross/net return in basis points, transaction cost, turnover, plus the Carhart factor contributions (MKT-RF, SMB, HML, UMD) and residual alpha — the institutional skill measure that strips market/size/value/momentum beta. Window aggregate: mean daily bps, hit rate, annualised Sharpe, cumulative net + alpha. Default 30 trading days; query `?days=N` (bounded to 365). Use this to ground any track-record claim the chat makes — e.g. 'our paper book made +29 bps yesterday, +111 bps alpha contribution'. 1h cache.

Full US Congress roster (House + Senate, alternative-data) with disclosed trade counts per member. Call it to resolve a politician name to a BioGuideID before pulling their trades, or for 'most-active disclosed traders in Congress' lists. Heavy full-roster pull.

Current US T-bill yields + parked-cash quick-reference. Use this for capital-allocation responses — the model needs to compare risky vs risk-free expected return ('T-bills currently yield X% — the equity allocation must clear that hurdle'). Returns 1m/3m/2y/10y yields, `parked_yield_example` showing annual coupon on $10k principal across tenors, and curated T-bill ETF references (SGOV, BIL, SHV) with expense ratios + use-case so the model has something specific to cite. Sourced from FRED. 5-min cache.

Recent 13F position snapshots (alternative-data, cross-fund/cross-ticker, last ~10k rows): fund, ticker, shares, value_usd, report_period — the institutional-ownership signal. Call this when the user asks 'which funds hold X?' or 'what does fund Y own?'; filter by ticker and/or fund (substring match).

Quarter-over-quarter 13F position deltas (alternative-data), sign preserved: positive = added, negative = trimmed. Call this when the user asks 'are institutions adding or dumping X?'; set min_pct (absolute change fraction, e.g. 0.5 = 50%) to drop noise.

Institutional-holder history — a holder × quarter matrix of 13F positions (shares per quarter-end + latest value) from the institutional-holdings 13F archive. Call it to track when funds built or exited a stock across quarters; for only the latest snapshot use /intel/sec13f.

FINRA bi-monthly short interest: short_interest_shares, short_interest_pct_of_float, days_to_cover, short_interest_change_pct_30d (vs prior settlement), avg_daily_volume_at_settlement. Call for 'how shorted is X?' / squeeze questions. borrow_fee_pct_annualized is null — see /intel/borrow_cost. Market-data FINRA re-publish; 6h cache.

Deep short-selling history — daily off-exchange short-volume series (short vs total shares across FINRA venues + short ratio, back to 2006) plus the official bi-monthly short-interest series from the securities-finance/licensed-research archive. Call it for multi-year squeeze setups or shorting pressure around events; for today's borrow cost use /intel/short_interest.

Street consensus EPS + options-implied expected move per earnings event, with beat_rate_pct and 8-quarter surprise history (est vs actual vs surprise_pct). Call this for 'what does the Street expect?' or 'how big a move is priced in?'. report_date_basis 'estimation' = projected date, NOT confirmed — cross-check tengu_v3_earnings_next.

Management guidance history — every company-issued guidance range (measure, period, low/high, announce date, street consensus at that date) from the analyst-estimate Guidance archive. Call it to compare what management promised vs what the street expected, or to study guidance-cut reactions.

Analyst-level estimate revision timeline — every individual broker estimate (announce/revision dates, analyst id, fiscal period, value, realised actual) from the analyst-estimate detail archive back to 1980. Call it to reconstruct how the street walked numbers up or down before a print; for the consensus snapshot use /intel/street_estimates.

Top institutional / fund / insider shareholders for a ticker (alternative-data), as two lists — ownership (shares) and ownership_options (contracts) — because options exposure reads differently from equity holdings. Call this when the user asks 'who owns X?' or wants the largest holders.

How much institutional-ownership history has actually landed — per quarter: rows, securities and distinct holders held right now, plus a flag on any quarter still loading. Call it BEFORE treating a quarter-on-quarter change as a real position change: during a backfill a newly-opened quarter is incomplete, and a naive comparison makes every name look like it lost most of its holders. Pass a ticker for per-company coverage.

CURRENT INSTITUTIONAL HOLDERS of a company, largest first — holder-level positions with shares, market value (USD), percent of shares outstanding (percent, 0-100) and the change against the prior report, so new, increased, decreased and exited positions are visible. This is the FRESH ownership view; /intel/top_shareholders and /intel/sec13f serve the older archive. The archive is being backfilled, so the response lists every quarter it actually holds with its holder count, defaults to the most COMPLETE quarter and flags any quarter still loading rather than serving a half-loaded snapshot as fact. A 'new_position' can also be a renamed or re-coded holder entity, which the response says explicitly.

Daily Twitter mention volume and follower count for one ticker from the alternative-data feed (default 60 days). Call this when the user asks how much social buzz a name has or whether attention is spiking; pair with tengu_v3_intel_wsb for the r/wallstreetbets read.

standardized implied-vol SURFACE for a company, joined from a plain equity ticker (resolves the symbol to the surface's internal id via the link table). Returns the standardized surface grid: for each maturity (days = 30/60/91/182/365) and delta node, per call/put the interpolated implied volatility and its dispersion — the clean vol skew + term structure behind risk-reversals, butterflies and the ATM vol term structure. Use to read a name's vol smile or how implied vol changes across expiries. Omit date for the latest-available surface (lagged academic archive — currently the 2011 slice, 3,956 names); pass date=YYYY-MM-DD for a specific session and days= to pin one maturity. Standardized grid, NOT the raw chain — for live per-contract quotes use /intel/options_chain.

Causal attribution for a voter's score on a ticker. Instrumented voters: `insider_flow` (EDGAR Form-4 + insider feed, deduped by name/date/value; CEO/CFO 2x, officer 1.5x, director 1.2x weighting; contribution amounts + reconstructed score); `options_flow` (options-flow alerts with direction inferred from option_type+side: CALL@ASK=+1, PUT@ASK=-1, CALL@BID=-1, PUT@BID=+1; weighted by premium/median); `fundamental` (metadata mode — surfaces which 4 ratios the voter consumes + how to interpret). Transforms scores into EVIDENCE rather than a number. Remaining voters (sentiment, analyst_revisions, regime_hmm, technical, ml_ensemble) pending instrumentation. Optional ?voter=insider_flow|options_flow|fundamental, ?days_back=30. 15min cache.

Per-ticker accounting for every voter in the 19-voter ensemble. For each voter returns the current score, baseline weight, status (firing | silent_data | shadow | no_signal), and a human-readable `why` explaining each silent voter's upstream data source so an operator can chase the gap. The `coverage_summary` block reports `weight_firing` (effective ensemble weight in use) vs `weight_silent_live` (paid-for but silent). Use this when a model_prediction shows low voter_coverage — it tells you exactly which data pipelines to wake up. 5min cache.

Per-voter information-coefficient drift vs baseline for all 19 voters, recomputed daily: live_ic vs baseline_ic, ic_ratio (sign-flip flagged at <0), drift_status (green/yellow/red), sorted by absolute drift severity. Call it before leaning on a verdict — reduce confidence in any voter with red drift_status. 60min cache.

Daily r/wallstreetbets mention count and sentiment for one ticker from the alternative-data feed (default 60 days). Call this when the user asks whether retail is piling into a name or how retail buzz is trending; pair with tengu_v3_intel_twitter for the Twitter-side social read.

Live US Treasury yield curve + recession-watch spreads + breakeven inflation. Returns DGS1MO/3MO/2/5/10/30 yields, the 10Y-2Y and 10Y-3M spreads (with 'inverted' flags — classic recession signal), 5Y/10Y breakeven inflation, and the trade-weighted USD index. Quote these numbers verbatim — DO NOT recall yields from training data, which is months stale. 5-min cache. For a focused short-end + cash-park view, use tengu_v3_intel_risk_free_rate.

Uncertainty-discounted Kelly fraction for one ticker — the bet size after haircutting full Kelly for estimation error. Call this when the user asks 'how much should I bet on X?' or to know how large a position the evidence actually supports before sizing a trade.

Live lab deployments (paper/tiny-cap)

Strategies in the sandbox lab

Live US Treasury yield curve (market-data feed, T+1): 1m-30y tenor points, per-tenor 1-day change (bps), computed 2s10s and 3m10y spreads with inversion flags. Call this when the user asks about rates, curve shape, or inversion. Honest as_of = the feed's record date.

Finite catch-up page for retained market events after a Redis stream id; use after reconnect and preserve each event's source freshness fields.

Cross-process shared warm-set catalog plus the dedicated US-equity producer heartbeat, research-universe count, capacity and effective readiness. Warm means requested, not provider-confirmed.

Recall memory items by free-text query

Post-trade reflections journal

Recent system metrics (latency/QPS/error)

MARKET-WIDE feed — not per-ticker (that is tengu_v3_news_summary). Aggregated cross-source news stream over the last N hours (default 24) for broad market-news sweeps and cross-source coverage checks.

Headline-only alert stream — lighter and faster than full news items; category=general for market-wide or category=ticker with tickers for specific names. Call this when the user wants breaking headlines or the very latest on a name and speed matters more than article bodies.

Sentiment leaderboard across the full tracked ticker universe over a date_range (default last7days), paginated. Call this when the user asks which stocks have the most positive or negative news sentiment right now — a screening pass before single-name digs.

Topic-filtered headlines (earnings, analysts, dividend, mergers, acquisition, ipo, fda, guidance, stock_buyback, insider, lawsuit, esg, crypto, and more), optionally per ticker, over a date_range (default last7days, 50 items). Call it when the user asks about a specific event type — 'any FDA news?', 'recent M&A headlines'.

Category-scoped news feed: section=general for market-wide or alltickers for company-tagged stories, filterable by topic, sector, industry, and source. Call this when the user wants themed or sector-level news rather than coverage of a specific ticker.

Sentiment leaderboard across the full tracked crypto universe — every coin's sentiment_score over the window (default last7days). Call this when the user asks which coins have the most bullish or most bearish news sentiment right now.

Crypto news by section: section='general' for overall crypto-market headlines, section='alltickers' for cross-coin coverage. PRIMARY tool for broad 'what's happening in crypto today' questions — for a single coin use news_crypto_latest instead. 120s cache.

Clustered crypto headline events — related stories grouped into discrete events; fetch recent events, filter by ticker, or drill into one eventid. Call this when the user asks what distinct news events hit a coin rather than a raw headline list.

Recent crypto news with sentiment for one or more symbols: title, source, sentiment (Positive/Neutral/Negative), date, topic tags. PRIMARY tool for ticker-specific crypto drilling (BTC, ETH, SOL, COIN, MSTR) — call when the user asks what's happening with a specific coin; use by_category for market-wide questions. 60s cache.

Overall crypto market sentiment rollup across the news feed (no ticker filter). Call this when the user asks whether crypto as a whole looks bullish or bearish right now — for a specific coin's sentiment use news_crypto_latest. 300s cache.

Crypto news where ALL the listed coins co-appear in the same story — a correlation feed. Call this when the user asks how two or more coins are linked in the news, e.g. stories covering both BTC and ETH together.

crypto-news: daily sentiment rollup for a crypto symbol (-1.5 to +1.5). Densest single-call signal — N days of (positive_count, negative_count, neutral_count, sentiment_score). Use to detect sentiment regime shifts on BTC/ETH/etc. 300s cache.

crypto-news: one-shot per-coin intel summary. Parallel-fetches recent news (24h) + 7-day sentiment stats + trending headlines. The single call to make when asked 'what's going on with BTC?' or any crypto-name analysis. 90s cache.

Evening crypto market-recap digest, published Mon-Fri at 7pm ET. Call this when the user asks for an end-of-day crypto wrap-up or a morning briefing needs an overnight crypto recap.