feat(options-gps): market line shopping — multi-exchange divergence comparison

[MkDev11]

Summary

Adds Market Line Shopping to Options GPS — compares Synth's theoretical option prices against multiple exchanges (Aevo, Deribit, OKX) to identify market divergence, like a sports bettor "shopping for lines" to find an edge. Exchange divergence is visualized on the Market Context screen (Screen 1b) and used to refine the Confidence metric that drives Screens 1 and 2.

What's included:

• exchanges.py — Pluggable ExchangeProvider abstraction with three mock providers (Aevo, Deribit, OKX), each with a distinct pricing personality. Computes per-exchange divergence metrics: avg/max absolute divergence, signed call/put divergence vs Synth fair value. Reads AEVO_API_KEY, DERIBIT_CLIENT_ID, DERIBIT_CLIENT_SECRET from env so real adapters can be plugged in later; defaults to mock-only mode.
• Confidence metric integration — adjust_confidence_for_divergence() in pipeline.py nudges confidence based on market consensus: strong agreement (+0.05), moderate (no change), weak (−0.03), disagreement (−0.07). Contextual overlay, not a hard guardrail.
• CLI visualization — "MARKET LINE SHOPPING" block on Screen 1b showing consensus classification and per-exchange divergence summary (e.g., Aevo: avg |Δ| 2.8pp, max 7.2pp; calls +3.1pp, puts -2.2pp vs Synth).
• Decision log — market_lines JSON section with consensus, avg/max divergence, and per-exchange breakdown.
• 24 new tests covering divergence computation, mock provider behavior, consensus classification, confidence adjustment boundaries, edge cases (zero prices, empty data, failing providers), and end-to-end integration.

Related Issues

Closes #32

Type of Change

• Bug fix
• Improvement to existing tool
• Documentation
• Other (describe below)

Testing

• Tested against Synth API
• Manually tested
• Tests added/updated

Test command: python -m pytest tools/options-gps/tests/ -v
Result: 104 passed (80 existing + 24 new) in 0.14s

Manual verification: Ran python tools/options-gps/main.py --symbol BTC --view bullish --risk medium --no-prompt --screen 1 — confirmed MARKET LINE SHOPPING block renders on Screen 1b with per-exchange divergence, consensus label, and adjusted confidence in decision log.

Checklist

• Code follows project style guidelines
• Self-review completed
• Changes are documented (if applicable)

Files Changed

File	Change
tools/options-gps/exchanges.py	New — Exchange abstraction, mock providers, divergence computation
tools/options-gps/pipeline.py	Added adjust_confidence_for_divergence()
tools/options-gps/main.py	Wired exchange divergence into pipeline, Screen 1b display, decision log
tools/options-gps/tests/test_exchanges.py	New — 24 tests for exchange divergence + confidence adjustment
tools/options-gps/README.md	Added Market Line Shopping documentation section

Demo Video

11.03.2026_12.15.40_REC.mp4

[ventura-oss]

1. Live Execution Requirement: The tool must move past detecting environment variables to actual network execution. If API keys are present, the end output must be functional, real-time quotes from Aevo, Deribit, etc.

2. High-Signal UI (Handoff for Execution): The data presentation must be actionable at a glance without manual calculation. The UI should explicitly "point to the winner" by highlighting the venue offering the best execution price for the chosen strategy. This is a critical requirement as this tool will transition into an automated execution layer next.

3. Edge Detection (Alpha over Agreement): Alpha is found in disagreement, not consensus. Higher divergence from the market consensus should drive higher conviction/confidence in the trade. This should be modeled statistically (Standard Deviation/Z-score) to quantify how far Synth deviates from the market mean.

[ventura-oss]

Closing this in favor of the implementation in PR #39. Thank you for the contribution!