io.github.Hlobo-dev/tengu-firm

Detail for a single backtest run

List recent backtest runs

Calibrated trust per signal source

Daily briefing for a given user_id: regime, overnight futures, earnings_today, macro_today, watchlist_signals, news_highlights, risk_exposure, top_movers. ALWAYS returns a briefing — served from a precomputed cache (~5ms) when available, else built on demand (~3s, no LLM calls). The response carries '_source': 'precomputed' or 'computed:request_time' so callers can tell which path served them. Pass precompute_only=true ONLY when you specifically need to know whether the cron has already run (e.g. monitoring scripts) — that path returns 404 instead of building.

Presence check for today's briefing payload for a user/date. Call when the user asks whether the daily briefing was generated or why it looks missing.

EMPTY UNTIL FIRST USE — not broken. Tracked decisions live in Redis and a row is appended ONLY on a state CHANGE, so this populates the FIRST time a tracked decision transitions. Say that to the user rather than reporting an outage. Alerts from the tracked-decision monitor: thesis intact/weakening/broken transitions, earnings-imminent, interval breaches — poll after decision_track. The 2x/day monitor job sweeps every tracked decision and appends a row ONLY on state change (deduped), so every alert here is a NEW transition worth surfacing. alert_type in {status_change, earnings_imminent, interval_breach, stale_decision}; each row carries entry/last price, realised return, score_original → score_current delta, prev_status → thesis_status, severity and a render-ready narrative. Filter with ?ticker= and ?since_hours= (default 72).

Pre-trade expected execution cost for a ticker: spread, market impact, and commission for a given qty (default 100) and side (buy/sell). Call it to know what a trade will actually cost before sizing or routing it; use twap_plan/vwap_plan for the execution schedule itself.

One-call credit snapshot for a company — call FIRST for any 'how risky is this company's debt?' question: latest securities-finance 5Y CDS spread (bps) with ~90-quote trend + market-implied default probability, current S&P rating with the last upgrade/downgrade action, a recent FINRA TRACE bond yield/volume summary, and the syndicated-loan-facility count. Blocks degrade independently (a missing dataset returns an error field in its block, never a failed call). Drill down with the credit bonds/cds/ratings/loans tools.

FINRA TRACE corporate-bond trade prints for one issuer — individual OTC trades (price, yield, volume, buy/sell side) showing where the company's bonds ACTUALLY trade (realised credit spreads, not quotes). Matched by the FINRA bond-symbol prefix of the equity ticker; window spans at most 90 days (422 beyond). TRACE on licensed-research lags realtime by months — when the default recent window is empty the response includes latest_available; page backwards from it.

Daily 5Y single-name CDS spread history: composite par spreads (raw + bps), market-implied default probability, average/implied agency rating. Call it for how default risk has trended (tengu_v3_credit is the one-call snapshot). Coverage 2005 to end-2025, 5Y tenor; tickers match the equity symbol for liquid US names (F, T, GE...).

Credit-index composites — the credit market's VIX-equivalents: CDX (NA IG/HY) + iTraxx (Europe/Asia/SovX) daily composite spreads and prices by series/version/tenor, 2018 to T-2. Call it for credit-market risk appetite, spread-widening episodes, or cross-asset stress context. FRESHNESS IS T-2 (daily composite) — never present as realtime.

Syndicated loan book for one borrower: per-facility size, type (revolver/term), maturity, security/seniority, all-in drawn/undrawn spread bps, covenants; include_lenders adds recent-facility syndicate allocations. Private-credit complement to the TRACE bond tape; call for leverage, facility or covenant questions; match on borrower ticker.

Full S&P rating-action history for one issuer's debt — every licensed institutional action (new rating, upgrade, downgrade, outlook/creditwatch change) with from/to symbols, newest first. Use when asked what a company is rated or when/why it was up/downgraded. Equity ticker is resolved to the issuer CUSIP-6 via the fundamentals security master; actions are instrument-level, so several rows can share a date.

Use when: the user asks for a specific ticker's next earnings date, when a company reports, the earnings calendar entry for a name, or anything of the form "when is X's next earnings?". This is the CANONICAL multi-source consensus tool — fans out to market-data, market-data, newswire, news, and web search in parallel; reconciles via primacy-weighted majority; returns a single canonical answer with per-source breakdown, deduplicated citations, and a ``vendor_coverage_alert`` when paid vendors silently lack data the web confirms. ``_meta.confidence`` is `high` (≥2 sources agree, or 1 primary source = market-data|web_search), `medium` (1 secondary source), or `low` (no confirmed date — projections demoted to ``_meta.next_earnings_date_projection_only``). Top-level ``summary`` field for FE rendering. 15-min cache.

STREAMING variant of ``tengu_v3_earnings_next`` — same consensus contract, delivered as Server-Sent Events (text/event-stream). Emits two events: ``partial`` when paid vendors reach consensus (~500ms first paint with `is_projected=false`, confidence=high based on paid alone) and ``result`` when web_search has verified (~2-3s; updates `vendor_coverage_alert` if web disagrees). Use when a consumer can render incrementally and wants the fastest possible first paint — chat surfaces and live tickers. Synchronous consumers should keep using ``tengu_v3_earnings_next`` (cost-aware: skips the web_search call entirely when paid agrees).

Company corporate-event history from a licensed events feed (41.9M events, 1990-2026): M&A, guidance changes, buybacks, exec changes, activism, offerings, index adds/drops + 100 more types, newest-first dated headlines + summaries. PRIMARY tool for 'what happened at COMPANY'; filter type= (see /api/v3/events/types), since/until.

Legend of the 105 licensed institutional KeyDev corporate-event types: id, human label, and the slug accepted by the type= filter of /api/v3/events/{ticker}. Static — call once to discover valid event-type filters.

Monthly time series of ONE factor characteristic for a stock (e.g. mom_12m, bm, mktcap, realized_vol, sue, turnover), newest first. Call it to chart how an anomaly signal evolved for a name or to compare signal drift across names; a typo in `char` returns 422 with the full list of valid column names.

Latest monthly firm-characteristic vector from the academic firm-characteristic panel (~460 columns incl. the 102 published anomaly characteristics — size, book-to-market, momentum, liquidity, accruals, analyst coverage, plus macro interactions). Call it when you need the full quant feature set for one stock, or a point-in-time vector via as_of. Ticker is resolved to its internal security key automatically.

Rolling factor betas (Fama-French 5 + momentum) for one stock: beta_mkt/smb/hml/rmw/cma/umd with alpha, idiosyncratic/total volatility and regression R², plus the monthly history of those loadings. Call it to know what factor bets a position actually carries before hedging or sizing it.

academic open-source predictor panel for one stock — a compact vector of 13 replicated accounting anomalies (Sloan accruals, Cooper-Gulen-Schill asset growth, Titman capital investment, Novy-Marx gross profitability, Fama-French operating profitability, cash-to-assets, leverage change, earnings consistency, revenue growth, positive-NI/positive-CFO flags, current ratio, net share issuance) at monthly grain. Call it for a ready-made feature vector when you don't need the full ~460-column factor panel. Returns the series newest-last, or with latest=true only the single most-recent row as a name->value map; with no start/end it serves the LATEST AVAILABLE rows (lagged quarterly archive) and reports the actual window. Ticker is resolved to its internal security key automatically (the table has no ticker column).

FEATURE-STORE CATALOGUE — the derived research panels this platform computes for its own models: what exists, how much of it there is, how far back it goes, and how fresh it actually is. Every entry carries MEASURED coverage (rows, symbols, distinct observation dates, history window) and a measured freshness block. freshness.status is `current` when the producer is inside twice its own declared cadence, or `archival` when the producer has stopped but the dataset is a genuine historical panel — an archival dataset is still readable and EVERY read of it says so. A second, independent flag, stale_for_its_own_cadence, fires when the newest observation is old relative to the table's own typical gap: it catches a panel rewritten nightly whose data still ends months ago because the upstream licence lags. Datasets whose producer stopped and which are NOT panels are listed under `withheld` with the measurement that disqualified them and have NO route at all; `excluded` lists live datasets deliberately not sold here, with the reason. Live-measured 2026-08-02: 19 servable datasets totalling 17,062,613 rows — 14 current, 5 archival (spanning 1962, 1970, 2000, 2025-05 and 2026-05 forward) — plus 5 withheld and 2 excluded. Call it first: it is the only place the slugs for /api/v3/features/{dataset} are published.

READ ONE DERIVED FEATURE PANEL — the model-ready research features this platform computes for itself: price/return and liquidity features, monthly fundamentals, analyst-estimate dynamics, options and volatility-surface features, insider and institutional-ownership features, news-sentiment features, betas, regime and macro features. Discover the slugs via /api/v3/features/datasets — they are product names, not table names. With ?ticker= you get that symbol's observations newest first; without it you get the LATEST cross-section (every symbol on the most recent observation date), which is bounded by construction rather than by sorting the whole panel. Symbols resolve through the shared security resolver first and identity.identity_verified states whether the read was keyed on an authoritative identifier or on the resolved security's symbol; an ambiguous symbol is refused, never guessed. Every response carries the dataset's measured coverage (rows_total, symbols_total, observation_dates, history window) and its freshness, so an empty rows array arrives beside the count of symbols that DO have rows and can never be read as a dead upstream — `result` is the machine-readable outcome (rows, no_rows_for_symbol, no_rows_in_window). Five of the 19 servable datasets are `archival`: their producer has stopped, they are served for their history, and every response says so rather than implying currency. An unknown or withheld slug is a 404 and an unreadable store is a 503 — both refunded, because a billed 200 over an empty array is the defect this endpoint exists to remove.

Lightweight catalogue of all registered frameworks — one row per framework with framework_id + intent + 1-line applies_when + version. Useful for discovery / debugging without parsing the full library. For the actual decision template, call tengu_v3_framework_lookup.

AI-generated company analysis for one ticker — summary, strengths, concerns, peer comparison and a quality score. Call this when the user wants a synthesized qualitative read rather than raw numbers. Premium: metered at 100 credits/mo.

All three financial statements — income, balance sheet, and cash flow — for a ticker in one round-trip (default quarterly, last 4 periods). Call this when the user wants a full fundamental picture of a company instead of three separate statement calls.

SEC EDGAR balance sheets for a ticker — assets, liabilities, and equity line-items per period, quarterly or annual (default quarterly, last 8 periods). Call this when the user asks about cash on hand, debt load, or book value straight from reported filings.

SEC EDGAR cash-flow statements for a ticker — operating, investing, and financing flows per period, quarterly or annual (default quarterly, last 8 periods). Call this when the user asks about cash generation, capex, buybacks, or how earnings convert to actual cash.

Static company profile for one ticker — sector, industry, CIK, exchange, market cap and employee count. Call it to know what a company is and how big it is before deeper analysis. Not the XBRL corpus — that discovery lives at /fundamentals/companyfacts/{ticker}.

One-call company snapshot — info + TTM + ratios + growth + MRQ balance (fundamentalsapi.com)

Directory of every as-reported XBRL concept (us-gaap/dei/ifrs-full) a company has filed — unit(s), observation count and period coverage — from the in-house SEC EDGAR companyfacts corpus. Call it FIRST to find the concept tag for /fundamentals/xbrl/{ticker}/{concept}. Point-in-time, no vendor restatement.

Dividend profile per ticker — DPS, payout ratio, consecutive-growth streak and 10Y history; accepts comma-separated tickers. Call this for any dividend-safety, income or 'how long has X raised its dividend' question.

Full text of a company's earnings press releases, including guidance language (default limit 8). Call this when the user asks what management said or guided in an earnings release, or wants exact announcement wording.

One-shot fundamentals bundle for a ticker — metrics snapshot, TTM income, latest balance sheet and cash-flow, company facts, recent insider trades and top institutional holders, fetched in parallel. PRIMARY tool for 'give me the full fundamental picture of X' — call it instead of assembling the pieces one by one.

Growth metrics — YoY, 3Y CAGR, 5Y CAGR and margin trends; accepts comma-separated tickers for one-call bulk comparison. Call this when the user asks how fast a company is growing, whether margins are trending up, or to compare growth across several names.

Multi-decade historical financial statements for one ticker from SEC EDGAR — income, balance, and cash-flow, filterable by statement_type and start_year/end_year, annual by default with include_quarterly opt-in. Call this when the user asks how fundamentals have trended over many years, not just the latest print.

SEC EDGAR income statements (P&L line-items, revenue through net income/EPS) for a ticker — quarterly, annual, or TTM (default quarterly, last 8 periods). Call this when the user asks about revenue or earnings trends and wants the actual reported statements.

Form-4 insider transactions for one ticker — officer and director buys and sells (default limit 50). Call this when the user asks whether insiders are buying or selling a stock, or wants insider-conviction evidence for a name.

13F institutional holdings for one ticker, itemized by holding institution (default limit 50). Call this when the user asks which institutions or funds own a stock or how concentrated institutional ownership is.

Derived financial-metric rows per period for a ticker — P/E, ROE, margins, FCF yield, debt ratios — quarterly, annual, or TTM (default quarterly, last 4 periods). Call this when the user asks about valuation or quality ratios and their trend without needing raw statement line-items.

Latest financial-metrics snapshot for a ticker — a single TTM row of valuation and quality ratios. Call this for a quick 'what's the P/E, how profitable is X right now?' check; use fundamentals_metrics when the user needs the per-period history.

Curated news articles for one ticker from the fundamentals market-data feed, with start_date/end_date filtering (default 50). Call it for ticker-scoped headlines while working inside fundamentals; it is distinct from the primary news surface — use the news tools for broad or breaking coverage.

Same-industry comparables for a ticker, ranked by revenue, margins and ROE (default 10). Call this when the user asks who a company's competitors are or how it stacks up against peers — fetch it before any relative-valuation take.

WHAT THE MARKET ACTUALLY KNEW on a given date — as-FIRST-REPORTED quarterly financials for a ticker as they stood on `as_of`: for each fiscal period, the latest published version whose knowledge date is on or before that day. Later restatements are excluded BY CONSTRUCTION, which is what makes this safe to backtest on — the ordinary financials endpoints serve the restated view and will leak look-ahead. Each period also reports whether it has been restated since and what the figure reads today, so you are never silently handed a stale number. Omit as_of for the current view. Figures are in MILLIONS of each filing's own reporting currency (carried per period) — never assume USD.

The honest bounds of the point-in-time primitive: how many published versions are held, for how many companies, the span of KNOWLEDGE dates (which is what an as_of query can answer) and the span of fiscal periods covered. Call it before trusting an as_of earlier than the archive starts — outside the knowledge span the answer is 'not knowable here', not 'no data'. Pass a ticker for per-company bounds.

THE RESTATEMENT TRAIL for one fiscal quarter — every published version of the period in order, each with the day it became the live view, the day it was superseded, and exactly WHICH line items changed from the previous version. Call it to check whether a figure you are relying on has been quietly revised, and by how much: a quarter can be restated several times, and only the trail shows it. The still-current version reports a null supersede date rather than a far-future sentinel. Omit datadate for the most recent quarter held.

Latest quote for one ticker — last trade plus the current daily bar. Call this when the user asks what the price is now or how the stock is moving today; for history use /fundamentals/prices. CRYPTO: pass asset_class=crypto for BTC/ETH/SOL/LTC/LINK etc. Several crypto symbols are ALSO US-listed equity tickers (BTC is a Grayscale trust at ~$29; LINK is Interlink Electronics), so a bare ticker returns the EQUITY. Never use an equity price for a crypto asset. Check is_stale before using the price.

Historical OHLCV bars for one ticker at second/minute/hour/day/week/month granularity (interval_multiplier for e.g. 5-minute bars; start_date/end_date window, default limit 1000). Call this when the user asks for price history, returns over a window, or intraday bars; for the latest quote use /fundamentals/price_snapshot. CRYPTO: pass asset_class=crypto for BTC/ETH/SOL/LTC/LINK etc. Several crypto symbols are ALSO US-listed equity tickers (BTC is a Grayscale trust at ~$29; LINK is Interlink Electronics), so a bare ticker returns the EQUITY. Never use an equity price for a crypto asset.

Multi-filter stock screener combining profitability (ROE, ROA, net margin), growth (revenue, EPS), financial-health (debt/equity, current ratio) and dividend filters, with sector/industry scoping and sort control. PRIMARY tool for 'find me stocks that…' asks; ready-made strategies live in /fundamentals/screener/presets.

Catalog of pre-built screener strategies — Aristocrats, Cash Cows, Value, Quality and more. Call it when the user asks for a named strategy screen or wants screening ideas before composing /fundamentals/screener filters.