io.github.Hlobo-dev/tengu-firm

SSE stream of freshness-labelled market events. Every record carries source as-of time, feed lag and staleness so old data cannot masquerade as a new breach.

SSE stream of structured-news items

News publisher status: polls completed, articles seen/published, dedup hits, newswire availability. Call when the user asks why news looks missing/stale or whether the pipeline is healthy.

SSE stream of live per-venue bid/ask quote events for the requested symbols (bid/ask price+size + per-side venue IDs). Connecting auto-subscribes coverage within ~5s. Quiet outside US market hours — that is correct, not broken. Sizes are the venue's numbers untransformed; never present them as share counts.

Agent protocol for real-time queries: which SSE feed maps to which intent (live price, signals, decisions, news, alerts), payload shapes, when to prefer SSE over REST, and fallback rules when flags are off

Effective signal-generator status across the optional in-process worker and dedicated processor heartbeat: input ticks, emitted signals and deployment state. Call when live signals look missing/stale.

SSE stream of fused signals

Bounded Redis reachability plus expiring market-producer and signal-pipeline heartbeats, per-capability readiness, coverage modes/limits and known SSE endpoints. Call before claiming live data or diagnosing missing/stale feeds.

Tick writer (tick-persistence buffer) status: buffered rows, batches written, last flush duration. Call when the user asks whether the pipeline is healthy or why stored tick data looks missing.

SSE stream of live US-equity trades. A filtered connect queues cross-process T+Q coverage; the dedicated producer reconciles it asynchronously (target ~5s).

Legacy in-process UniverseManager diagnostics for dev. For production cross-process warm coverage use tengu_v3_market_universe and tengu_v3_stream_status.

GEOGRAPHIC REVENUE EXPOSURE for one company — where the revenue actually comes from, estimated region by region and country by country for a fiscal period, with a per-row confidence score. This is the tariff / geopolitical lens: it answers 'how much of this company's revenue is China?' for names that never break that out. Returns the requested hierarchy layer as `regions`, the country leaves as `countries`, concentration metrics (largest country share and an HHI), the period served and the other periods available. ?country=CN,TW returns a per-period HISTORY for exactly those countries. Each layer sums to 100 on its own, so never add a region to a country. Amounts carry NO currency code in the source and the reporting currency can change between periods, so compare on PERCENT, not amount. Estimates, not company-reported segments — for reported segments use /fundamentals/segments/{ticker}.

The SUPPLY-CHAIN GRAPH around one company — its customers, suppliers, competitors and partners in one call, each with the relationship's start date, whether it is still open, which side reported it, and revenue dependence where it was estimated. Both directions are merged and normalised to the queried company's point of view, so 'customers' includes companies that report THIS company as their supplier. Call it to map second-order exposure (whose earnings move when this name moves) or to find the listed suppliers behind a product cycle. Defaults to CURRENT relationships; status=all or as_of=YYYY-MM-DD gives history. One entry per counterparty by default (several records can back one pair) — group_by=record gives the underlying versions. revenue_percent belongs to the company named in revenue_percent_of_ticker, is an ESTIMATE on every row, and is present on only a minority of edges; coverage is reported per group.

REVENUE DEPENDENCE, both sides — the revenue-at-risk map around one company. `customer_concentration`: how much of THIS company's revenue each customer accounts for. `dependents_on_company`: other companies whose revenue depends on THIS one (e.g. a component maker that books most of its revenue from one handset vendor) — the list that reprices when this name changes its orders, and it is in no filing screen. Percentages are of the DEPENDENT company's revenue and every row names whose revenue it is, so the number can never be read backwards. Coverage is sparse and disclosed: only a minority of relationships carry an estimated percentage, so absence means UNKNOWN, never zero.

Aggregate system health with per-subsystem status. Call when the user asks whether the system/data pipeline is healthy or why data looks missing/stale.

Intraday minute bars for one equity from FIRM's own market-data capture (~10.5k tickers, extended hours included). Use when an agent needs REAL intraday price/volume history — how a ticker traded through an event, VWAP context, or a finer-grained chart than daily bars. Archive begins 2026-05-10; pass date=YYYY-MM-DD (or start+end, max 5 trading days). 1m is the native grain; 5m/15m/1h are resampled server-side.

Raw CME futures trade prints for one root (NG, CL, ES...) and one day, from FIRM's own capture: per-print price, size, notional, block flag across contract months. Call it for real futures flow: energy tape, rolls, block prints. date mandatory; archive from 2026-05-13, mostly CME energy (NG heavy) — empty = not-yet-captured, not quiet.

Futures term structure for one CME root (27 roots incl. ES, NQ, CL, NG, GC, ZN) from FIRM's daily chain snapshots — per contract month: last/settlement, bid/ask, session OHLC, volume, open interest, days-to-expiry. Call it for curve shape (contango/backwardation), roll, or OI distribution; omit date for latest, snapshots begin 2026-05-18.

Intraday minute bars for the major index tapes — SPX, NDX, DJI, RUT, VIX — from FIRM's own market-data indices capture. Use for intraday market/vol context around an event (how did SPX and VIX move through the FOMC statement?) or as the benchmark leg next to tengu_v3_tape_bars. Archive begins 2026-05-14; one day or max 5 trading days per call.

60s microstructure windows per ticker from FIRM's live tape: rolling vwap, trade count/avg size, block count/vol, buy/sell imbalance, large-trade premium. Call it to separate smart-money accumulation from retail moves. Active-set coverage (~few hundred names/session; empty = uncaptured); omit date for latest, capture from 2026-05-13.

Raw options trade prints for one underlying on one trading day from FIRM's own market-data capture — per-print premium (notional_usd), strike, expiry, block/sweep flags, sorted largest premium first. Use when an agent needs the actual options tape behind a flow signal: whale prints, sweep activity, what struck around a specific time. Archive begins 2026-05-11; date is mandatory (70 GB day-partitioned table).

Full historical OPTIONS CHAIN for one underlying on one snapshot day from FIRM's own daily market-data capture — per contract: strike, expiry, dte, bid/ask/mid/last, day volume + VWAP, implied volatility, the full greeks (delta/gamma/theta/vega), open interest and underlying price, plus a chain summary (contract/expiration counts, put/call OI + volume ratios, front-month ATM IV). Use it to reconstruct the IV surface, greeks or OI distribution AS IT STOOD on a past day, find where OI/volume concentrated, or pull the near-the-money strikes around an event. Omit date for the latest captured day (reported as snapshot_day); filter by side, expiration/dte, min OI/volume or a moneyness band; sort by open interest or dollar notional. Capture begins 2026-05-10. For the raw options TRADE tape use tengu_v3_tape_options; for live GEX/dealer flow use the options_flow tools.

Currently-active decision thresholds — the live cutoff values gating automated trade decisions right now. Call it to know which thresholds are in force before interpreting why a signal did or didn't become a decision.

Top trade setups from the decision engine with **defensive-alternates baked in**. When the screen is one-sided (>=70% same direction across 3+ picks), the response carries `universe_skew` = 'bearish' | 'bullish' | 'mixed' AND a `regime_warranted_alternative` block containing the editorial fallback basket (defensive | cash_heavy | value_tilt | momentum). Each alternative carries strategy label, curated candidates with thesis per name, and a one-sentence rationale. Brain consumes the alternative when the primary picks don't fit the user's risk frame — e.g. all-bearish screen on a long-bias capital-allocation query surfaces the `defensive` basket so the model never has to refuse or invent. Schema is ADDITIVE — primary `setups` array unchanged from v2.41.

Full earnings-call transcript as ordered speaker turns — use when the user wants what management or analysts actually SAID on a call. ``event_id`` comes from /api/v3/transcripts/{ticker} or /transcripts/search. Each turn carries speaker name + role (executive/analyst/operator) and section (presentation vs qa). ~2 MB text cap (``truncated: true`` when hit — refetch with components= to slice). Text coverage 2020-2025.

List a company's earnings calls and investor-event transcripts (licensed institutional, 1.75M calls), newest first — call this FIRST to get the ``event_id`` you pass to the full-text route. One row per call (versions collapsed to the best copy: Proofed > Edited > Spellchecked) with date, title and event type. Full text coverage is 2020-2025; older calls are metadata-only.

Search earnings-call transcripts. scope=headlines (default) searches call titles across ALL companies; scope=text searches the spoken words inside one company's transcripts (ticker REQUIRED) and returns per-call hit counts + a snippet. Use when the user asks 'which calls mention X' — then fetch the full text with the returned event_id.

TWAP child-order schedule for a ticker: a qty (default 100) sliced into evenly-timed child orders over `minutes` (default 60). Call this when the user asks how to work an order over time; use vwap_plan for a volume-curve schedule and cost_estimate for expected cost.

Ultimate-engine aggregate decision for one ticker — the top-level verdict aggregated across the engine stack. PRIMARY tool for 'so what's the final call on <ticker>?' — call it when the user wants one consolidated decision rather than raw component signals.

Latest universe-scanner output: the most recent scan results across the tradable universe, up to `limit` names (default 100). Call this when the user asks what the scanner is flagging right now or wants a market-wide sweep before drilling into single tickers.

Lifetime count of registered trials — the N used for DSR deflation. Call it to know how heavy the multiple-testing burden is before interpreting any deflated Sharpe, or when the user asks how many strategy variants have been tried.

Recent trials recorded in the DSR registry (limit param, default 100). Call it when the user asks what backtests or experiments have been run, or to audit the multiple-testing history behind a deflated Sharpe.

VWAP child-order schedule for a ticker: a qty (default 100) sliced along the intraday U-curve volume profile. Call this when the user wants an order worked in line with typical intraday volume; use twap_plan for even time-slicing and cost_estimate for expected cost.

CROSS-SECTIONAL LAYOFF SCREEN — which listed companies filed WARN-Act layoff notices in the last N days, ranked by employees noticed. One row per ticker (company, filing count, employees noticed, first/latest event date, states touched, largest single filing) across the whole listed universe. Call it for 'who is cutting right now' — notices are filed weeks before the cut, so this surfaces restructurings before the press release. Only employers matched to a listed symbol appear; most WARN filers are private and are excluded by design. For one company's filings use /workforce/layoffs/{ticker}.

WARN-Act LAYOFF FILINGS for one company — the public notices an employer must file WEEKS BEFORE a cut, so they lead the press release and the next earnings call. Returns each filing (notice date, effective date, employees affected, site city/state, layoff type) newest first, plus TRUE window totals, a month-by-month series and the largest single filing; with_workforce also sizes the total against estimated headcount and names the headcount month used. Call it as a downside early-warning, or to confirm the scale of an announced restructuring — filings are SITE-level, so one restructuring appears as many rows. Coverage is US WARN notices from 1989 forward including forward-dated notices; only employers matched to a listed symbol are reachable by ticker, so an empty result is not proof there were no layoffs.

Monthly EMPLOYMENT MOMENTUM for one company — headcount trend, hiring vs attrition and salary level, from a monthly workforce panel rather than an annual filing. Returns the latest month's headcount with its hiring, attrition and net-hiring rates (percent of headcount per month plus annualized twins), 1m/3m/12m headcount growth, average salary per employee (USD per year) with its coverage, and the full monthly series. Call it to see a company expanding or shrinking MONTHS before the next 10-K, or to catch attrition rising while headcount looks flat. Values are modelled estimates, not company-reported figures. The panel is being backfilled: `coverage` reports the months actually present and any lookback the panel cannot support returns null with a reason — never an interpolated number. Ticker is not unique across venues; the response names the entity served and lists alternates you can pin with employer_id.

CROSS-SECTIONAL HIRING SCREEN — rank listed employers by headcount growth between the panel's latest month and N months earlier: ticker, company, headcount then and now, percent and absolute change, latest hiring and attrition rates and average salary, sorted fastest-growing or fastest-shrinking. This is the workforce factor as a screen — who is actually staffing up (or quietly shrinking) months before it reaches a filing. The monthly panel is MID-BACKFILL, so a months_back longer than the loaded window returns an explicit warning listing the lookbacks that ARE available — never a silently shortened comparison.