Three modes:
  - mode="text" (default): pattern search by query string or
    symbol+date+timeframe. Cheap, fast, ~50ms.
    Examples:
      search(query="NVDA 2024-08-05 1h")
      search(symbol="NVDA", date="2024-08-05", timeframe="1h")
  - mode="live_bars": find historical analogs of a raw bar sequence
    the agent constructed (not yet stored in our DB). Pass `bars`
    as a list of {open, high, low, close, volume, timestamp}.
  - mode="similar": find cohorts most similar to a given (symbol,
    date) anchor at the cohort level, not the chart-pattern level.
    Useful for "what other setups historically clustered with this
    one?"

Returns: {status, data: {cohort_id, anchor, n_matches, top_matches,
survivorship}, meta}. The cohort_id can be chained into `cohort`,
`analyze`, or `explain` to compose richer responses without re-running
kNN.

Args:
    query: 'SYMBOL YYYY-MM-DD [timeframe]' (alt to symbol+date)
    symbol, date, timeframe: anchor components (alt to query)
    top_k: cohort size (10-2000)
    mode: "text" | "live_bars" | "similar"
    bars: list of OHLCV dicts (mode="live_bars" only)
    cross_timeframe: search across timeframes (mode="live_bars" only)

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.

Three modes:

  mode="picks" (default):
    Top picks ranked by cohort score. Default limit 20, lookback 3
    days, horizon 5.

  mode="daily_setups":
    Tomorrow's brief — top picks pre-enriched with full-cohort
    statistics, top-3 features, and yesterday's calibration recap,
    all in one response. Replaces the multi-call discovery dance.
    Default top=3, timeframe="1d".

  mode="risk_adjusted":
    Today's picks ranked by Sharpe-like score. Default min_sharpe
    0.3.

Args:
    mode: "picks" | "daily_setups" | "risk_adjusted"
    limit: max picks returned (mode="picks")
    lookback_days: scan window in days (mode="picks")
    horizon: forward horizon for ranking (mode="picks")
    top: number of pre-enriched setups (mode="daily_setups")
    timeframe: cohort timeframe (mode="daily_setups")
    date: ISO date override (mode="risk_adjusted"; default today)
    min_sharpe: minimum Sharpe threshold (mode="risk_adjusted")
    fields: daily_setups only — optional allowlist of top-level
        response keys. Valid: setups, yesterday_recap. as_of_date
        and cohort_timeframe are always returned. Use to drop
        yesterday_recap when you only need today's picks.

metric values:
  - "anomaly"             — is the pattern unusual vs the symbol's
                              own history? (needs symbol)
  - "volume_profile"      — intraday volume vs historical norms
                              (needs symbol)
  - "crowding"            — cross-symbol crowding indicator
                              (market-wide; no symbol needed)
  - "correlation_shift"   — rolling correlation breakdowns
                              (extra_args: lookback, window, symbols)
  - "earnings_reaction"   — historical earnings gap reactions
                              (needs symbol; extra_args: min_gap)
  - "pattern_degradation" — are signals losing edge vs historical
                              accuracy? (market-wide)
  - "regime_accuracy"     — win rates filtered by current regime
                              (needs symbol)
  - "decompose"           — find slice conditions that separated
                              winners from losers within a cohort
                              (needs cohort_id; horizon, max_slices,
                              explain_slices apply)
  - "clusters"            — cluster a cohort into k forward-return
                              groups (needs cohort_id; horizon, k)

Supply cohort_id (preferred, anchor inherited) OR explicit
symbol+date for the symbol-needing metrics.

Args:
    metric: see list above
    cohort_id: handle from `search` or `cohort` (required for
        decompose, clusters; preferred for symbol-needing metrics)
    symbol, date: explicit anchor when no cohort_id available
    extra_args: per-metric optional kwargs (see metric list)
    horizon: forward horizon in trading days (decompose, clusters,
        regime_accuracy)
    max_slices: max returned slice conditions (decompose)
    explain_slices: include Haiku narrative tying slices together
        (decompose)
    k: cluster count override (clusters; default chosen automatically)

target accepts four shapes:
  - "market" (default): SPY/QQQ regime + sector rotation +
                          breadth + macro
  - "SYMBOL" (e.g. "NVDA"): ticker metadata + sector + market cap
  - {"symbol": "NVDA", "date": "2024-08-05"}: anchor metadata —
    sector, cap, point-in-time regime, news, days_since_earnings,
    etc. Lightweight; no kNN.
  - "system": DB coverage stats (embedding count, daily bar count,
    date range)

Args:
    target: "market" | "SYMBOL" | {symbol, date} | "system"

Two modes:

  mode="pulse" (default):
    Single-symbol narrative pulse — frequency anomaly, tone shift,
    sentiment-price misalignment (priced-in vs narrative-change),
    FinBERT sentiment composite. Surfaces catalysts that price
    hasn't yet reflected. Needs symbol.

  mode="alerts":
    Market-wide narrative anomalies — top tickers right now where
    sentiment and price are most divergent. Default min_pulse 0.30,
    limit 30.

Args:
    mode: "pulse" | "alerts"
    symbol: ticker (mode="pulse" only)
    min_pulse: minimum narrative_change_score threshold
        (mode="alerts")
    limit: max alerts returned (mode="alerts")

style values:
  - "filter_ranking"    — rank candidate filters by how much each
                          one shifts the distribution at the given
                          horizon. Use to discover conditional
                          structure before calling `cohort` with the
                          winning filter.
  - "prose"             — plain-English summary of the cohort
                          outcome (Claude Haiku).
  - "position_guidance" — exit-signal recommendation for an open
                          position. Derives symbol+entry_date from
                          the cohort anchor.
  - "risk_ranking"      — today's risk-adjusted picks (Sharpe-like)
                          from forward tests.

Args:
    cohort_id: handle from `search` or `cohort`
    style: see list above (default "filter_ranking")
    horizon: forward horizon in trading days (default 5)

Two modes:

  mode="basic" (default):
    Multi-holding conditional distribution. Runs per-holding cohorts
    in parallel, weight-averages the distributions, ranks tail
    contributors (weight × p10, most negative first). PM-agent
    primitive. Pass holdings=[{symbol, weight, date}].

  mode="symbol_intel":
    Per-symbol track record + Layer 5 memory — what does Chart
    Library know about this single symbol across all prior
    analyses? Returns prior cohort_observations, feature_reliability
    learned for the symbol, and the symbol's per-pattern accuracy
    history. Pass symbol=X, lookback_days=N.

Args:
    holdings: list of {symbol, weight, date} (mode="basic")
    symbol: ticker (mode="symbol_intel")
    mode: "basic" | "symbol_intel"
    horizons: forward horizons (mode="basic"; default [5, 10])
    top_k_per_holding: cohort size per holding (mode="basic")
    include_path_stats: include MAE/MFE (mode="basic"; slower)
    lookback_days: history window (mode="symbol_intel"; default 365)

Composes cohort_analyze (depth=full) + anchor metadata + Layer 5 memory
(symbol_intelligence) + narrative pulse into a single structured brief.

── HOW TO TURN THIS INTO A GOOD ANSWER ──────────────────────────
Read `summary` first. It contains deterministic classification flags:

    verdict_class:    bullish | lean_bull | coin_flip | lean_bear | bearish | broken
    edge_class:       trivial | small | meaningful | large
    regime_alignment: tailwind | neutral | headwind
    sample_quality:   thin | ok | strong
    conviction:       low | med | high
    swing_factors:    [ { factor, direction, framing } ]
    caveat_flags:     [ thin_in_regime_sample, regime_was_derived, ... ]

Paraphrase the `framing` strings in your OWN voice — do not quote them
verbatim. Cite the raw numbers in parentheses, don't enumerate every
structured field. Lead with the verdict, then the context, then the
swing factors as things to watch, then conviction.

Example (your voice may differ):
  "Honestly, this NVDA setup is a coin flip. In-regime cohort (n=21)
   printed +0.09% median over 5d (52% wins) — basically identical to
   other regimes (+0.27%, 52%). Sector is lagging hard (-10.4 RS),
   which is muting reads. Soft sample size — directional, not thesis."

── RESPONSE STRUCTURE ───────────────────────────────────────────
  summary                       (read this first — see above)
  current_regime                (anchor's regime label + features)
  cohort_total                  (all analogs, all regimes)
  in_current_regime             (subset matching the anchor's regime)
  outside_current_regime        (rest, weighted average)
  conditional_edge              (median_lift_pp + win_rate_lift_pp)
  thesis_invalidation_triggers  (top 5 features, narrative-ready with
                                 interpretation strings — quote these
                                 when explaining what would flip the read)
  feature_importance            (top 20 features ranked by within-cohort
                                 importance, compact shape — use this
                                 when the user asks about a specific
                                 feature or you need depth beyond the
                                 top 5. Mirrors the full attribution
                                 view the /intelligence UI shows.)
  n_features_total              (count of all features computed; if
                                 greater than 20 the rest are available
                                 via /api/v1/cohort_analyze directly)
  memory_context                (Layer 5 prior observations)
  narrative_context             (news pulse)
  conviction                    (legacy — same as summary.conviction)

When to use this vs the primitives:
  - decision_brief: agents asking "what should I know about this anchor?"
  - cohort (depth='full'): when you need full feature_importance / raw stats
  - analyze (metric=...): single metric drill-downs

Args:
    symbol, date, timeframe: anchor (timeframe default "1h" — current; "1d" lags ~3 days)
    cohort_size: target K (default 300)
    horizon_days: forward horizon for the headline read (default 5)
    include_memory: include Layer 5 prior-observations context (default True)
    include_narrative: include news pulse / narrative-change context (default True)

Use this when something looks wrong (unexpected response shape,
surprising statistics, an error you can describe), or when you
spot a missing capability that would have unblocked you. Reports
land in Graham's inbox and feed the roadmap.

Args:
    message: free-text description (required)
    endpoint: which API endpoint, if any (e.g. "cohort_analyze")
    symbol: associated ticker, if any
    severity: "low" | "medium" | "high"

Layer 3 cohort intelligence. Forwarded to cohort(depth="full").