Aggressive Options Agent

Event intelligence → dual tiering → threshold-hit optimisation. The system researches scheduled catalysts, scores impact separately from trade opportunity, and uses deterministic simulation and risk gates to choose only paper trades that improve the weighted chance of hitting the tournament threshold. AI gathers and explains evidence; it never sizes or submits an order. The architecture and risk policy live in AGGRESSIVE_PLAN.md.

Block 0 scope

• One dedicated Alpaca paper account is the system of record.
• MVP catalysts: scheduled US macro releases and confirmed corporate earnings.
• Supported structures: long calls/puts/strangles for underpriced movement and defined-risk iron condors for sufficiently overpriced movement. Naked short options remain prohibited.
• Backspreads remain disabled until the complete research-to-execution path passes its tests.
• AI researches events and explains tiers; deterministic code owns metrics, sizing and order gates.

Local setup

cp .env.example .env
chmod 600 .env
uv sync --dev
uv run alpaca-account-check

Do not replace an existing .env when following the example above. The account check prints only non-secret capabilities and never prints API credentials or account identifiers.

Alpaca MCP

The project-scoped Codex configuration starts Alpaca's official MCP server through scripts/run_alpaca_mcp.py. The wrapper reads the ignored .env, maps the existing credential names to the MCP server's expected names, forces paper mode, and enables only the account, trading, asset, stock/options data, corporate-action and news toolsets.

Restart Codex after first setup, then inspect MCP servers in the app. Write-capable MCP tools should remain approval-gated. Direct application execution still passes through deterministic order guards.

Block 1 state contracts

• Domain models reject undeclared fields and naive datetimes, and enforce deterministic tier labels.
• The event-research and event-tiering trust boundaries use version-controlled JSON schemas in schemas/; invalid AI output is vetoed and recorded in the append-only journal.
• Stable IDs are derived by code from normalized event, decision and structure identities.
• Events, tier revisions, quotes, trade records and journal entries use locked append-only JSONL.
• The latest performance snapshot uses a locked, atomic JSON replacement.

Regenerate schemas and run the full validation suite with:

uv run python scripts/export_schemas.py
uv run ruff check .
uv run pytest -q

Implementation status and validation evidence are in docs/BLOCK0_STATUS.md and docs/BLOCK1_STATUS.md.

Block 2 market and event data

• Alpaca IEX daily bars normalize into provenance-carrying records used for returns, realized volatility and close-to-next-open event gaps.
• yfinance option chains normalize missing IV, volume, open interest, quote size and timestamps without inventing values. Alpaca's indicative chain provides a secondary coverage check.
• Deterministic quote quality vetoes stale, crossed, locked, wide or materially conflicting markets. Low OI/volume are visible score penalties rather than vetoes; absent displayed size is capped at one paper contract.
• Official event adapters cover the BLS calendar, corporate investor-relations pages and SEC filing evidence. The demo calendar reads the verified fixture without network access.
• Live and offline validation evidence is in docs/BLOCK2_STATUS.md.

Run the read-only live checks with:

uv run python scripts/validate_block2_live.py --external
uv run python scripts/validate_event_sources_live.py
# Run during 09:30-16:00 ET; prints veto histograms and never sends an order.
uv run python scripts/diagnose_live_quote_quality.py AVGO SPY

Block 3 event intelligence

• In paper mode, an AI discovery pass searches the configured competition universe every six hours, persists source-linked candidates, and keeps them estimated until independently confirmed.
• The scheduler exposes discovery, T−48h, T−6h, T−30m freeze, T+15m and next-session states.
• Live research uses two bounded calls: web search first, then a separate forced schema submission. Code controls validation, revisions and freshness times.
• Every persisted timestamp, asset list and numeric value must map to evidence that explicitly supports its field path. Unsupported URLs and claims become journalled vetoes.
• The live provider uses an OpenAI-compatible Responses API with web search; offline fixture mode requires no LLM key and powers deterministic tests/dashboard demos.

To enable live research, add these values only to the ignored .env:

DEEPSEEK_API_KEY=your_deepseek_api_key
LLM_BASE_URL=https://api.deepseek.com
EVENT_INTELLIGENCE_MODEL=deepseek-v4-flash
EVENT_TIERING_MODEL=deepseek-v4-flash

Run the safe offline three-event validation with:

uv run python scripts/validate_block3_demo.py

Implementation and manual citation/time checks are recorded in docs/BLOCK3_STATUS.md.

Block 4 signals and event tiers

• The implied-move screen uses fresh paired call/put bid-ask midpoints at the nearest common strike.
• A missing executable same-strike ATM call/put pair is reported explicitly as invalid_atm_pair, rather than being hidden inside the generic bad_quote category.
• Historical absolute event gaps receive recency weights and shrink toward an explicit sector prior; the packet retains a lower/upper uncertainty interval.
• The screener combines evidence freshness, expiry, quote quality, source agreement, liquidity, spread and risk-gate checks. Narrative evidence conflicts and low OI/volume reduce numeric confidence/opportunity; only hard execution or timing failures force opportunity tier X.
• Impact and opportunity are independent deterministic scores. The AI can explain qualitative modifiers and conflicts but cannot modify scores, confidence, vetoes, structures or orders.
• Long volatility requires forecast median / implied move ≥ 1.15. Short volatility requires implied move / forecast upper bound ≥ 1.20 and uses a four-leg iron condor with bought protective wings.
• The Block 5 portfolio risk gate fails closed by default. The Block 4 A demo uses an explicitly passed synthetic gate and is not permission to execute an order.

Run the offline contrast demo with:

uv run python scripts/validate_block4_demo.py

Implementation details and validation evidence are in docs/BLOCK4_STATUS.md.

Block 5 tournament engine and execution

• Threshold scenarios retain attributable update history and account for current return.
• Exact option payoff paths feed a seeded correlated simulation that maximizes incremental weighted threshold-hit probability under liquidity and defined-risk caps.
• Credit structures are sized against maximum wing loss, monitored as one multi-leg position, take profit after retaining 50% of entry credit, and stop when loss reaches 100% of entry credit.
• Every order passes deterministic preflight. Client order IDs are stable, so restarted or duplicate cycles reconcile instead of submitting twice.
• Monitoring covers partial fills, cancel/replace, expiry exits and the Friday 10:45 ET hard flatten.
• Agent token totals and estimated cost are persisted for a discreet dashboard corner monitor; the provider/model name is intentionally not displayed.

Set the two generic per-million-token rates in .env to keep cost estimates current. Run the safe offline execution validation with:

uv run python scripts/validate_block5_demo.py

Implementation details and validation evidence are in docs/BLOCK5_STATUS.md.

Block 6 metrics and operating console

The dashboard includes Events, Performance, Decisions & Audit and System Health. Its Events table always shows the official upcoming calendar plus accepted AI-discovered candidates, even when a research dossier is still awaiting work or has failed. Metrics are grouped by complete trade_id, shadow positions use executable bid/ask prices, and every view shows freshness rather than silently treating old data as current. Order controls remain read-only. Its single write control is an authenticated, rate-limited Run research now queue for a selected scheduled event.

Run it locally with:

uv run streamlit run src/aggressive_options_agent/ui/app.py

For a persistent deployment, set STATE_ROOT=/app/state and mount the durable volume there. The dashboard only persists a research request; the slow intelligence worker consumes it and performs dossier research. The independent market worker explicitly defers any order for five minutes after a manual refresh. Stopping the web process does not stop either worker or change a paper order.

Run the populated offline console validation with:

uv run python scripts/validate_block6_demo.py

Implementation details and validation evidence are in docs/BLOCK6_STATUS.md.

Block 7 autonomous runner

The restart-safe runtime has two loops. The slow intelligence loop discovers events and refreshes evidence at scheduled milestones. The fast market loop runs independently, polls confirmed events with declared monitoring windows, recalculates quote gates and scores, submits guard-approved paper orders, reconciles positions and writes metrics/health. It caches the external reference chain for five minutes and writes a fail-closed pending tier when a dossier needs explanation. The slow worker resolves that explanation once per dossier revision, so live quote changes never trigger an LLM call. The committed defaults are deliberately safe: fixture data and no broker submission.

# Full offline research → tiering → simulation → guard → mock order → metrics → UI replay
uv run python scripts/validate_block7_replay.py

# One safe fixture cycle
uv run aggressive-runner --once

# Continuous fixture loop
uv run aggressive-runner

# The two production worker roles supervised by scripts/start_railway.py
uv run aggressive-runner --role intelligence
uv run aggressive-runner --role market

Paper submission requires all three conditions: RUNNER_MODE=paper, the Alpaca paper domain, and ENABLE_PAPER_ORDER_SUBMISSION=true. Leave the last flag false through deployment smoke testing.

Railway preparation and the exact activation sequence are in docs/RAILWAY_DEPLOYMENT.md. Block 7 evidence is in docs/BLOCK7_STATUS.md.

Material limitations and competition disclosure

• This is tournament-specific, aggressively sized paper trading, not investment advice and not a strategy calibrated for normal capital preservation.
• Alpaca option-chain data used here may be indicative. Source disagreement and stale/illiquid quotes fail closed, but indicative data can still differ from an executable market.
• Offline demos use synthetic quotes and synthetic paper fills. Their P&L proves plumbing only and is not live performance or evidence of profitability.
• Shadow P&L liquidates longs at bid and shorts at ask using timestamped quotes. It is a conservative estimate, not a broker fill or guaranteed liquidation value.
• AI research can be wrong or unavailable. Strict schemas, evidence binding and deterministic vetoes reduce that risk; they do not eliminate it.