The GammaRips candidate pool for a scan date. One tool, four `view`s:

  * view="enriched" (DEFAULT) — the AI-enriched pool: news, technicals,
    catalyst, the recommended contract (an OTM call chosen on contract
    liquidity), and the 60-day momentum feature `mom_60`. Funnel for
    scan_date >= 2026-08-24 (liquid-universe era): the 100 most liquid
    optionable names, BULLISH only, one call each, roughly 40-50 rows.
    Liquidity decides membership, not unusual activity; the $500K UOA
    floor is retired and `overnight_score>=1` is a cosmetic floor.
    Earlier scan dates come from the prior UOA-gated funnel (UOA>$500K,
    top-50 BULLISH); the two eras are not one population.
    This is the daily candidate set your agent reasons over to its OWN
    contract (see get_playbook("run-your-own-tournament")). Served from a
    leakage-safe view (forward-outcome columns physically stripped);
    `summary=True` gives ~21 decision columns, `fields=[...]` a strict
    projection, `summary=False` full rows, `offset` pages.
  * view="raw" — the wide overnight scan BEFORE the pool cut (the ranked
    liquid universe for scan_date >= 2026-08-24; the market-wide
    unusual-activity scan for earlier dates). Honors `direction`,
    `min_score`, `ticker`, `limit`.
  * view="features" — point-in-time FEATURE VECTORS from the leakage-safe
    allowlist view `enriched_features_v1` (identity + features + cohort
    metadata only; no outcome/label/telemetry column can appear). The
    quantitative substrate for joining against query_outcomes. Lags the
    live pool by ~1-2 trading days.
  * view="preview" — a minimal public teaser (ticker, direction, score,
    headline, directional UOA) for the most recent scan; no contract
    specifics or thesis.

TIER: view="preview" is FREE (no key). The enriched / raw / features views
are the paid product — they require an active pro subscription key; an anon
call to them returns `subscription_required` (get_pool(view='preview') is
named as the free entry point).

Liquidity caveat (all views): `recommended_oi`/`recommended_volume` are
scan-time snapshots, not live values; `recommended_spread_pct` is
permanently NULL on the current data plan — re-check with get_liquidity.

Args:
    view: "enriched" (default) | "raw" | "features" | "preview".
    scan_date: YYYY-MM-DD (default: latest available scan for the view).
    direction: "bull"/"bear" prefix filter (enriched / raw).
    ticker: exact ticker filter (enriched / raw / features).
    min_score: overnight_score floor (raw view only; clamped 0-10).
    limit: max rows (enriched/raw clamp 1-50, features 1-100, preview 1-20).
    summary: enriched only — True=compact columns, False=full rows.
    fields: enriched only — explicit strict column projection.
    offset: enriched only — pagination offset.

Deep dive on a single ticker/contract. Two `view`s:

  * view="detail" (DEFAULT) — the full enriched signal for one ticker:
    thesis, catalyst, the recommended contract, and point-in-time
    features (leakage-safe view). `full=true` includes the long narrative
    (news_summary, flow_intent_reasoning). If the ticker isn't in the
    pool for the date, the error lists the dates on which it does appear.
  * view="earnings" — the doctrine earnings-window check (RM-003): the
    next scheduled earnings date and whether it lands ON OR BEFORE the
    contract expiration (`earnings_in_window`). The engine applies this
    rail only at its own pick time, NOT in the pool, so pool rows CAN
    carry earnings-window names — check every candidate yourself. Pass
    the pool's `recommended_contract` and both ticker and expiration are
    derived. FAIL-CLOSED: unknown date -> earnings_in_window=null, treat
    as in-window.

Args:
    ticker: underlying symbol (required for detail; optional for earnings
        if `contract` is given).
    view: "detail" (default) | "earnings".
    scan_date: detail only — YYYY-MM-DD (default: latest for the ticker).
    full: detail only — include the long narrative fields.
    expiration: earnings only — option expiration YYYY-MM-DD to test.
    contract: earnings only — OCC ticker supplying ticker+expiration.

FRESH (entry-day) liquidity — the read the pool's session-frozen
`recommended_oi`/`recommended_volume` cannot give you (the overnight sweep
only becomes OI the next morning). Two modes, chosen by whether you pass a
single `contract`:

  * `contract` given — ONE contract's snapshot: open interest, session
    volume, last trade, day range, underlying price, greeks. Cache-first
    (the engine re-reads the pool every ~10 min in market hours); pass
    live=true to force a fresh upstream fetch or read a contract NOT in
    today's pool.
  * `contract` omitted — the WHOLE current pool (or your `contracts`
    shortlist, max 60) in ONE call — the batch companion for the ~10:00 ET
    decision window. Most-recent read per contract with explicit `as_of`.

Deliberately serves NO bid/ask/mid/spread (not available on the current
data plan — absent, not NULL). Judge fill risk from open_interest (updates
once each morning), day_volume (live session), last_trade recency, and the
day range.

Args:
    contract: OCC ticker for the single-contract mode (verbatim from the
        pool's `recommended_contract`). Omit for the whole-pool batch.
    scan_date: pool date YYYY-MM-DD (batch mode; default: latest pool).
    contracts: optional shortlist filter for the batch mode (max 60).
    live: single-contract mode — force a fresh upstream fetch.

The realized-outcome + receipts substrate behind the engine. One tool,
nine `view`s. Whole-pool composites under any FIXED exit are NEGATIVE by
construction — these are a research surface (how outcomes distribute
across features and exits), never a strategy track record.

  * view="labels" (DEFAULT) — row-level realized bracket LABELS joined to
    point-in-time features. horizon "same_day" (live V7.1 GIGO +40/-30) or
    "3d" (legacy +80/-60) — never pooled. NULL-label and illiquid rows
    excluded (counts in meta). `aggregate_only=True` returns summary stats
    instead of rows. Filters: scan_date_from/to, ticker, delta_min/max,
    min_overnight_score, exit_reason.
  * view="summary" — grouped aggregates over the labeled pool. `group_by`
    one of none|delta_bucket|overnight_score|premium_score|exit_reason|
    day_of_week|moneyness_bucket.
  * view="surface" — the OPPORTUNITY SURFACE: per-contract realized MFE/MAE
    excursions with NO exit applied (profit potential, exit free). Uses
    scan_date OR a `days` lookback, `ticker`, `delta_min/max`,
    `include_open`. `aggregate_only=True` returns MFE/MAE quantiles over
    the FULL filtered set — use it for exit design. The row mode is capped
    at 200 and truncates oldest-first WITHIN a scan_date, so its oldest
    date is a highest-MFE-only slice; it reports `truncated`,
    `matched_rows`, and `partial_scan_date` so you can see that happen.
  * view="harvest" — the touch-probability curve: P(premium touched +X%)
    with CIs, day-of-peak buckets, stop-touch rates. `targets`, `stops`,
    date range, delta band.
  * view="exit_rule" — RESEARCH-ONLY "bring your exit, we score it":
    rule="bracket" (target_pct/stop_pct) or rule="trailing" (trail_pct,
    activation_pct) scored against the surface / minute tape.
  * view="signal_performance" — UNDERLYING-STOCK direction outcomes for
    the broad pool (NOT option PnL). Filters scan_date, ticker, direction,
    outcome.
  * view="win_rate" — aggregate UNDERLYING-direction win rate over `days`
    (NOT option PnL; headline key carries its universe).
  * view="positions" — the RECEIPTS: realized (closed) paper trades from
    the engine's own daily pick, row-level, cohort-filtered
    (`policy_version`, default live). Over `days`, `limit`.
  * view="performance" — cohort AGGREGATE of the receipts over `days`
    (win rate, avg/median/best/worst), `direction`, `min_premium_score`,
    `policy_version`. When the cohort has no closed trades, every aggregate
    is `null` and `total_trades` is 0 — NEVER 0.0. A `null` here means "not
    measured yet", not "zero percent"; do not render it as a result.

All returns are FRACTIONS (0.40 = +40%). Realized data serves closed
windows only. Paper-traded research data; not investment advice.

Args:
    view: which surface (see above). Default "labels".
    horizon: "same_day" | "3d" (labels/summary/exit_rule). If omitted, the
        native default per view is used: labels/summary => "same_day" (the
        live GIGO policy), exit_rule => "3d" (its excursion window).
    group_by: summary grouping dimension.
    scan_date / scan_date_from / scan_date_to: date filters (per view).
    ticker / direction / delta_min / delta_max / min_overnight_score /
        exit_reason / outcome: row/aggregate filters (per view).
    days: lookback window (surface/win_rate/positions/performance).
    limit: max rows (labels 1-200, signal_performance 1-50, positions 1-200).
    aggregate_only: labels/surface views — summary stats instead of rows.
        On `surface` this is also the only mode immune to the 200-row cap.
    include_open: surface view — include not-yet-closed windows.
    targets / stops: harvest view — PERCENT grids.
    target_pct / stop_pct / rule / trail_pct / activation_pct: exit_rule view.
    policy_version: positions/performance cohort filter. The live default
        is the PAIR (policy label + cohort start date) — the label alone
        does not define the cohort, since disowned cohorts remain in the
        ledger under the same label. Responses carry `cohort_start`; a zero
        row_count under the live cohort means it has not accrued closed
        trades yet, not that there is no track record, and the aggregates
        come back `null` rather than 0.0. Pass "all" for every era, but
        note that "all" returns cohorts the engine has REPUDIATED — not
        merely older exit mechanics — so it is not a track record and must
        not be aggregated into one. Read the response `note` before
        quoting any number from it.
    min_premium_score: performance view floor.

Raw option price data for YOUR OWN entry/exit rule. This server does NOT
simulate or validate exits — it returns bars (the RM-002/RM-004 boundary).
Two `granularity` modes:

  * granularity="minute" (DEFAULT) — the intraday minute path for one
    session (`date` required). Optionally pass a bracket (target_pct/
    stop_pct, PERCENT of the 10:00 ET anchor) and the response also reports
    the exact FIRST-CROSSING sequence measured from the tape. Pool
    excursion windows are served from the engine's minute-path table;
    anything else falls back to an upstream minute fetch.
  * granularity="day" — the DAILY mark series (OHLCV) over a date range,
    to mark a live paper position day by day or replay a closed one. Uses
    `from_date`/`to_date` (span capped at 120 days); `date` is ignored.

Option tape is THIN — minutes/days with no prints have no bar; treat
touch times as evidence, not tick-perfect truth. Paper-trade research
data; not investment advice.

Args:
    contract: OCC option ticker (e.g. "O:UNIT260717C00030000").
    date: minute mode — ET session date YYYY-MM-DD (required).
    granularity: "minute" (default) | "day".
    target_pct: minute mode — optional +X% level for first-crossing.
    stop_pct: minute mode — optional -Y% level for first-crossing.
    from_date: day mode — start YYYY-MM-DD (default: 30d before to_date).
    to_date: day mode — end YYYY-MM-DD inclusive (default: today ET).

Point-in-time market-regime context for a scan date: VIX close, VIX3M,
SPY trend state, and the 5-day VIX delta — all as-of <= scan_date (the
selection point, leakage-safe), plus the engine's regime safety rail
evaluated on those values.

The rail: the engine fail-closes (no trade) when spot VIX > VIX3M
(backwardation — the market pricing imminent volatility is an adverse
regime for short-dated directional longs).

Served from the labeled substrate, which lags the live pool by ~1-2
trading days. Values are constant per scan_date.

Args:
    scan_date: YYYY-MM-DD. Defaults to the latest scan date carrying
        regime features.

Returns:
    {scan_date, vix_at_scan, vix3m_at_enrich, spy_trend_at_scan,
     vix_5d_delta_at_scan, regime_rail_pass, rail_definition}

Market-calendar reference. Two `view`s:

  * view="status" (DEFAULT) — is the US equity market open today, plus the
    next open/close, holiday, and early-close flags (NYSE calendar,
    deterministic — no "is the market open?" hallucination).
  * view="scan_dates" — which recent scan dates have GammaRips data, with
    per-date signal counts (the pool's data-availability calendar).

Args:
    view: "status" (default) | "scan_dates".

Methodology + reference, versioned server-side (re-fetch rather than
caching long-term). Arg-driven:

  * `field` given — the plain-English DEFINITION + role of a signal field
    (deterministic lookup, no LLM). e.g. field="mom_60". The response's
    `available_fields` lists every documented field.
  * `name` given — a methodology playbook (markdown) by name, OR two
    special reference pages:
      - name="schema" (or "data-contract") -> the machine-readable
        substrate DATA CONTRACT: every outcome/label column with its
        leakage classification (feature|label|opportunity|
        regime_telemetry|identity) and as-of boundary. Only `feature`
        columns are safe as selection inputs.
      - any other name -> the playbook markdown (start-here,
        daily-workflow, run-your-own-tournament, exit-lab,
        leakage-and-data-contract, changelog).
  * neither — the CATALOG of published playbooks (name/title/summary),
    plus a pointer to the field dict (`field=`) and schema page.

Args:
    name: playbook name, or "schema"/"data-contract" for the data contract.
    field: a signal field name to explain (overrides `name`).

The daily intelligence report. Two `view`s:

  * view="report" (DEFAULT) — the full report (title, markdown content,
    scan_date) for `date`, or the most recent report if `date` is omitted.
  * view="list" — recent reports, most recent first (scan_date, title,
    created_at), titles deduped. Use `limit`.

Args:
    date: report date YYYY-MM-DD (report view; default: most recent).
    view: "report" (default) | "list".
    limit: list view — how many reports (default 10, clamped 1-30).