GammaRips Options Intelligence

Next scheduled earnings date for a ticker, and — given an expiration or an OCC contract — whether that print lands ON OR BEFORE the expiration (`earnings_in_window`). This is the doctrine hard-exclusion check: never hold a long single-leg option through earnings (IV crush). The engine applies this rail only at its own pick time, NOT in the pool — pool rows CAN carry earnings-window names, so check every candidate yourself. One call per candidate: pass the pool's `recommended_contract` verbatim a…

RESEARCH / POWER-USER tool. If you just need what a field MEANS, `get_signal_explainer` is the everyday path — this is the formal contract for grounding research code. The substrate DATA CONTRACT, machine-readable: every column of the outcome/label substrate with its leakage classification and as-of boundary, plus the exact column set exposed by the point-in-time features view (what `get_pool_features` serves). Classifications: identity | feature | label | opportunity | regime_telemetry. Only `f…

The curated candidate pool for a scan date — AI-enriched signals with news, technicals, catalyst context, a delta-targeted recommended contract, and (since 2026-06) the 60-day momentum feature `mom_60`. Enrichment gate: `overnight_score >= 4` AND directional UOA > $500K, then edge-ranked to the top ~50 BULLISH names. This is the pool the engine's own selection works from; your agent should treat it as the daily candidate set and reason to its OWN contract (see get_playbook("run-your-own-tourname…

Top N enriched signals for the most recent scan, with minimal fields. Used for public/freemium teasers: ticker, direction, score, headline, directional UOA dollar volume. No contract specifics or full thesis — use get_signal_detail for that. Args: limit: How many preview rows to return (default 5, max 20). Returns: List of {ticker, direction, overnight_score, call_dollar_volume, put_dollar_volume, key_headline, scan_date}.

The HARVEST CURVE — for each profit target X, the probability a pool contract's premium TOUCHED +X% at least once inside the 3-trading-day excursion window (10:00 ET entry), with confidence intervals, which day the peak landed on, and stop-touch rates. Computed live from the closed- window opportunity surface, so it moves as data accrues. This is the ceiling for any limit-at-+X% exit: a TOUCH IS NOT A FILL (bar- high events, no exit slippage). Measured context (2026-07-06 study): about half of c…

Aggregate realized paper-trading performance (the engine's RECEIPTS) over a lookback window — one tournament pick per day, real-fill simulation. Defaults to the LIVE cohort (`V7_1_TILTED_GIGO`, since 2026-06-26: enter 10:00 ET day after scan, +40% target / -30% stop, flat 15:45 ET same day). The cohort is young — expect small N; small-N aggregates are noise-heavy and should be quoted with their N. Pass policy_version="all" to see all eras (different exit mechanics — comparison is on you). Realiz…

Returns whether the US equity market is open today + the next open/close. Uses pandas_market_calendars (NYSE) so it knows about holidays + early closes deterministically — eliminates the chat-agent "is the market open?" hallucination class. Returns: { "is_open_today": bool, "current_date": "YYYY-MM-DD" (Eastern), "current_time_et": "ISO8601" (Eastern), "next_open": "ISO8601" (Eastern, schedule open boundary), "next_close": "ISO8601" (Eastern, schedule close boundary), "is_holiday": bool, "holida…

The OPPORTUNITY SURFACE — per-contract realized excursions of the option premium over a fixed multi-day window with NO exit rule applied. This is "profit potential with the exit left as a free variable": your agent derives any entry/exit policy offline from these extremes. Per contract: `opp_peak_return` (max favorable excursion / MFE) and `opp_trough_return` (max adverse excursion / MAE) as FRACTIONS of the 10:00 ET entry cost basis (0.40 = +40%), `opp_minutes_to_peak/trough` (minutes from entr…

Aggregate realized-label statistics over the full labeled pool, optionally grouped by a whitelisted feature dimension. The exploration companion to `query_outcomes` — use it to see how outcomes distribute before pulling row-level data. Per group: n, win_rate (label > 0), avg/median/p25/p75 of the label, avg MFE (`opp_peak_return`) and avg MAE (`opp_trough_return`). Labels and excursions are FRACTIONS (0.40 = +40%). IMPORTANT: the whole-pool composite under any fixed exit is NEGATIVE by design of…

Raw overnight scanner signals for a scan date — the wide net BEFORE curation. Use this to see where unusual options activity concentrated overnight across the full scan universe. The curated, enriched pool (what the engine actually works from) is `get_enriched_signals`.

Fetch one methodology playbook (markdown) by name. Start with `start-here`. Use `list_playbooks` to see everything published. Playbooks are living documents — re-fetch rather than caching long-term; the `changelog` playbook records dated methodology/data changes. Args: name: Playbook name as returned by `list_playbooks` (e.g. "start-here", "daily-workflow", "run-your-own-tournament", "exit-lab", "leakage-and-data-contract", "changelog"). Returns: {name, title, content} — content is markdown.

Point-in-time FEATURE VECTORS for the labeled candidate pool, served from the leakage-safe allowlist view `enriched_features_v1` (identity + features + cohort metadata only — no outcome, label, or telemetry column can appear here by construction). This is the quantitative substrate for research and for joining against `query_outcomes` / `get_opportunity_surface`. NOTE: the labeled substrate lags the live pool by ~1-2 trading days (rows appear once the same-day replay has run). For TODAY'S live p…

Latest liquidity snapshot for the WHOLE current pool (or your shortlist) in ONE call — the batch companion to `get_contract_snapshot`. The engine re-reads every pool contract's open interest, session volume, last trade, day range, and underlying price every ~10 minutes during market hours (plus one pre-open pass); this returns the most recent read per contract, each with explicit `as_of` provenance. Built for the ~10:00 ET decision window: one call replaces N per-contract fetches at the busiest …

The RECEIPTS — realized (closed) paper trades from the engine's own daily selection, row-level. One tournament pick per day, simulated with real fills under the bracket policy live at the time. Realized-only by construction: rows appear only after the trade's exit, never same-day, so this tool cannot front-run the engine's private selection. No-trade days are reported separately in `skip_days` (they are part of the honest track record); invalid-liquidity rows are excluded. Live policy (`V7_1_TIL…

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. V…

List available reports, most recent first. Repeated titles across dates are deduplicated (the generator occasionally reuses a headline) — each title appears once, at its most recent scan_date. Args: limit: Number of reports to return (default 10). Returns: List of {scan_date, title, created_at}.

Deep dive on a single ticker's enriched signal — thesis, catalyst, the recommended contract, and point-in-time features. Served from the leakage-safe enriched view. By default the extra-long narrative fields (news_summary, flow_intent_reasoning) are omitted to keep the response tight — the thesis and all decision fields are always included. Pass `full=true` for everything. If the ticker is not in the pool for the requested date, the error lists the recent dates on which it DOES appear.

Return a plain-English definition + role of a GammaRips signal field. Deterministic lookup table — no LLM, no hallucination. Use this for the "what does X mean?" pattern when a chat user asks about a metric we surfaced. If the field isn't in our dictionary, returns an "unknown" row rather than guessing. Args: field_name: Field name as it appears in tool responses (e.g., "premium_score", "volume_oi_ratio", "recommended_contract"). Returns: {field_name, label, definition, how_used, available_field…

UNDERLYING-STOCK directional outcomes for the broad enriched pool — did the direction call work on the stock over the 3-day forward window? This is NOT option PnL. On the same pool, the underlying moving the right way (~54%) does not mean the option made money (~41%) — theta, IV and the exit bracket eat the difference. For realized OPTION trades use `get_position_history`; for the full-pool option labels use `query_outcomes`. Args: scan_date: Filter by date (YYYY-MM-DD). ticker: Filter to specif…

Aggregate UNDERLYING-STOCK direction statistics for the broad enriched pool over a lookback window. This win rate answers "how often was the direction call right on the STOCK" — it is NOT an option-PnL win rate and NOT the paper-trading track record. For those use `get_historical_performance` (realized option trades) or `get_outcome_summary` (full-pool option labels). There is deliberately NO bare `win_rate` field in the response: the headline is `underlying_direction_win_rate` (and bull_/bear_ …

List the methodology playbooks this server publishes. Playbooks are versioned server-side documentation of HOW to use the data tools: the daily workflow, the run-your-own-tournament selection pattern, the exit lab, and the data contract / leakage rules. Fetch one with `get_playbook(name)`. Returns: List of {name, title, summary}.

Row-level REALIZED LABELS for the full candidate pool, joined to their point-in-time feature vectors. Ask questions like "how did pool contracts with |delta| 0.20-0.46 behave under the same-day bracket?" Two distinct label horizons — never pooled together: * `same_day`: the live V7.1 GIGO bracket (enter 10:00 ET day after scan, +40% target / -30% stop, flat 15:45 ET same day). Label = `realized_return_pct` (FRACTION). * `3d`: the legacy 3-trading-day companion bracket (+80% / -60%, exit 15:50 ET…

INTRADAY minute path for one option contract on one session — the exact tape an intraday entry/exit rule replays against (RM-002). 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: when each level was first touched and which came first — measured from the tape, not inferred from extremes. Pool contracts' excursion windows (entry day + 2 sessions) are served from the engine's minute-path table; anything…

Performs a Google Web Search using the Custom Search JSON API via direct HTTP requests. Useful for finding real-time information, news, or verifying facts (grounding). Args: query: The search query string. num_results: Number of results to return (default 5, max 10). Returns: A formatted string containing the top search results (Title, Snippet, Link).