Tengu
Sign up
OverviewProductsPrivate MarketsTengu BrainAPI Reference

Quant Signals

The platform's machine-learning brain: nightly ensemble forecasts on 13K+ stocks with 90% conformal prediction intervals, SHAP feature attributions, 19-voter decomposition, and trade setup recommendations grounded in real alpha signals.

What's inside#

The Quant Signals product powers the AI's decision-making with four core intelligence layers:

LayerSourceCoverageRefresh
ML Predictionsgold.ensemble_predictions~13K stocks (Mon–Fri)Nightly (22:45 ET)
Conformal Intervalsgold.live_conformal_coverage90% stated, 87%–90% realized 30dDaily
SHAP Driverss3://nuble-data-warehouse/firm-runtime/reports/ml_drivers/Top-5 features per ticker × tierNightly
19-Voter Decompositiongold.ensemble_predictions (voter_* columns)Consensus score + per-signal weightNightly
Trade SetupsDecision engine over ensemble scores25–500 top picks with convictionNightly

All data is sourced from the nightly materialize_predictions job (Fargate, AWS) which runs Mon–Fri at 22:45 ET. The 19-voter ensemble (macroeconomic context, momentum, value, sentiment, insider flow, options positioning, etc.) is production-frozen and never mutated mid-cycle; confidence margins include real 30-day backtest calibration so the bands are not theoretical.

Access#

3 credits per call · Starter and up

Quant Signals is included in Starter ($99/mo) and all paid plans. Each call to the ML stack (predictions, drivers, intervals, voters, trade setups) costs 3 credits from your monthly wallet. See Pricing & credits for plan limits and per-product breakdowns.

Endpoints#

MethodPathDescription
GET/api/v3/intel/ml_prediction/{ticker}Latest ensemble forecast: predicted_return_pct, blended_score (0–1), conformal band, 19-voter decomposition, universe rank.
GET/api/v3/intel/ml_drivers/{ticker}Top-N SHAP feature attributions: which features pushed the score bullish/bearish and by how much.
GET/api/v3/intel/factor_importanceFama-French 5-factor loadings + Bayesian voter posteriors: "what drives the strategy's returns?"
GET/api/v3/intel/voter_coverage/{ticker}Per-voter accounting: each of the 19 voters' current score, weight, status (firing/silent_data/shadow), and freshness.
GET/api/v3/intel/voter_ic_driftVoter health dashboard: IC (information coefficient) per voter over trailing 30–60 days; flags degrading confidence.
GET/api/v3/intel/voter_attribution/{ticker}Attribution: which voters drive consensus, their thresholds, and interaction effects on the final score.
GET/api/v3/intel/model_calibrationLive conformal-coverage stats: stated 90%, realized 30d, trend, calibration curve.
GET/api/v3/intel/pnl_attributionP&L attribution: signal-level contribution to portfolio returns (Brain use: "which signals made money this week?").
GET/api/v3/decision/trade_setupsTop trade setups by conviction: LONG/SHORT/NEUTRAL picks + regime-skew context; powers "what should I trade?"
GET/api/v3/signals/fusionFused signal score (consensus across all layers).
GET/api/v3/signals/mtf/{ticker}Multi-timeframe signals: daily/weekly/monthly consensus alignment.
GET/api/v3/signals/veto_stateCircuit-breaker state: when ensemble enters "all-same-direction" veto mode.
GET/api/v3/factors/predictors/{ticker}Chen–Zimmermann open-source predictor panel: 13 replicated accounting anomalies (Sloan accruals, Cooper–Gulen–Schill asset growth, Titman capital investment, Novy-Marx gross profitability, Fama–French operating profitability, net share issuance, …) at month-end grain, permno-keyed (the ticker is resolved automatically — the panel has no ticker column). ?latest=true returns the single most-recent row as a name→value map; otherwise the newest-last time series (?start/?end). Lagged academic archive — latest-available if no dates. Returns {ticker, permno, series | predictors, predictor_glossary}.
GET/api/ml/predict/{ticker}Alternative endpoint (legacy route): latest prediction envelope.

Examples#

Example 1: Fetch the latest ML forecast with conformal band and voter breakdown#

Pull the ensemble prediction for a ticker: directional score, return forecast, 90% prediction interval, and which of the 19 voters drove the call.

Shell
1curl -H "Authorization: Bearer $TENGU_API_KEY" \2  "https://firm.tengu.co/api/v3/intel/ml_prediction/AAPL"3 4# Response structure:5# {6#   "ok": true,7#   "timestamp": "2026-07-05T10:30:00Z",8#   "ticker": "AAPL",9#   "available": true,10#   "as_of": "2026-07-04T22:45:00Z",11#   "knowledge_ts": "2026-07-03T23:59:59Z",12#   "data_staleness_days": 1.04,13#   "model_version": "v2.3",14#   "model_type": "xgboost_ensemble",15#   "tier": "tier_2",16#   "regime": "neutral",17#   "sector": "Technology",18#   "prediction": {19#     "predicted_return_pct": 2.15,20#     "blended_score": 0.642,21#     "conviction": 0.642,22#     "decile": 7,23#     "rank": 1850,24#     "n_universe": 13245,25#     "percentile_rank": 86.0526#   },27#   "conformal_interval": {28#     "lo": -4.32,29#     "hi": 8.62,30#     "half_width": 6.47,31#     "method": "conformal_quantile",32#     "stated_coverage": 0.90,33#     "realised_30d": 0.8812,34#     "coverage_as_of": "2026-07-04"35#   },36#   "voters": {37#     "momentum_daily": 0.185420,38#     "value_ff3": 0.128640,39#     "macro_context": 0.095230,40#     "insider_net": 0.068450,41#     "options_positioning": 0.052810,42#     ...43#   },44#   "source": "gold.ensemble_predictions"45# }
Python
1import os, requests2 3r = requests.get(4    "https://firm.tengu.co/api/v3/intel/ml_prediction/AAPL",5    headers={"Authorization": f"Bearer {os.environ['TENGU_API_KEY']}"},6    timeout=30,7)8r.raise_for_status()9data = r.json()10 11if data["ok"] and data.get("available"):12    pred = data["prediction"]13    interval = data["conformal_interval"]14    print(f"Ticker: {data['ticker']}")15    print(f"Direction: {'LONG' if pred['blended_score'] > 0.5 else 'SHORT'}")16    print(f"Predicted return: {pred['predicted_return_pct']:.2f}%")17    print(f"Conviction: {pred['conviction']:.2%}")18    print(f"Forecast band (90%): [{interval['lo']:.2f}%, {interval['hi']:.2f}%]")19    print(f"Top voter: {max(data['voters'].items(), key=lambda x: x[1])}")

Example 2: Get SHAP feature drivers and top trade setups#

Pull the top bullish/bearish features for a ticker and the current highest-conviction trade picks.

Shell
1# Top SHAP drivers for AAPL2curl -H "Authorization: Bearer $TENGU_API_KEY" \3  "https://firm.tengu.co/api/v3/intel/ml_drivers/AAPL?top=5"4 5# Response structure:6# {7#   "ok": true,8#   "timestamp": "2026-07-05T10:30:15Z",9#   "ticker": "AAPL",10#   "available": true,11#   "tier": "tier_2",12#   "n_features_returned": 5,13#   "drivers": [14#     {15#       "rank": 1,16#       "feature": "price_momentum_20d",17#       "shap_value": 0.287453,18#       "direction": "bullish"19#     },20#     {21#       "rank": 2,22#       "feature": "earnings_surprise_pct",23#       "shap_value": 0.156240,24#       "direction": "bullish"25#     },26#     {27#       "rank": 3,28#       "feature": "short_interest_change",29#       "shap_value": -0.082150,30#       "direction": "bearish"31#     },32#     {33#       "rank": 4,34#       "feature": "insider_net_transactions",35#       "shap_value": 0.058640,36#       "direction": "bullish"37#     },38#     {39#       "rank": 5,40#       "feature": "options_iv_percentile",41#       "shap_value": -0.031240,42#       "direction": "bearish"43#     }44#   ],45#   "interpretation": "Top-5 SHAP attributions for the tier_2-tier ensemble model's score on AAPL. Positive shap_value = the feature pushed the score higher (bullish), negative = lower (bearish).",46#   "source": "reports/ml_drivers/latest.parquet (S3 firm-runtime sidecar)"47# }48 49# Top trade setups (LONG/SHORT picks with conviction)50curl -H "Authorization: Bearer $TENGU_API_KEY" \51  "https://firm.tengu.co/api/v3/decision/trade_setups?limit=10&min_conviction=0.5"52 53# Response structure (partial):54# {55#   "ok": true,56#   "timestamp": "2026-07-05T10:30:30Z",57#   "setups": [58#     {59#       "ticker": "AAPL",60#       "direction": "LONG",61#       "conviction": 0.642,62#       "blended_score": 0.642,63#       "predicted_return_pct": 2.15,64#       "interval_lo": -4.32,65#       "interval_hi": 8.62,66#       "decile": 7,67#       "rank": 185068#     },69#     {70#       "ticker": "TSM",71#       "direction": "SHORT",72#       "conviction": 0.534,73#       "blended_score": -0.534,74#       "predicted_return_pct": -1.82,75#       "interval_lo": -6.54,76#       "interval_hi": 2.90,77#       "decile": 2,78#       "rank": 1238879#     }80#   ],81#   "universe_skew": "bullish",82#   "regime_warranted_alternative": {83#     "strategy": "defensive",84#     "candidates": [85#       { "ticker": "JNJ", "name": "Johnson & Johnson", "expected_role": "hedge" }86#     ],87#     "rationale": "70% of picks are LONG; defensive alternatives loaded."88#   },89#   "filter": { "min_conviction": 0.5 },90#   "count": 1091# }
Python
1import os, requests2 3# Fetch SHAP drivers4r = requests.get(5    "https://firm.tengu.co/api/v3/intel/ml_drivers/AAPL",6    params={"top": 5},7    headers={"Authorization": f"Bearer {os.environ['TENGU_API_KEY']}"},8    timeout=30,9)10r.raise_for_status()11drivers = r.json()12 13if drivers["ok"]:14    for d in drivers["drivers"]:15        print(f"{d['rank']}. {d['feature']:30} | SHAP: {d['shap_value']:+.6f} ({d['direction']})")16 17# Fetch trade setups18r = requests.get(19    "https://firm.tengu.co/api/v3/decision/trade_setups",20    params={"limit": 10, "min_conviction": 0.5},21    headers={"Authorization": f"Bearer {os.environ['TENGU_API_KEY']}"},22    timeout=30,23)24r.raise_for_status()25setups = r.json()26 27for s in setups["setups"]:28    print(f"{s['ticker']:6} | {s['direction']:6} | Conviction: {s['conviction']:.1%} | Return: {s['predicted_return_pct']:+.2f}%")

Example 3: Chen–Zimmermann predictor vector for a ticker#

Pull the compact academic characteristic vector for a name — 13 replicated accounting anomalies — without loading the full ~460-column GKX panel. The panel is a lagged quarterly archive keyed by CRSP permno; the exchange symbol is resolved automatically. Use latest=true for the single most-recent row.

Shell
1curl -H "Authorization: Bearer $TENGU_API_KEY" \2  "https://firm.tengu.co/api/v3/factors/predictors/AAPL?latest=true"3 4# Response structure:5# {6#   "ok": true,7#   "timestamp": "2026-07-05T10:31:00Z",8#   "ticker": "AAPL",9#   "permno": 14593,10#   "mode": "latest",11#   "as_of": "2026-02-28",12#   "n_predictors": 13,13#   "predictors": {14#     "accruals": -0.031,15#     "asset_growth": 0.084,16#     "investment": 0.052,17#     "gross_profit_at": 0.412,18#     "oper_prof": 0.318,19#     "cash_at": 0.089,20#     "leverage_change": -0.014,21#     "earnings_consistency": 0.91,22#     "revenue_growth": 0.021,23#     "positive_ni": 1,24#     "positive_cfo": 1,25#     "current_ratio": 1.04,26#     "share_issuance": -0.00827#   },28#   "predictor_glossary": {29#     "accruals": "Sloan (1996) balance-sheet accruals anomaly",30#     "gross_profit_at": "Novy-Marx gross profitability (GP/assets)",31#     ...32#   },33#   "note": "cz_predictors has NO ticker column — the symbol is resolved to a CRSP permno via the live universe registry",34#   "source": "warehouse:bronze.cz_predictors"35# }
Python
1import os, requests2 3# Latest predictor vector for a name4r = requests.get(5    "https://firm.tengu.co/api/v3/factors/predictors/AAPL",6    params={"latest": "true"},7    headers={"Authorization": f"Bearer {os.environ['TENGU_API_KEY']}"},8    timeout=30,9)10r.raise_for_status()11data = r.json()12print(f"{data['ticker']} (permno {data['permno']}) as of {data['as_of']}")13for name, val in data["predictors"].items():14    print(f"  {name:22} {val}")15 16# ...or the full monthly time series (newest last)17r = requests.get(18    "https://firm.tengu.co/api/v3/factors/predictors/AAPL",19    params={"start": "2024-01-01", "limit": 24},20    headers={"Authorization": f"Bearer {os.environ['TENGU_API_KEY']}"},21    timeout=30,22)23r.raise_for_status()24series = r.json()25print(f"\n{series['n']} monthly rows, {series['start']} → {series['end']}")

Related#