Cohort Intelligence

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), cohort tightness
    score, AND a deterministic `summary` block of classification
    flags (verdict_class, edge_class, regime_alignment,
    sample_quality, conviction, swing_factors with framings,
    caveat_flags). Read `summary` first — paraphrase the framings
    in your own voice rather than narrating the raw stats; cite
    numbers in parentheses for support. `summary` is included
    when `include_anchor_metadata=True` (the regime classification
    needs the anchor's metadata). 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
    include_modes: full-mode only — when True, returns a `modes`
        array clustering the cohort into K outcome playbooks (e.g.
        "smooth uptrend +4.2%", "sharp downtrend -8.1%"). Each
        entry has mode_id, label, n, median_return, win_rate,
        std_return, p25/p75_return, and centroid_cum_returns
        (sparkline-ready trajectory). Sorted ASC by median_return
        so mode_id=0 is the worst realized cluster. Use for
        "playbook" framing — the cohort isn't one outcome, it's
        K distinct historical paths.
    n_modes: number of modes to cluster into (2-6, default 4).
        Adaptive: degrades to fewer modes if cohort_size is small.
    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.