oracle3 1.1.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. coinjure/__init__.py +0 -0
  2. coinjure/matching/__init__.py +66 -0
  3. coinjure/matching/_cache.py +35 -0
  4. coinjure/matching/_category.py +347 -0
  5. coinjure/matching/_date.py +123 -0
  6. coinjure/matching/_fetchers.py +284 -0
  7. coinjure/matching/_pipeline.py +263 -0
  8. coinjure/matching/_resolution.py +66 -0
  9. coinjure/matching/_template.py +240 -0
  10. coinjure/matching/_text.py +63 -0
  11. coinjure/matching/_types.py +72 -0
  12. oracle3/__init__.py +3 -0
  13. oracle3/agent/__init__.py +9 -0
  14. oracle3/agent/coordinator.py +328 -0
  15. oracle3/alerts/__init__.py +6 -0
  16. oracle3/alerts/alerter.py +173 -0
  17. oracle3/alerts/telegram_alerter.py +45 -0
  18. oracle3/analytics/performance_analyzer.py +336 -0
  19. oracle3/backtest/backtester.py +123 -0
  20. oracle3/blinks/__init__.py +1 -0
  21. oracle3/blinks/generator.py +62 -0
  22. oracle3/blinks/server.py +242 -0
  23. oracle3/cli/__init__.py +1 -0
  24. oracle3/cli/agent_commands.py +1008 -0
  25. oracle3/cli/cli.py +444 -0
  26. oracle3/cli/control.py +416 -0
  27. oracle3/cli/data_commands.py +260 -0
  28. oracle3/cli/market_commands.py +655 -0
  29. oracle3/cli/monitor.py +733 -0
  30. oracle3/cli/news_commands.py +246 -0
  31. oracle3/cli/research_commands.py +2369 -0
  32. oracle3/cli/textual_monitor.py +1129 -0
  33. oracle3/cli/trade_commands.py +231 -0
  34. oracle3/cli/utils.py +120 -0
  35. oracle3/config/__init__.py +23 -0
  36. oracle3/config/config.py +185 -0
  37. oracle3/core/trading_engine.py +822 -0
  38. oracle3/dashboard/__init__.py +5 -0
  39. oracle3/dashboard/server.py +423 -0
  40. oracle3/dashboard/static/demo.html +1691 -0
  41. oracle3/dashboard/static/index.html +1255 -0
  42. oracle3/dashboard/static/live.html +1208 -0
  43. oracle3/data/backtest/dflow_recorder.py +218 -0
  44. oracle3/data/backtest/historical_data_source.py +162 -0
  45. oracle3/data/backtest/history_reader.py +66 -0
  46. oracle3/data/backtest/kalshi_replay_data_source.py +212 -0
  47. oracle3/data/base_fetcher.py +144 -0
  48. oracle3/data/composite_data_source.py +82 -0
  49. oracle3/data/data_source.py +26 -0
  50. oracle3/data/live/coingecko_x402_data_source.py +213 -0
  51. oracle3/data/live/dflow_data_source.py +322 -0
  52. oracle3/data/live/dflow_ws_data_source.py +269 -0
  53. oracle3/data/live/google_news_data_source.py +517 -0
  54. oracle3/data/live/kalshi_data_source.py +308 -0
  55. oracle3/data/live/live_data_source.py +1073 -0
  56. oracle3/data/live/onchain_signal_source.py +207 -0
  57. oracle3/data/live/polymarket_orderflow.py +473 -0
  58. oracle3/data/live/twitter_fetcher.py +515 -0
  59. oracle3/data/market_data_manager.py +233 -0
  60. oracle3/data/preprocessing/__init__.py +1 -0
  61. oracle3/data/preprocessing/news_processor.py +678 -0
  62. oracle3/engine/__init__.py +1 -0
  63. oracle3/engine/control.py +363 -0
  64. oracle3/engine/registry.py +351 -0
  65. oracle3/events/events.py +165 -0
  66. oracle3/live/live_trader.py +789 -0
  67. oracle3/market/__init__.py +25 -0
  68. oracle3/market/relations.py +405 -0
  69. oracle3/market/validation.py +639 -0
  70. oracle3/mock/__init__.py +0 -0
  71. oracle3/mock/mock_mode.py +96 -0
  72. oracle3/onchain/__init__.py +5 -0
  73. oracle3/onchain/logger.py +182 -0
  74. oracle3/onchain/reputation.py +236 -0
  75. oracle3/order/order_book.py +50 -0
  76. oracle3/position/position_manager.py +189 -0
  77. oracle3/pricing/__init__.py +76 -0
  78. oracle3/pricing/calibrator.py +369 -0
  79. oracle3/pricing/contract_scorer.py +269 -0
  80. oracle3/pricing/distortion.py +338 -0
  81. oracle3/pricing/fair_value.py +330 -0
  82. oracle3/pricing/greeks.py +224 -0
  83. oracle3/pricing/premium_tracker.py +339 -0
  84. oracle3/pricing/wang_mle.py +620 -0
  85. oracle3/risk/correlation_risk_manager.py +301 -0
  86. oracle3/risk/onchain_risk_manager.py +208 -0
  87. oracle3/risk/risk_manager.py +345 -0
  88. oracle3/storage/__init__.py +6 -0
  89. oracle3/storage/serializers.py +202 -0
  90. oracle3/storage/state_store.py +177 -0
  91. oracle3/strategy/__init__.py +19 -0
  92. oracle3/strategy/agent_strategy.py +331 -0
  93. oracle3/strategy/contrib/__init__.py +25 -0
  94. oracle3/strategy/contrib/adaptive_onchain_strategy.py +585 -0
  95. oracle3/strategy/contrib/allocation_strategy.py +159 -0
  96. oracle3/strategy/contrib/coint_spread_strategy.py +409 -0
  97. oracle3/strategy/contrib/conditional_arb_strategy.py +364 -0
  98. oracle3/strategy/contrib/cross_market_arbitrage_strategy.py +820 -0
  99. oracle3/strategy/contrib/debate_strategy.py +850 -0
  100. oracle3/strategy/contrib/event_sum_arb_strategy.py +250 -0
  101. oracle3/strategy/contrib/exclusivity_arb_strategy.py +289 -0
  102. oracle3/strategy/contrib/fair_value_strategy.py +278 -0
  103. oracle3/strategy/contrib/implication_arb_strategy.py +276 -0
  104. oracle3/strategy/contrib/lead_lag_strategy.py +722 -0
  105. oracle3/strategy/contrib/llm_news_strategy.py +384 -0
  106. oracle3/strategy/contrib/multi_agent_strategy.py +106 -0
  107. oracle3/strategy/contrib/premium_decay_strategy.py +397 -0
  108. oracle3/strategy/contrib/prompts.py +222 -0
  109. oracle3/strategy/contrib/solana_agent_strategy.py +458 -0
  110. oracle3/strategy/contrib/structural_arb_strategy.py +356 -0
  111. oracle3/strategy/loader.py +52 -0
  112. oracle3/strategy/market_making_strategy.py +168 -0
  113. oracle3/strategy/momentum_mean_reversion_strategy.py +213 -0
  114. oracle3/strategy/orderbook_imbalance_strategy.py +161 -0
  115. oracle3/strategy/quant_strategy.py +34 -0
  116. oracle3/strategy/simple_strategy.py +1017 -0
  117. oracle3/strategy/strategy.py +373 -0
  118. oracle3/strategy/test_strategy.py +66 -0
  119. oracle3/ticker/ticker.py +139 -0
  120. oracle3/trader/atomic_trader.py +275 -0
  121. oracle3/trader/flash_loan.py +263 -0
  122. oracle3/trader/jito_submitter.py +253 -0
  123. oracle3/trader/kalshi_trader.py +296 -0
  124. oracle3/trader/paper_trader.py +192 -0
  125. oracle3/trader/polymarket_trader.py +356 -0
  126. oracle3/trader/solana_trader.py +426 -0
  127. oracle3/trader/spread_executor.py +308 -0
  128. oracle3/trader/trader.py +136 -0
  129. oracle3/trader/types.py +119 -0
  130. oracle3/trading/__init__.py +5 -0
  131. oracle3/trading/allocator.py +211 -0
  132. oracle3/trading/sizing.py +218 -0
  133. oracle3-1.1.2.dist-info/METADATA +166 -0
  134. oracle3-1.1.2.dist-info/RECORD +137 -0
  135. oracle3-1.1.2.dist-info/WHEEL +4 -0
  136. oracle3-1.1.2.dist-info/entry_points.txt +3 -0
  137. oracle3-1.1.2.dist-info/licenses/LICENSE +190 -0
@@ -0,0 +1,284 @@
1
+ """API fetchers for Polymarket and Kalshi public endpoints."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import logging
7
+ from datetime import datetime, timezone
8
+
9
+ import httpx
10
+
11
+ from ._cache import TTLCache
12
+ from ._types import NormalizedMarket
13
+
14
+ logger = logging.getLogger(__name__)
15
+
16
+ GAMMA_API = 'https://gamma-api.polymarket.com'
17
+ KALSHI_API = 'https://api.elections.kalshi.com/trade-api/v2'
18
+
19
+ _DEFAULT_TIMEOUT = 30.0
20
+
21
+
22
+ def _parse_iso_date(s: str | None) -> datetime | None:
23
+ """Parse an ISO 8601 date string to a datetime."""
24
+ if not s:
25
+ return None
26
+ try:
27
+ s = s.replace('Z', '+00:00')
28
+ return datetime.fromisoformat(s)
29
+ except (ValueError, TypeError):
30
+ return None
31
+
32
+
33
+ def _parse_unix_ts(ts: int | str | None) -> datetime | None:
34
+ """Parse a Unix timestamp (seconds) to a datetime."""
35
+ if ts is None:
36
+ return None
37
+ try:
38
+ return datetime.fromtimestamp(int(ts), tz=timezone.utc)
39
+ except (ValueError, TypeError, OSError):
40
+ return None
41
+
42
+
43
+ def _parse_json_field(raw: object, default: list[object] | None = None) -> list[object]:
44
+ """Parse a JSON field that may be a string or already a list."""
45
+ if default is None:
46
+ default = []
47
+ if isinstance(raw, str):
48
+ try:
49
+ return json.loads(raw) # type: ignore[return-value]
50
+ except (json.JSONDecodeError, TypeError):
51
+ return default
52
+ if isinstance(raw, list):
53
+ return raw
54
+ return default
55
+
56
+
57
+ def _extract_tags(raw_tags: object) -> list[str]:
58
+ """Extract tag labels from a raw tags field."""
59
+ if not isinstance(raw_tags, list):
60
+ return []
61
+ return [
62
+ t.get('label', t) if isinstance(t, dict) else str(t)
63
+ for t in raw_tags
64
+ ]
65
+
66
+
67
+ def _normalize_poly_market(
68
+ mkt: dict[str, object],
69
+ event_id: str,
70
+ event_title: str,
71
+ event_tags: list[str],
72
+ event_end_date: str | None,
73
+ ) -> NormalizedMarket:
74
+ """Convert a raw Polymarket market dict to a NormalizedMarket."""
75
+ question = str(mkt.get('question', event_title))
76
+ end_date = _parse_iso_date(
77
+ str(mkt.get('endDate', '')) or event_end_date
78
+ )
79
+
80
+ token_ids = _parse_json_field(mkt.get('clobTokenIds', '[]'))
81
+ prices = _parse_json_field(mkt.get('outcomePrices', '[]'))
82
+ yes_price = float(prices[0]) if prices else None # type: ignore[arg-type]
83
+
84
+ mkt_tags = _extract_tags(mkt.get('tags', []))
85
+ all_tags = event_tags + mkt_tags
86
+
87
+ return NormalizedMarket(
88
+ platform='polymarket',
89
+ event_id=event_id,
90
+ market_id=str(mkt.get('id', '')),
91
+ title=question,
92
+ end_date=end_date,
93
+ tags=all_tags,
94
+ resolution_source=str(mkt.get('resolutionSource', '')),
95
+ extra={
96
+ 'token_id': token_ids[0] if token_ids else '',
97
+ 'no_token_id': token_ids[1] if len(token_ids) > 1 else '',
98
+ 'yes_price': yes_price,
99
+ 'volume': float(str(mkt.get('volume', 0) or 0)),
100
+ 'description': str(mkt.get('description', '')),
101
+ },
102
+ )
103
+
104
+
105
+ def _normalize_kalshi_market(
106
+ mkt: dict[str, object],
107
+ ev_title: str,
108
+ series_ticker: str,
109
+ ev_category: str,
110
+ ev_event_ticker: str,
111
+ ) -> NormalizedMarket:
112
+ """Convert a raw Kalshi market dict to a NormalizedMarket."""
113
+ title = str(mkt.get('title', '')) or ev_title
114
+ end_date = _parse_iso_date(
115
+ str(mkt.get('expiration_time', ''))
116
+ or str(mkt.get('close_time', ''))
117
+ )
118
+
119
+ # Kalshi prices are in cents (1-99)
120
+ yes_bid = mkt.get('yes_bid')
121
+ yes_ask = mkt.get('yes_ask')
122
+ yes_price = None
123
+ if yes_bid is not None and yes_ask is not None:
124
+ yes_price = (float(yes_bid) + float(yes_ask)) / 2.0 / 100.0 # type: ignore[arg-type]
125
+ elif yes_ask is not None:
126
+ yes_price = float(yes_ask) / 100.0 # type: ignore[arg-type]
127
+
128
+ mkt_series = str(mkt.get('series_ticker', '')) or series_ticker
129
+ event_ticker = str(mkt.get('event_ticker', '')) or ev_event_ticker
130
+
131
+ tags: list[str] = []
132
+ if ev_category:
133
+ tags.append(ev_category)
134
+
135
+ return NormalizedMarket(
136
+ platform='kalshi',
137
+ event_id=event_ticker,
138
+ market_id=str(mkt.get('ticker', '')),
139
+ title=title,
140
+ end_date=end_date,
141
+ tags=tags,
142
+ series_ticker=mkt_series,
143
+ resolution_source=str(mkt.get('settlement_source', '')),
144
+ extra={
145
+ 'market_ticker': str(mkt.get('ticker', '')),
146
+ 'event_ticker': event_ticker,
147
+ 'yes_price': yes_price,
148
+ 'volume': mkt.get('volume', 0),
149
+ 'rules': str(
150
+ mkt.get('rules_primary', mkt.get('settlement_timer_duration', ''))
151
+ ),
152
+ },
153
+ )
154
+
155
+
156
+ async def fetch_polymarket_events(
157
+ cache: TTLCache | None = None,
158
+ max_events: int = 500,
159
+ ) -> list[NormalizedMarket]:
160
+ """Fetch active Polymarket events and normalize their markets."""
161
+ cache_key = f'polymarket_events_{max_events}'
162
+ if cache is not None:
163
+ cached = cache.get(cache_key)
164
+ if cached is not None:
165
+ return cached # type: ignore[return-value]
166
+
167
+ markets: list[NormalizedMarket] = []
168
+ offset = 0
169
+ page_size = 100
170
+
171
+ async with httpx.AsyncClient(timeout=_DEFAULT_TIMEOUT) as client:
172
+ while offset < max_events:
173
+ try:
174
+ resp = await client.get(
175
+ f'{GAMMA_API}/events',
176
+ params={
177
+ 'active': 'true',
178
+ 'closed': 'false',
179
+ 'limit': min(page_size, max_events - offset),
180
+ 'offset': offset,
181
+ },
182
+ )
183
+ resp.raise_for_status()
184
+ events = resp.json()
185
+ if not events:
186
+ break
187
+
188
+ for ev in events:
189
+ event_id = str(ev.get('id', ''))
190
+ event_title = str(ev.get('title', ''))
191
+ event_tags = _extract_tags(ev.get('tags', []))
192
+ event_end = ev.get('endDate')
193
+
194
+ for mkt in ev.get('markets', []):
195
+ markets.append(_normalize_poly_market(
196
+ mkt, event_id, event_title, event_tags,
197
+ str(event_end) if event_end else None,
198
+ ))
199
+
200
+ offset += len(events)
201
+ if len(events) < page_size:
202
+ break
203
+ except httpx.HTTPError as exc:
204
+ logger.warning('Polymarket fetch offset=%d: %s', offset, exc)
205
+ break
206
+
207
+ logger.info('Fetched %d Polymarket markets', len(markets))
208
+ if cache is not None:
209
+ cache.set(cache_key, markets)
210
+ return markets
211
+
212
+
213
+ def _process_kalshi_events_page(
214
+ events: list[dict[str, object]],
215
+ ) -> list[NormalizedMarket]:
216
+ """Convert a page of raw Kalshi events to NormalizedMarkets."""
217
+ markets: list[NormalizedMarket] = []
218
+ for ev in events:
219
+ ev_title = str(ev.get('title', ''))
220
+ series = str(ev.get('series_ticker', ''))
221
+ category = str(ev.get('category', ''))
222
+ ev_ticker = str(ev.get('event_ticker', ''))
223
+
224
+ raw_markets = ev.get('markets', [])
225
+ if not isinstance(raw_markets, list):
226
+ continue
227
+ for mkt in raw_markets:
228
+ if not isinstance(mkt, dict):
229
+ continue
230
+ markets.append(_normalize_kalshi_market(
231
+ mkt, ev_title, series, category, ev_ticker,
232
+ ))
233
+ return markets
234
+
235
+
236
+ async def fetch_kalshi_events(
237
+ cache: TTLCache | None = None,
238
+ max_pages: int = 15,
239
+ ) -> list[NormalizedMarket]:
240
+ """Fetch active Kalshi events and normalize their markets."""
241
+ cache_key = f'kalshi_events_{max_pages}'
242
+ if cache is not None:
243
+ cached = cache.get(cache_key)
244
+ if cached is not None:
245
+ return cached # type: ignore[return-value]
246
+
247
+ markets: list[NormalizedMarket] = []
248
+ cursor: str | None = None
249
+
250
+ async with httpx.AsyncClient(timeout=_DEFAULT_TIMEOUT) as client:
251
+ for _ in range(max_pages):
252
+ try:
253
+ params: dict[str, str | int] = {
254
+ 'status': 'open',
255
+ 'limit': 100,
256
+ 'with_nested_markets': 'true',
257
+ }
258
+ if cursor:
259
+ params['cursor'] = cursor
260
+
261
+ resp = await client.get(
262
+ f'{KALSHI_API}/events',
263
+ params=params,
264
+ headers={'Accept': 'application/json'},
265
+ )
266
+ resp.raise_for_status()
267
+ data = resp.json()
268
+ events = data.get('events', [])
269
+ if not events:
270
+ break
271
+
272
+ markets.extend(_process_kalshi_events_page(events))
273
+
274
+ cursor = data.get('cursor')
275
+ if not cursor:
276
+ break
277
+ except httpx.HTTPError as exc:
278
+ logger.warning('Kalshi fetch page: %s', exc)
279
+ break
280
+
281
+ logger.info('Fetched %d Kalshi markets', len(markets))
282
+ if cache is not None:
283
+ cache.set(cache_key, markets)
284
+ return markets
@@ -0,0 +1,263 @@
1
+ """Market matching pipeline orchestrator."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+
7
+ from ._cache import TTLCache
8
+ from ._category import build_category_buckets, categories_compatible
9
+ from ._date import date_proximity_score, extract_date
10
+ from ._fetchers import fetch_kalshi_events, fetch_polymarket_events
11
+ from ._resolution import check_resolution_compatibility
12
+ from ._template import match_template, template_score
13
+ from ._text import MIN_TEXT_SIMILARITY, text_similarity
14
+ from ._types import MatchConfidence, MatchResult, NormalizedMarket, StageScores
15
+
16
+ logger = logging.getLogger(__name__)
17
+
18
+ # Stage weights
19
+ _W_CATEGORY = 0.10
20
+ _W_DATE = 0.20
21
+ _W_TEMPLATE = 0.30
22
+ _W_TEXT = 0.30
23
+ _W_RESOLUTION = 0.10
24
+
25
+
26
+ def _compute_confidence(
27
+ scores: StageScores,
28
+ template_passed: bool,
29
+ ) -> MatchConfidence:
30
+ """Determine confidence level from stage scores."""
31
+ if template_passed:
32
+ return MatchConfidence.HIGH
33
+
34
+ # Count stages that "passed"
35
+ passing = 0
36
+ if scores.category > 0:
37
+ passing += 1
38
+ if scores.date > 0.5: # better than neutral
39
+ passing += 1
40
+ if scores.text >= MIN_TEXT_SIMILARITY:
41
+ passing += 1
42
+ if scores.resolution > 0.5:
43
+ passing += 1
44
+
45
+ if passing >= 3:
46
+ return MatchConfidence.HIGH
47
+ if passing >= 2:
48
+ return MatchConfidence.MEDIUM
49
+ return MatchConfidence.LOW
50
+
51
+
52
+ def _compute_spread(
53
+ poly: NormalizedMarket,
54
+ kalshi: NormalizedMarket,
55
+ ) -> float | None:
56
+ """Compute the YES price spread between two markets."""
57
+ poly_price = poly.get_extra_float('yes_price')
58
+ kalshi_price = kalshi.get_extra_float('yes_price')
59
+ if poly_price is not None and kalshi_price is not None:
60
+ return abs(poly_price - kalshi_price)
61
+ return None
62
+
63
+
64
+ def _score_pair(
65
+ poly: NormalizedMarket,
66
+ kalshi: NormalizedMarket,
67
+ ) -> MatchResult | None:
68
+ """Run stages 2-5 on a candidate pair and return a MatchResult or None."""
69
+ scores = StageScores()
70
+
71
+ # Stage 1: category already bucketed, give baseline score
72
+ if categories_compatible(poly.category, kalshi.category):
73
+ scores.category = 1.0
74
+ else:
75
+ return None
76
+
77
+ # Stage 2: date proximity
78
+ poly_date = extract_date(poly)
79
+ kalshi_date = extract_date(kalshi)
80
+ scores.date = date_proximity_score(poly_date, kalshi_date)
81
+ # Hard filter: if both have dates and score is 0, reject
82
+ if poly_date and kalshi_date and scores.date == 0.0:
83
+ return None
84
+
85
+ # Stage 3: template matching
86
+ poly_tmpl = match_template(poly)
87
+ kalshi_tmpl = match_template(kalshi)
88
+ t_score = template_score(poly_tmpl, kalshi_tmpl)
89
+ if t_score < 0:
90
+ # Hard reject: same template, different fields
91
+ return None
92
+ scores.template = t_score
93
+ template_passed = t_score > 0
94
+
95
+ # Stage 4: text similarity
96
+ scores.text = text_similarity(poly.title, kalshi.title)
97
+ if scores.text < MIN_TEXT_SIMILARITY and not template_passed:
98
+ return None
99
+
100
+ # Stage 5: resolution check
101
+ compatible, warnings = check_resolution_compatibility(poly, kalshi)
102
+ if compatible is False:
103
+ return None # hard reject: incompatible resolution sources
104
+ elif compatible is None:
105
+ scores.resolution = 0.5 # unknown: neutral
106
+ else:
107
+ scores.resolution = 1.0
108
+
109
+ # Weighted score
110
+ total = (
111
+ _W_CATEGORY * scores.category
112
+ + _W_DATE * scores.date
113
+ + _W_TEMPLATE * scores.template
114
+ + _W_TEXT * scores.text
115
+ + _W_RESOLUTION * scores.resolution
116
+ )
117
+
118
+ confidence = _compute_confidence(scores, template_passed)
119
+ spread = _compute_spread(poly, kalshi)
120
+
121
+ label = poly.title[:80]
122
+
123
+ return MatchResult(
124
+ poly_market=poly,
125
+ kalshi_market=kalshi,
126
+ confidence=confidence,
127
+ score=round(total, 4),
128
+ stage_scores=scores,
129
+ label=label,
130
+ spread=spread,
131
+ warnings=warnings,
132
+ resolution_compatible=compatible,
133
+ )
134
+
135
+
136
+ class MarketMatchingPipeline:
137
+ """Multi-stage pipeline for matching prediction markets across platforms.
138
+
139
+ Usage::
140
+
141
+ pipeline = MarketMatchingPipeline()
142
+ matches = await pipeline.scan()
143
+ for m in matches:
144
+ print(m.label, m.confidence, m.spread)
145
+ """
146
+
147
+ def __init__(
148
+ self,
149
+ cache_ttl: float = 300.0,
150
+ max_poly_events: int = 500,
151
+ max_kalshi_pages: int = 15,
152
+ min_volume: float = 100.0,
153
+ ) -> None:
154
+ self._cache = TTLCache(ttl_seconds=cache_ttl)
155
+ self._max_poly_events = max_poly_events
156
+ self._max_kalshi_pages = max_kalshi_pages
157
+ self._min_volume = min_volume
158
+
159
+ async def scan(self) -> list[MatchResult]:
160
+ """Fetch markets from both platforms and run the matching pipeline.
161
+
162
+ Returns a list of MatchResult sorted by score (descending).
163
+ """
164
+ # Fetch
165
+ poly_markets = await fetch_polymarket_events(
166
+ cache=self._cache,
167
+ max_events=self._max_poly_events,
168
+ )
169
+ kalshi_markets = await fetch_kalshi_events(
170
+ cache=self._cache,
171
+ max_pages=self._max_kalshi_pages,
172
+ )
173
+
174
+ logger.info(
175
+ 'Pipeline: %d Poly x %d Kalshi markets (raw)',
176
+ len(poly_markets),
177
+ len(kalshi_markets),
178
+ )
179
+
180
+ # Volume filter
181
+ if self._min_volume > 0:
182
+ pre_poly = len(poly_markets)
183
+ pre_kalshi = len(kalshi_markets)
184
+ poly_markets = [
185
+ m for m in poly_markets
186
+ if (m.get_extra_float('volume') or 0.0) >= self._min_volume
187
+ ]
188
+ kalshi_markets = [
189
+ m for m in kalshi_markets
190
+ if (m.get_extra_float('volume') or 0.0) >= self._min_volume
191
+ ]
192
+ logger.info(
193
+ 'Volume filter (min=%.0f): Poly %d→%d, Kalshi %d→%d',
194
+ self._min_volume,
195
+ pre_poly,
196
+ len(poly_markets),
197
+ pre_kalshi,
198
+ len(kalshi_markets),
199
+ )
200
+
201
+ # Stage 1: category bucketing
202
+ buckets = build_category_buckets(poly_markets, kalshi_markets)
203
+ total_comparisons = sum(
204
+ len(p) * len(k) for p, k in buckets.values()
205
+ )
206
+ logger.info(
207
+ 'After bucketing: %d buckets, ~%d comparisons '
208
+ '(vs %d full cross-product)',
209
+ len(buckets),
210
+ total_comparisons,
211
+ len(poly_markets) * len(kalshi_markets),
212
+ )
213
+
214
+ # Stages 2-5: pairwise scoring within buckets
215
+ results: list[MatchResult] = []
216
+ seen_pairs: set[tuple[str, str]] = set()
217
+
218
+ for _bucket_name, (p_list, k_list) in buckets.items():
219
+ for poly in p_list:
220
+ for kalshi in k_list:
221
+ pair_key = (poly.market_id, kalshi.market_id)
222
+ if pair_key in seen_pairs:
223
+ continue
224
+ seen_pairs.add(pair_key)
225
+
226
+ match = _score_pair(poly, kalshi)
227
+ if match is not None:
228
+ results.append(match)
229
+
230
+ # Sort by score descending
231
+ results.sort(key=lambda m: m.score, reverse=True)
232
+
233
+ # Deduplicate: keep best match per poly market
234
+ best_by_poly: dict[str, MatchResult] = {}
235
+ for r in results:
236
+ key = r.poly_market.market_id
237
+ if key not in best_by_poly or r.score > best_by_poly[key].score:
238
+ best_by_poly[key] = r
239
+
240
+ # Also deduplicate per kalshi market
241
+ best_by_kalshi: dict[str, MatchResult] = {}
242
+ for r in sorted(
243
+ best_by_poly.values(), key=lambda m: m.score, reverse=True
244
+ ):
245
+ key = r.kalshi_market.market_id
246
+ if key not in best_by_kalshi:
247
+ best_by_kalshi[key] = r
248
+
249
+ final = sorted(
250
+ best_by_kalshi.values(), key=lambda m: m.score, reverse=True
251
+ )
252
+ logger.info(
253
+ 'Pipeline complete: %d matches (%d HIGH, %d MEDIUM, %d LOW)',
254
+ len(final),
255
+ sum(1 for m in final if m.confidence == MatchConfidence.HIGH),
256
+ sum(1 for m in final if m.confidence == MatchConfidence.MEDIUM),
257
+ sum(1 for m in final if m.confidence == MatchConfidence.LOW),
258
+ )
259
+ return final
260
+
261
+ def clear_cache(self) -> None:
262
+ """Clear the API response cache."""
263
+ self._cache.clear()
@@ -0,0 +1,66 @@
1
+ """Stage 5: Resolution rule compatibility check."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from ._types import NormalizedMarket
6
+
7
+ # Known resolution sources (normalized lowercase)
8
+ _OFFICIAL_SOURCES = frozenset({
9
+ 'ap', 'associated press', 'reuters', 'official results',
10
+ 'nba.com', 'nfl.com', 'mlb.com', 'espn',
11
+ 'federal reserve', 'bls', 'bea', 'coinmarketcap', 'coingecko',
12
+ })
13
+
14
+
15
+ def _extract_resolution_source(market: NormalizedMarket) -> str:
16
+ """Extract resolution source from market metadata."""
17
+ src = market.resolution_source.strip().lower()
18
+ if src:
19
+ return src
20
+ # Try to infer from extra metadata
21
+ rules = str(market.extra.get('rules', '')).lower()
22
+ desc = str(market.extra.get('description', '')).lower()
23
+ text = rules + ' ' + desc
24
+ for source in _OFFICIAL_SOURCES:
25
+ if source in text:
26
+ return source
27
+ return ''
28
+
29
+
30
+ def check_resolution_compatibility(
31
+ poly_market: NormalizedMarket,
32
+ kalshi_market: NormalizedMarket,
33
+ ) -> tuple[bool | None, list[str]]:
34
+ """Check if two markets have compatible resolution rules.
35
+
36
+ Returns:
37
+ (compatible, warnings) where compatible is True/False/None (unknown).
38
+ """
39
+ warnings: list[str] = []
40
+
41
+ poly_src = _extract_resolution_source(poly_market)
42
+ kalshi_src = _extract_resolution_source(kalshi_market)
43
+
44
+ # Date difference check
45
+ if poly_market.end_date and kalshi_market.end_date:
46
+ delta = abs((poly_market.end_date - kalshi_market.end_date).days)
47
+ if delta > 7:
48
+ warnings.append(
49
+ f'End dates differ by {delta} days '
50
+ f'(Poly: {poly_market.end_date.date()}, '
51
+ f'Kalshi: {kalshi_market.end_date.date()})'
52
+ )
53
+
54
+ # Source comparison
55
+ if not poly_src or not kalshi_src:
56
+ return None, warnings # unknown
57
+
58
+ if poly_src == kalshi_src:
59
+ return True, warnings
60
+
61
+ # Both have sources but they differ
62
+ warnings.append(
63
+ f'Different resolution sources: '
64
+ f'Poly="{poly_src}", Kalshi="{kalshi_src}"'
65
+ )
66
+ return False, warnings