io.github.Hlobo-dev/tengu-firm

Fuzzy company lookup — resolves a free-text name or partial ticker to matching companies (default 10). Call it FIRST when the user names a company without a ticker, before firing any ticker-keyed fundamentals tool.

SEC filings list for a ticker — 10-K, 10-Q, 8-K, S-1 and more, with an optional form_type filter (default limit 20). Call this when the user asks what a company has filed or wants to locate a specific filing type.

Business + geographic SEGMENT breakdown for one company — decomposes a fiscal period into reportable segments by line of business, geography, ASC-280 operating segment and US state, each with sales, revenue, operating income and SIC, grouped by segment type. Call it to see WHERE a company earns: revenue mix by region (e.g. Greater China share) or which line of business carries the margin. Internally keyed (the ticker is resolved via the point-in-time name master, most-recent row); the archive lags, so with no year/date it returns the LATEST available period and reports the datadate served. Values are in the reported currency, fundamentals's millions convention.

Paged listing of the full covered ticker universe, filterable to S&P 500 membership or one sector (limit/page paging). Call it when the user wants all the stocks in a sector or an index-membership list to feed a screen.

One XBRL concept's as-reported history — period, value, fiscal year/period, SEC form, accession, filed date — from the in-house SEC EDGAR companyfacts corpus. Call it for exact as-filed fundamentals: as_of= for point-in-time (no restatement look-ahead), history=true for all restatements; find tags via /fundamentals/companyfacts.

Which mutual funds hold a stock — each fund's percent_tna, shares and market value, largest first, plus report_dt and n_funds, from the survivor-bias-free holdings archive (coverage 2002-2021; no date = latest lagged quarter-end). Call it for mutual-fund demand base or holder concentration; for 13F institutional holders use /intel/sec13f.

One-call corporate-governance dossier: board size + composition (independent vs executive directors, current members, from board-relationship), director interlocks with other boards, restatement record, auditor-change history, and the latest year's executive compensation (CEO/CFO and top-5 named officers, from executive-compensation). Call it for any management-quality, board-oversight or comp question; blocks degrade independently. For graded forensic red flags use /api/v3/intel/accounting_flags.

Index hedge proposals (SPY/QQQ/IWM) computed from live dealer positioning — protective puts when dealers are short gamma and IV rank is cheap, collars when the 25-delta risk reversal shows calls rich, plus IV term-structure context

Analyst consensus: rating_label (Strong Buy…Strong Sell), rating_score (1-5), bucket counts, price_target_avg/high/low/count, recent_actions[] (upgrades/downgrades/PT changes, firm+analyst+from→to; recent_action_limit). Call for 'what do analysts say about X?' / price targets. Actions from newswire (client-side ticker filter). 1h cache.

Securities-lending borrow cost (annualized fee %, rebate, utilization, shares available) — LIVE. Source chain, first hit wins (see `source`): 1) options-flow shorts feed (intraday) + recent SEC fails-to-deliver enrichment; 2) licensed-research securities-finance Securities Finance latest archived daily row; 3) implied-vol option-implied borrow. `is_stale` flags prints older than 48h (warehouse rows trail on the licensed-research refresh lag). data_source_pending=true ONLY when all three sources miss — then fall back to /intel/short_interest as the squeeze proxy. Use /intel/borrow_cost_history for the daily series. 15-min cache.

Daily securities-lending borrow-cost HISTORY for one ticker from the licensed-research warehouse (default: last 90 days of coverage; max 365-day window). Primary source securities-finance Securities Finance (~50M rows 2010->latest licensed-research drop): annualized fee_pct / rebate_pct, utilization_pct and on-loan/lendable share quantities — the institutional squeeze-watch series (rising fee + utilization = tightening borrow). Falls back to implied-vol option-implied borrow (shortest tenor per day) when securities-finance lacks the name. licensed-research refreshes on a lag — check as_of before treating the newest row as current; use /intel/borrow_cost for the live snapshot. 1h cache.

newswire: upcoming earnings conference-call schedule. Returns ticker, company, date, start_time, period (Q1/Q2/...), webcast_url, phone_num, international_num, access_code, and importance (5 = mega-cap market-mover). Distinct from /calendar/earnings — this carries the call logistics analysts need to attend.

Macro economic-release calendar from the newswire — CPI, NFP, FOMC, GDP, retail sales and more, filterable by ISO-3 country (USA, CAN, DEU) and date range; importance 5 = market-moving. Call this when the user asks what macro events or data releases are coming up or could move markets this week.

Analyst rating actions and price-target changes from the newswire: analyst_firm, analyst_name, action_company (Maintains/Initiates), action_pt (Raises/Lowers), pt_current, pt_prior, pt_pct_change, rating_current/prior. Call this when the user asks about upgrades, downgrades, or price-target moves on a ticker.

CFTC Commitments-of-Traders report — futures positioning by cohort (producers/hedgers, money managers, other reportables, non-reportables). Polled weekly on Fridays at 18:00 ET, the CFTC's standard publication window. Without filter: returns top-10 money-manager longs and shorts across all contracts on the latest report — the institutional-spec directional bets. With `?contract=GOLD` (substring match, also accepts WTI, NATGAS, SP500-EMINI, BITCOIN-MICRO, 10Y-NOTE, etc.) returns the matched contract's 5-week positioning history with cohort net positions, % of OI, and a 4-week net delta. Extreme money-manager longs at the top of a rally historically mark exhaustion; commercial-hedger net longs at the bottom historically mark reaccumulation — leading indicator. 4h cache (CFTC publishes weekly so the data is stale-by-design).

Candlestick chart with optional RSI/MACD/Bollinger overlays — returns a base64 PNG in a standard image envelope plus an OHLCV summary block (interval minute|hour|day|week|month, default day; 120 bars). Call this when the user asks to see a chart; powers chart-emitting skills (TA Master, Trading Plan, Apex Equity Intel).

REAL-TIME spot prices for the macro commodities (oil WTI/Brent, gold, silver, nat-gas, copper). AUTHORITATIVE source for any numeric commodity claim — call this BEFORE quoting a price level. QUOTE 'spot' DIRECTLY — it's the live commodity price (FRED's last published close anchored to the live commodity-tracking ETF's cumulative return since that date, so it reflects today's market not FRED's T+1..T+5 publish lag). 'unit' tells you the dimension (USD/barrel for oil, USD/MMBtu for natgas, USD/metric-ton for copper). Response fields per item: 'spot' (live number — quote this), 'unit' (dimension), 'spot_basis' ('live_etf_bridged' = FRED+ETF bridge | 'fred_close' = FRED only, no ETF available | 'etf_share_price' = FRED dead, falling back to ETF SHARE price [unit reads 'USD per share of {ETF}'] — DO NOT claim $/oz when basis is etf_share_price), 'spot_time' (timestamp of the live observation), 'live_spot_estimate' (same as spot when bridged, else null), 'live_basis' (transparent arithmetic, e.g. 'FRED WTI $99.89 (2026-04-27) × (USO 142.80 / 134.72)'), 'bridge_return_pct' (ETF return applied to FRED), 'official_close' + 'official_close_as_of' (FRED audit value — quote ONLY if user explicitly asks for the last settlement / closing price), 'change_pct_1d/5d/30d' (FRED-window returns), 'history_5d' (last 6 FRED observations newest-first), 'fred_days_stale' + 'is_stale' (publish-lag flags — informational; spot is still live regardless), 'etf_proxy_quote' (the underlying ETF snapshot used for the bridge; for transparency only). 'symbol=oil' returns both WTI and Brent; default 'all' returns all six.

Congressional stock trades from two coverage sources — a realtime cross-ticker feed (provider=options_flow, default) or a bulk alternative-data feed (provider=alternative_data) — with an optional ticker filter. Call this when the user asks what Congress members have been buying or selling, market-wide or in a specific name.

Corporate-PAC donations linked to the ticker's parent company (alternative-data): candidate, committee, amount, transaction_date, cycle — a campaign-finance influence signal. Call this when the user asks who a company donates to or about its political exposure.

Historical dark-pool (off-exchange) prints for one ticker — the per-print warehouse capture behind the live /intel/darkpool tool. Call to find WHEN large blocks hit and whether they printed at bid/mid/ask. Each row is an individual execution: executed_at, price, size, premium (USD), market center + the NBBO at print time; newest first, plus total premium/size summary. REQUIRES date OR start(+end), max 7 days per request (422 otherwise); coverage begins 2026-05-10. 5-min cache.

Most recent dark-pool prints across all tickers from the options-flow feed (default 50). Call this when the user asks about market-wide dark-pool or block activity — 'any big dark-pool prints today?'; use tengu_v3_intel_darkpool_ticker for a single name.

Dark-pool prints for one ticker from the options-flow feed (default 50). Call this when the user asks whether large blocks are crossing off-exchange in a specific name; use tengu_v3_intel_off_exchange for daily aggregate off-exchange volume instead of individual prints.

Last N quarters of earnings for a ticker — report date, EPS estimate vs actual, surprise %, and the day-of-report intraday price move %. Used by the verdict prompt to anchor 'stock typically moves ±X% on earnings' claims in real numbers. Composite (newswire + market-data). 6h cache.

alternative-data: ETF composition or inverse-lookup. Pass ?etf=SPY for full holdings of an ETF, OR ?ticker=NVDA for every ETF that holds the stock (with weight). At least one is required; when both are passed, etf takes precedence.

One-call ETF intelligence rollup — top holdings + commodity exposure + which other v3 tools work for this ticker. Returns top constituents by weight (holdings provider), and for commodity-tracking ETFs (USO/BNO/GLD/IAU/SGOL/SLV/SIVR/UNG/BOIL/CPER) the linked FRED spot + live proxy price. CALL THIS BEFORE saying 'no data' on any ETF question — most ETFs have rich underlying-level intel even when the wrapper itself doesn't trade analyst targets / insider flow.

Annual executive compensation history for a ticker (alternative-data): CEO + named officers with name, role, year, salary, bonus, stock_option_awards, total_compensation. Call this when the user asks 'how much is the CEO paid?' or wants pay-vs-performance context.

What drives the model: Fama-French 5-factor loadings showing which systematic factors explain the strategy's returns, plus the ensemble's Bayesian voter posteriors ranking which signals it trusts most (top_n, default 50). PRIMARY tool for 'why does the model like this?' and 'what is the strategy actually betting on?' questions.

Aggregate gamma exposure (GEX) and delta exposure for one ticker from the options-flow feed. Call this when the user asks about dealer positioning or gamma levels, or whether options exposure could dampen or amplify moves in a name; pair with tengu_v3_intel_max_pain for expiry pin levels.

Historical dealer gamma-exposure (GEX) for one ticker — daily per-strike snapshots behind the live /intel/gex tool. Call for 'how did dealer positioning shift into OPEX / earnings?'. Default returns ONE ROW PER TRADING DAY (call/put/net GEX totals, strike count, max-gamma strike); pass per_strike=true for the full strike ladder (gamma/charm/vanna + call/put GEX per strike). REQUIRES date OR start(+end), max 30 days per request (422 otherwise); coverage begins 2026-05-10. 10-min cache.

Federal government contracts awarded to one ticker's company from the alternative-data feed (limit, default 50). Call this when the user asks how much government business a company wins or whether contract awards are accelerating; pair with tengu_v3_intel_lobbying for the lobbying-spend side.

Quarterly cross-ticker federal-contracts feed (alternative-data) — top-line award totals only, lighter than per-ticker tengu_v3_intel_gov_contracts (no agency or description fields). Call this for 'which companies win government money?' screens; use tengu_v3_intel_gov_contracts for line-items.

INSIDER TRANSACTIONS SPLIT BY WHETHER THE TRADE WAS PRE-SCHEDULED — Form 4/5 activity for one company with the metadata free feeds drop: the Rule 10b5-1 flag and the filing lag. Sales made under a 10b5-1 plan were scheduled in advance and carry NO view, so they are aggregated separately from discretionary trades and never blended into one 'net insider flow'; a third bucket holds rows with no plan flag, which is unknown, not discretionary. Only open-market buys and sells enter the flow buckets — grants, option exercises and tax-withholding are counted apart. Use as_of to reproduce what was PUBLIC on a date: it filters on the filing date, the only correct as-of key for insider data (a trade-date filter leaks late-filed trades).

What insider history exists, for which dates, and how much of it carries a Rule 10b5-1 plan flag — rows by record type, distinct filers, the transaction- and filing-date spans, and the share of rows that actually carry the plan flag. Call it before reading a plan split as complete: rows without the flag are unknown, and this says how many there are. Pass a ticker for per-company coverage.

INSIDER INTENT-TO-SELL NOTICES — supply before it hits the tape. Form 144 is filed BEFORE a sale of restricted or control stock, so it is forward-looking: who intends to sell, roughly how many shares, through which broker, at what notified market value, and how the stock was acquired. Call it to see overhang building ahead of the completed sales, which only show up later in the Form-4 flow. A notice is an INTENT — it may be executed smaller, later, or not at all, so never treat notified value as realised selling.

SEC Form 4 insider trades for one ticker — recent buys and sells by officers, directors, and large holders (default 25). Call this when the user asks 'are insiders buying or selling X?' or wants to check insider conviction before acting on a name.

Live cross-ticker Form-4 insider-transaction feed (alternative-data, last ~20k rows): name, transaction_code, shares, price_per_share, value_usd, shares_owned_following. Call this when the user asks 'are insiders buying or selling?' — one name or market-wide. Optional ticker filter is applied client-side.

LIVE implied-volatility analytics in one call: IV RANK (current IV + its 1-year percentile — the standard 'is vol cheap or rich' gauge, with a plain-language verdict), SKEW (risk-reversal per delta — put-vs-call demand / crash premium), and TERM STRUCTURE (IV per expiry + option-implied move, labelled backwardation vs contango). Use for 'should I buy or sell premium on X', earnings-vol setups, and hedging cost. Omit date for the latest session. Each block degrades independently. NOT the same as /intel/vol_surface, which serves the lagged academic surface.

Quarterly corporate lobbying spend for one ticker from the alternative-data feed (limit, default 50). Call this when the user asks how much a company spends lobbying or whether its policy exposure is growing; pair with tengu_v3_intel_gov_contracts for the government-contract side of the same story.

NOW WITH a `credit` block: CDX IG/HY on-the-run 5Y composite spreads + 1-session delta (T-2 by source, cadence-aware staleness; full series at /api/v3/credit/indices). Cross-asset macro composite returning REAL underlying values, all real-time where the data source permits. Fields: `vix` (real-time spot), `ten_year_yield_pct` (FRED DGS10, %), `usd_index_narrow_dxy` (computed from FRED 6-pair basket via the standard geometric weighted formula — the institutional standard ~99), `usd_index_trade_weighted_broad` (FRED DTWEXBGS — Fed's broader policy measure ~118), `wti_oil_usd_bbl` (FRED DCOILWTICO, $/bbl), `gold_usd_oz` (real-time forex spot, $/oz), `sp500` (real-time index; SPY×10 emergency fallback), `nasdaq100` (real-time index; QQQ×41 emergency fallback), `djia` (real-time index; null when unavailable — no ETF proxy emitted), `russell2000` (real-time index; IWM×10 emergency fallback). Every numeric field is gated by a plausibility guard — out-of-band values are nulled with an `error.implausible_value` field rather than served, so the chat Brain never cites a wrong number with the [macro_snapshot] tag. Includes `vol_regime` (low_vol/normal/elevated/stress per VIX bucket), `data_freshness` timestamp, and a `sources` block with the series reference for each indicator. 60s cache.

Max-pain price per options expiration for one ticker from the options-flow feed. Call this when the user asks where a stock is likely to pin into expiry or what the max-pain level is; pair with tengu_v3_intel_gex for aggregate gamma/delta exposure.

Top-N SHAP feature attributions for the ML ensemble score on a ticker: drivers[] ranked by |SHAP| with feature (e.g. beta_cma, vol_21d), signed shap_value, direction (bullish/bearish/neutral). PRIMARY tool for 'why is the model bullish/bearish on X?'. Nightly run; default top=5, max 20; available:false outside the ML universe. 5min cache.

Latest ensemble ML prediction for the ticker, with full conformal interval + 19-voter decomposition. Sourced from the nightly ensemble scoring run (refreshed nightly Mon-Fri, ~13K tickers scored per cycle). Returns `prediction` block (predicted_return_pct, blended_score, conviction, decile, rank, percentile_rank, n_universe), `conformal_interval` block (lo/hi/half_width/method + stated_coverage 0.90 + realised_coverage_recent from live calibration table), `voter_decomposition` (per-voter contribution across the 19 voters — e.g. ml_ensemble, regime_hmm, technical_advanced, sentiment_finbert, macro_context, fundamental, options_flow, insider_flow, analyst_revisions, futures_macro, congress_trading, short_pressure), `context` (voter_coverage, confluence, feature_coverage), plus model_version, tier (small/mid/large universe), regime, sector. When a ticker isn't in the latest scoring universe, returns `available: false` with reason. 5min cache. NAMESPACE: predictions are US-EQUITY only. Nine crypto tickers collide with equities (BTC, ETH, LINK, LTC, COMP, ARB, NEAR, APT, ATOM) — such responses carry a `ticker_collision` note; for the crypto asset pass asset_class=crypto (fails closed 404: no crypto model yet). NEVER present an equity prediction as a crypto view.

Live conformal-coverage telemetry: how often the model's stated 90% intervals actually contain the realised 5d returns. Built nightly over the trailing 30 days of prediction-outcome pairs. Returns `stated_coverage` (target, typically 0.90), `realised_coverage` (actual, e.g. 0.78), `coverage_delta` (gap, negative = under-covering), `status` (red/amber/green), `n_pairs` (sample size, ~110K typical), `mean_interval_width_pct`, `mean_predicted_return_pct`, `mean_realised_return_pct`, and an `interpretation` string. Treat status=red as a verdict-grade caveat — chat should attach 'model intervals currently under-covering' to any ml_prediction citation when this returns red. 1h cache.

Newswire 'Crypto' channel — crypto news stream covering BTC, ETH, exchanges, regulation, miners. Call this when the user asks about crypto news; pair with coin-stock proxies (COIN, MSTR, RIOT, MARA) to fuse the equity-side reaction. 60s cache.

MARKET-WIDE ONLY — never for one ticker's news (that is tengu_v3_news_summary). Live cross-publisher newswire headlines: headline, publisher, tickers, is_major flag, feed-supplied sentiment; seconds-fresh, 120s cache. For 'what's happening in the market right now?' scans and cross-ticker sweeps.

Newswire 'Movers' channel — coverage of stocks making the biggest intraday moves (gainers, losers, halts, breakouts). Call this for 'biggest movers today' questions and end-of-day 'what moved' recaps; pass tickers to narrow. 60s cache.

newswire 'Press Releases' channel — corporate press releases on the newswire (PR Newswire, Business Wire, GlobeNewswire). Use when the user asks for the company's own announcements rather than analyst/journalist coverage. 60s cache.

Real-time newswire stories — cross-ticker, ticker-filtered (comma-separated), or by channel: id, title, teaser, url, ticker(s), channels, tags, created (ISO-8601); body=true adds full HTML (slower, larger). Call this when the user wants themed or full-text news beyond headlines. Confirmed-working channels (probed 2026-04-30; exact case + apostrophe matter): "Press Releases", "Crypto", "Movers", "Why It's Moving", "Earnings", "Earnings Beats", "Earnings Misses", "Guidance", "Top Stories", "Tech", "Markets", "Analyst Color", "Federal Reserve", "Government", "ETFs", "Forex", "Commodities", "Treasuries", "Futures", "Emerging Markets", "Eurozone", "Asia", "Global", "Equities", "Bonds", "Trading Ideas", "After-Hours Center".

MOVER-EXPLANATION ONLY — for 'why is X moving / what's driving X right now?' questions; never for generic 'latest news on X' (that is tengu_v3_news_summary). Newswire 'Why It's Moving' channel: short explainers for stocks making notable intraday moves. 60s cache.

Daily off-exchange (dark pool + ATS) volume for one ticker from the alternative-data feed (default 30 days). Call this when the user asks how much of a stock's volume trades off-exchange or how dark-pool share is trending; use tengu_v3_intel_darkpool_ticker for individual prints.