cmpnd 0.23.1__tar.gz → 0.23.2__tar.gz

{cmpnd-0.23.1 → cmpnd-0.23.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.23.1
+Version: 0.23.2
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>

{cmpnd-0.23.1 → cmpnd-0.23.2}/cmpnd/callback.py

@@ -181,6 +181,27 @@ def _normalize_usage(usage: Any) -> dict[str, int | None]:
     columns behind them are ``NOT NULL``). ``reasoning_tokens`` and
     ``cache_write_tokens`` come back as ``None`` when the provider said nothing.
     """
+    evidence = _normalize_usage_evidence(usage)
+    prompt = evidence["prompt_tokens"]
+    completion = evidence["completion_tokens"]
+    total = evidence["total_tokens"]
+    if total is None and (prompt is not None or completion is not None):
+        # The legacy span projection has always derived a total. The evidence
+        # object keeps an omitted total as null and preserves the raw block.
+        total = (prompt or 0) + (completion or 0)
+
+    return {
+        "prompt_tokens": prompt or 0,
+        "completion_tokens": completion or 0,
+        "total_tokens": total or 0,
+        "cached_prompt_tokens": evidence["cache_read_tokens"] or 0,
+        "reasoning_tokens": evidence["reasoning_tokens"],
+        "cache_write_tokens": evidence["cache_write_tokens"],
+    }
+
+
+def _normalize_usage_evidence(usage: Any) -> dict[str, int | None]:
+    """Normalize queryable counters without flattening absence into zero."""
     prompt = _reported_count(
         _usage_field(usage, "prompt_tokens"),
         _usage_field(usage, "input_tokens"),
@@ -190,11 +211,6 @@ def _normalize_usage(usage: Any) -> dict[str, int | None]:
         _usage_field(usage, "output_tokens"),
     )
     total = _reported_count(_usage_field(usage, "total_tokens"))
-    if total is None and (prompt is not None or completion is not None):
-        # Derived only where the provider omitted it — a reported total is
-        # evidence and stays as sent, even when the split disagrees with it.
-        total = (prompt or 0) + (completion or 0)
-
     cached = _reported_count(
         _usage_detail(usage, "prompt_tokens_details", "cached_tokens"),
         _usage_detail(usage, "input_tokens_details", "cached_tokens"),
@@ -209,20 +225,159 @@ def _normalize_usage(usage: Any) -> dict[str, int | None]:
     cache_write = _reported_count(
         _usage_field(usage, "cache_write_tokens"),
         _usage_field(usage, "cache_creation_input_tokens"),
+        _usage_detail(usage, "prompt_tokens_details", "cache_creation_tokens"),
+    )
+    cache_write_5m = _reported_count(
+        _usage_detail(usage, "cache_creation", "ephemeral_5m_input_tokens"),
+        _usage_detail(usage, "cache_creation_token_details", "ephemeral_5m_input_tokens"),
+    )
+    cache_write_1h = _reported_count(
+        _usage_detail(usage, "cache_creation", "ephemeral_1h_input_tokens"),
+        _usage_detail(usage, "cache_creation_token_details", "ephemeral_1h_input_tokens"),
+    )
+    audio_prompt = _reported_count(
+        _usage_detail(usage, "prompt_tokens_details", "audio_tokens"),
+        _usage_detail(usage, "input_tokens_details", "audio_tokens"),
+        _usage_field(usage, "input_audio_tokens"),
+        _usage_field(usage, "audio_prompt_tokens"),
+    )
+    audio_completion = _reported_count(
+        _usage_detail(usage, "completion_tokens_details", "audio_tokens"),
+        _usage_detail(usage, "output_tokens_details", "audio_tokens"),
+        _usage_field(usage, "output_audio_tokens"),
+        _usage_field(usage, "audio_completion_tokens"),
     )
 
     return {
-        "prompt_tokens": prompt or 0,
-        "completion_tokens": completion or 0,
-        "total_tokens": total or 0,
-        # A subset of prompt_tokens: every dialect above counts its cache reads
-        # inside the prompt total, so the subset invariant holds by construction.
-        "cached_prompt_tokens": cached or 0,
+        "prompt_tokens": prompt,
+        "completion_tokens": completion,
+        "total_tokens": total,
+        "cache_read_tokens": cached,
         "reasoning_tokens": reasoning,
         "cache_write_tokens": cache_write,
+        "cache_write_5m_tokens": cache_write_5m,
+        "cache_write_1h_tokens": cache_write_1h,
+        "audio_prompt_tokens": audio_prompt,
+        "audio_completion_tokens": audio_completion,
     }
 
 
+_MISSING = object()
+
+
+def _value_field(value: Any, key: str) -> Any:
+    """Read a field from a mapping, DSPy model, or response object."""
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return value.get(key)
+    getter = getattr(value, "get", None)
+    if callable(getter):
+        try:
+            found = getter(key, _MISSING)
+        except TypeError:
+            try:
+                found = getter(key)
+            except (KeyError, TypeError):
+                found = _MISSING
+        if found is not _MISSING:
+            return found
+    return getattr(value, key, None)
+
+
+def _text_field(value: Any, key: str) -> str | None:
+    found = _value_field(value, key)
+    if isinstance(found, str) and found:
+        return found
+    return None
+
+
+def _bool_field(value: Any, key: str) -> bool | None:
+    found = _value_field(value, key)
+    return found if isinstance(found, bool) else None
+
+
+def _present_field(value: Any, key: str) -> tuple[bool, Any]:
+    """Read a field while preserving whether the object declared it."""
+    if isinstance(value, dict):
+        return key in value, value.get(key)
+    model_fields = getattr(type(value), "model_fields", None)
+    if isinstance(model_fields, dict) and key in model_fields:
+        return True, getattr(value, key, None)
+    values = getattr(value, "__dict__", None)
+    if isinstance(values, dict) and key in values:
+        return True, values.get(key)
+    return False, None
+
+
+def _history_usage(entry: Any) -> tuple[bool, Any]:
+    """Return whether history carried usage and the value it carried."""
+    response = _value_field(entry, "response")
+    response_declares_usage, response_usage = _present_field(response, "usage")
+    if response_declares_usage:
+        return response_usage is not None, response_usage
+    if isinstance(entry, dict):
+        usage = entry.get("usage")
+        return "usage" in entry and usage is not None, usage
+    usage = _value_field(entry, "usage")
+    return usage is not None, usage
+
+
+def _usage_dialect(instance: Any, usage: Any) -> str | None:
+    """Name the response surface only when its shape establishes one."""
+    model_type = _text_field(instance, "model_type")
+    if model_type == "responses":
+        return "responses"
+    if model_type in {"chat", "text"}:
+        return "chat_completions"
+    if _usage_field(usage, "inputTokens") is not None or _usage_field(usage, "outputTokens") is not None:
+        return "converse"
+    if _usage_field(usage, "prompt_tokens") is not None or _usage_field(usage, "completion_tokens") is not None:
+        return "chat_completions"
+    return None
+
+
+def _cache_ttl_requested(*values: Any) -> str | None:
+    """Return one unambiguous requested cache TTL from request data."""
+    found: set[str] = set()
+
+    def visit(value: Any, in_cache_control: bool = False) -> None:
+        if isinstance(value, dict):
+            for key, child in value.items():
+                if key in {"cache_ttl", "cache_ttl_requested"} and child is not None:
+                    found.add(str(child))
+                elif in_cache_control and key == "ttl" and child is not None:
+                    found.add(str(child))
+                else:
+                    visit(child, in_cache_control or key == "cache_control")
+        elif isinstance(value, (list, tuple)):
+            for child in value:
+                visit(child, in_cache_control)
+
+    for value in values:
+        visit(value)
+    return next(iter(found)) if len(found) == 1 else None
+
+
+def _request_selector(entry: Any, instance: Any, key: str) -> str | None:
+    history_kwargs = _value_field(entry, "kwargs")
+    return _text_field(history_kwargs, key) or _text_field(getattr(instance, "kwargs", None), key)
+
+
+def _response_text(response: Any, key: str) -> str | None:
+    """Read provider response metadata from DSPy's supported containers."""
+    for container in (
+        response,
+        _value_field(response, "provider_data"),
+        _value_field(response, "metadata"),
+        _value_field(response, "_hidden_params"),
+    ):
+        found = _text_field(container, key)
+        if found:
+            return found
+    return None
+
+
 def _finish_reason(response: Any) -> str | None:
     """Read why the model stopped, from whichever response shape answered.
 
@@ -991,6 +1146,13 @@ class _LMMixin(_CallbackBase):
         lm_kwargs = {
             k: v for k, v in getattr(instance, "kwargs", {}).items() if k not in {"api_key", "api_base", "api_secret"}
         }
+        span.lm_usage = models.LMUsageObservationV1(
+            sdk_call_id=call_id,
+            model_requested=span.model_name,
+            service_tier_requested=_text_field(lm_kwargs, "service_tier"),
+            cache_ttl_requested=_cache_ttl_requested(lm_kwargs, inputs),
+            binding=_text_field(instance, "binding"),
+        )
         span.attributes.update(
             {
                 "lm.model_type": getattr(instance, "model_type", "unknown"),
@@ -1027,38 +1189,95 @@ class _LMMixin(_CallbackBase):
 
         span.end_time = datetime.now(timezone.utc)
 
+        latest_entry: Any = None
+        response: Any = None
+        usage: Any = None
+        usage_reported = False
+        if instance and hasattr(instance, "history") and instance.history:
+            try:
+                latest_entry = instance.history[-1]
+                usage_reported, usage = _history_usage(latest_entry)
+                response = _value_field(latest_entry, "response")
+                logger.debug(
+                    f"LM history usage for {span.model_name}: "
+                    f"history_len={len(instance.history)}, "
+                    f"usage_type={type(usage).__name__}, "
+                    f"usage={usage}"
+                )
+            except (IndexError, AttributeError, TypeError) as e:
+                logger.debug(f"LM history access failed: {e}")
+        else:
+            has_hist = hasattr(instance, "history") if instance else False
+            hist_len = len(instance.history) if has_hist else "N/A"
+            logger.debug(
+                f"LM history unavailable: instance={instance is not None}, "
+                f"has_history={has_hist}, history_len={hist_len}"
+            )
+
+        if not usage_reported and isinstance(outputs, dict) and "usage" in outputs:
+            usage = outputs.get("usage")
+            usage_reported = usage is not None
+            if response is None:
+                response = outputs
+
+        observation = span.lm_usage
+        if observation is not None:
+            observation.observed_at = span.end_time
+            observation.outcome = "success" if exception is None else None
+            cache_hit = _bool_field(response, "cache_hit")
+            if cache_hit is None:
+                cache_hit = _bool_field(_value_field(response, "_hidden_params"), "cache_hit")
+            observation.dspy_client_cache_hit = cache_hit
+            observation.usage_reported = usage_reported and cache_hit is not True
+            serialized_usage = models._safe_serialize(usage)
+            observation.usage_raw = (
+                serialized_usage if observation.usage_reported and isinstance(serialized_usage, dict) else None
+            )
+            observation.usage_dialect = _usage_dialect(instance, usage)
+            if observation.usage_dialect in {"chat_completions", "responses"}:
+                observation.prompt_inclusion = "includes_cache_reads"
+            elif observation.usage_dialect == "converse":
+                observation.prompt_inclusion = "excludes_cache_reads"
+
+            if usage_reported and usage is not None:
+                evidence = _normalize_usage_evidence(usage)
+                for name, value in evidence.items():
+                    setattr(observation, name, value)
+                if (
+                    observation.prompt_tokens is not None
+                    and observation.cache_read_tokens is not None
+                    and observation.prompt_inclusion == "includes_cache_reads"
+                    and observation.cache_read_tokens <= observation.prompt_tokens
+                ):
+                    observation.fresh_input_tokens = observation.prompt_tokens - observation.cache_read_tokens
+                elif observation.prompt_tokens is not None and observation.prompt_inclusion == "excludes_cache_reads":
+                    observation.fresh_input_tokens = observation.prompt_tokens
+
+            requested_model = _text_field(latest_entry, "model")
+            if requested_model:
+                observation.model_requested = requested_model
+            reported_model = _text_field(latest_entry, "response_model") or _text_field(response, "model")
+            if reported_model:
+                observation.model_reported = reported_model
+            requested_tier = _request_selector(latest_entry, instance, "service_tier")
+            if requested_tier:
+                observation.service_tier_requested = requested_tier
+            requested_ttl = _cache_ttl_requested(_value_field(latest_entry, "kwargs"))
+            if requested_ttl:
+                observation.cache_ttl_requested = requested_ttl
+            effective_tier = _response_text(response, "service_tier")
+            if effective_tier:
+                observation.service_tier_effective = effective_tier
+            observation.provider_response_id = _response_text(response, "response_id") or _response_text(response, "id")
+            observation.egress_call_id = _response_text(response, "egress_call_id") or _text_field(
+                latest_entry, "egress_call_id"
+            )
+
         if exception:
             span.set_error(exception)
         else:
             span.status = models.TraceStatus.OK
 
-            # Extract token usage - try LM's history first (where DSPy stores it),
-            # then fall back to outputs dict (for backwards compatibility / testing)
-            usage = {}
-            if instance and hasattr(instance, "history") and instance.history:
-                try:
-                    latest_entry = instance.history[-1]
-                    usage = latest_entry.get("usage", {})
-                    logger.debug(
-                        f"LM history usage for {span.model_name}: "
-                        f"history_len={len(instance.history)}, "
-                        f"usage_type={type(usage).__name__}, "
-                        f"usage={usage}"
-                    )
-                except (IndexError, AttributeError, TypeError) as e:
-                    logger.debug(f"LM history access failed: {e}")
-            else:
-                has_hist = hasattr(instance, "history") if instance else False
-                hist_len = len(instance.history) if has_hist else "N/A"
-                logger.debug(
-                    f"LM history unavailable: instance={instance is not None}, "
-                    f"has_history={has_hist}, history_len={hist_len}"
-                )
-
-            # Fallback: check outputs dict for usage (legacy / test compatibility)
-            if not usage and isinstance(outputs, dict):
-                usage = outputs.get("usage", {})
-
             if usage:
                 counts = _normalize_usage(usage)
                 span.prompt_tokens = counts["prompt_tokens"] or 0
@@ -1072,14 +1291,9 @@ class _LMMixin(_CallbackBase):
                 logger.debug(f"NO usage data for {span.model_name} (call_id={call_id})")
 
             # Extract finish_reason from LM history response
-            if instance and hasattr(instance, "history") and instance.history:
-                try:
-                    latest_entry = instance.history[-1]
-                    finish_reason = _finish_reason(latest_entry.get("response"))
-                    if finish_reason:
-                        span.set_attribute("lm.finish_reason", finish_reason)
-                except (IndexError, AttributeError, TypeError):
-                    pass
+            finish_reason = _finish_reason(response)
+            if finish_reason:
+                span.set_attribute("lm.finish_reason", finish_reason)
 
             # Capture response outputs (truncated)
             if outputs and self._capture_outputs:

{cmpnd-0.23.1 → cmpnd-0.23.2}/cmpnd/models.py

@@ -2,13 +2,14 @@
 
 from __future__ import annotations
 
+import hashlib
 import json
 import re
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from enum import Enum
 from typing import Any
-from uuid import UUID
+from uuid import UUID, uuid4
 
 from . import identity, imaging
 
@@ -412,6 +413,91 @@ class TraceStatus(str, Enum):
     ERROR = "error"
 
 
+@dataclass
+class LMUsageObservationV1:
+    """Provider-usage evidence attached to one SDK-observed LM call.
+
+    Optional counters preserve the distinction between an absent measurement
+    and a reported zero. ``provider_cost`` accepts only a provider-origin amount.
+    DSPy and LiteLLM calculated costs do not belong here.
+    """
+
+    source_observation_id: str = field(default_factory=lambda: str(uuid4()))
+    observed_at: datetime | None = None
+    usage_reported: bool = False
+    usage_raw: dict[str, Any] | None = None
+    usage_dialect: str | None = None
+    normalization_version: int = 1
+    prompt_inclusion: str | None = None
+    model_requested: str | None = None
+    model_reported: str | None = None
+    service_tier_requested: str | None = None
+    service_tier_effective: str | None = None
+    cache_ttl_requested: str | None = None
+    provider_cost: str | None = None
+    provider_cost_currency: str | None = None
+    dspy_client_cache_hit: bool | None = None
+    binding: str | None = None
+    sdk_call_id: str | None = None
+    provider_response_id: str | None = None
+    egress_call_id: str | None = None
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    total_tokens: int | None = None
+    fresh_input_tokens: int | None = None
+    cache_read_tokens: int | None = None
+    cache_write_tokens: int | None = None
+    cache_write_5m_tokens: int | None = None
+    cache_write_1h_tokens: int | None = None
+    reasoning_tokens: int | None = None
+    audio_prompt_tokens: int | None = None
+    audio_completion_tokens: int | None = None
+    outcome: str | None = None
+
+    def to_api_dict(self) -> dict[str, Any]:
+        """Return the versioned wire object with a deterministic digest."""
+        payload = {
+            "schema_version": 1,
+            "source_observation_id": self.source_observation_id,
+            "observed_at": self.observed_at.isoformat() if self.observed_at else None,
+            "usage_reported": self.usage_reported,
+            "usage_raw": _safe_serialize(self.usage_raw),
+            "usage_dialect": self.usage_dialect,
+            "normalization_version": self.normalization_version,
+            "prompt_inclusion": self.prompt_inclusion,
+            "model_requested": self.model_requested,
+            "model_reported": self.model_reported,
+            "service_tier_requested": self.service_tier_requested,
+            "service_tier_effective": self.service_tier_effective,
+            "cache_ttl_requested": self.cache_ttl_requested,
+            "provider_cost": self.provider_cost,
+            "provider_cost_currency": self.provider_cost_currency,
+            "dspy_client_cache_hit": self.dspy_client_cache_hit,
+            "binding": self.binding,
+            "sdk_call_id": self.sdk_call_id,
+            "provider_response_id": self.provider_response_id,
+            "egress_call_id": self.egress_call_id,
+            "prompt_tokens": self.prompt_tokens,
+            "completion_tokens": self.completion_tokens,
+            "total_tokens": self.total_tokens,
+            "fresh_input_tokens": self.fresh_input_tokens,
+            "cache_read_tokens": self.cache_read_tokens,
+            "cache_write_tokens": self.cache_write_tokens,
+            "cache_write_5m_tokens": self.cache_write_5m_tokens,
+            "cache_write_1h_tokens": self.cache_write_1h_tokens,
+            "reasoning_tokens": self.reasoning_tokens,
+            "audio_prompt_tokens": self.audio_prompt_tokens,
+            "audio_completion_tokens": self.audio_completion_tokens,
+            "outcome": self.outcome,
+        }
+        safe_payload = _safe_serialize(payload)
+        if not isinstance(safe_payload, dict):
+            raise TypeError("LM usage observation did not serialize to a JSON object")
+        canonical = json.dumps(safe_payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+        safe_payload["source_payload_digest"] = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+        return safe_payload
+
+
 @dataclass
 class SpanBuilder:
     """Mutable span builder for collecting data during execution."""
@@ -469,6 +555,7 @@ class SpanBuilder:
     # Normalized by callback._normalize_usage.
     reasoning_tokens: int | None = None
     cache_write_tokens: int | None = None
+    lm_usage: LMUsageObservationV1 | None = None
     # Left unset by the SDK. A dollar figure is a derivation from these counts
     # and a dated rate catalog, and only serve holds the catalog; the SDK's job
     # is to report what the provider said. serve still reads the wire field, so
@@ -582,6 +669,7 @@ class SpanBuilder:
             "cached_prompt_tokens": self.cached_prompt_tokens,
             "reasoning_tokens": self.reasoning_tokens,
             "cache_write_tokens": self.cache_write_tokens,
+            "lm_usage": self.lm_usage.to_api_dict() if self.lm_usage else None,
             "cost": self.cost,
             "demos": _safe_serialize(self.demos),
             "demo_count": self.demo_count if self.demo_count else len(self.demos),

{cmpnd-0.23.1 → cmpnd-0.23.2}/docs/sdk-instrumentation.md

@@ -37,7 +37,7 @@ For an explicit, scoped alternative that traces only the programs you run throug
 The hook methods, in the order you'd expect them to fire for a typical `dspy.ChainOfThought` call:
 
 - **Module lifecycle** — `on_module_start` (`callback.py:195`) creates a new `SpanBuilder`, and, if this is the root module call, also creates a new `TraceBuilder` via `_create_trace` (`callback.py:579`). `on_module_end` (`callback.py:307`) closes the span, attaches outputs, and, if it was the root, exports the trace. A call is root when no span is on the stack — or when the only span above it is the `Evaluate` span, which contains many independent program runs and parents none of them, so each run under a `dspy.Evaluate` roots its own trace. Such a root span is built with `create_child_span(..., root=True)` so it does not adopt the `Evaluate` span as its parent.
-- **LM calls** — `on_lm_start` (`callback.py:448`) / `on_lm_end` (`callback.py:498`) wrap the actual provider call. These are where token counts, cost, model name, and the raw prompt get attached. `capture_prompts` (`config.py:29`) controls whether the prompt payload is recorded.
+- **LM calls.** `on_lm_start` and `on_lm_end` wrap the provider call. The callback records the model, the current span token projections, and a versioned `lm_usage` evidence object. `capture_prompts` controls whether the prompt payload is recorded.
 - **Adapter format/parse** — `on_adapter_format_start` / `_end` and `on_adapter_parse_start` / `_end` (`callback.py:604`–`631`). Both route through shared helpers `_start_adapter_span` (`callback.py:640`) and `_end_adapter_span` (`callback.py:664`). Adapter spans have their raw inputs/outputs stripped in `models.py` — see `_ADAPTER_SPAN_TYPES` handling in `python-sdk/cmpnd/models.py:177` — because the same content already appears on the enclosing LM span.
 - **Tools** — `on_tool_start` (`callback.py:700`) / `on_tool_end` (`callback.py:733`). One span per `dspy.Tool` invocation, with the tool's args as inputs.
 - **Interpreter (code execution)** — `_InterpreterMixin` (`callback.py:1119`), for the DSPy `CodeInterpreter` hooks DSPy >= 3.3.1 fires around a program running code in the interpreter (`RLM`, `ProgramOfThought`, `CodeAct`, `Flex` — every module reaching it through `_create_interpreter`; `ReAct` / `ReActV2` use no interpreter and fire none). `on_interpreter_execute_start` / `_end` emit one `INTERPRETER_EXECUTE` span per REPL cell — the code in, its captured stdout out, and the `SUBMIT()` result (a DSPy `FinalOutput`) recorded distinctly from stdout. `on_interpreter_tool_call_start` / `_end` synthesize a `TOOL` span for a tool called from interpreter code **only when no real `dspy.Tool` span covered the call** (a user tool routes through `Tool.__call__` and fires `on_tool_*`, so its row is suppressed to avoid a duplicate; the `llm_query` builtins fire no tool hook, so they get the synthesized span). `on_interpreter_startup_*` / `on_interpreter_shutdown_*` emit no span — their duration folds into an `interpreter.startup_ms` / `interpreter.shutdown_ms` attribute on the enclosing span, and an event with no enclosing span (a pooled pre-warm) is dropped.
@@ -387,7 +387,7 @@ The exporter POSTs to a handful of endpoints, all under `/api/v1/` on the cmpnd-
 - `POST /api/v1/traces/:id/start` and `/finalize` — two-tier ingestion. `/start` writes an `in_progress` placeholder row; `/finalize` closes a streaming (RLM) trace.
 - `POST /api/v1/eval_runs`, `POST /api/v1/optimization_runs`, and related progress endpoints.
 
-The trace payload is built in `python-sdk/cmpnd/models.py` by `TraceBuilder.to_api_dict()` (`models.py:398`) and `SpanBuilder.to_api_dict()` (`models.py:300`). A span's dict looks roughly like this, with every field mirrored verbatim to the Postgres `spans` schema documented in [`serve/DB.md`](../../serve/DB.md) ("Analytics tables"):
+The trace payload is built in `python-sdk/cmpnd/models.py` by `TraceBuilder.to_api_dict()` and `SpanBuilder.to_api_dict()`. Serve stores the span's compatibility fields on the `spans` row and stores its `lm_usage` evidence separately. A span's dict looks roughly like this:
 
 ```python
 {
@@ -404,6 +404,22 @@ The trace payload is built in `python-sdk/cmpnd/models.py` by `TraceBuilder.to_a
     "cached_prompt_tokens": 96,  # provider prompt-cache reads, subset of prompt_tokens
     "reasoning_tokens": 12,      # subset of completion_tokens; None when unreported
     "cache_write_tokens": None,  # prompt-cache writes; None when unreported
+    "lm_usage": {
+        "schema_version": 1,
+        "source_observation_id": "...",
+        "source_payload_digest": "...",
+        "observed_at": "...",
+        "usage_reported": True,
+        "usage_raw": {"prompt_tokens": 137, "completion_tokens": 42},
+        "model_requested": "gpt-4o-mini",
+        "model_reported": "gpt-4o-mini-2026-08-01",
+        "prompt_tokens": 137,
+        "completion_tokens": 42,
+        "cache_read_tokens": 96,
+        "cache_write_tokens": None,
+        "reasoning_tokens": 12,
+        # ...plus selectors and correlation IDs when DSPy exposes them
+    },
     "inputs": { ... },
     "outputs": { ... },
     # ...plus status, timings, attributes, events
@@ -412,6 +428,16 @@ The trace payload is built in `python-sdk/cmpnd/models.py` by `TraceBuilder.to_a
 
 See the `to_api_dict` methods in `python-sdk/cmpnd/models.py` for the full field list — don't trust a doc to stay in sync with it.
 
+### LM usage evidence
+
+Every LM span carries one `LMUsageObservationV1`. The observation preserves the complete JSON-compatible usage object that DSPy exposes. LiteLLM may have normalized that object before the SDK receives it, so the SDK labels a dialect only when the response surface or usage shape establishes one.
+
+The queryable counters use `None` for an absent measurement and `0` for a reported zero. The legacy span counters keep their established defaults for compatibility. The evidence object also records requested and reported models, requested and effective service tiers, one unambiguous requested cache TTL, DSPy client-cache status, provider response identity, and an optional hosted egress call ID.
+
+The callback mints `source_observation_id` when the LM call starts and records `observed_at` when it ends. Export retries serialize the same observation, including the same identity, timestamp, and SHA-256 payload digest. A DSPy client-cache hit remains an SDK observation, but `usage_reported` is false because no provider call occurred.
+
+`provider_cost` stays `None`. DSPy and LiteLLM can attach a calculated cost to history, but that value is not provider evidence. The SDK will populate this field only when an adapter can prove that the provider supplied both the amount and its currency.
+
 ## Field truncation (span inputs/outputs)
 
 A span's `inputs`/`outputs` whose serialized JSON exceeds the 64 KB budget (`_MAX_FIELD_JSON_SIZE`) are truncated **structurally** — the shape is preserved and only the oversized leaves become `_truncated` envelopes — rather than collapsed to a flat string preview. `_MAX_FIELD_JSON_SIZE` is a **whole-payload** cap: `truncate_field(value, max_size)` returns a value whose serialized length is `<= max_size` at the top level, so the emitted `inputs`/`outputs` payload is bounded as a whole, not merely leaf by leaf. The one truncator is `truncate_field` in `python-sdk/cmpnd/models.py` (with the dict case in `_truncate_dict`); treat that as the source of truth and read it rather than trusting the summary below to stay exact.

{cmpnd-0.23.1 → cmpnd-0.23.2}/pyproject.toml

@@ -5,7 +5,7 @@ name = "cmpnd"
 # it's new) — no git tags. Bump with `uv version --bump {minor,patch}` or by
 # hand. Runtime `cmpnd.__version__` reads installed metadata, so it tracks
 # this automatically. See docs/plans/2026-07-02-sdk-pypi-tag-free-publish.md.
-version = "0.23.1"
+version = "0.23.2"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.10"

{cmpnd-0.23.1 → cmpnd-0.23.2}/scripts/test-in-linux.sh

@@ -10,15 +10,15 @@
 # Discovering that in CI, one push at a time, is the loop this replaces.
 #
 # The repo-root `docs/` comes along because the ingest-conformance fixtures read
-# `docs/ingest-api.yaml` and `docs/schemas/*` by path from the repo root. Without
-# it the lane reports a handful of FileNotFoundError failures that look like
-# defects and are not — and a lane that cries wolf is a lane whose output you stop
-# reading.
+# `docs/ingest-api.yaml` and `docs/schemas/*` by path from the repo root. The
+# editable fake-provider package comes along because uv resolves it from the SDK
+# lock. Without either tree, the lane fails before it tests the SDK.
 #
 # It deliberately does NOT mount the host `.venv`: those wheels are macOS
 # wheels, and a container reusing them fails in ways that teach you nothing about
 # the code. uv resolves fresh inside, which is also what makes this a real answer
-# to "would CI see this too".
+# to "would CI see this too". The copy also drops `.pyc` files because their
+# embedded source paths may name a worktree that moved or no longer exists.
 #
 # Usage — everything, or a pytest selector:
 #   python-sdk/scripts/test-in-linux.sh
@@ -46,4 +46,4 @@ exec docker run --rm \
     --tmpfs /work:exec,size=3g \
     -e UV_LINK_MODE=copy \
     "${IMAGE}" \
-    bash -c "mkdir -p /work && cp -r /repo/python-sdk /repo/docs /work/ && rm -rf /work/python-sdk/.venv && uv sync --extra dev --quiet && uv run --no-sync python -m pytest $(printf '%q ' "${ARGS[@]}")"
+    bash -c "mkdir -p /work && cp -r /repo/python-sdk /repo/fake-provider /repo/docs /work/ && rm -rf /work/python-sdk/.venv && find /work/python-sdk -name '*.pyc' -delete && uv sync --extra dev --quiet && uv run --no-sync python -m pytest $(printf '%q ' "${ARGS[@]}")"