[codex] add cross-provider analysis showcase

[hudsonaikins]

Summary

This PR tightens the SDK's cross-provider data story and gives the examples directory a clearer proof that the analysis stack works on standardized external market data.

On the data side, it fixes Kalshi sports parsing so ticker dates and matchup extraction resolve correctly for NBA and related helpers, and it expands the Polymarket US adapter so public market reads work without credentials where the upstream public Retail Market API allows it. That means the SDK can now pull public Kalshi and Polymarket snapshots through a more consistent normalized interface, instead of treating Polymarket reads as auth-only.

On the examples side, it adds a progressive showcase set:

• a daily Kalshi NBA snapshot example
• a daily Polymarket US NBA snapshot example
• a live cross-provider bridge that normalizes public data from both providers and runs one shared analysis pass
• a deterministic cross-provider replay that proves the analysis stack produces buy_yes, buy_no, and hold decisions on one standardized stream

The deterministic replay matters because live public feeds are not reliable as a proof artifact for analysis quality. Live markets can stay flat, move too little, or expose incomplete public quote depth, which makes the pipeline look inert even when the strategy layer is correct. The replay gives us a reproducible artifact that demonstrates normalization, stream construction, signal generation, and risk sizing under controlled conditions.

Root Cause

Before this change, two gaps made the SDK harder to demonstrate clearly:

First, Kalshi sports parsing had a date interpretation bug and some brittle title parsing, which meant derived game metadata could be wrong even when the underlying market pull succeeded.

Second, the Polymarket US integration required credentials up front even for public market data, and the examples directory did not yet show a strong cross-provider narrative from raw pulls through analysis decisions.

Fix

The PR:

• fixes Kalshi sports ticker date parsing and matchup extraction
• corrects the CFB helper request shape
• adds regression coverage for Kalshi sports parsing
• enables public Polymarket US market listing and quote reads via the public gateway endpoints
• enriches Polymarket sports rows with parsed team, date, and market type metadata
• adds and hardens Polymarket adapter/source tests for public reads and pagination behavior
• adds cross-provider examples for public daily snapshots and shared analysis
• adds a deterministic replay example plus regression coverage so the analysis proof stays stable over time
• documents the new highlighted examples in the README

Validation

I validated the change set with targeted checks focused on the touched modules and examples:

uv run ruff check README.md neural/data_collection/kalshi.py neural/data_collection/polymarket_us.py neural/trading/polymarket_us_adapter.py tests/data_collection/test_kalshi_sports_parsing.py tests/data_collection/test_polymarket_us_source.py tests/exchanges/test_polymarket_adapter.py tests/streaming/test_deterministic_cross_provider_replay.py examples/09_daily_nba_markets.py examples/10_daily_nba_markets_polymarket.py examples/12_cross_provider_analysis_bridge.py examples/13_deterministic_cross_provider_replay.py
uv run pytest tests/data_collection/test_kalshi_sports_parsing.py tests/data_collection/test_polymarket_us_source.py tests/exchanges/test_polymarket_adapter.py tests/streaming/test_deterministic_cross_provider_replay.py -q -o addopts=
python -m py_compile examples/09_daily_nba_markets.py examples/10_daily_nba_markets_polymarket.py examples/12_cross_provider_analysis_bridge.py examples/13_deterministic_cross_provider_replay.py
uv run python examples/13_deterministic_cross_provider_replay.py

The deterministic replay run produced the expected mix of buy_yes, buy_no, and hold outputs and wrote inspectable CSV artifacts under data/deterministic_cross_provider/.

[github-actions]

📚 Documentation Status

✅ Code changes detected

• Docstring coverage checked
• API documentation validation completed
  ✅ Example changes detected
• Example documentation validated
• Code syntax verified
  ✅ README changes detected

---

This comment is automatically generated by the documentation workflow.