cohort
Read-onlyIdempotent
Analyzes historical analogs for a given stock anchor, returning outcome distributions (p10-p90, win rate) and feature importance. Compares cohorts or stratifies by regime for deeper insight.
Instructions
Conditional-distribution analysis — the Chart Library core primitive.
Three depth modes:
depth="basic" (default, fast ~50ms):
Returns kNN cohort + outcome distribution (p10/p25/p50/p75/p90,
win rate, MAE, MFE) + survivorship. Supply cohort_id (refine
prior cohort) OR query OR symbol+date.
depth="full" (Layer 3, ~280ms, paid tier):
Returns the basic outputs PLUS feature importance (which Layer 2
features separated winners from losers within this cohort),
regime stratification (outcomes sliced by vol/macro), risk
profile (drawdown / runup percentiles), and cohort tightness
score. Requires symbol+date+timeframe (cohort_id alone isn't
enough — the Layer 3 analyzer needs the full anchor).
depth="compare" (~400ms):
Compare TWO anchors' cohorts side-by-side. Pass symbol+date for
the primary AND compare_with={"symbol":..., "date":..., "timeframe":...} for the secondary. Returns both cohorts'
distributions plus a delta summary.
Filters (Layer 2 metadata constraints):
vol_regime: list of "low"/"mid"/"high"
macro_state: list of "bullish"/"neutral"/"bearish"
has_news: bool
days_since_earnings / days_since_ath / sector_rs /
realized_vol / relative_volume: dict with "min" / "max"
Empirical-distribution analysis only. Does NOT predict a single
point return; surfaces what historical analogs did and which features
separated them.
Args:
symbol, date, timeframe: anchor (default timeframe "1h")
query: alt to symbol+date, "SYMBOL YYYY-MM-DD"
cohort_id: refine a stored cohort (basic mode only)
depth: "basic" | "full" | "compare"
filters: Layer 2 constraints
horizons: forward horizons in trading days (default [5, 10] for
basic, [1, 5, 10] for full)
cohort_size: target K (10-2000)
compare_with: secondary anchor for depth="compare"
include_feature_importance, include_regime_stratification,
include_risk_profile: full-mode toggles
exclude_same_symbol_days: drop same-symbol analogs within N
calendar days of the anchor (autocorrelation control;
default 10)
include_path_stats: include MAE/MFE/realized-vol (basic mode)
fields: full-mode only — optional allowlist of top-level
response keys to return. None (default) = full payload.
Valid: outcome_distribution, feature_importance,
regime_stratification, risk_profile, cohort_tightness_score,
cohort_score, combined_conviction, pulse_boost,
narrative_pulse, cohort_anchors, anchor_metadata. Use to
slim the JSON when you only need a subset (e.g.
fields=["outcome_distribution"] drops 97% of bytes).
anchor, cohort_size_actual, elapsed_ms, warnings are
always returned.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | No | ||
| date | No | ||
| timeframe | No | 1h | |
| query | No | ||
| cohort_id | No | ||
| depth | No | basic | |
| filters | No | ||
| horizons | No | ||
| cohort_size | No | ||
| compare_with | No | ||
| include_feature_importance | No | ||
| include_regime_stratification | No | ||
| include_risk_profile | No | ||
| exclude_same_symbol_days | No | ||
| include_path_stats | No | ||
| fields | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |