xrtm-data 0.1.0__tar.gz → 0.2.0__tar.gz

{xrtm_data-0.1.0/src/xrtm_data.egg-info → xrtm_data-0.2.0}/PKG-INFO

@@ -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.1.0 → xrtm_data-0.2.0}/README.md

@@ -2,15 +2,27 @@
 
 [![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
@@ -35,6 +47,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.1.0 → xrtm_data-0.2.0}/pyproject.toml

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

xrtm_data-0.2.0/src/xrtm/data/__init__.py

@@ -0,0 +1,56 @@
+# 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"""
+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-0.2.0/src/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-0.2.0/src/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-0.1.0/src/xrtm/data → xrtm_data-0.2.0/src/xrtm/data/core/schemas}/__init__.py

@@ -13,9 +13,17 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from xrtm.data.schemas.forecast import (
+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,
@@ -27,4 +35,5 @@ __all__ = [
     "ForecastOutput",
     "CausalNode",
     "CausalEdge",
+    "ConfidenceInterval",
 ]

xrtm_data-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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"]