xrtm-data 0.2.4__tar.gz → 0.2.5__tar.gz

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrtm-data
-Version: 0.2.4
+Version: 0.2.5
 Summary: The Snapshot Vault for XRTM.
 Author-email: XRTM Team <moy@xrtm.org>
 License-Expression: Apache-2.0

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xrtm-data"
-version = "0.2.4"
+version = "0.2.5"
 description = "The Snapshot Vault for XRTM."
 readme = "README.md"
 requires-python = ">=3.11,<3.13"

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/src/xrtm/data/__init__.py

@@ -31,7 +31,7 @@ Example:
 """
 
 # Core interfaces
-from xrtm.data.core import DataSource
+from xrtm.data.core import DataSource, DataSourceError, SourceFetchError, SourceTemporalIntegrityError
 
 # Core schemas (public API)
 from xrtm.data.core.schemas import (
@@ -46,6 +46,9 @@ from xrtm.data.core.schemas import (
 __all__ = [
     # Interfaces
     "DataSource",
+    "DataSourceError",
+    "SourceFetchError",
+    "SourceTemporalIntegrityError",
     # Schemas
     "MetadataBase",
     "ForecastQuestion",

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/src/xrtm/data/core/__init__.py

@@ -21,6 +21,6 @@ providers must implement. The core module is domain-agnostic and MUST NOT
 import from kit/ or providers/.
 """
 
-from xrtm.data.core.interfaces import DataSource
+from xrtm.data.core.interfaces import DataSource, DataSourceError, SourceFetchError, SourceTemporalIntegrityError
 
-__all__ = ["DataSource"]
+__all__ = ["DataSource", "DataSourceError", "SourceFetchError", "SourceTemporalIntegrityError"]

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/src/xrtm/data/core/interfaces.py

@@ -23,18 +23,31 @@ data provider, regardless of the source.
 Example:
     >>> from xrtm.data.core import DataSource
     >>> class MySource(DataSource):
-    ...     async def fetch_questions(self, query=None, limit=5):
+    ...     async def fetch_questions(self, query=None, limit=5, *, snapshot_time=None):
     ...         return []
     ...     async def get_question_by_id(self, question_id):
     ...         return None
 """
 
 import abc
+from datetime import datetime
 from typing import List, Optional
 
 from xrtm.data.core.schemas.forecast import ForecastQuestion
 
 
+class DataSourceError(RuntimeError):
+    r"""Base exception for data source failures."""
+
+
+class SourceFetchError(DataSourceError):
+    r"""Raised when a provider cannot fetch or decode source data."""
+
+
+class SourceTemporalIntegrityError(DataSourceError):
+    r"""Raised when a provider cannot satisfy a requested snapshot safely."""
+
+
 class DataSource(abc.ABC):
     r"""
     Abstract interface for gathering or streaming forecasting workloads.
@@ -47,18 +60,22 @@ class DataSource(abc.ABC):
 
     Example:
         >>> class LocalSource(DataSource):
-        ...     async def fetch_questions(self, query=None, limit=5):
+        ...     async def fetch_questions(self, query=None, limit=5, *, snapshot_time=None):
         ...         return [ForecastQuestion(id="1", title="Test")]
     """
 
     @abc.abstractmethod
-    async def fetch_questions(self, query: Optional[str] = None, limit: int = 5) -> List[ForecastQuestion]:
+    async def fetch_questions(
+        self, query: Optional[str] = None, limit: int = 5, *, snapshot_time: Optional[datetime] = None
+    ) -> List[ForecastQuestion]:
         r"""
         Fetch a list of forecast questions from the data source.
 
         Args:
             query: Optional search/filter string.
             limit: Maximum number of questions to return.
+            snapshot_time: Optional end-of-history timestamp. Providers that cannot
+                satisfy historical snapshots must surface a temporal integrity error.
 
         Returns:
             List of ForecastQuestion objects matching the criteria.
@@ -66,12 +83,16 @@ class DataSource(abc.ABC):
         pass
 
     @abc.abstractmethod
-    async def get_question_by_id(self, question_id: str) -> Optional[ForecastQuestion]:
+    async def get_question_by_id(
+        self, question_id: str, *, snapshot_time: Optional[datetime] = None
+    ) -> Optional[ForecastQuestion]:
         r"""
         Retrieve a single question by its unique identifier.
 
         Args:
             question_id: The unique identifier of the question.
+            snapshot_time: Optional end-of-history timestamp. Providers that cannot
+                satisfy historical snapshots must surface a temporal integrity error.
 
         Returns:
             The ForecastQuestion if found, None otherwise.
@@ -79,4 +100,4 @@ class DataSource(abc.ABC):
         pass
 
 
-__all__ = ["DataSource"]
+__all__ = ["DataSource", "DataSourceError", "SourceFetchError", "SourceTemporalIntegrityError"]

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/src/xrtm/data/core/schemas/forecast.py

@@ -28,7 +28,7 @@ Example:
 from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional
 
-from pydantic import AliasChoices, BaseModel, ConfigDict, Field, model_validator
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, field_validator, model_validator
 
 
 class MetadataBase(BaseModel):
@@ -66,6 +66,14 @@ class MetadataBase(BaseModel):
     source_version: Optional[str] = Field(None, description="Version of the data source")
     raw_data: Optional[Dict[str, Any]] = Field(None, description="Original unprocessed data")
 
+    @field_validator("created_at", "snapshot_time", mode="after")
+    @classmethod
+    def _normalize_temporal_fields(cls, value: datetime) -> datetime:
+        r"""Store temporal boundary fields as timezone-aware UTC datetimes."""
+        if value.tzinfo is None:
+            return value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc)
+
     def get(self, key: str, default: Any = None) -> Any:
         r"""Backward compatibility for dict-like access."""
         return getattr(self, key, default)

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/src/xrtm/data/core/schemas/trade.py

@@ -31,10 +31,17 @@ Example:
     ... )
 """
 
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Optional
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+def _as_utc(value: datetime) -> datetime:
+    r"""Normalize datetimes to timezone-aware UTC without rejecting legacy naive inputs."""
+    if value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
 
 
 class TradeEvent(BaseModel):
@@ -98,6 +105,12 @@ class TradeEvent(BaseModel):
         description="Transaction hash for verification",
     )
 
+    @field_validator("timestamp", mode="after")
+    @classmethod
+    def _normalize_timestamp(cls, value: datetime) -> datetime:
+        r"""Normalize trade timestamps to UTC to make window comparisons stable."""
+        return _as_utc(value)
+
     @property
     def yes_weight(self) -> float:
         r"""Volume-weighted contribution to Yes outcome: price × amount."""
@@ -149,6 +162,27 @@ class TradeWindow(BaseModel):
         description="Identifier for the market these trades belong to",
     )
 
+    @field_validator("start_time", "end_time", mode="after")
+    @classmethod
+    def _normalize_window_boundary(cls, value: datetime) -> datetime:
+        r"""Normalize window boundaries to UTC before enforcing leakage invariants."""
+        return _as_utc(value)
+
+    @model_validator(mode="after")
+    def _validate_temporal_bounds(self) -> "TradeWindow":
+        r"""Ensure a trade window cannot contain future or pre-window events."""
+        if self.end_time < self.start_time:
+            raise ValueError("end_time must not precede start_time")
+
+        leaked = [
+            trade.timestamp
+            for trade in self.trades
+            if trade.timestamp < self.start_time or trade.timestamp > self.end_time
+        ]
+        if leaked:
+            raise ValueError("trades must fall within [start_time, end_time]")
+        return self
+
     @property
     def total_volume(self) -> float:
         r"""Total trading volume in the window."""

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/src/xrtm/data/corpora/real_binary.py

@@ -486,7 +486,9 @@ class RealBinaryCorpusSource(DataSource):
         self._questions = [record.to_forecast_question() for record in self._records]
         self._questions_by_id = {question.id: question for question in self._questions}
 
-    async def fetch_questions(self, query: Optional[str] = None, limit: int = 5) -> list[ForecastQuestion]:
+    async def fetch_questions(
+        self, query: Optional[str] = None, limit: int = 5, *, snapshot_time: Optional[datetime] = None
+    ) -> list[ForecastQuestion]:
         r"""Fetch deterministic corpus questions, optionally filtering title/content text."""
         query_lower = query.lower() if query else None
         matches: list[ForecastQuestion] = []
@@ -498,7 +500,9 @@ class RealBinaryCorpusSource(DataSource):
                 break
         return matches
 
-    async def get_question_by_id(self, question_id: str) -> Optional[ForecastQuestion]:
+    async def get_question_by_id(
+        self, question_id: str, *, snapshot_time: Optional[datetime] = None
+    ) -> Optional[ForecastQuestion]:
         r"""Retrieve a deterministic corpus question by id."""
         question = self._questions_by_id.get(question_id)
         if question is None:

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/src/xrtm/data/providers/local/csv.py

@@ -29,8 +29,11 @@ import asyncio
 import json
 import logging
 import threading
+from datetime import datetime
 from typing import Any, List, Optional
 
+from pydantic import ValidationError
+
 from xrtm.data.core import DataSource
 from xrtm.data.core.schemas import ForecastQuestion
 
@@ -75,7 +78,7 @@ class LocalDataSource(DataSource):
             try:
                 with open(self.file_path, "r") as f:
                     raw_data = json.load(f)
-            except Exception as e:
+            except (OSError, json.JSONDecodeError) as e:
                 logger.error("Failed to read local questions from %s: %s", self.file_path, e)
                 self._questions = []
                 self._questions_by_id = {}
@@ -95,7 +98,7 @@ class LocalDataSource(DataSource):
                     continue
                 try:
                     question = ForecastQuestion(**item)
-                except Exception as e:
+                except ValidationError as e:
                     logger.warning("Skipping invalid local question %s from %s: %s", idx, self.file_path, e)
                     continue
 
@@ -124,13 +127,17 @@ class LocalDataSource(DataSource):
                 break
         return questions
 
-    async def fetch_questions(self, query: Optional[str] = None, limit: int = 5) -> List[ForecastQuestion]:
+    async def fetch_questions(
+        self, query: Optional[str] = None, limit: int = 5, *, snapshot_time: Optional[datetime] = None
+    ) -> List[ForecastQuestion]:
         r"""
         Fetch questions from the local JSON file.
 
         Args:
             query: Optional search string to filter questions by title.
             limit: Maximum number of questions to return.
+            snapshot_time: Accepted for DataSource compatibility. Local snapshots
+                are already frozen by the file contents.
 
         Returns:
             List of ForecastQuestion objects matching the criteria.
@@ -152,12 +159,16 @@ class LocalDataSource(DataSource):
             return []
         return [question.model_dump(mode="json") for question in self._questions]
 
-    async def get_question_by_id(self, question_id: str) -> Optional[ForecastQuestion]:
+    async def get_question_by_id(
+        self, question_id: str, *, snapshot_time: Optional[datetime] = None
+    ) -> Optional[ForecastQuestion]:
         r"""
         Retrieve a single question by ID from the local file.
 
         Args:
             question_id: The unique identifier of the question.
+            snapshot_time: Accepted for DataSource compatibility. Local snapshots
+                are already frozen by the file contents.
 
         Returns:
             The ForecastQuestion if found, None otherwise.

xrtm_data-0.2.5/src/xrtm/data/providers/online/polymarket.py

@@ -0,0 +1,256 @@
+# coding=utf-8
+# Copyright 2026 XRTM Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+r"""
+Polymarket Gamma API data source.
+
+This module provides a DataSource implementation that fetches forecast
+questions from the Polymarket Gamma API.
+
+Example:
+    >>> from xrtm.data.providers.online import PolymarketSource
+    >>> source = PolymarketSource()
+    >>> questions = await source.fetch_questions(query="election", limit=5)
+"""
+
+import logging
+from contextlib import asynccontextmanager
+from datetime import datetime, timedelta, timezone
+from types import TracebackType
+from typing import Any, Dict, List, Optional
+from urllib.parse import urlencode
+
+import aiohttp
+
+from xrtm.data.core import DataSource, DataSourceError, SourceFetchError, SourceTemporalIntegrityError
+from xrtm.data.core.schemas import ForecastQuestion, MetadataBase
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["PolymarketSource"]
+
+_LIVE_SNAPSHOT_TOLERANCE = timedelta(seconds=60)
+
+
+class PolymarketSource(DataSource):
+    r"""
+    DataSource implementation that fetches from the Polymarket Gamma API.
+
+    This provider connects to Polymarket's public Gamma API to retrieve
+    event metadata for forecasting. For trade history with OrderFilled
+    events, see the subgraph provider (to be added).
+
+    Attributes:
+        API_BASE: Base URL for the Polymarket Gamma API.
+
+    Example:
+        >>> source = PolymarketSource()
+        >>> questions = await source.fetch_questions(limit=10)
+        >>> print(f"Fetched {len(questions)} questions")
+    """
+
+    API_BASE = "https://gamma-api.polymarket.com"
+
+    def __init__(
+        self,
+        session: Optional[aiohttp.ClientSession] = None,
+        *,
+        raise_on_error: bool = False,
+    ) -> None:
+        self._session = session
+        self._owns_session = False
+        self.raise_on_error = raise_on_error
+        self.last_error: Optional[DataSourceError] = None
+
+    async def __aenter__(self) -> "PolymarketSource":
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+            self._owns_session = True
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+            self._session = None
+            self._owns_session = False
+
+    @asynccontextmanager
+    async def _get_session(self):
+        if self._session is not None and not self._session.closed:
+            yield self._session
+            return
+
+        session = aiohttp.ClientSession()
+        try:
+            yield session
+        finally:
+            await session.close()
+
+    def _fail(self, error: DataSourceError) -> None:
+        self.last_error = error
+        logger.error("%s", error)
+        if self.raise_on_error:
+            raise error
+
+    @staticmethod
+    def _as_utc(value: datetime) -> datetime:
+        if value.tzinfo is None:
+            return value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc)
+
+    def _live_snapshot_time(self, snapshot_time: Optional[datetime]) -> datetime:
+        request_time = datetime.now(timezone.utc)
+        if snapshot_time is None:
+            return request_time
+
+        snapshot_utc = self._as_utc(snapshot_time)
+        if snapshot_utc < request_time - _LIVE_SNAPSHOT_TOLERANCE:
+            raise SourceTemporalIntegrityError(
+                "Polymarket Gamma is a live-only API and cannot satisfy historical "
+                f"snapshot_time={snapshot_utc.isoformat()} without future leakage."
+            )
+        if snapshot_utc > request_time + _LIVE_SNAPSHOT_TOLERANCE:
+            raise SourceTemporalIntegrityError(
+                f"snapshot_time={snapshot_utc.isoformat()} is in the future for a live Polymarket request."
+            )
+        return snapshot_utc
+
+    async def fetch_questions(
+        self,
+        query: Optional[str] = None,
+        limit: int = 5,
+        *,
+        snapshot_time: Optional[datetime] = None,
+    ) -> List[ForecastQuestion]:
+        r"""
+        Fetch active forecast questions from Polymarket.
+
+        Args:
+            query: Optional search string to filter events.
+            limit: Maximum number of questions to return.
+
+        Returns:
+            List of ForecastQuestion objects from active markets.
+        """
+        try:
+            effective_snapshot_time = self._live_snapshot_time(snapshot_time)
+        except SourceTemporalIntegrityError as e:
+            self._fail(e)
+            return []
+
+        params = {"active": "true", "closed": "false", "limit": str(limit)}
+        if query:
+            params["search"] = query
+        url = f"{self.API_BASE}/events?{urlencode(params)}"
+
+        try:
+            async with self._get_session() as session:
+                async with session.get(url) as resp:
+                    if resp.status != 200:
+                        self._fail(SourceFetchError(f"Polymarket API returned status {resp.status} for events request."))
+                        return []
+
+                    data = await resp.json()
+                    if not isinstance(data, list):
+                        self._fail(SourceFetchError("Polymarket API returned a non-list events payload."))
+                        return []
+
+                    questions: list[ForecastQuestion] = []
+                    for idx, item in enumerate(data):
+                        if not isinstance(item, dict):
+                            logger.warning("Skipping Polymarket event %s: item must be an object.", idx)
+                            continue
+                        try:
+                            questions.append(self._normalize(item, effective_snapshot_time))
+                        except (TypeError, ValueError) as e:
+                            logger.warning("Skipping invalid Polymarket event %s: %s", idx, e)
+                    self.last_error = None
+                    return questions
+        except (aiohttp.ClientError, TimeoutError, TypeError, ValueError) as e:
+            self._fail(SourceFetchError(f"Failed to fetch questions from Polymarket: {e}"))
+            return []
+
+    async def get_question_by_id(
+        self,
+        question_id: str,
+        *,
+        snapshot_time: Optional[datetime] = None,
+    ) -> Optional[ForecastQuestion]:
+        r"""
+        Retrieve a single Polymarket event by ID.
+
+        Args:
+            question_id: The unique event identifier.
+
+        Returns:
+            The ForecastQuestion if found, None otherwise.
+        """
+        try:
+            effective_snapshot_time = self._live_snapshot_time(snapshot_time)
+        except SourceTemporalIntegrityError as e:
+            self._fail(e)
+            return None
+
+        url = f"{self.API_BASE}/events/{question_id}"
+        try:
+            async with self._get_session() as session:
+                async with session.get(url) as resp:
+                    if resp.status == 200:
+                        data = await resp.json()
+                        if not isinstance(data, dict):
+                            self._fail(SourceFetchError(f"Polymarket event {question_id} payload is not an object."))
+                            return None
+                        question = self._normalize(data, effective_snapshot_time)
+                        self.last_error = None
+                        return question
+                    if resp.status != 404:
+                        self._fail(
+                            SourceFetchError(
+                                f"Polymarket API returned status {resp.status} for event {question_id} request."
+                            )
+                        )
+                    return None
+        except (aiohttp.ClientError, TimeoutError, TypeError, ValueError) as e:
+            self._fail(SourceFetchError(f"Failed to retrieve Polymarket event {question_id}: {e}"))
+            return None
+
+    def _normalize(self, item: Dict[str, Any], snapshot_time: datetime) -> ForecastQuestion:
+        r"""
+        Normalize Polymarket API response to ForecastQuestion schema.
+
+        Args:
+            item: Raw API response dict.
+
+        Returns:
+            Normalized ForecastQuestion instance.
+        """
+        return ForecastQuestion(
+            id=str(item.get("id", "")),
+            title=item.get("title", "Untitled Event"),
+            description=item.get("description", ""),
+            metadata=MetadataBase(
+                tags=item.get("tags", []),
+                snapshot_time=snapshot_time,
+                subject_type="binary",
+                source_version="polymarket-gamma-v1",
+                raw_data=item,
+                fetched_at=datetime.now(timezone.utc),
+            ),
+        )

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/src/xrtm/data/providers/subgraph/polymarket.py

@@ -38,9 +38,17 @@ from typing import Any, Optional
 
 import aiohttp
 
+from xrtm.data.core import SourceFetchError
 from xrtm.data.core.schemas.trade import TradeEvent, TradeWindow
 
 
+def _as_utc(value: datetime) -> datetime:
+    r"""Normalize datetimes to timezone-aware UTC without rejecting legacy naive inputs."""
+    if value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
+
+
 class PolymarketTradeSource:
     r"""
     Data provider for Polymarket Goldsky Subgraph.
@@ -81,6 +89,17 @@ class PolymarketTradeSource:
         """
         self.endpoint = endpoint or self.ENDPOINT
         self.timeout = timeout
+        self.last_error: Optional[SourceFetchError] = None
+
+    @staticmethod
+    def _validate_window(start_time: datetime, end_time: datetime, limit: int) -> tuple[datetime, datetime]:
+        start_utc = _as_utc(start_time)
+        end_utc = _as_utc(end_time)
+        if end_utc < start_utc:
+            raise ValueError("end_time must not precede start_time")
+        if limit <= 0:
+            raise ValueError("limit must be positive")
+        return start_utc, end_utc
 
     async def fetch_trades(
         self,
@@ -101,6 +120,8 @@ class PolymarketTradeSource:
         Returns:
             List of TradeEvent objects in chronological order.
         """
+        start_utc, end_utc = self._validate_window(start_time, end_time, limit)
+
         # Query filtering by makerAssetId (assuming token is the asset being traded)
         query = """
         query($assetId: String!, $start: Int!, $end: Int!, $first: Int!) {
@@ -141,8 +162,8 @@ class PolymarketTradeSource:
 
         variables = {
             "assetId": market_id,
-            "start": int(start_time.timestamp()),
-            "end": int(end_time.timestamp()),
+            "start": int(start_utc.timestamp()),
+            "end": int(end_utc.timestamp()),
             "first": limit,
         }
 
@@ -155,11 +176,29 @@ class PolymarketTradeSource:
                 response.raise_for_status()
                 data = await response.json()
 
-        return self._parse_trades(data, market_id)
+        if not isinstance(data, dict):
+            error = SourceFetchError("Polymarket subgraph returned a non-object GraphQL payload.")
+            self.last_error = error
+            raise error
+        if data.get("errors"):
+            error = SourceFetchError(f"Polymarket subgraph returned GraphQL errors: {data['errors']}")
+            self.last_error = error
+            raise error
 
-    def _parse_trades(self, data: dict[str, Any], market_id: str) -> list[TradeEvent]:
+        self.last_error = None
+        return self._parse_trades(data, market_id, start_utc, end_utc)
+
+    def _parse_trades(
+        self,
+        data: dict[str, Any],
+        market_id: str,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+    ) -> list[TradeEvent]:
         r"""Parse GraphQL response into TradeEvent objects."""
         trades: list[TradeEvent] = []
+        start_utc = _as_utc(start_time) if start_time is not None else None
+        end_utc = _as_utc(end_time) if end_time is not None else None
 
         order_filleds = data.get("data", {}).get("orderFilledEvents", [])
         for item in order_filleds:
@@ -209,6 +248,10 @@ class PolymarketTradeSource:
 
                 # Convert timestamp
                 timestamp = datetime.fromtimestamp(int(item.get("timestamp", 0)), tz=timezone.utc)
+                if start_utc is not None and timestamp < start_utc:
+                    continue
+                if end_utc is not None and timestamp > end_utc:
+                    continue
 
                 trade = TradeEvent(
                     price=max(0.0, min(1.0, price)),
@@ -244,11 +287,12 @@ class PolymarketTradeSource:
         Returns:
             TradeWindow containing all trades in the specified window.
         """
-        trades = await self.fetch_trades(market_id, start_time, end_time, limit)
+        start_utc, end_utc = self._validate_window(start_time, end_time, limit)
+        trades = await self.fetch_trades(market_id, start_utc, end_utc, limit)
         return TradeWindow(
             trades=trades,
-            start_time=start_time,
-            end_time=end_time,
+            start_time=start_utc,
+            end_time=end_utc,
             market_id=market_id,
         )
 
@@ -289,6 +333,16 @@ class PolymarketTradeSource:
                 response.raise_for_status()
                 data = await response.json()
 
+        if not isinstance(data, dict):
+            error = SourceFetchError("Polymarket subgraph returned a non-object GraphQL payload.")
+            self.last_error = error
+            raise error
+        if data.get("errors"):
+            error = SourceFetchError(f"Polymarket subgraph returned GraphQL errors: {data['errors']}")
+            self.last_error = error
+            raise error
+
+        self.last_error = None
         markets = data.get("data", {}).get("markets", [])
         return [
             {

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/src/xrtm/data/version.py

@@ -21,7 +21,7 @@ This module provides the single source of truth for the package version.
 
 __all__ = ["__version__", "__author__", "__contact__", "__license__", "__copyright__"]
 
-__version__ = "0.2.4"
+__version__ = "0.2.5"
 __author__ = "XRTM Team"
 __contact__ = "moy@xrtm.org"
 __license__ = "Apache-2.0"

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/src/xrtm_data.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrtm-data
-Version: 0.2.4
+Version: 0.2.5
 Summary: The Snapshot Vault for XRTM.
 Author-email: XRTM Team <moy@xrtm.org>
 License-Expression: Apache-2.0

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/tests/test_local_datasource.py

@@ -15,6 +15,7 @@
 
 import asyncio
 import json
+from datetime import datetime, timezone
 
 import pytest
 
@@ -79,6 +80,19 @@ async def test_fetch_questions_query_case_insensitive(sample_data):
     assert questions[0].id == "q2"
 
 
+@pytest.mark.asyncio
+async def test_accepts_snapshot_time_for_datasource_compatibility(sample_data):
+    source = LocalDataSource(sample_data)
+    snapshot_time = datetime(2026, 1, 1, tzinfo=timezone.utc)
+
+    questions = await source.fetch_questions(limit=1, snapshot_time=snapshot_time)
+    question = await source.get_question_by_id("q1", snapshot_time=snapshot_time)
+
+    assert len(questions) == 1
+    assert question is not None
+    assert question.id == "q1"
+
+
 @pytest.mark.asyncio
 async def test_get_question_by_id(sample_data):
     source = LocalDataSource(sample_data)

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/tests/test_polymarket_source.py

@@ -13,10 +13,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from datetime import datetime, timedelta, timezone
 from unittest.mock import patch
 
 import pytest
 
+from xrtm.data.core import SourceFetchError, SourceTemporalIntegrityError
 from xrtm.data.providers.online.polymarket import PolymarketSource
 
 
@@ -36,16 +38,17 @@ class FakeResponse:
 
 
 class FakeSession:
-    def __init__(self, payload=None):
+    def __init__(self, payload=None, status: int = 200):
         self.payload = payload or [{"id": "p1", "title": "Will local tests pass?", "description": "Smoke"}]
+        self.status = status
         self.closed = False
         self.get_calls = 0
 
     def get(self, url):
         self.get_calls += 1
         if url.endswith("/events/p1"):
-            return FakeResponse(self.payload[0])
-        return FakeResponse(self.payload)
+            return FakeResponse(self.payload[0], self.status)
+        return FakeResponse(self.payload, self.status)
 
     async def __aenter__(self):
         return self
@@ -99,3 +102,49 @@ async def test_closed_external_session_falls_back_to_one_off_session():
     assert closed_session.get_calls == 0
     assert replacement.get_calls == 1
     assert replacement.closed is True
+
+
+@pytest.mark.asyncio
+async def test_successful_fetch_uses_one_snapshot_for_all_questions():
+    payload = [
+        {"id": "p1", "title": "Question 1", "description": "Smoke"},
+        {"id": "p2", "title": "Question 2", "description": "Smoke"},
+    ]
+    source = PolymarketSource(session=FakeSession(payload=payload))
+
+    questions = await source.fetch_questions(limit=2)
+
+    assert len(questions) == 2
+    assert questions[0].metadata.snapshot_time == questions[1].metadata.snapshot_time
+    assert questions[0].metadata.snapshot_time.tzinfo == timezone.utc
+    assert source.last_error is None
+
+
+@pytest.mark.asyncio
+async def test_historical_snapshot_is_rejected_without_live_fetch():
+    session = FakeSession()
+    source = PolymarketSource(session=session)
+
+    questions = await source.fetch_questions(snapshot_time=datetime.now(timezone.utc) - timedelta(hours=1))
+
+    assert questions == []
+    assert session.get_calls == 0
+    assert isinstance(source.last_error, SourceTemporalIntegrityError)
+
+
+@pytest.mark.asyncio
+async def test_source_failure_is_recorded_for_compatibility():
+    source = PolymarketSource(session=FakeSession(status=503))
+
+    questions = await source.fetch_questions(limit=1)
+
+    assert questions == []
+    assert isinstance(source.last_error, SourceFetchError)
+
+
+@pytest.mark.asyncio
+async def test_raise_on_error_surfaces_source_failure():
+    source = PolymarketSource(session=FakeSession(status=503), raise_on_error=True)
+
+    with pytest.raises(SourceFetchError):
+        await source.fetch_questions(limit=1)

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/tests/test_polymarket_subgraph.py

@@ -20,6 +20,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
+from xrtm.data.core import SourceFetchError
 from xrtm.data.providers.subgraph import PolymarketTradeSource
 
 
@@ -144,6 +145,83 @@ class TestPolymarketTradeSource:
             assert len(window.trades) == 2
             assert window.total_volume == 300.0
 
+    @pytest.mark.asyncio
+    async def test_fetch_trades_filters_response_to_requested_window(self, source: PolymarketTradeSource) -> None:
+        r"""Provider response cannot leak trades outside the requested snapshot window."""
+        data = {
+            "data": {
+                "orderFilledEvents": [
+                    {
+                        "id": "inside",
+                        "makerAmountFilled": "100",
+                        "takerAmountFilled": "75",
+                        "timestamp": "1704067200",
+                        "maker": "0xmaker1",
+                        "taker": "0xtaker1",
+                    },
+                    {
+                        "id": "future",
+                        "makerAmountFilled": "100",
+                        "takerAmountFilled": "80",
+                        "timestamp": "1704153600",
+                        "maker": "0xmaker2",
+                        "taker": "0xtaker2",
+                    },
+                ]
+            }
+        }
+        mock_response = MagicMock()
+        mock_response.json = AsyncMock(return_value=data)
+        mock_response.raise_for_status = MagicMock()
+
+        mock_response_ctx = AsyncMock()
+        mock_response_ctx.__aenter__.return_value = mock_response
+        mock_response_ctx.__aexit__.return_value = None
+
+        mock_session = MagicMock()
+        mock_session.post.return_value = mock_response_ctx
+
+        mock_session_ctx = AsyncMock()
+        mock_session_ctx.__aenter__.return_value = mock_session
+        mock_session_ctx.__aexit__.return_value = None
+
+        with patch("aiohttp.ClientSession", return_value=mock_session_ctx):
+            trades = await source.fetch_trades(
+                market_id="0xmarket",
+                start_time=datetime(2024, 1, 1, tzinfo=timezone.utc),
+                end_time=datetime(2024, 1, 1, 12, tzinfo=timezone.utc),
+            )
+
+        assert [trade.maker for trade in trades] == ["0xmaker1"]
+
+    @pytest.mark.asyncio
+    async def test_graphql_errors_raise_source_fetch_error(self, source: PolymarketTradeSource) -> None:
+        r"""GraphQL error payloads must not be silently interpreted as empty data."""
+        mock_response = MagicMock()
+        mock_response.json = AsyncMock(return_value={"errors": [{"message": "bad query"}]})
+        mock_response.raise_for_status = MagicMock()
+
+        mock_response_ctx = AsyncMock()
+        mock_response_ctx.__aenter__.return_value = mock_response
+        mock_response_ctx.__aexit__.return_value = None
+
+        mock_session = MagicMock()
+        mock_session.post.return_value = mock_response_ctx
+
+        mock_session_ctx = AsyncMock()
+        mock_session_ctx.__aenter__.return_value = mock_session
+        mock_session_ctx.__aexit__.return_value = None
+
+        with patch("aiohttp.ClientSession", return_value=mock_session_ctx):
+            with pytest.raises(SourceFetchError):
+                await source.fetch_trades(
+                    market_id="0xmarket",
+                    start_time=datetime(2024, 1, 1, tzinfo=timezone.utc),
+                    end_time=datetime(2024, 1, 3, tzinfo=timezone.utc),
+                )
+
+        assert isinstance(source.last_error, SourceFetchError)
+
     def test_parse_trades_empty_response(self, source: PolymarketTradeSource) -> None:
         r"""Test parsing empty response."""
         trades = source._parse_trades({}, "market1")

{xrtm_data-0.2.4 → xrtm_data-0.2.5}/tests/test_schemas.py

@@ -12,11 +12,12 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+from datetime import datetime, timedelta, timezone
 
 import pytest
 
-from xrtm.data import CausalEdge, CausalNode, ForecastOutput
+from xrtm.data import CausalEdge, CausalNode, ForecastOutput, MetadataBase
+from xrtm.data.core.schemas import TradeEvent, TradeWindow
 
 
 def test_forecast_output_initialization():
@@ -100,3 +101,50 @@ def test_to_networkx_conversion():
         assert dg.has_edge("n1", "n2")
     except ImportError:
         pytest.skip("NetworkX not installed")
+
+
+def test_metadata_temporal_fields_normalize_to_utc():
+    """Metadata timestamps remain timezone-aware for deterministic snapshot comparisons."""
+    metadata = MetadataBase(
+        created_at=datetime(2024, 1, 1, 12, 0),
+        snapshot_time=datetime(2024, 1, 1, 13, 0),
+    )
+
+    assert metadata.created_at.tzinfo == timezone.utc
+    assert metadata.snapshot_time.tzinfo == timezone.utc
+
+
+def test_trade_window_rejects_future_leakage():
+    """TradeWindow enforces that no trade falls outside its snapshot window."""
+    start = datetime(2024, 1, 1, tzinfo=timezone.utc)
+    end = datetime(2024, 1, 2, tzinfo=timezone.utc)
+    future_trade = TradeEvent(
+        price=0.5,
+        amount=1.0,
+        timestamp=end + timedelta(seconds=1),
+        maker="0xmaker",
+        taker="0xtaker",
+    )
+
+    with pytest.raises(ValueError, match="trades must fall within"):
+        TradeWindow(trades=[future_trade], start_time=start, end_time=end, market_id="m1")
+
+
+def test_trade_window_normalizes_naive_boundaries_and_timestamps():
+    """Legacy naive datetimes are interpreted as UTC before invariant checks."""
+    trade = TradeEvent(
+        price=0.5,
+        amount=1.0,
+        timestamp=datetime(2024, 1, 1, 12, 0),
+        maker="0xmaker",
+        taker="0xtaker",
+    )
+    window = TradeWindow(
+        trades=[trade],
+        start_time=datetime(2024, 1, 1),
+        end_time=datetime(2024, 1, 2),
+        market_id="m1",
+    )
+
+    assert window.start_time.tzinfo == timezone.utc
+    assert window.trades[0].timestamp.tzinfo == timezone.utc

xrtm_data-0.2.4/src/xrtm/data/providers/online/polymarket.py

@@ -1,167 +0,0 @@
-# coding=utf-8
-# Copyright 2026 XRTM Team. All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-r"""
-Polymarket Gamma API data source.
-
-This module provides a DataSource implementation that fetches forecast
-questions from the Polymarket Gamma API.
-
-Example:
-    >>> from xrtm.data.providers.online import PolymarketSource
-    >>> source = PolymarketSource()
-    >>> questions = await source.fetch_questions(query="election", limit=5)
-"""
-
-import logging
-from contextlib import asynccontextmanager
-from types import TracebackType
-from typing import Any, Dict, List, Optional
-
-import aiohttp
-
-from xrtm.data.core import DataSource
-from xrtm.data.core.schemas import ForecastQuestion, MetadataBase
-
-logger = logging.getLogger(__name__)
-
-__all__ = ["PolymarketSource"]
-
-
-class PolymarketSource(DataSource):
-    r"""
-    DataSource implementation that fetches from the Polymarket Gamma API.
-
-    This provider connects to Polymarket's public Gamma API to retrieve
-    event metadata for forecasting. For trade history with OrderFilled
-    events, see the subgraph provider (to be added).
-
-    Attributes:
-        API_BASE: Base URL for the Polymarket Gamma API.
-
-    Example:
-        >>> source = PolymarketSource()
-        >>> questions = await source.fetch_questions(limit=10)
-        >>> print(f"Fetched {len(questions)} questions")
-    """
-
-    API_BASE = "https://gamma-api.polymarket.com"
-
-    def __init__(self, session: Optional[aiohttp.ClientSession] = None) -> None:
-        self._session = session
-        self._owns_session = False
-
-    async def __aenter__(self) -> "PolymarketSource":
-        if self._session is None or self._session.closed:
-            self._session = aiohttp.ClientSession()
-            self._owns_session = True
-        return self
-
-    async def __aexit__(
-        self,
-        exc_type: Optional[type[BaseException]],
-        exc: Optional[BaseException],
-        traceback: Optional[TracebackType],
-    ) -> None:
-        if self._owns_session and self._session is not None:
-            await self._session.close()
-            self._session = None
-            self._owns_session = False
-
-    @asynccontextmanager
-    async def _get_session(self):
-        if self._session is not None and not self._session.closed:
-            yield self._session
-            return
-
-        session = aiohttp.ClientSession()
-        try:
-            yield session
-        finally:
-            await session.close()
-
-    async def fetch_questions(self, query: Optional[str] = None, limit: int = 5) -> List[ForecastQuestion]:
-        r"""
-        Fetch active forecast questions from Polymarket.
-
-        Args:
-            query: Optional search string to filter events.
-            limit: Maximum number of questions to return.
-
-        Returns:
-            List of ForecastQuestion objects from active markets.
-        """
-        url = f"{self.API_BASE}/events?active=true&closed=false&limit={limit}"
-        if query:
-            url += f"&search={query}"
-
-        try:
-            async with self._get_session() as session:
-                async with session.get(url) as resp:
-                    if resp.status != 200:
-                        logger.error(f"Polymarket API returned status {resp.status}")
-                        return []
-
-                    data = await resp.json()
-                    questions = []
-                    for item in data:
-                        questions.append(self._normalize(item))
-                    return questions
-        except Exception as e:
-            logger.error(f"Failed to fetch questions from Polymarket: {e}")
-            return []
-
-    async def get_question_by_id(self, question_id: str) -> Optional[ForecastQuestion]:
-        r"""
-        Retrieve a single Polymarket event by ID.
-
-        Args:
-            question_id: The unique event identifier.
-
-        Returns:
-            The ForecastQuestion if found, None otherwise.
-        """
-        url = f"{self.API_BASE}/events/{question_id}"
-        try:
-            async with self._get_session() as session:
-                async with session.get(url) as resp:
-                    if resp.status == 200:
-                        return self._normalize(await resp.json())
-                    return None
-        except Exception as e:
-            logger.error(f"Failed to retrieve Polymarket event {question_id}: {e}")
-            return None
-
-    def _normalize(self, item: Dict[str, Any]) -> ForecastQuestion:
-        r"""
-        Normalize Polymarket API response to ForecastQuestion schema.
-
-        Args:
-            item: Raw API response dict.
-
-        Returns:
-            Normalized ForecastQuestion instance.
-        """
-        return ForecastQuestion(
-            id=str(item.get("id", "")),
-            title=item.get("title", "Untitled Event"),
-            description=item.get("description", ""),
-            metadata=MetadataBase(
-                tags=item.get("tags", []),
-                subject_type="binary",
-                source_version="polymarket-gamma-v1",
-                raw_data=item,
-            ),
-        )