xrtm-data 0.2.7__tar.gz → 0.3.1__tar.gz

xrtm_data-0.3.1/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: xrtm-data
+Version: 0.3.1
+Summary: The Snapshot Vault for XRTM.
+Author-email: XRTM Team <moy@xrtm.org>
+License-Expression: Apache-2.0
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: scipy>=1.11.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# xrtm-data v0.3.0
+
+[![PyPI](https://img.shields.io/pypi/v/xrtm-data?style=flat-square)](https://pypi.org/project/xrtm-data/)
+
+[![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/)
+
+**The Snapshot Vault for XRTM.**
+
+`xrtm-data` provides the schemas, question sources, and temporal sandboxing for the XRTM forecasting ecosystem.
+
+## Installation
+
+```bash
+pip install xrtm-data
+```
+
+## Schemas
+
+- **`ForecastQuestion`** — Standardized forecast question input
+- **`ForecastOutput`** (alias `ForecastResult`) — Forecast result with probability, reasoning trace, causal graph
+- **`CausalNode` / `CausalEdge` / `CausalGraph`** — Reasoning chain DAG
+- **`BetaPrior` / `PriorState`** — Beta distribution for belief states
+- **`TradeEvent` / `TradeWindow`** — Market trade data with temporal integrity
+
+## Question Sources
+
+| Source | API Key | Description |
+|--------|---------|-------------|
+| **real-binary** | None | 21 embedded historical binary questions (CI fixture) |
+| **Polymarket** | None (public) | Live prediction market data via Gamma API |
+| **Metaculus** | Free account | Forecasting questions from Metaculus |
+
+```python
+from xrtm.data.corpora import load_real_binary_questions
+from xrtm.data.providers.online import PolymarketSource, MetaculusSource
+
+# Built-in corpus
+
+
+questions = load_real_binary_questions(limit=5)
+
+# Live prediction markets (no API key)
+poly = PolymarketSource()
+markets = await poly.fetch_questions(limit=10)
+
+# Metaculus (needs METACULUS_API_KEY)
+meta = MetaculusSource()
+meta_qs = await meta.fetch_questions(limit=10)
+```
+
+## License
+
+Apache 2.0

xrtm_data-0.3.1/README.md

@@ -0,0 +1,54 @@
+# xrtm-data v0.3.0
+
+[![PyPI](https://img.shields.io/pypi/v/xrtm-data?style=flat-square)](https://pypi.org/project/xrtm-data/)
+
+[![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/)
+
+**The Snapshot Vault for XRTM.**
+
+`xrtm-data` provides the schemas, question sources, and temporal sandboxing for the XRTM forecasting ecosystem.
+
+## Installation
+
+```bash
+pip install xrtm-data
+```
+
+## Schemas
+
+- **`ForecastQuestion`** — Standardized forecast question input
+- **`ForecastOutput`** (alias `ForecastResult`) — Forecast result with probability, reasoning trace, causal graph
+- **`CausalNode` / `CausalEdge` / `CausalGraph`** — Reasoning chain DAG
+- **`BetaPrior` / `PriorState`** — Beta distribution for belief states
+- **`TradeEvent` / `TradeWindow`** — Market trade data with temporal integrity
+
+## Question Sources
+
+| Source | API Key | Description |
+|--------|---------|-------------|
+| **real-binary** | None | 21 embedded historical binary questions (CI fixture) |
+| **Polymarket** | None (public) | Live prediction market data via Gamma API |
+| **Metaculus** | Free account | Forecasting questions from Metaculus |
+
+```python
+from xrtm.data.corpora import load_real_binary_questions
+from xrtm.data.providers.online import PolymarketSource, MetaculusSource
+
+# Built-in corpus
+
+
+questions = load_real_binary_questions(limit=5)
+
+# Live prediction markets (no API key)
+poly = PolymarketSource()
+markets = await poly.fetch_questions(limit=10)
+
+# Metaculus (needs METACULUS_API_KEY)
+meta = MetaculusSource()
+meta_qs = await meta.fetch_questions(limit=10)
+```
+
+## License
+
+Apache 2.0

{xrtm_data-0.2.7 → xrtm_data-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xrtm-data"
-version = "0.2.7"
+version = "0.3.1"
 description = "The Snapshot Vault for XRTM."
 readme = "README.md"
 requires-python = ">=3.11,<3.13"
@@ -14,11 +14,7 @@ authors = [
 ]
 dependencies = [
     "pydantic>=2.0.0",
-    "aiohttp>=3.9.0",
     "scipy>=1.11.0",
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pyarrow>=14.0.0",
 ]
 
 [project.optional-dependencies]
@@ -30,9 +26,6 @@ dev = [
     "mypy>=1.0.0",
 ]
 
-[project.scripts]
-xrtm-data = "xrtm.data.cli:main"
-
 [tool.setuptools]
 package-dir = {"" = "src"}
 packages = {find = {where = ["src"], include = ["xrtm*"], namespaces = true}}
@@ -55,3 +48,4 @@ python_version = "3.11"
 ignore_missing_imports = true
 strict = false
 explicit_package_bases = true
+exclude = ["build/", "dist/"]

{xrtm_data-0.2.7 → xrtm_data-0.3.1}/src/xrtm/data/__init__.py

@@ -27,7 +27,6 @@ Structure:
 
 Example:
     >>> from xrtm.data import ForecastQuestion, DataSource
-    >>> from xrtm.data.providers import LocalDataSource
 """
 
 # Core interfaces

{xrtm_data-0.2.7 → xrtm_data-0.3.1}/src/xrtm/data/core/schemas/forecast.py

@@ -155,7 +155,7 @@ class CausalEdge(BaseModel):
 
     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")
+    weight: float = Field(default=1.0, ge=-1, le=1, description="Strength of causal relationship (negative = inhibitory)")
     description: Optional[str] = Field(None, description="Context for this causal link")
 
 

xrtm_data-0.3.1/src/xrtm/data/corpora/__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"""Public entry points for XRTM corpora."""
+
+from xrtm.data.corpora.real_binary import (
+    REAL_BINARY_CORPUS_ID,
+    RealBinaryCorpusSource,
+    RealBinaryQuestionRecord,
+    load_real_binary_corpus,
+    load_real_binary_questions,
+    load_real_binary_resolved_outcomes,
+    validate_real_binary_corpus,
+)
+from xrtm.data.corpora.registry import (
+    CorpusManifest,
+    CorpusMetadata,
+    CorpusRegistry,
+    CorpusSplit,
+    CorpusTier,
+    LicenseType,
+    get_corpus,
+    get_corpus_metadata,
+    list_available_corpora,
+)
+
+__all__ = [
+    "REAL_BINARY_CORPUS_ID",
+    "RealBinaryQuestionRecord",
+    "RealBinaryCorpusSource",
+    "load_real_binary_corpus",
+    "load_real_binary_questions",
+    "load_real_binary_resolved_outcomes",
+    "validate_real_binary_corpus",
+    "CorpusRegistry",
+    "CorpusMetadata",
+    "CorpusManifest",
+    "CorpusTier",
+    "LicenseType",
+    "CorpusSplit",
+    "get_corpus",
+    "get_corpus_metadata",
+    "list_available_corpora",
+]

xrtm_data-0.3.1/src/xrtm/data/corpora/_builtin_corpora.py

@@ -0,0 +1,61 @@
+# 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"""Concrete built-in corpus registrations."""
+
+from __future__ import annotations
+
+from typing import List
+
+from xrtm.data.corpora.real_binary import REAL_BINARY_CORPUS_ID, RealBinaryCorpusSource
+from xrtm.data.corpora.registry import (
+    CorpusManifest,
+    CorpusMetadata,
+    CorpusSplit,
+    CorpusTier,
+    LicenseType,
+)
+
+
+def build_builtin_manifests() -> List[CorpusManifest]:
+    """Build manifests for the corpora shipped with the registry bootstrap."""
+    return [
+        _build_real_binary_manifest(),
+    ]
+
+
+def _build_real_binary_manifest() -> CorpusManifest:
+    real_binary_metadata = CorpusMetadata(
+        corpus_id=REAL_BINARY_CORPUS_ID,
+        name="XRTM Real Binary v1",
+        tier=CorpusTier.TIER_1,
+        license_type=LicenseType.APACHE_2_0,
+        description="Minimal deterministic real-world binary question corpus for CI smoke tests",
+        version="1.0",
+        release_gate_approved=True,
+        bundled=True,
+        size_estimate=25,
+        tags=["binary", "deterministic", "embedded", "seed-corpus"],
+        provenance_url="https://github.com/xrtm/xrtm",
+        license_url="https://www.apache.org/licenses/LICENSE-2.0",
+    )
+
+    return CorpusManifest(
+        corpus_id=REAL_BINARY_CORPUS_ID,
+        metadata=real_binary_metadata,
+        loader_fn=lambda: RealBinaryCorpusSource(),
+        available_splits=[CorpusSplit.FULL],
+        default_split=CorpusSplit.FULL,
+    )

{xrtm_data-0.2.7/src/xrtm/data/providers/local → xrtm_data-0.3.1/src/xrtm/data/providers}/__init__.py

@@ -13,8 +13,4 @@
 # 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"]
+r"""External data providers implementing the DataSource ABC."""

{xrtm_data-0.2.7 → xrtm_data-0.3.1}/src/xrtm/data/providers/online/__init__.py

@@ -13,8 +13,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-r"""Online API-based data providers."""
+r"""Online data providers (Metaculus, Polymarket, etc.)."""
 
+from xrtm.data.providers.online.metaculus import MetaculusSource
 from xrtm.data.providers.online.polymarket import PolymarketSource
 
-__all__ = ["PolymarketSource"]
+__all__ = ["MetaculusSource", "PolymarketSource"]

xrtm_data-0.3.1/src/xrtm/data/providers/online/metaculus.py

@@ -0,0 +1,155 @@
+# 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"""Metaculus data provider.
+
+Fetches forecasting questions from the Metaculus API.
+Requires a Metaculus API key (free account). Set ``METACULUS_API_KEY``
+environment variable or pass ``api_key`` to the constructor.
+
+Get a key: https://www.metaculus.com/accounts/signup/
+API docs: https://www.metaculus.com/api2/
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.request
+from datetime import datetime, timezone
+from typing import Any
+
+from xrtm.data.core.interfaces import DataSource, DataSourceError
+from xrtm.data.core.schemas.forecast import ForecastQuestion, MetadataBase
+
+logger = logging.getLogger(__name__)
+
+METACULUS_API_BASE = "https://www.metaculus.com/api2"
+
+
+class MetaculusSource(DataSource):
+    r"""Data source for Metaculus forecasting questions.
+
+    Fetches open binary questions from the Metaculus API.
+    Requires a Metaculus API key. Set ``METACULUS_API_KEY`` env var
+    or pass ``api_key`` to the constructor.
+    (Free account at https://www.metaculus.com/accounts/signup/)
+
+    Example:
+        >>> source = MetaculusSource(api_key="...")
+        >>> questions = await source.fetch_questions(limit=5)
+    """
+
+    def __init__(self, api_base: str = METACULUS_API_BASE, api_key: str | None = None):
+        import os
+        self.api_base = api_base.rstrip("/")
+        self.api_key = api_key or os.environ.get("METACULUS_API_KEY", "")
+        if not self.api_key:
+            logger.warning(
+                "MetaculusSource: No METACULUS_API_KEY set. API calls will fail. "
+                "Get a free key at https://www.metaculus.com/accounts/signup/"
+            )
+
+    async def fetch_questions(
+        self,
+        limit: int = 10,
+        offset: int = 0,
+        **kwargs: Any,
+    ) -> list[ForecastQuestion]:
+        r"""Fetch open binary questions from Metaculus.
+
+        Args:
+            limit: Maximum number of questions to return.
+            offset: Pagination offset.
+            **kwargs: Additional filters (ignored).
+
+        Returns:
+            List of ``ForecastQuestion`` objects.
+        """
+        url = (
+            f"{self.api_base}/questions/?"
+            f"limit={min(limit, 100)}&offset={offset}"
+            f"&order_by=-activity&status=open&type=binary"
+        )
+        data = self._get_json(url)
+        results = data.get("results", [])
+
+        questions = []
+        for item in results[:limit]:
+            try:
+                questions.append(self._to_forecast_question(item))
+            except Exception as exc:
+                logger.warning(f"Skipping Metaculus question {item.get('id')}: {exc}")
+        return questions
+
+    async def get_question_by_id(self, question_id: str) -> ForecastQuestion | None:
+        r"""Fetch a single Metaculus question by ID."""
+        try:
+            url = f"{self.api_base}/questions/{question_id}/"
+            data = self._get_json(url)
+            return self._to_forecast_question(data)
+        except Exception as exc:
+            logger.warning(f"Metaculus question {question_id} not found: {exc}")
+            return None
+
+    def _get_json(self, url: str) -> dict[str, Any]:
+        r"""Fetch JSON from a URL."""
+        headers = {"User-Agent": "xrtm/0.1"}
+        if self.api_key:
+            headers["Authorization"] = f"Token {self.api_key}"
+        req = urllib.request.Request(url, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=15) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except Exception as exc:
+            raise DataSourceError(f"Metaculus API error: {exc}") from exc
+
+    @staticmethod
+    def _to_forecast_question(item: dict[str, Any]) -> ForecastQuestion:
+        r"""Convert a Metaculus API question dict to ``ForecastQuestion``."""
+        qid = str(item.get("id", ""))
+        title = item.get("title", "") or item.get("name", "")
+        description = item.get("description", "") or ""
+        resolution_criteria = item.get("resolution_criteria", "") or ""
+
+        publish_time = item.get("publish_time") or item.get("created_at")
+        close_time = item.get("close_time") or item.get("resolve_time")
+        snapshot_time = datetime.now(timezone.utc)
+
+        if close_time:
+            try:
+                snapshot_time = datetime.fromisoformat(close_time.replace("Z", "+00:00"))
+            except (ValueError, TypeError):
+                pass
+
+        return ForecastQuestion(
+            id=f"metaculus-{qid}",
+            title=title[:500],
+            description=description[:2000] if description else f"Metaculus binary question {qid}",
+            resolution_criteria=resolution_criteria[:1000] if resolution_criteria else "",
+            metadata=MetadataBase(
+                snapshot_time=snapshot_time,
+                source_version="metaculus",
+                tags=["metaculus", "binary"],
+                raw_data={
+                    "metaculus_id": qid,
+                    "publish_time": publish_time,
+                    "community_prediction": item.get("community_prediction"),
+                },
+            ),
+        )
+
+
+__all__ = ["MetaculusSource"]

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

@@ -0,0 +1,161 @@
+# 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 data provider.
+
+Fetches prediction market data from the Polymarket Gamma API.
+The API is free and public for read access.
+
+API docs: https://docs.polymarket.com/
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.request
+from datetime import datetime, timezone
+from typing import Any
+
+from xrtm.data.core.interfaces import DataSource, DataSourceError
+from xrtm.data.core.schemas.forecast import ForecastQuestion, MetadataBase
+
+logger = logging.getLogger(__name__)
+
+POLYMARKET_GAMMA_API = "https://gamma-api.polymarket.com"
+
+
+class PolymarketSource(DataSource):
+    r"""Data source for Polymarket prediction markets.
+
+    Fetches open binary markets from the Polymarket Gamma API.
+    No authentication required for read access.
+
+    Args:
+        api_base: Override the API base URL.
+
+    Example:
+        >>> source = PolymarketSource()
+        >>> questions = await source.fetch_questions(limit=5)
+    """
+
+    def __init__(self, api_base: str = POLYMARKET_GAMMA_API):
+        self.api_base = api_base.rstrip("/")
+
+    async def fetch_questions(
+        self,
+        limit: int = 10,
+        offset: int = 0,
+        **kwargs: Any,
+    ) -> list[ForecastQuestion]:
+        r"""Fetch open binary markets from Polymarket.
+
+        Args:
+            limit: Maximum number of markets to return.
+            offset: Pagination offset.
+            **kwargs: Additional filters.
+
+        Returns:
+            List of ``ForecastQuestion`` objects.
+        """
+        url = (
+            f"{self.api_base}/markets?"
+            f"limit={min(limit, 100)}&offset={offset}"
+            f"&closed=false&order=volume24hr&ascending=false"
+        )
+        try:
+            data = self._get_json(url)
+        except DataSourceError:
+            # Gamma API may return a list directly
+            url = f"{self.api_base}/events?limit={min(limit, 50)}&closed=false"
+            data = self._get_json(url)
+
+        # Gamma API may wrap in "markets" key or return list directly
+        items = data if isinstance(data, list) else data.get("markets", data.get("results", []))
+
+        questions = []
+        for item in items[:limit]:
+            try:
+                questions.append(self._to_forecast_question(item))
+            except Exception as exc:
+                logger.warning(f"Skipping Polymarket market {item.get('id')}: {exc}")
+        return questions
+
+    async def get_question_by_id(self, question_id: str) -> ForecastQuestion | None:
+        r"""Fetch a single Polymarket market by ID."""
+        # Strip prefix if present
+        market_id = question_id.replace("polymarket-", "")
+        try:
+            url = f"{self.api_base}/markets/{market_id}"
+            data = self._get_json(url)
+            return self._to_forecast_question(data)
+        except Exception as exc:
+            logger.warning(f"Polymarket market {market_id} not found: {exc}")
+            return None
+
+    def _get_json(self, url: str) -> Any:
+        r"""Fetch JSON from a URL."""
+        req = urllib.request.Request(url, headers={"User-Agent": "xrtm/0.1"})
+        try:
+            with urllib.request.urlopen(req, timeout=15) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except Exception as exc:
+            raise DataSourceError(f"Polymarket API error: {exc}") from exc
+
+    @staticmethod
+    def _to_forecast_question(item: dict[str, Any]) -> ForecastQuestion:
+        r"""Convert a Polymarket API market dict to ``ForecastQuestion``."""
+        market_id = str(item.get("id", ""))
+        question_text = item.get("question", "") or item.get("title", "") or ""
+        description = item.get("description", "") or ""
+
+        # Extract outcome prices if available
+        outcomes = item.get("outcomes", []) or []
+        outcome_prices = item.get("outcomePrices", []) or []
+        price_info = ""
+        if outcomes and outcome_prices and len(outcomes) == len(outcome_prices):
+            parts = [f"{o}: {float(p)*100:.1f}%" for o, p in zip(outcomes, outcome_prices)]
+            price_info = "Current prices: " + ", ".join(parts)
+
+        close_time = item.get("endDate") or item.get("closeTime")
+        snapshot_time = datetime.now(timezone.utc)
+        if close_time:
+            try:
+                snapshot_time = datetime.fromisoformat(close_time.replace("Z", "+00:00"))
+            except (ValueError, TypeError):
+                pass
+
+        return ForecastQuestion(
+            id=f"polymarket-{market_id}",
+            title=question_text[:500],
+            description=(
+                f"{description[:1000]}\n\n{price_info}" if description or price_info
+                else f"Polymarket binary market {market_id}. {price_info}"
+            ),
+            metadata=MetadataBase(
+                snapshot_time=snapshot_time,
+                source_version="polymarket",
+                tags=["polymarket", "binary", "prediction-market"],
+                raw_data={
+                    "polymarket_id": market_id,
+                    "volume_24hr": item.get("volume24hr"),
+                    "liquidity": item.get("liquidity"),
+                    "outcome_prices": outcome_prices,
+                },
+            ),
+        )
+
+
+__all__ = ["PolymarketSource"]

{xrtm_data-0.2.7 → xrtm_data-0.3.1}/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.6"
+__version__ = "0.3.1"
 __author__ = "XRTM Team"
 __contact__ = "moy@xrtm.org"
 __license__ = "Apache-2.0"