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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrtm-data
-Version: 0.3.2
+Version: 0.4.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.4.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.4.0}/README.md

@@ -1,4 +1,4 @@
-# xrtm-data v0.3.0
+# xrtm-data v0.4.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.4.0}/pyproject.toml

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

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

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

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

@@ -25,11 +25,13 @@ from xrtm.data.core.schemas.forecast import (
     CausalNode,
     ConfidenceInterval,
     ForecastOutput,
+    ForecastProvenance,
     ForecastQuestion,
     ForecastRequest,
     ForecastResult,
     MetadataBase,
     ReasoningTrace,
+    TokenUsage,
 )
 from xrtm.data.core.schemas.prior import BetaPrior, PriorState
 from xrtm.data.core.schemas.trade import TradeEvent, TradeWindow
@@ -46,6 +48,8 @@ __all__ = [
     "CausalGraph",
     "ReasoningTrace",
     "ConfidenceInterval",
+    "TokenUsage",
+    "ForecastProvenance",
     # Prior schemas
     "BetaPrior",
     "PriorState",

{xrtm_data-0.3.2 → xrtm_data-0.4.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.3.2 → xrtm_data-0.4.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.4.0"
 __author__ = "XRTM Team"
 __contact__ = "moy@xrtm.org"
 __license__ = "Apache-2.0"

{xrtm_data-0.3.2 → xrtm_data-0.4.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.4.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.4.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.4.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"