Address starter model and replay issues

szeitner · szeitner · commit 98c8b063792f · 2026-06-15T16:53:05.000-07:00
Closes #1.\nCloses #2.\nCloses #3.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,7 +12,11 @@ by date and public-prep milestone.
 
 - Code of Conduct for community participation expectations.
 - GitHub social-preview source asset for sharing the project.
+- Model assumptions documentation covering volume-as-open-interest proxy, sign
+  convention, zero-gamma behavior, and known limitations.
 - Product vision notes for signature capabilities and contributor-facing ideas.
+- Synthetic ES 0DTE full-session replay dataset for no-credential testing.
+- Zero-gamma interpolation edge-case tests.
 
 ## 2026-06-12
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -57,6 +57,7 @@ You can also run the terminal with normalized replay data:
 
 ```bash
 gex-terminal --replay sample_data/demo_replay.jsonl
+gex-terminal --replay sample_data/es_synthetic_full_session.jsonl
 ```
 
 Demo and replay modes are useful for UI and engine work that should not require
diff --git a/README.md b/README.md
@@ -340,8 +340,13 @@ Run with normalized replay data:
 
 ```bash
 gex-terminal --replay sample_data/demo_replay.jsonl
+gex-terminal --replay sample_data/es_synthetic_full_session.jsonl
 ```
 
+`demo_replay.jsonl` is the shortest local fixture. `es_synthetic_full_session.jsonl`
+is a synthetic ES 0DTE replay that walks through open, mid-session, and
+late-session activity without requiring live credentials.
+
 Override `.env` settings from the command line:
 
 ```bash
@@ -413,6 +418,8 @@ pip install -e .
 - See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community expectations.
 - See [CHANGELOG.md](CHANGELOG.md) for notable project changes.
 - See [docs/adapters.md](docs/adapters.md) for the provider adapter contract.
+- See [docs/model-assumptions.md](docs/model-assumptions.md) for GEX model
+  assumptions and limitations.
 - See [docs/product-vision.md](docs/product-vision.md) for signature capability
   concepts and mockups.
 - See [ROADMAP.md](ROADMAP.md) for planned phases and future work.
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -26,7 +26,7 @@ dashboard and more like a focused market-structure workstation. See
   risk-free rate, expiry target, provider, and update interval.
 - [x] Improve startup validation so missing credentials or unsupported provider
   settings fail with clear messages.
-- [ ] Document the current model assumptions, including the
+- [x] Document the current model assumptions, including the
   volume-as-open-interest proxy, call/put sign convention, and limitations versus
   proprietary dealer-positioning models.
 
@@ -99,7 +99,7 @@ dashboard and more like a focused market-structure workstation. See
 - [x] Add provider registry scaffolds for Databento, IBKR, and yfinance.
 - [x] Add issue templates for bugs, feature requests, and provider adapters.
 - [x] Add a security policy for credential-handling issues.
-- [ ] Publish sample replay datasets so new users can evaluate the app without
+- [x] Publish sample replay datasets so new users can evaluate the app without
   paid data.
 - [ ] Add contribution notes for normalized provider payload fixtures.
 - [ ] Add a small set of labeled good-first issues after the first public push.
@@ -126,7 +126,7 @@ dashboard and more like a focused market-structure workstation. See
 
 - Add tests for `IntradayGexEngine.calculate_gamma`.
 - Add tests for malformed JSON and missing fields in `StatefulGexConsumer`.
-- Add a small sample replay dataset.
+- Add additional replay datasets for different symbols, expirations, or regimes.
 - Improve terminal empty states before live data arrives.
 - Document a known Tradovate options-chain payload shape.
 - Add README screenshots once replay mode exists.
diff --git a/docs/adapters.md b/docs/adapters.md
@@ -69,10 +69,13 @@ The replay adapter reads normalized JSONL records from disk:
 
 ```bash
 gex-terminal --replay sample_data/demo_replay.jsonl
+gex-terminal --replay sample_data/es_synthetic_full_session.jsonl
 ```
 
 Replay files are the preferred way to reproduce UI and engine behavior without
-live credentials.
+live credentials. `demo_replay.jsonl` is a compact screenshot/demo fixture, while
+`es_synthetic_full_session.jsonl` simulates open, mid-session, and late-session
+ES 0DTE activity for contributor testing.
 
 ## Tradovate Adapter
 
diff --git a/docs/model-assumptions.md b/docs/model-assumptions.md
@@ -0,0 +1,118 @@
+# Model Assumptions
+
+`gex-terminal` estimates intraday gamma exposure for research and engineering
+experimentation. It is not financial advice, an execution signal, or a
+replacement for licensed market-data products.
+
+This document explains the current model assumptions so contributors can improve
+the calculation path without treating the output as a black box.
+
+## Current Model
+
+The engine calculates theoretical Black-Scholes gamma for each strike, then
+scales that gamma into dollar gamma exposure per 1% move in the underlying.
+
+Current inputs:
+
+- Current underlying spot or futures price.
+- Strike price.
+- Implied volatility.
+- Days to expiry.
+- Risk-free rate.
+- Contract multiplier.
+- Accumulated intraday call and put volume.
+
+The terminal then aggregates strike-level exposure into:
+
+- Total net GEX.
+- Gamma wall.
+- Call wall and put wall.
+- Zero-gamma node.
+- Concentration bands.
+- Call/put imbalance.
+
+## Volume-As-Open-Interest Proxy
+
+Official open interest is usually delayed and may not update throughout the
+session. For intraday research, `gex-terminal` currently uses cumulative session
+volume as a practical proxy for changing open interest.
+
+This makes the terminal responsive to live activity, but it also introduces
+important limitations:
+
+- Volume does not reveal whether trades opened or closed positions.
+- Volume can double-count churn at the same strike.
+- Volume does not distinguish customer flow from dealer flow.
+- Volume can overstate exposure during high-turnover sessions.
+- Low-volume strikes can appear less important than their true open interest
+  would imply.
+
+Future provider integrations should add official open interest when available
+and let users compare volume-weighted, open-interest-weighted, and hybrid views.
+
+## Call And Put Sign Convention
+
+The current model treats call exposure as positive and put exposure as negative:
+
+- Call GEX = `call_volume * gamma_scaling_factor`
+- Put GEX = `put_volume * gamma_scaling_factor * -1`
+- Net GEX = `call_gex + put_gex`
+
+This convention is simple and useful for building an explainable first model,
+but it is not a complete dealer-positioning model. In real markets, the sign of
+dealer hedging pressure depends on trade direction, customer/dealer positioning,
+inventory, and whether trades are opening or closing.
+
+Future work should add dealer/customer direction inference when a provider
+exposes enough trade context to support it.
+
+## Zero-Gamma Node
+
+The zero-gamma node is estimated from the strike-level net GEX array:
+
+- If a strike has exactly zero net GEX, that strike is returned.
+- If adjacent strikes change sign, the node is linearly interpolated between
+  those strikes.
+- If no sign change exists, the model falls back to the strike with the smallest
+  absolute net GEX.
+
+This makes the output deterministic and stable for replay data, but it should be
+read as a structural estimate rather than an exact market boundary.
+
+## Gamma Wall And Concentration
+
+The gamma wall is the strike with the largest absolute net GEX concentration.
+The call wall and put wall are based on the largest call-side and put-side
+exposure respectively.
+
+The concentration band reports the smallest strike range that contains a target
+share of absolute net GEX. This is intended to show whether exposure is tightly
+clustered or spread across the chain.
+
+## Known Limitations
+
+Current limitations versus more mature commercial dealer-positioning tools:
+
+- No official open-interest ingestion yet.
+- No dealer/customer trade-direction model yet.
+- No opening/closing trade classification.
+- No vanna, charm, delta exposure, vega exposure, or theta exposure yet.
+- Live option-chain discovery still depends on provider-specific implementation
+  work.
+- Market-maker inventory and proprietary positioning assumptions are not modeled.
+- The model does not account for all expiration-specific, settlement, or
+  exchange microstructure details.
+
+These limits are intentional to document. The project should prefer a transparent
+model that contributors can inspect and improve over opaque confidence.
+
+## Contributor Guidance
+
+When changing model behavior:
+
+- Add deterministic tests for the exact assumption being changed.
+- Update this document when formulas, signs, inputs, or fallback behavior change.
+- Include replay or fixture data when the change depends on provider payloads.
+- Keep provider-specific parsing outside the engine.
+- Avoid presenting modeled levels as financial advice or guaranteed support and
+  resistance.
diff --git a/gex_terminal/table_rows.py b/gex_terminal/table_rows.py
@@ -0,0 +1,24 @@
+def arrange_rows(rows, sort_mode, filter_mode, spot, max_volume):
+    """Filter then sort the matrix rows."""
+    return sort_rows(filter_rows(rows, filter_mode, spot, max_volume), sort_mode)
+
+
+def filter_rows(rows, filter_mode, spot, max_volume):
+    """Filter rows by mode. Never returns empty if input was non-empty."""
+    if filter_mode == "near" and spot:
+        window = max(spot * 0.01, 1.0)
+        subset = [row for row in rows if abs(row["strike"] - spot) <= window]
+        return subset or list(rows)
+    if filter_mode == "active" and max_volume:
+        threshold = max_volume * 0.25
+        subset = [row for row in rows if row["volume"] >= threshold]
+        return subset or list(rows)
+    return list(rows)
+
+
+def sort_rows(rows, sort_mode):
+    if sort_mode == "net":
+        return sorted(rows, key=lambda row: abs(row["net_gex"]), reverse=True)
+    if sort_mode == "volume":
+        return sorted(rows, key=lambda row: row["volume"], reverse=True)
+    return sorted(rows, key=lambda row: row["strike"])
diff --git a/gex_terminal/tui.py b/gex_terminal/tui.py
@@ -14,6 +14,7 @@
 from gex_terminal.consumer import StatefulGexConsumer
 from gex_terminal.engine import IntradayGexEngine
 from gex_terminal.snapshot import build_snapshot, write_snapshot
+from gex_terminal.table_rows import arrange_rows, filter_rows, sort_rows
 
 
 class GexTerminalApp(App):
@@ -616,31 +617,16 @@ def _hex_status(status: str) -> str:
     @staticmethod
     def _arrange_rows(rows, sort_mode, filter_mode, spot, max_volume):
         """Filter then sort the matrix rows. Pure function for easy testing."""
-        return GexTerminalApp._sort_rows(
-            GexTerminalApp._filter_rows(rows, filter_mode, spot, max_volume),
-            sort_mode,
-        )
+        return arrange_rows(rows, sort_mode, filter_mode, spot, max_volume)
 
     @staticmethod
     def _filter_rows(rows, filter_mode, spot, max_volume):
         """Filter rows by mode. Never returns empty if input was non-empty (usability safety)."""
-        if filter_mode == "near" and spot:
-            window = max(spot * 0.01, 1.0)
-            subset = [row for row in rows if abs(row["strike"] - spot) <= window]
-            return subset or list(rows)
-        if filter_mode == "active" and max_volume:
-            threshold = max_volume * 0.25
-            subset = [row for row in rows if row["volume"] >= threshold]
-            return subset or list(rows)
-        return list(rows)
+        return filter_rows(rows, filter_mode, spot, max_volume)
 
     @staticmethod
     def _sort_rows(rows, sort_mode):
-        if sort_mode == "net":
-            return sorted(rows, key=lambda row: abs(row["net_gex"]), reverse=True)
-        if sort_mode == "volume":
-            return sorted(rows, key=lambda row: row["volume"], reverse=True)
-        return sorted(rows, key=lambda row: row["strike"])
+        return sort_rows(rows, sort_mode)
 
 
 async def run_mock_session():
diff --git a/sample_data/es_synthetic_full_session.jsonl b/sample_data/es_synthetic_full_session.jsonl
@@ -0,0 +1,31 @@
+{"type":"underlying_tick","symbol":"ES","price":5928.25,"timestamp":"2026-06-12T13:30:00Z","session_phase":"open"}
+{"type":"options_volume_tick","strike":5875,"option_type":"C","volume":180,"iv":0.185,"expiry":"0DTE","timestamp":"2026-06-12T13:30:05Z","session_phase":"open"}
+{"type":"options_volume_tick","strike":5875,"option_type":"P","volume":820,"iv":0.185,"expiry":"0DTE","timestamp":"2026-06-12T13:30:06Z","session_phase":"open"}
+{"type":"options_volume_tick","strike":5900,"option_type":"C","volume":420,"iv":0.172,"expiry":"0DTE","timestamp":"2026-06-12T13:30:10Z","session_phase":"open"}
+{"type":"options_volume_tick","strike":5900,"option_type":"P","volume":1240,"iv":0.172,"expiry":"0DTE","timestamp":"2026-06-12T13:30:11Z","session_phase":"open"}
+{"type":"options_volume_tick","strike":5925,"option_type":"C","volume":960,"iv":0.158,"expiry":"0DTE","timestamp":"2026-06-12T13:30:15Z","session_phase":"open"}
+{"type":"options_volume_tick","strike":5925,"option_type":"P","volume":1380,"iv":0.158,"expiry":"0DTE","timestamp":"2026-06-12T13:30:16Z","session_phase":"open"}
+{"type":"options_volume_tick","strike":5950,"option_type":"C","volume":1160,"iv":0.149,"expiry":"0DTE","timestamp":"2026-06-12T13:30:20Z","session_phase":"open"}
+{"type":"options_volume_tick","strike":5950,"option_type":"P","volume":760,"iv":0.149,"expiry":"0DTE","timestamp":"2026-06-12T13:30:21Z","session_phase":"open"}
+{"type":"underlying_tick","symbol":"ES","price":5941.50,"timestamp":"2026-06-12T15:15:00Z","session_phase":"mid"}
+{"type":"options_volume_tick","strike":5900,"option_type":"C","volume":780,"iv":0.165,"expiry":"0DTE","timestamp":"2026-06-12T15:15:05Z","session_phase":"mid"}
+{"type":"options_volume_tick","strike":5900,"option_type":"P","volume":640,"iv":0.165,"expiry":"0DTE","timestamp":"2026-06-12T15:15:06Z","session_phase":"mid"}
+{"type":"options_volume_tick","strike":5925,"option_type":"C","volume":1420,"iv":0.151,"expiry":"0DTE","timestamp":"2026-06-12T15:15:10Z","session_phase":"mid"}
+{"type":"options_volume_tick","strike":5925,"option_type":"P","volume":920,"iv":0.151,"expiry":"0DTE","timestamp":"2026-06-12T15:15:11Z","session_phase":"mid"}
+{"type":"options_volume_tick","strike":5950,"option_type":"C","volume":2120,"iv":0.142,"expiry":"0DTE","timestamp":"2026-06-12T15:15:15Z","session_phase":"mid"}
+{"type":"options_volume_tick","strike":5950,"option_type":"P","volume":700,"iv":0.142,"expiry":"0DTE","timestamp":"2026-06-12T15:15:16Z","session_phase":"mid"}
+{"type":"options_volume_tick","strike":5975,"option_type":"C","volume":1780,"iv":0.146,"expiry":"0DTE","timestamp":"2026-06-12T15:15:20Z","session_phase":"mid"}
+{"type":"options_volume_tick","strike":5975,"option_type":"P","volume":520,"iv":0.146,"expiry":"0DTE","timestamp":"2026-06-12T15:15:21Z","session_phase":"mid"}
+{"type":"options_volume_tick","strike":6000,"option_type":"C","volume":920,"iv":0.153,"expiry":"0DTE","timestamp":"2026-06-12T15:15:25Z","session_phase":"mid"}
+{"type":"options_volume_tick","strike":6000,"option_type":"P","volume":310,"iv":0.153,"expiry":"0DTE","timestamp":"2026-06-12T15:15:26Z","session_phase":"mid"}
+{"type":"underlying_tick","symbol":"ES","price":5962.75,"timestamp":"2026-06-12T19:45:00Z","session_phase":"late"}
+{"type":"options_volume_tick","strike":5925,"option_type":"C","volume":620,"iv":0.145,"expiry":"0DTE","timestamp":"2026-06-12T19:45:05Z","session_phase":"late"}
+{"type":"options_volume_tick","strike":5925,"option_type":"P","volume":380,"iv":0.145,"expiry":"0DTE","timestamp":"2026-06-12T19:45:06Z","session_phase":"late"}
+{"type":"options_volume_tick","strike":5950,"option_type":"C","volume":1980,"iv":0.136,"expiry":"0DTE","timestamp":"2026-06-12T19:45:10Z","session_phase":"late"}
+{"type":"options_volume_tick","strike":5950,"option_type":"P","volume":420,"iv":0.136,"expiry":"0DTE","timestamp":"2026-06-12T19:45:11Z","session_phase":"late"}
+{"type":"options_volume_tick","strike":5975,"option_type":"C","volume":2420,"iv":0.139,"expiry":"0DTE","timestamp":"2026-06-12T19:45:15Z","session_phase":"late"}
+{"type":"options_volume_tick","strike":5975,"option_type":"P","volume":360,"iv":0.139,"expiry":"0DTE","timestamp":"2026-06-12T19:45:16Z","session_phase":"late"}
+{"type":"options_volume_tick","strike":6000,"option_type":"C","volume":2180,"iv":0.146,"expiry":"0DTE","timestamp":"2026-06-12T19:45:20Z","session_phase":"late"}
+{"type":"options_volume_tick","strike":6000,"option_type":"P","volume":280,"iv":0.146,"expiry":"0DTE","timestamp":"2026-06-12T19:45:21Z","session_phase":"late"}
+{"type":"options_volume_tick","strike":6025,"option_type":"C","volume":760,"iv":0.158,"expiry":"0DTE","timestamp":"2026-06-12T19:45:25Z","session_phase":"late"}
+{"type":"options_volume_tick","strike":6025,"option_type":"P","volume":180,"iv":0.158,"expiry":"0DTE","timestamp":"2026-06-12T19:45:26Z","session_phase":"late"}
diff --git a/tests/test_gex_engine.py b/tests/test_gex_engine.py
@@ -14,6 +14,22 @@ def test_interpolates_zero_gamma_between_sign_changes(self):
 
         self.assertEqual(zero, 105.0)
 
+    def test_interpolates_zero_gamma_between_uneven_adjacent_strikes(self):
+        strikes = np.array([100.0, 125.0])
+        net_gex = np.array([-25.0, 75.0])
+
+        zero = IntradayGexEngine.interpolate_zero_gamma_strike(strikes, net_gex)
+
+        self.assertEqual(zero, 106.25)
+
+    def test_exact_zero_gamma_returns_that_strike(self):
+        strikes = np.array([100.0, 110.0, 120.0])
+        net_gex = np.array([-50.0, 0.0, 50.0])
+
+        zero = IntradayGexEngine.interpolate_zero_gamma_strike(strikes, net_gex)
+
+        self.assertEqual(zero, 110.0)
+
     def test_zero_gamma_falls_back_to_nearest_absolute_exposure_without_sign_change(self):
         strikes = np.array([100.0, 110.0, 120.0])
         net_gex = np.array([80.0, 20.0, 40.0])
@@ -22,6 +38,30 @@ def test_zero_gamma_falls_back_to_nearest_absolute_exposure_without_sign_change(
 
         self.assertEqual(zero, 110.0)
 
+    def test_zero_gamma_falls_back_for_all_negative_exposure(self):
+        strikes = np.array([100.0, 110.0, 120.0])
+        net_gex = np.array([-80.0, -20.0, -40.0])
+
+        zero = IntradayGexEngine.interpolate_zero_gamma_strike(strikes, net_gex)
+
+        self.assertEqual(zero, 110.0)
+
+    def test_multiple_sign_changes_choose_candidate_nearest_lowest_absolute_exposure(self):
+        strikes = np.array([90.0, 100.0, 110.0, 120.0])
+        net_gex = np.array([-10.0, 10.0, 1.0, -1.0])
+
+        zero = IntradayGexEngine.interpolate_zero_gamma_strike(strikes, net_gex)
+
+        self.assertEqual(zero, 115.0)
+
+    def test_empty_zero_gamma_input_returns_zero(self):
+        zero = IntradayGexEngine.interpolate_zero_gamma_strike(
+            np.array([]),
+            np.array([]),
+        )
+
+        self.assertEqual(zero, 0.0)
+
     def test_compute_matrix_returns_gamma_and_nearest_zero_strike(self):
         engine = IntradayGexEngine(multiplier=50)
 
diff --git a/tests/test_replay_adapter.py b/tests/test_replay_adapter.py
diff --git a/tests/test_tui_table.py b/tests/test_tui_table.py
