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), 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.

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)

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").