xrtm-data 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

xrtm/data/__init__.py

@@ -13,18 +13,44 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from xrtm.data.schemas.forecast import (
+r"""
+xrtm-data: The Foundation Layer (Layer 1)
+
+This package provides the core data schemas and interfaces for the xrtm
+ecosystem. It follows the "Zero Leakage" principle, ensuring all data
+is properly timestamped for temporal isolation.
+
+Structure:
+    - core/: Domain-agnostic interfaces and schemas
+    - kit/: High-level processors and utilities
+    - providers/: External data source implementations
+
+Example:
+    >>> from xrtm.data import ForecastQuestion, DataSource
+    >>> from xrtm.data.providers import LocalDataSource
+"""
+
+# Core interfaces
+from xrtm.data.core import DataSource
+
+# Core schemas (public API)
+from xrtm.data.core.schemas import (
     CausalEdge,
     CausalNode,
+    ConfidenceInterval,
     ForecastOutput,
     ForecastQuestion,
     MetadataBase,
 )
 
 __all__ = [
+    # Interfaces
+    "DataSource",
+    # Schemas
     "MetadataBase",
     "ForecastQuestion",
     "ForecastOutput",
     "CausalNode",
     "CausalEdge",
+    "ConfidenceInterval",
 ]

xrtm/data/core/__init__.py

@@ -0,0 +1,26 @@
+# 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"""
+Core interfaces and protocols for xrtm-data.
+
+This module defines the abstract base classes (protocols) that all data
+providers must implement. The core module is domain-agnostic and MUST NOT
+import from kit/ or providers/.
+"""
+
+from xrtm.data.core.interfaces import DataSource
+
+__all__ = ["DataSource"]

xrtm/data/core/interfaces.py

@@ -0,0 +1,82 @@
+# 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"""
+Abstract interfaces for xrtm-data providers.
+
+This module defines the protocols that all data sources must implement.
+These are domain-agnostic abstractions that can be used for any forecasting
+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):
+    ...         return []
+    ...     async def get_question_by_id(self, question_id):
+    ...         return None
+"""
+
+import abc
+from typing import List, Optional
+
+from xrtm.data.core.schemas.forecast import ForecastQuestion
+
+
+class DataSource(abc.ABC):
+    r"""
+    Abstract interface for gathering or streaming forecasting workloads.
+
+    All data providers (local, online, subgraph) must implement this interface
+    to ensure consistent access patterns across the ecosystem.
+
+    Attributes:
+        None. This is a pure protocol.
+
+    Example:
+        >>> class LocalSource(DataSource):
+        ...     async def fetch_questions(self, query=None, limit=5):
+        ...         return [ForecastQuestion(id="1", title="Test")]
+    """
+
+    @abc.abstractmethod
+    async def fetch_questions(self, query: Optional[str] = None, limit: int = 5) -> 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.
+
+        Returns:
+            List of ForecastQuestion objects matching the criteria.
+        """
+        pass
+
+    @abc.abstractmethod
+    async def get_question_by_id(self, question_id: str) -> Optional[ForecastQuestion]:
+        r"""
+        Retrieve a single question by its unique identifier.
+
+        Args:
+            question_id: The unique identifier of the question.
+
+        Returns:
+            The ForecastQuestion if found, None otherwise.
+        """
+        pass
+
+
+__all__ = ["DataSource"]

xrtm/data/core/schemas/__init__.py

@@ -0,0 +1,39 @@
+# 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"""
+Core data schemas for xrtm-data.
+
+This module exports all foundational Pydantic models used across the
+xrtm ecosystem for representing forecasting data structures.
+"""
+
+from xrtm.data.core.schemas.forecast import (
+    CausalEdge,
+    CausalNode,
+    ConfidenceInterval,
+    ForecastOutput,
+    ForecastQuestion,
+    MetadataBase,
+)
+
+__all__ = [
+    "MetadataBase",
+    "ForecastQuestion",
+    "ForecastOutput",
+    "CausalNode",
+    "CausalEdge",
+    "ConfidenceInterval",
+]

xrtm/data/core/schemas/forecast.py

@@ -0,0 +1,249 @@
+# 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"""
+Core forecast schemas for xrtm-data.
+
+This module defines the foundational Pydantic models used across the xrtm
+ecosystem for representing forecast questions, outputs, and causal reasoning
+structures.
+
+Example:
+    >>> from xrtm.data.core.schemas import ForecastQuestion
+    >>> q = ForecastQuestion(id="q1", title="Will it rain tomorrow?")
+"""
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field
+
+
+class MetadataBase(BaseModel):
+    r"""
+    A foundational metadata block used to ensure consistency across schemas.
+
+    This model captures temporal information critical for the Zero Leakage
+    principle, ensuring all data is properly timestamped.
+
+    Attributes:
+        id: Unique identifier for this metadata block.
+        created_at: When this metadata was created.
+        snapshot_time: The "Time T" at which the world state was frozen.
+        tags: List of classification tags.
+        subject_type: Type of subject being forecasted.
+        source_version: Version of the data source.
+        raw_data: Original unprocessed data.
+    """
+
+    model_config = ConfigDict(extra="allow")
+    id: str = Field(
+        default_factory=lambda: "meta_" + str(datetime.now(timezone.utc).timestamp()),
+        description="Unique identifier for this metadata block",
+    )
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="When this metadata was created",
+    )
+    snapshot_time: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="Zero Leakage: The specific 'Time T' at which the world state was frozen.",
+    )
+    tags: List[str] = Field(default_factory=list, description="Classification tags")
+    subject_type: Optional[str] = Field(None, description="Type of subject being forecasted")
+    source_version: Optional[str] = Field(None, description="Version of the data source")
+    raw_data: Optional[Dict[str, Any]] = Field(None, description="Original unprocessed data")
+
+    def get(self, key: str, default: Any = None) -> Any:
+        r"""Backward compatibility for dict-like access."""
+        return getattr(self, key, default)
+
+
+class ForecastQuestion(BaseModel):
+    r"""
+    The standardized input format for a forecasting task.
+
+    This is the primary input schema used throughout the xrtm ecosystem
+    to represent a question or hypothesis to be forecasted.
+
+    Attributes:
+        id: Unique identifier for the question.
+        title: The main question or statement being forecasted.
+        description: Detailed context and background.
+        resolution_criteria: Explicit rules for ground truth determination.
+        metadata: Associated metadata including temporal information.
+
+    Example:
+        >>> q = ForecastQuestion(
+        ...     id="q1",
+        ...     title="Will Company X announce earnings above expectations?",
+        ...     description="Q4 earnings call scheduled for Jan 15",
+        ... )
+    """
+
+    id: str = Field(..., description="Unique identifier for the question")
+    title: str = Field(..., description="The main question or statement being forecasted")
+    description: Optional[str] = Field(
+        None,
+        alias="content",
+        validation_alias=AliasChoices("description", "content"),
+        description="Detailed context and background",
+    )
+    resolution_criteria: Optional[str] = Field(None, description="Explicit rules for ground truth determination")
+    metadata: MetadataBase = Field(default_factory=MetadataBase)  # type: ignore[arg-type]
+
+    @property
+    def content(self) -> Optional[str]:
+        r"""Backward compatibility alias for description."""
+        return self.description
+
+
+class CausalNode(BaseModel):
+    r"""
+    Represents a single step in a logical reasoning chain.
+
+    Attributes:
+        event: The assumption or event in the chain.
+        probability: Optional probability assigned to this node.
+        description: Additional context for this reasoning step.
+        node_id: Unique identifier for graph operations.
+    """
+
+    event: str = Field(..., description="The assumption or event in the chain")
+    probability: Optional[float] = Field(None, ge=0, le=1, description="Probability of this event")
+    description: Optional[str] = Field(None, description="Additional context")
+    node_id: str = Field(
+        default_factory=lambda: "node_" + str(datetime.now().timestamp()),
+        description="Unique ID for graph operations",
+    )
+
+
+class CausalEdge(BaseModel):
+    r"""
+    Represents a directed causal dependency between two reasoning nodes.
+
+    Attributes:
+        source: ID of the source node.
+        target: ID of the target node.
+        weight: Strength of the causal relationship.
+        description: Context for this causal link.
+    """
+
+    source: str = Field(..., description="ID of the source node")
+    target: str = Field(..., description="ID of the target node")
+    weight: float = Field(default=1.0, ge=0, le=1, description="Strength of causal relationship")
+    description: Optional[str] = Field(None, description="Context for this causal link")
+
+
+class ConfidenceInterval(BaseModel):
+    r"""
+    Standard range for probabilistic calibration.
+
+    Attributes:
+        low: Lower bound of the interval.
+        high: Upper bound of the interval.
+        level: Confidence level (default 0.9 for 90%).
+    """
+
+    low: float = Field(..., description="Lower bound")
+    high: float = Field(..., description="Upper bound")
+    level: float = Field(0.9, ge=0, le=1, description="Confidence level")
+
+
+class ForecastOutput(BaseModel):
+    r"""
+    The structured result of an agent's forecasting reasoning.
+
+    This model captures not just the final probability, but also the
+    complete reasoning chain that led to it, enabling audit and calibration.
+
+    Attributes:
+        question_id: Reference to the input question.
+        probability: The assigned probability of the primary outcome.
+        uncertainty: Optional measure of forecast uncertainty.
+        confidence_interval: Range for calibration.
+        reasoning: Narrative reasoning for the forecast.
+        logical_trace: Bayesian-style sequence of assumptions.
+        logical_edges: Causal dependencies between nodes.
+        structural_trace: Order of graph nodes executed.
+        calibration_metrics: Performance metrics.
+        metadata: Associated temporal and source metadata.
+    """
+
+    question_id: str = Field(..., description="Reference to the input question")
+    probability: float = Field(
+        ...,
+        alias="confidence",
+        validation_alias=AliasChoices("probability", "confidence"),
+        ge=0,
+        le=1,
+        description="The assigned probability of the primary outcome",
+    )
+    uncertainty: Optional[float] = Field(None, ge=0, le=1, description="Measure of forecast uncertainty")
+    confidence_interval: Optional[ConfidenceInterval] = None
+    reasoning: str = Field(..., description="Narrative reasoning for the forecast")
+    logical_trace: List[CausalNode] = Field(
+        default_factory=list, description="The Bayesian-style sequence of assumptions"
+    )
+    logical_edges: List[CausalEdge] = Field(default_factory=list, description="Causal dependencies between nodes")
+    structural_trace: List[str] = Field(default_factory=list, description="Order of graph nodes executed")
+    calibration_metrics: Dict[str, Any] = Field(default_factory=dict, description="Performance metrics")
+    metadata: MetadataBase = Field(default_factory=MetadataBase)  # type: ignore[arg-type]
+
+    @property
+    def confidence(self) -> float:
+        r"""Backward compatibility alias for probability."""
+        return self.probability
+
+    @confidence.setter
+    def confidence(self, value: float) -> None:
+        r"""Backward compatibility setter for probability."""
+        self.probability = value
+
+    def to_networkx(self) -> Any:
+        r"""
+        Convert the logical trace to a NetworkX directed graph.
+
+        Returns:
+            A NetworkX DiGraph representing the reasoning chain.
+
+        Raises:
+            ImportError: If networkx is not installed.
+        """
+        try:
+            import networkx as nx
+        except ImportError:
+            raise ImportError("networkx is required for to_networkx(). Install it with 'uv add networkx'.")
+        dg = nx.DiGraph()
+        for node in self.logical_trace:
+            dg.add_node(
+                node.node_id,
+                event=node.event,
+                probability=node.probability,
+                description=node.description,
+            )
+        for edge in self.logical_edges:
+            dg.add_edge(edge.source, edge.target, weight=edge.weight, description=edge.description)
+        return dg
+
+
+__all__ = [
+    "MetadataBase",
+    "ForecastQuestion",
+    "CausalNode",
+    "CausalEdge",
+    "ConfidenceInterval",
+    "ForecastOutput",
+]

xrtm/data/kit/__init__.py

@@ -0,0 +1,27 @@
+# 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"""
+Researcher Kit for xrtm-data.
+
+This module provides high-level, composable utilities built on top of
+the core interfaces. Kit components use abstractions from core/ and
+MUST NOT import from providers/.
+
+Currently empty - will be populated with data processors (e.g., Beta fitters)
+during the training logic implementation phase.
+"""
+
+__all__: list[str] = []

xrtm/data/providers/__init__.py

@@ -0,0 +1,27 @@
+# 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"""
+Data providers for xrtm-data.
+
+This module exports concrete DataSource implementations that fetch data
+from various external sources. Providers implement the core interfaces
+and CAN import from core/ but MUST NOT import from kit/.
+"""
+
+from xrtm.data.providers.local import LocalDataSource
+from xrtm.data.providers.online import PolymarketSource
+
+__all__ = ["LocalDataSource", "PolymarketSource"]

xrtm/data/providers/local/__init__.py

@@ -0,0 +1,20 @@
+# 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"""Local file-based data providers."""
+
+from xrtm.data.providers.local.csv import LocalDataSource
+
+__all__ = ["LocalDataSource"]

xrtm/data/providers/local/csv.py

@@ -0,0 +1,120 @@
+# 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"""
+Local file-based data source.
+
+This module provides a DataSource implementation that reads forecast
+questions from local JSON files.
+
+Example:
+    >>> from xrtm.data.providers.local import LocalDataSource
+    >>> source = LocalDataSource("./questions.json")
+    >>> questions = await source.fetch_questions(limit=10)
+"""
+
+import asyncio
+import json
+import logging
+from typing import List, Optional
+
+from xrtm.data.core import DataSource
+from xrtm.data.core.schemas import ForecastQuestion
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["LocalDataSource"]
+
+
+class LocalDataSource(DataSource):
+    r"""
+    DataSource implementation that reads from a local JSON file.
+
+    This provider is useful for testing, development, and offline scenarios
+    where data has been pre-fetched and stored locally.
+
+    Args:
+        file_path: Path to the JSON file containing forecast questions.
+
+    Attributes:
+        file_path: The path to the local JSON file.
+
+    Example:
+        >>> source = LocalDataSource("./test_questions.json")
+        >>> questions = await source.fetch_questions(query="weather", limit=5)
+    """
+
+    def __init__(self, file_path: str) -> None:
+        self.file_path = file_path
+        self._questions: Optional[List[dict]] = None
+
+    def _fetch_questions_sync(self, query: Optional[str] = None, limit: int = 5) -> List[ForecastQuestion]:
+        r"""Synchronous implementation of question fetching."""
+        try:
+            if self._questions is None:
+                with open(self.file_path, "r") as f:
+                    self._questions = json.load(f)
+
+            questions = []
+            for item in self._questions:
+                if not query or query.lower() in item.get("title", "").lower():
+                    questions.append(ForecastQuestion(**item))
+
+                if len(questions) >= limit:
+                    break
+            return questions
+        except Exception as e:
+            logger.error(f"Failed to read local questions from {self.file_path}: {e}")
+            return []
+
+    async def fetch_questions(self, query: Optional[str] = None, limit: int = 5) -> 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.
+
+        Returns:
+            List of ForecastQuestion objects matching the criteria.
+        """
+        return await asyncio.to_thread(self._fetch_questions_sync, query, limit)
+
+    def _get_question_by_id_sync(self, question_id: str) -> Optional[ForecastQuestion]:
+        r"""Synchronous implementation of single question retrieval."""
+        try:
+            if self._questions is None:
+                with open(self.file_path, "r") as f:
+                    self._questions = json.load(f)
+
+            for item in self._questions:
+                if item.get("id") == question_id:
+                    return ForecastQuestion(**item)
+            return None
+        except Exception as e:
+            logger.error(f"Failed to retrieve question {question_id} from {self.file_path}: {e}")
+            return None
+
+    async def get_question_by_id(self, question_id: str) -> Optional[ForecastQuestion]:
+        r"""
+        Retrieve a single question by ID from the local file.
+
+        Args:
+            question_id: The unique identifier of the question.
+
+        Returns:
+            The ForecastQuestion if found, None otherwise.
+        """
+        return await asyncio.to_thread(self._get_question_by_id_sync, question_id)

xrtm/data/providers/online/__init__.py

@@ -0,0 +1,20 @@
+# 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"""Online API-based data providers."""
+
+from xrtm.data.providers.online.polymarket import PolymarketSource
+
+__all__ = ["PolymarketSource"]

xrtm/data/providers/{data/online → online}/polymarket.py

@@ -1,13 +1,37 @@
 # 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 typing import Any, Dict, List, Optional
 
 import aiohttp
 
-from xrtm.data.providers.data.base import DataSource
-from xrtm.data.schemas.forecast import ForecastQuestion, MetadataBase
+from xrtm.data.core import DataSource
+from xrtm.data.core.schemas import ForecastQuestion, MetadataBase
 
 logger = logging.getLogger(__name__)
 
@@ -17,11 +41,33 @@ __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"
 
     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}"
@@ -43,6 +89,15 @@ class PolymarketSource(DataSource):
             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 aiohttp.ClientSession() as session:
@@ -55,10 +110,19 @@ class PolymarketSource(DataSource):
             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"),
-            content=item.get("description", ""),
+            description=item.get("description", ""),
             metadata=MetadataBase(
                 tags=item.get("tags", []),
                 subject_type="binary",

xrtm/data/version.py

@@ -0,0 +1,28 @@
+# 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"""
+Version information for xrtm-data.
+
+This module provides the single source of truth for the package version.
+"""
+
+__all__ = ["__version__", "__author__", "__contact__", "__license__", "__copyright__"]
+
+__version__ = "0.2.0"
+__author__ = "XRTM Team"
+__contact__ = "moy@xrtm.org"
+__license__ = "Apache-2.0"
+__copyright__ = "Copyright 2026 XRTM Team"

{xrtm_data-0.1.0.dist-info → xrtm_data-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrtm-data
-Version: 0.1.0
+Version: 0.2.0
 Summary: The Snapshot Vault for XRTM.
 Author-email: XRTM Team <moy@xrtm.org>
 License: Apache-2.0
@@ -21,15 +21,27 @@ Dynamic: license-file
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/xrtm-data.svg)](https://pypi.org/project/xrtm-data/)
 
 **The Snapshot Vault for XRTM.**
 
 `xrtm-data` provides the rigid schemas and temporal sandboxing infrastructure required for zero-leakage forecasting. It defines the "Ground Truth" data structures that the rest of the ecosystem (Forecast, Eval, Train) relies on.
 
+## Part of the XRTM Ecosystem
+
+```
+Layer 4: xrtm-train    → (imports all)
+Layer 3: xrtm-forecast → (imports eval, data)
+Layer 2: xrtm-eval     → (imports data)
+Layer 1: xrtm-data     → (zero dependencies) ← YOU ARE HERE
+```
+
+`xrtm-data` is the foundation layer with **zero dependencies** on other xrtm packages.
+
 ## Installation
 
 ```bash
-uv pip install xrtm-data
+pip install xrtm-data
 ```
 
 ## Core Primitives
@@ -54,6 +66,19 @@ prediction = ForecastOutput(
 ### 2. Zero Leakage
 The `MetadataBase` enforces a strict `snapshot_time`. This timestamp represents the "End of History" for the model. Any data point generated after this time is considered "Future Leakage" and is programmatically inaccessible during backtesting.
 
+## Project Structure
+
+```
+src/xrtm/data/
+├── core/            # Interfaces & Schemas (domain-agnostic)
+│   ├── interfaces.py    # DataSource protocol
+│   └── schemas/         # ForecastQuestion, ForecastOutput, etc.
+├── kit/             # Composable utilities (processors)
+└── providers/       # External data source implementations
+    ├── local/           # LocalDataSource (JSON files)
+    └── online/          # PolymarketSource (Gamma API)
+```
+
 ## Development
 
 Prerequisites:

xrtm_data-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+xrtm/data/__init__.py,sha256=UTaJBIZScoMJMlnaopghWecvAOCSSBXM72JOLBfW-Yc,1578
+xrtm/data/version.py,sha256=unDkjMG2k5bVOLaPToqkq8QKf10iSygOTCyxCOrHEig,964
+xrtm/data/core/__init__.py,sha256=eONxw_v-xjXkErcC-BH2K15-KJx57aBZZxxvZM-qEcY,920
+xrtm/data/core/interfaces.py,sha256=i8CZv-p4PXk1sTnoUAEHw5grbL2s3sbVZI01JbwI4LI,2589
+xrtm/data/core/schemas/__init__.py,sha256=CAErO_XSAQMkfAYr2wVgdR_kYaiYG-hC4HXmbKOtdfY,1092
+xrtm/data/core/schemas/forecast.py,sha256=IiFEMjZzhr9aJci4RbcX42BGK5gjNWh45s41BRMDukA,9607
+xrtm/data/kit/__init__.py,sha256=C02rIncfR_bde2KZJ6O47qog3kdTzp__FjTyrrPhXWU,974
+xrtm/data/providers/__init__.py,sha256=mg76kKnfOESoeHPArreDUZXaQtEcU3axJo_JntF-3RY,1013
+xrtm/data/providers/local/__init__.py,sha256=CWucgoHFHMnOsUTvh3B5a7_JukmJFJzkPHTvBKf0YiI,741
+xrtm/data/providers/local/csv.py,sha256=AwyvE5Kq0nyyLdkYzgUbZDShV28-uieBaI4A_V6R7WQ,4202
+xrtm/data/providers/online/__init__.py,sha256=aB55dO83DfAQ2Pj0J8eUxI_LbfyGoQ5blFl9wbgoOvM,751
+xrtm/data/providers/online/polymarket.py,sha256=Kllm1ZvVqM1C1BT3YVaLzLxg2c-lLX0Gz2dCXSZD2S0,4476
+xrtm_data-0.2.0.dist-info/licenses/LICENSE,sha256=BexUTTsX5WlzyJ0Tqajo1h_LFYfCtfFgWdRaGltpm5I,11328
+xrtm_data-0.2.0.dist-info/METADATA,sha256=XR2vdhbtRA8-WFuNqZqs1mWt3jmRn91zgCeUO7AMtBU,3032
+xrtm_data-0.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+xrtm_data-0.2.0.dist-info/top_level.txt,sha256=Jz-i0a9P8GVrIR9KJTT-9wT95E1brww6U5o2QViAt20,5
+xrtm_data-0.2.0.dist-info/RECORD,,

xrtm/data/providers/data/__init__.py

@@ -1,4 +0,0 @@
-from .base import DataSource
-from .local import LocalDataSource
-
-__all__ = ["DataSource", "LocalDataSource"]

xrtm/data/providers/data/base.py

@@ -1,24 +0,0 @@
-# coding=utf-8
-# Copyright 2026 XRTM Team. All rights reserved.
-
-import abc
-from typing import List, Optional
-
-from xrtm.data.schemas.forecast import ForecastQuestion
-
-
-class DataSource(abc.ABC):
-    r"""
-    Abstract interface for gathering or streaming forecasting workloads.
-    """
-
-    @abc.abstractmethod
-    async def fetch_questions(self, query: Optional[str] = None, limit: int = 5) -> List[ForecastQuestion]:
-        pass
-
-    @abc.abstractmethod
-    async def get_question_by_id(self, question_id: str) -> Optional[ForecastQuestion]:
-        pass
-
-
-__all__ = ["DataSource"]

xrtm/data/providers/data/local.py

@@ -1,52 +0,0 @@
-# coding=utf-8
-# Copyright 2026 XRTM Team. All rights reserved.
-
-import json
-import logging
-from typing import List, Optional
-
-from xrtm.data.providers.data.base import DataSource
-from xrtm.data.schemas.forecast import ForecastQuestion
-
-logger = logging.getLogger(__name__)
-
-__all__ = ["LocalDataSource"]
-
-
-class LocalDataSource(DataSource):
-    r"""
-    DataSource implementation that reads from a local JSON file.
-    """
-
-    def __init__(self, file_path: str):
-        self.file_path = file_path
-
-    async def fetch_questions(self, query: Optional[str] = None, limit: int = 5) -> List[ForecastQuestion]:
-        try:
-            with open(self.file_path, "r") as f:
-                data = json.load(f)
-
-            questions = []
-            for item in data:
-                if not query or query.lower() in item.get("title", "").lower():
-                    questions.append(ForecastQuestion(**item))
-
-                if len(questions) >= limit:
-                    break
-            return questions
-        except Exception as e:
-            logger.error(f"Failed to read local questions from {self.file_path}: {e}")
-            return []
-
-    async def get_question_by_id(self, question_id: str) -> Optional[ForecastQuestion]:
-        try:
-            with open(self.file_path, "r") as f:
-                data = json.load(f)
-
-            for item in data:
-                if item.get("id") == question_id:
-                    return ForecastQuestion(**item)
-            return None
-        except Exception as e:
-            logger.error(f"Failed to retrieve question {question_id} from {self.file_path}: {e}")
-            return None

xrtm/data/providers/data/online/__init__.py

@@ -1,3 +0,0 @@
-from .polymarket import PolymarketSource
-
-__all__ = ["PolymarketSource"]

xrtm/data/schemas/__init__.py

@@ -1,3 +0,0 @@
-from .forecast import ForecastQuestion, MetadataBase
-
-__all__ = ["MetadataBase", "ForecastQuestion"]

xrtm/data/schemas/forecast.py

@@ -1,137 +0,0 @@
-# coding=utf-8
-# Copyright 2026 XRTM Team. All rights reserved.
-
-from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional
-
-from pydantic import AliasChoices, BaseModel, ConfigDict, Field
-
-
-class MetadataBase(BaseModel):
-    r"""
-    A foundational metadata block used to ensure consistency across schemas.
-    """
-
-    model_config = ConfigDict(extra="allow")
-    id: str = Field(default_factory=lambda: "meta_" + str(datetime.now(timezone.utc).timestamp()))
-    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
-    snapshot_time: datetime = Field(
-        default_factory=lambda: datetime.now(timezone.utc),
-        description="Zero Leakage: The specific 'Time T' at which the world state was frozen."
-    )
-    tags: List[str] = Field(default_factory=list)
-    subject_type: Optional[str] = None
-    source_version: Optional[str] = None
-    raw_data: Optional[Dict[str, Any]] = None
-
-    def get(self, key: str, default: Any = None) -> Any:
-        r"""Backward compatibility for dict-like access."""
-        return getattr(self, key, default)
-
-
-class ForecastQuestion(BaseModel):
-    r"""
-    The standardized input format for a forecasting task.
-    """
-
-    id: str = Field(..., description="Unique identifier for the question")
-    title: str = Field(..., description="The main question or statement being forecasted")
-    description: Optional[str] = Field(
-        None,
-        alias="content",
-        validation_alias=AliasChoices("description", "content"),
-        description="Detailed context and background",
-    )
-    resolution_criteria: Optional[str] = Field(None, description="Explicit rules for ground truth determination")
-    metadata: MetadataBase = Field(default_factory=MetadataBase)
-
-    @property
-    def content(self) -> Optional[str]:
-        r"""Backward compatibility alias for description."""
-        return self.description
-
-
-class CausalNode(BaseModel):
-    r"""
-    Represents a single step in a logical reasoning chain.
-    """
-    event: str = Field(..., description="The assumption or event in the chain")
-    probability: Optional[float] = Field(None, ge=0, le=1)
-    description: Optional[str] = None
-    node_id: str = Field(
-        default_factory=lambda: "node_" + str(datetime.now().timestamp()), description="Unique ID for graph operations"
-    )
-
-
-class CausalEdge(BaseModel):
-    r"""
-    Represents a directed causal dependency between two reasoning nodes.
-    """
-    source: str
-    target: str
-    weight: float = Field(default=1.0, ge=0, le=1)
-    description: Optional[str] = None
-
-
-class ConfidenceInterval(BaseModel):
-    r"""Standard range for probabilistic calibration."""
-    low: float
-    high: float
-    level: float = 0.9
-
-
-class ForecastOutput(BaseModel):
-    r"""
-    The structured result of an agent's forecasting reasoning, compliant with Governance v1.
-    """
-    question_id: str
-    probability: float = Field(
-        ...,
-        alias="confidence",
-        validation_alias=AliasChoices("probability", "confidence"),
-        ge=0,
-        le=1,
-        description="The assigned probability of the primary outcome",
-    )
-    uncertainty: Optional[float] = Field(None, ge=0, le=1)
-    confidence_interval: Optional[ConfidenceInterval] = None
-    reasoning: str = Field(..., description="Narrative reasoning for the forecast")
-    logical_trace: List[CausalNode] = Field(
-        default_factory=list, description="The Bayesian-style sequence of assumptions (Mental Model)"
-    )
-    logical_edges: List[CausalEdge] = Field(
-        default_factory=list, description="Causal dependencies between nodes in the trace"
-    )
-    structural_trace: List[str] = Field(default_factory=list, description="Order of graph nodes executed (Audit Trail)")
-    calibration_metrics: Dict[str, Any] = Field(default_factory=dict)
-    metadata: MetadataBase = Field(default_factory=MetadataBase)
-
-    @property
-    def confidence(self) -> float:
-        r"""Backward compatibility alias for probability."""
-        return self.probability
-
-    @confidence.setter
-    def confidence(self, value: float):
-        r"""Backward compatibility setter for probability."""
-        self.probability = value
-
-    def to_networkx(self) -> Any:
-        try:
-            import networkx as nx
-        except ImportError:
-            raise ImportError("networkx is required for to_networkx(). Install it with 'pip install networkx'.")
-        dg = nx.DiGraph()
-        for node in self.logical_trace:
-            dg.add_node(
-                node.node_id,
-                event=node.event,
-                probability=node.probability,
-                description=node.description,
-            )
-        for edge in self.logical_edges:
-            dg.add_edge(edge.source, edge.target, weight=edge.weight, description=edge.description)
-        return dg
-
-
-__all__ = ["MetadataBase", "ForecastQuestion", "CausalNode", "CausalEdge", "ForecastOutput"]

xrtm_data-0.1.0.dist-info/RECORD

@@ -1,13 +0,0 @@
-xrtm/data/__init__.py,sha256=e3DN4n5besbAxcEiFR5nBEXcaFvvtD1NulRXOWwSZSc,863
-xrtm/data/providers/data/__init__.py,sha256=53T9VrE33ndux16r0Z2vQQlpIUzV9yaudqXr2YOMgmY,109
-xrtm/data/providers/data/base.py,sha256=sXtAqJ9PF2z7TTRhD-RG1ORVkmmPJdi6DPFTlTblrec,585
-xrtm/data/providers/data/local.py,sha256=J7nQfaT4yGJF3-dYNZQM5zl6hB8pEVz48YGqhzk2HXY,1645
-xrtm/data/providers/data/online/__init__.py,sha256=AD6BTffDyajN_qZfpjzTOKk6KhFTBh1T51bAOzHew3o,73
-xrtm/data/providers/data/online/polymarket.py,sha256=VOZtl_lc6wpQ3V2sAKIEJVAMC4P9lnkZ1wL0ERYIBi4,2418
-xrtm/data/schemas/__init__.py,sha256=Y6OSOai_6qd9b0-ZhWPSNZfWXI3STM7kta60DjF9hBY,101
-xrtm/data/schemas/forecast.py,sha256=Wu5W_ThUTQSjm6Sx3WMcBw-MwlCMqAqSbcoW1d3moHk,4952
-xrtm_data-0.1.0.dist-info/licenses/LICENSE,sha256=BexUTTsX5WlzyJ0Tqajo1h_LFYfCtfFgWdRaGltpm5I,11328
-xrtm_data-0.1.0.dist-info/METADATA,sha256=9X7NnYWCptYXNC7GIO5I8nZz4n34RIeCEF1A4MrxqSY,2124
-xrtm_data-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-xrtm_data-0.1.0.dist-info/top_level.txt,sha256=Jz-i0a9P8GVrIR9KJTT-9wT95E1brww6U5o2QViAt20,5
-xrtm_data-0.1.0.dist-info/RECORD,,