xrtm-data 0.3.2__tar.gz → 0.5.0__tar.gz

{xrtm_data-0.3.2/src/xrtm_data.egg-info → xrtm_data-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrtm-data
-Version: 0.3.2
+Version: 0.5.0
 Summary: The Snapshot Vault for XRTM.
 Author-email: XRTM Team <moy@xrtm.org>
 License-Expression: Apache-2.0
@@ -17,7 +17,7 @@ Requires-Dist: ruff>=0.1.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Dynamic: license-file
 
-# xrtm-data v0.3.0
+# xrtm-data v0.5.0
 
 [![PyPI](https://img.shields.io/pypi/v/xrtm-data?style=flat-square)](https://pypi.org/project/xrtm-data/)
 

{xrtm_data-0.3.2 → xrtm_data-0.5.0}/README.md

@@ -1,4 +1,4 @@
-# xrtm-data v0.3.0
+# xrtm-data v0.5.0
 
 [![PyPI](https://img.shields.io/pypi/v/xrtm-data?style=flat-square)](https://pypi.org/project/xrtm-data/)
 

{xrtm_data-0.3.2 → xrtm_data-0.5.0}/pyproject.toml

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

{xrtm_data-0.3.2 → xrtm_data-0.5.0}/src/xrtm/data/__init__.py

@@ -39,11 +39,14 @@ from xrtm.data.core.schemas import (
     CausalNode,
     ConfidenceInterval,
     ForecastOutput,
+    ForecastProvenance,
     ForecastQuestion,
     ForecastRequest,
     ForecastResult,
+    MarketSnapshot,
     MetadataBase,
     ReasoningTrace,
+    TokenUsage,
 )
 
 __all__ = [
@@ -63,4 +66,7 @@ __all__ = [
     "CausalGraph",
     "ReasoningTrace",
     "ConfidenceInterval",
+    "TokenUsage",
+    "ForecastProvenance",
+    "MarketSnapshot",
 ]

{xrtm_data-0.3.2 → xrtm_data-0.5.0}/src/xrtm/data/core/schemas/__init__.py

@@ -25,12 +25,15 @@ from xrtm.data.core.schemas.forecast import (
     CausalNode,
     ConfidenceInterval,
     ForecastOutput,
+    ForecastProvenance,
     ForecastQuestion,
     ForecastRequest,
     ForecastResult,
     MetadataBase,
     ReasoningTrace,
+    TokenUsage,
 )
+from xrtm.data.core.schemas.market import MarketSnapshot
 from xrtm.data.core.schemas.prior import BetaPrior, PriorState
 from xrtm.data.core.schemas.trade import TradeEvent, TradeWindow
 
@@ -46,6 +49,10 @@ __all__ = [
     "CausalGraph",
     "ReasoningTrace",
     "ConfidenceInterval",
+    "TokenUsage",
+    "ForecastProvenance",
+    # Market schemas
+    "MarketSnapshot",
     # Prior schemas
     "BetaPrior",
     "PriorState",

{xrtm_data-0.3.2 → xrtm_data-0.5.0}/src/xrtm/data/core/schemas/forecast.py

@@ -178,6 +178,57 @@ class ConfidenceInterval(BaseModel):
     level: float = Field(0.9, ge=0, le=1, description="Confidence level")
 
 
+class TokenUsage(BaseModel):
+    r"""
+    Token accounting for a single forecast or inference run.
+
+    Attributes:
+        prompt_tokens: Total input tokens billed for this run.
+        completion_tokens: Total output tokens billed for this run.
+        cached_prompt_tokens: Input tokens served from a provider prefix cache.
+        reasoning_tokens: Output tokens spent on chain-of-thought reasoning.
+        total_tokens: Total billed tokens (prompt + completion).
+    """
+
+    prompt_tokens: int = Field(default=0, ge=0, description="Total input tokens billed for this run")
+    completion_tokens: int = Field(default=0, ge=0, description="Total output tokens billed for this run")
+    cached_prompt_tokens: int = Field(default=0, ge=0, description="Input tokens served from a provider prefix cache")
+    reasoning_tokens: int = Field(default=0, ge=0, description="Output tokens spent on chain-of-thought reasoning")
+    total_tokens: int = Field(default=0, ge=0, description="Total billed tokens (prompt + completion)")
+
+    @model_validator(mode="after")
+    def _fill_total_tokens(self) -> "TokenUsage":
+        r"""Derive ``total_tokens`` when a producer did not provide it."""
+        if self.total_tokens == 0:
+            self.total_tokens = self.prompt_tokens + self.completion_tokens
+        return self
+
+
+class ForecastProvenance(BaseModel):
+    r"""
+    Operational provenance for a forecast: which engine, model, and prompt produced it.
+
+    Attributes:
+        provider: Inference provider family (e.g. ``"deepseek"``, ``"typesafe"``).
+        model_id: Model identifier as requested (e.g. ``"deepseek-flash"``).
+        model_version: Model version or checkpoint reported by the provider.
+        prompt_id: Identifier or version of the prompt template used.
+        temperature: Sampling temperature used for the run.
+        thinking: Whether provider reasoning/thinking mode was enabled.
+        cache_hit: True when the result was served from a cache.
+        run_id: Identifier shared by all calls belonging to one forecast run.
+    """
+
+    provider: Optional[str] = Field(default=None, description="Inference provider family (e.g. 'deepseek')")
+    model_id: Optional[str] = Field(default=None, description="Model identifier as requested")
+    model_version: Optional[str] = Field(default=None, description="Model version or checkpoint reported by the provider")
+    prompt_id: Optional[str] = Field(default=None, description="Identifier or version of the prompt template used")
+    temperature: Optional[float] = Field(default=None, description="Sampling temperature used for the run")
+    thinking: Optional[bool] = Field(default=None, description="Whether provider reasoning/thinking mode was enabled")
+    cache_hit: bool = Field(default=False, description="True when the result was served from a cache")
+    run_id: Optional[str] = Field(default=None, description="Identifier shared by all calls belonging to one forecast run")
+
+
 class MappingCompatibleModel(BaseModel):
     r"""Base model with lightweight dict-style compatibility helpers."""
 
@@ -293,6 +344,16 @@ class ForecastOutput(BaseModel):
         description="Ordered workflow stages executed for this forecast result",
     )
     calibration_metrics: Dict[str, Any] = Field(default_factory=dict, description="Performance metrics")
+    parse_status: str = Field(
+        default="unknown",
+        description="Parse outcome for the model output: 'ok', 'empty_content', 'invalid_json', "
+        "'schema_error', 'provider_error', or 'unknown'.",
+    )
+    usage: TokenUsage = Field(default_factory=TokenUsage, description="Token accounting for this forecast")
+    provenance: Optional[ForecastProvenance] = Field(
+        default=None,
+        description="Model and prompt provenance for this forecast",
+    )
     metadata: MetadataBase = Field(default_factory=MetadataBase)  # type: ignore[arg-type]
 
     @model_validator(mode="before")
@@ -458,6 +519,8 @@ __all__ = [
     "ReasoningTrace",
     "ForecastOutput",
     "ForecastResult",
+    "TokenUsage",
+    "ForecastProvenance",
 ]
 
 ForecastResult = ForecastOutput

xrtm_data-0.5.0/src/xrtm/data/core/schemas/market.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"""Point-in-time market snapshot schema.
+
+A shared contract for prediction-market state (price, book, liquidity) that
+applications, evaluators, and backtests can all consume without re-inventing
+venue-specific shapes.
+
+Zero Leakage: every snapshot carries the ``snapshot_time`` at which the world
+state was frozen; no data after that instant should influence a forecast.
+"""
+
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+__all__ = ["MarketSnapshot"]
+
+
+class MarketSnapshot(BaseModel):
+    r"""Point-in-time state of a prediction market.
+
+    Attributes:
+        market_id: Venue-specific market identifier.
+        question_id: Optional link to the ``ForecastQuestion`` this market resolves.
+        probability: Implied/mid probability of the primary outcome (0-1).
+        best_bid: Best bid price (0-1).
+        best_ask: Best ask price (0-1).
+        spread: Bid/ask spread (0-1), derived from bid/ask when omitted.
+        volume_24h: Trailing 24h volume, in the venue's currency.
+        liquidity: Available liquidity, in the venue's currency.
+        snapshot_time: The "Time T" at which the market state was frozen.
+        source: Venue/source identifier (e.g. ``"polymarket"``).
+        raw_data: Original venue payload for debugging/audit.
+    """
+
+    market_id: str = Field(..., description="Venue-specific market identifier")
+    question_id: Optional[str] = Field(default=None, description="Linked ForecastQuestion id")
+    probability: Optional[float] = Field(default=None, ge=0, le=1, description="Implied/mid probability")
+    best_bid: Optional[float] = Field(default=None, ge=0, le=1, description="Best bid price")
+    best_ask: Optional[float] = Field(default=None, ge=0, le=1, description="Best ask price")
+    spread: Optional[float] = Field(default=None, ge=0, le=1, description="Bid/ask spread")
+    volume_24h: Optional[float] = Field(default=None, ge=0, description="Trailing 24h volume")
+    liquidity: Optional[float] = Field(default=None, ge=0, description="Available liquidity")
+    snapshot_time: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="Zero Leakage: the instant this market state was frozen",
+    )
+    source: Optional[str] = Field(default=None, description="Venue/source identifier")
+    raw_data: Optional[Dict[str, Any]] = Field(default=None, description="Original venue payload")
+
+    @field_validator("snapshot_time", mode="after")
+    @classmethod
+    def _normalize_snapshot_time(cls, value: datetime) -> datetime:
+        r"""Store the snapshot boundary as a timezone-aware UTC datetime."""
+        if value.tzinfo is None:
+            return value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc)
+
+    @model_validator(mode="after")
+    def _validate_book(self) -> "MarketSnapshot":
+        r"""Derive the spread and reject crossed books."""
+        if self.best_bid is not None and self.best_ask is not None:
+            if self.best_bid > self.best_ask:
+                raise ValueError("best_bid must not exceed best_ask")
+            if self.spread is None:
+                self.spread = round(self.best_ask - self.best_bid, 10)
+        return self

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

{xrtm_data-0.3.2 → xrtm_data-0.5.0/src/xrtm_data.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrtm-data
-Version: 0.3.2
+Version: 0.5.0
 Summary: The Snapshot Vault for XRTM.
 Author-email: XRTM Team <moy@xrtm.org>
 License-Expression: Apache-2.0
@@ -17,7 +17,7 @@ Requires-Dist: ruff>=0.1.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Dynamic: license-file
 
-# xrtm-data v0.3.0
+# xrtm-data v0.5.0
 
 [![PyPI](https://img.shields.io/pypi/v/xrtm-data?style=flat-square)](https://pypi.org/project/xrtm-data/)
 

{xrtm_data-0.3.2 → xrtm_data-0.5.0}/src/xrtm_data.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ src/xrtm/data/core/__init__.py
 src/xrtm/data/core/interfaces.py
 src/xrtm/data/core/schemas/__init__.py
 src/xrtm/data/core/schemas/forecast.py
+src/xrtm/data/core/schemas/market.py
 src/xrtm/data/core/schemas/prior.py
 src/xrtm/data/core/schemas/trade.py
 src/xrtm/data/corpora/__init__.py
@@ -23,6 +24,7 @@ src/xrtm_data.egg-info/dependency_links.txt
 src/xrtm_data.egg-info/requires.txt
 src/xrtm_data.egg-info/top_level.txt
 tests/test_corpus_registry.py
+tests/test_market_snapshot.py
 tests/test_prior_schemas.py
 tests/test_real_binary_corpus.py
 tests/test_schemas.py

xrtm_data-0.5.0/tests/test_market_snapshot.py

@@ -0,0 +1,63 @@
+# 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"""Tests for the MarketSnapshot schema."""
+
+from datetime import datetime, timezone
+
+import pytest
+
+from xrtm.data import MarketSnapshot
+
+
+def test_snapshot_normalizes_naive_time_to_utc():
+    snapshot = MarketSnapshot(market_id="m1", snapshot_time=datetime(2026, 9, 26, 12, 0))
+    assert snapshot.snapshot_time.tzinfo == timezone.utc
+
+
+def test_spread_is_derived_from_book():
+    snapshot = MarketSnapshot(market_id="m2", best_bid=0.40, best_ask=0.44)
+    assert snapshot.spread == pytest.approx(0.04)
+
+
+def test_explicit_spread_is_preserved():
+    snapshot = MarketSnapshot(market_id="m3", best_bid=0.40, best_ask=0.44, spread=0.05)
+    assert snapshot.spread == pytest.approx(0.05)
+
+
+def test_crossed_book_is_rejected():
+    with pytest.raises(ValueError, match="best_bid"):
+        MarketSnapshot(market_id="m4", best_bid=0.60, best_ask=0.50)
+
+
+def test_snapshot_serializes_and_round_trips():
+    snapshot = MarketSnapshot(
+        market_id="m5",
+        question_id="q5",
+        probability=0.42,
+        best_bid=0.41,
+        best_ask=0.43,
+        volume_24h=150_000,
+        liquidity=20_000,
+        source="polymarket",
+        raw_data={"token_id": "123"},
+    )
+    payload = snapshot.model_dump(mode="json")
+    assert payload["spread"] == pytest.approx(0.02)
+
+    reloaded = MarketSnapshot.model_validate(payload)
+    assert reloaded.market_id == "m5"
+    assert reloaded.question_id == "q5"
+    assert reloaded.raw_data == {"token_id": "123"}

{xrtm_data-0.3.2 → xrtm_data-0.5.0}/tests/test_schemas.py

@@ -16,7 +16,16 @@ from datetime import datetime, timedelta, timezone
 
 import pytest
 
-from xrtm.data import CausalEdge, CausalNode, ForecastOutput, ForecastQuestion, ForecastResult, MetadataBase
+from xrtm.data import (
+    CausalEdge,
+    CausalNode,
+    ForecastOutput,
+    ForecastProvenance,
+    ForecastQuestion,
+    ForecastResult,
+    MetadataBase,
+    TokenUsage,
+)
 from xrtm.data.core.schemas import TradeEvent, TradeWindow
 
 
@@ -202,3 +211,56 @@ def test_forecast_question_context_serializes():
 
     reloaded = ForecastQuestion.model_validate(payload)
     assert reloaded.context == {"key": "value", "nested": {"a": 1}}
+
+
+def test_token_usage_derives_total():
+    """total_tokens is derived when a producer omits it."""
+    usage = TokenUsage(prompt_tokens=1200, completion_tokens=300)
+    assert usage.total_tokens == 1500
+
+
+def test_token_usage_preserves_explicit_total():
+    """An explicit total_tokens from the provider is not overwritten."""
+    usage = TokenUsage(prompt_tokens=10, completion_tokens=5, total_tokens=99)
+    assert usage.total_tokens == 99
+
+
+def test_forecast_output_telemetry_defaults():
+    """Telemetry fields are optional and safe for legacy producers."""
+    output = ForecastOutput(question_id="q_telemetry", probability=0.5, reasoning="legacy")
+    assert output.parse_status == "unknown"
+    assert output.usage.total_tokens == 0
+    assert output.provenance is None
+
+
+def test_forecast_output_telemetry_round_trip():
+    """Telemetry survives JSON serialization and re-validation."""
+    output = ForecastOutput(
+        forecast_request_id="q_telemetry_2",
+        probability=0.72,
+        reasoning="telemetry round trip",
+        parse_status="ok",
+        usage=TokenUsage(
+            prompt_tokens=900,
+            completion_tokens=250,
+            cached_prompt_tokens=800,
+            reasoning_tokens=120,
+        ),
+        provenance=ForecastProvenance(
+            provider="deepseek",
+            model_id="deepseek-flash",
+            prompt_id="analyst-v2",
+            temperature=0.2,
+            thinking=False,
+            cache_hit=False,
+        ),
+    )
+    payload = output.model_dump(mode="json")
+    assert payload["parse_status"] == "ok"
+    assert payload["usage"]["total_tokens"] == 1150
+    assert payload["provenance"]["model_id"] == "deepseek-flash"
+
+    reloaded = ForecastOutput.model_validate(payload)
+    assert reloaded.usage.cached_prompt_tokens == 800
+    assert reloaded.provenance is not None
+    assert reloaded.provenance.provider == "deepseek"