trodo-python 2.7.0__py3-none-any.whl → 2.9.0__py3-none-any.whl

trodo/__init__.py

@@ -40,7 +40,7 @@ Downstream microservice (join the caller's run instead of making a new one):
 
 from __future__ import annotations
 
-__version__ = "2.7.0"
+__version__ = "2.9.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 

trodo/otel/auto_instrument.py

@@ -22,6 +22,13 @@ def _hr_to_iso(nanos: Optional[int]) -> Optional[str]:
     return datetime.fromtimestamp(nanos / 1e9, tz=timezone.utc).isoformat().replace("+00:00", "Z")
 
 
+def _trunc(s: Any, max_len: int) -> Optional[str]:
+    if s is None:
+        return None
+    s = str(s)
+    return s[:max_len] if len(s) > max_len else s
+
+
 def _infer_kind(attrs: Dict[str, Any]) -> str:
     if not attrs:
         return "generic"
@@ -111,6 +118,29 @@ def otel_span_to_trodo_span(otel_span: Any) -> Optional[TrodoSpan]:
     except Exception:
         ok = "error" if (status_code and str(status_code).endswith("ERROR")) else "ok"
 
+    # Rich error detail. The real exception class + stacktrace live in the OTel
+    # `exception` event (record_exception — emitted by the Anthropic/OpenAI/
+    # LangChain instrumentors), NOT span.status. The old bridge read only the
+    # status code and dropped all of it.
+    status_desc = getattr(status, "description", None)
+    exc_attrs: Dict[str, Any] = {}
+    for ev in (getattr(otel_span, "events", None) or []):
+        if getattr(ev, "name", None) == "exception":
+            exc_attrs = dict(getattr(ev, "attributes", {}) or {})
+            break
+    err_type = exc_attrs.get("exception.type") or attrs.get("exception.type") or attrs.get("error.type")
+    err_msg = exc_attrs.get("exception.message") or attrs.get("exception.message") or status_desc
+    err_stack = exc_attrs.get("exception.stacktrace") or attrs.get("exception.stacktrace")
+    status_code_val = (
+        attrs.get("http.response.status_code")
+        or attrs.get("http.status_code")
+        or attrs.get("gen_ai.response.status_code")
+        or attrs.get("error.code")
+    )
+    has_error = ok == "error" or err_type is not None
+    ok = "error" if has_error else "ok"
+    level = "error" if has_error else "default"
+
     # Accept both stable and experimental GenAI semconv keys.
     in_toks = (
         attrs.get("gen_ai.usage.input_tokens")
@@ -138,6 +168,11 @@ def otel_span_to_trodo_span(otel_span: Any) -> Optional[TrodoSpan]:
         kind=kind,
         name=getattr(otel_span, "name", kind),
         status=ok,
+        level=level,
+        error_type=_trunc(err_type, 128) if err_type else None,
+        error_message=_trunc(err_msg, 4_000) if err_msg else None,
+        status_code=_trunc(status_code_val, 32) if status_code_val is not None else None,
+        stack_trace=_trunc(err_stack, 20_000) if err_stack else None,
         started_at=started_at,
         ended_at=ended_at,
         duration_ms=duration_ms,

trodo/otel/helpers.py

@@ -232,6 +232,52 @@ def _default_usage_extractor(result: Any) -> Tuple[Optional[int], Optional[int]]
     return (None, None)
 
 
+def _coerce_num(v: Any) -> Optional[float]:
+    try:
+        n = float(v)
+    except (TypeError, ValueError):
+        return None
+    return n
+
+
+def _default_usage_map(result: Any) -> Optional[Dict[str, float]]:
+    """Forward the FULL provider usage object (incl. cache/reasoning) as an open
+    map. The backend normalises raw keys (``prompt_tokens`` -> input,
+    ``cache_read_input_tokens`` / ``cached_tokens`` -> cache_read,
+    ``cache_creation_input_tokens`` -> cache_write, ``reasoning_tokens`` ->
+    reasoning, ...), so passing whatever the provider returned is enough.
+
+    Flattens OpenAI ``*_tokens_details`` so cached/reasoning leaves survive.
+    Accepts either the bare usage object or a full response carrying ``usage`` /
+    ``usageMetadata``.
+    """
+    if result is None:
+        return None
+    raw: Any = None
+    if isinstance(result, dict):
+        raw = result.get("usage") or result.get("usageMetadata")
+        # Bare usage object passed directly (has numeric token leaves).
+        if raw is None and any(_coerce_num(v) is not None or isinstance(v, dict) for v in result.values()):
+            raw = result
+    else:
+        raw = getattr(result, "usage", None) or getattr(result, "usageMetadata", None)
+    if not isinstance(raw, dict):
+        return None
+    out: Dict[str, float] = {}
+    for k, v in raw.items():
+        if isinstance(v, dict):
+            # OpenAI prompt_tokens_details / completion_tokens_details — flatten.
+            for dk, dv in v.items():
+                n = _coerce_num(dv)
+                if n is not None:
+                    out[dk] = n
+            continue
+        n = _coerce_num(v)
+        if n is not None:
+            out[k] = n
+    return out or None
+
+
 def llm(
     name: Any = None,
     fn: Optional[Callable[..., Any]] = None,
@@ -240,13 +286,16 @@ def llm(
     provider: Optional[str] = None,
     temperature: Optional[float] = None,
     extract_usage: Optional[Callable[[Any], Tuple[Optional[int], Optional[int]]]] = None,
+    extract_usage_map: Optional[Callable[[Any], Optional[Dict[str, float]]]] = None,
 ) -> Any:
     """Wrap an LLM call as a ``kind='llm'`` span with auto token extraction.
 
-    The helper records ``model``/``provider`` on entry; on return it inspects
-    the response for the common usage shapes (OpenAI ``usage.prompt_tokens``,
-    Anthropic ``usage.input_tokens``, Gemini ``usageMetadata.promptTokenCount``)
-    and records tokens. Pass ``extract_usage=lambda r: (in, out)`` to override.
+    By default the helper forwards the FULL provider usage object (OpenAI
+    ``usage``, Anthropic ``usage`` incl. cache fields, Gemini ``usageMetadata``)
+    as an open map, so cache/reasoning tokens are captured and priced
+    automatically by the backend. Pass ``extract_usage=lambda r: (in, out)`` to
+    fall back to scalar-only extraction, or ``extract_usage_map=lambda r: {..}``
+    to build the map yourself.
 
     Usage::
 
@@ -257,7 +306,6 @@ def llm(
         @trodo.llm('plan', model='claude-haiku-4-5', provider='anthropic')
         def plan(messages): ...
     """
-    extractor = extract_usage or _default_usage_extractor
 
     def _set_llm(s: SpanHandle) -> None:
         if model or provider or temperature is not None:
@@ -268,18 +316,25 @@ def llm(
             )
 
     def _on_result(s: SpanHandle, result: Any) -> None:
+        if extract_usage is not None:
+            # Caller opted into scalar-only extraction (back-compat).
+            try:
+                pt, ct = extract_usage(result)
+            except Exception:
+                pt, ct = (None, None)
+            if pt is not None or ct is not None:
+                s.set_llm(
+                    model=model, provider=provider,
+                    input_tokens=pt, output_tokens=ct, temperature=temperature,
+                )
+            return
+        # Default: forward the full provider usage map (incl. cache/reasoning).
         try:
-            pt, ct = extractor(result)
+            usage_map = (extract_usage_map or _default_usage_map)(result)
         except Exception:
-            pt, ct = (None, None)
-        if pt is not None or ct is not None:
-            s.set_llm(
-                model=model,
-                provider=provider,
-                input_tokens=pt,
-                output_tokens=ct,
-                temperature=temperature,
-            )
+            usage_map = None
+        if usage_map:
+            s.set_llm(model=model, provider=provider, temperature=temperature, usage_details=usage_map)
 
     return _dual_form("llm")(
         name, fn, kind="llm", extra_set=_set_llm, on_result=_on_result
@@ -358,6 +413,7 @@ def track_mcp(
         "kind": "tool",
         "name": f"tool.{tool}",
         "status": status,
+        "level": "error" if error else "default",
         "input": _stringify({"tool": tool, "params": input}) if input is not None else None,
         "output": _stringify(output_to_record),
         "tool_name": tool,
@@ -387,6 +443,11 @@ def track_llm_call(
     provider: Optional[str] = None,
     input_tokens: Optional[int] = None,
     output_tokens: Optional[int] = None,
+    cache_read_tokens: Optional[int] = None,
+    cache_write_tokens: Optional[int] = None,
+    usage_details: Optional[Dict[str, float]] = None,
+    usage: Any = None,
+    cost_details: Optional[Dict[str, float]] = None,
     prompt: Any = None,
     completion: Any = None,
     temperature: Optional[float] = None,
@@ -397,23 +458,38 @@ def track_llm_call(
     """Record a one-shot LLM span for a raw-HTTP caller.
 
     Opens and immediately closes a ``span(kind='llm')`` populated with the
-    model + token counts + prompt/completion. No-op outside an active run
-    context.
+    model + tokens + prompt/completion. No-op outside an active run context.
+
+    Cost can be reported three ways (in priority order):
+      1. ``cost`` — a final USD figure (overrides all server-side derivation).
+      2. ``cost_details`` — a per-category USD breakdown (authoritative).
+      3. tokens only — the backend prices them against the team's model prices.
+
+    Tokens can be passed as scalars (``input_tokens``/``output_tokens``),
+    cache shorthands (``cache_read_tokens``/``cache_write_tokens``), an open
+    ``usage_details`` map, or a raw provider ``usage`` object to auto-extract
+    from (e.g. ``resp['usage']`` or ``resp['usageMetadata']``).
 
     Usage:
         resp = httpx.post(url, json=body).json()
         trodo.track_llm_call(
-            model='gemini-2.5-flash',
-            provider='google',
-            input_tokens=resp['usageMetadata']['promptTokenCount'],
-            output_tokens=resp['usageMetadata']['candidatesTokenCount'],
-            prompt=body,
-            completion=resp,
+            model='claude-sonnet-4', provider='anthropic',
+            usage=resp['usage'],          # cache fields captured automatically
+            prompt=body, completion=resp,
         )
     """
     if get_active_context() is None:
         return
     span_name = name or (f"llm.{provider}.{model}" if model else "llm")
+    # Merge an explicit usage_details map with anything auto-extracted from a
+    # raw `usage` object the caller passed through.
+    merged_usage: Dict[str, float] = {}
+    if usage is not None:
+        from_usage = _default_usage_map(usage)
+        if from_usage:
+            merged_usage.update(from_usage)
+    if usage_details:
+        merged_usage.update(usage_details)
     with span_ctx(span_name, kind="llm", input=prompt, attributes=metadata) as s:
         s.set_llm(
             model=model,
@@ -421,6 +497,10 @@ def track_llm_call(
             input_tokens=input_tokens,
             output_tokens=output_tokens,
             cost=cost,
+            usage_details=merged_usage or None,
+            cost_details=cost_details,
+            cache_read_tokens=cache_read_tokens,
+            cache_write_tokens=cache_write_tokens,
             temperature=temperature,
         )
         if completion is not None:

trodo/otel/processor.py

@@ -20,12 +20,18 @@ class TrodoRun:
     conversation_id: Optional[str] = None
     parent_run_id: Optional[str] = None
     status: str = "ok"  # 'running' | 'ok' | 'error'
+    # Severity (Langfuse parity): 'debug' | 'default' | 'warning' | 'error'.
+    # Optional — backend derives it from status when omitted.
+    level: Optional[str] = None
     input: Optional[Union[str, Dict[str, Any]]] = None
     output: Optional[Union[str, Dict[str, Any]]] = None
     started_at: Optional[str] = None
     ended_at: Optional[str] = None
     duration_ms: Optional[int] = None
     error_summary: Optional[str] = None
+    # Exception class of the run-level failure (runs previously only had the
+    # free-text error_summary).
+    error_type: Optional[str] = None
     metadata: Optional[Dict[str, Any]] = None
     # Aggregates summed from child spans at finalisation.
     total_tokens_in: Optional[int] = None
@@ -47,6 +53,8 @@ class TrodoSpan:
     kind: str = "generic"  # 'llm' | 'tool' | 'agent' | 'retrieval' | 'generic'
     name: str = ""
     status: str = "ok"
+    # Severity (Langfuse parity): 'debug' | 'default' | 'warning' | 'error'.
+    level: Optional[str] = None
     started_at: Optional[str] = None
     ended_at: Optional[str] = None
     duration_ms: Optional[int] = None
@@ -54,11 +62,23 @@ class TrodoSpan:
     output: Optional[Union[str, Dict[str, Any]]] = None
     error_type: Optional[str] = None
     error_message: Optional[str] = None
+    # HTTP/provider status code (e.g. '429', 'rate_limit_exceeded').
+    status_code: Optional[str] = None
+    # Truncated exception stacktrace.
+    stack_trace: Optional[str] = None
     model: Optional[str] = None
     provider: Optional[str] = None
     input_tokens: Optional[int] = None
     output_tokens: Optional[int] = None
     cost: Optional[float] = None
+    # Open token-usage map forwarded to the backend, which normalises raw
+    # provider field names to canonical categories (input, output, cache_read,
+    # cache_write, reasoning, + custom keys) and prices each against the team's
+    # configured model prices.
+    usage_details: Optional[Dict[str, float]] = None
+    # Per-category cost breakdown in USD (authoritative when set — ingested cost
+    # always wins over server-side derivation).
+    cost_details: Optional[Dict[str, float]] = None
     temperature: Optional[float] = None
     tool_name: Optional[str] = None
     attributes: Optional[Dict[str, Any]] = None

trodo/otel/wrap_agent.py

@@ -26,6 +26,7 @@ from __future__ import annotations
 
 import json
 import time
+import traceback
 import uuid
 from datetime import datetime, timezone
 from typing import Any, Callable, Dict, Optional, Union
@@ -79,6 +80,54 @@ def _truncate(value: Any, max_len: int = _MAX_VALUE_LEN) -> Optional[str]:
     return s[:max_len] if len(s) > max_len else s
 
 
+def describe_error(exc_type, exc, tb=None) -> Dict[str, Optional[str]]:
+    """Extract rich error detail from a caught exception so spans carry error
+    TYPE, HTTP/provider STATUS CODE, and STACK TRACE — not just a message.
+
+    Works generically across provider SDKs: OpenAI (``exc.status`` /
+    ``exc.code``), Anthropic (``exc.status``), httpx/requests
+    (``exc.response.status_code``), and stdlib errors (``exc.errno``). Never
+    raises. Returns keys: error_type, error_message, status_code, stack_trace,
+    level.
+    """
+    if exc is None:
+        return {"error_type": None, "error_message": None, "status_code": None,
+                "stack_trace": None, "level": "error"}
+    error_type = getattr(exc_type, "__name__", None) or type(exc).__name__
+    error_message = _truncate(str(exc), 4_000)
+
+    status_code: Optional[str] = None
+    # HTTP status first (numeric), then a provider/system error code.
+    for attr in ("status", "status_code"):
+        v = getattr(exc, attr, None)
+        if v is not None:
+            status_code = str(v)[:32]
+            break
+    if status_code is None:
+        resp = getattr(exc, "response", None)
+        rc = getattr(resp, "status_code", None) if resp is not None else None
+        if rc is not None:
+            status_code = str(rc)[:32]
+    if status_code is None:
+        code = getattr(exc, "code", None) or getattr(exc, "errno", None)
+        if code is not None:
+            status_code = str(code)[:32]
+
+    stack_trace: Optional[str] = None
+    try:
+        stack_trace = _truncate("".join(traceback.format_exception(exc_type, exc, tb)), 20_000)
+    except Exception:
+        stack_trace = None
+
+    return {
+        "error_type": (error_type or "Error")[:128],
+        "error_message": error_message,
+        "status_code": status_code,
+        "stack_trace": stack_trace,
+        "level": "error",
+    }
+
+
 def _prepare_value(value: Any, max_len: int = _MAX_VALUE_LEN) -> Optional[Union[str, Dict[str, Any]]]:
     """Prepare a value for storage in the JSONB input/output column.
 
@@ -197,8 +246,22 @@ class SpanHandle:
         self.input_tokens: Optional[int] = None
         self.output_tokens: Optional[int] = None
         self.cost: Optional[float] = None
+        # Open token-usage map (canonical or raw provider keys — the backend
+        # normalises). Lets callers report cache/reasoning/custom categories.
+        self.usage_details: Optional[Dict[str, float]] = None
+        # Optional per-category cost breakdown in USD (authoritative when set).
+        self.cost_details: Optional[Dict[str, float]] = None
         self.temperature: Optional[float] = None
         self.tool_name: Optional[str] = None
+        # Severity for this span (Langfuse parity). Leave None for the default
+        # behaviour (backend derives 'error' on a thrown exception, else
+        # 'default'). Set 'warning' for a recovered/retried step, 'debug' for
+        # verbose spans.
+        self.level: Optional[str] = None
+
+    def set_level(self, level: str) -> None:
+        """Mark this span's severity (does not change ok/error status)."""
+        self.level = level
 
     def set_input(self, value: Any) -> None:
         self.input = _prepare_value(value)
@@ -217,6 +280,10 @@ class SpanHandle:
         input_tokens: Optional[int] = None,
         output_tokens: Optional[int] = None,
         cost: Optional[float] = None,
+        usage_details: Optional[Dict[str, float]] = None,
+        cost_details: Optional[Dict[str, float]] = None,
+        cache_read_tokens: Optional[int] = None,
+        cache_write_tokens: Optional[int] = None,
         temperature: Optional[float] = None,
     ) -> None:
         if model is not None:
@@ -231,6 +298,28 @@ class SpanHandle:
             self.cost = float(cost)
         if temperature is not None:
             self.temperature = float(temperature)
+        # Merge any usage map + cache shorthands into one forwarded map.
+        if usage_details or cache_read_tokens is not None or cache_write_tokens is not None:
+            merged: Dict[str, float] = dict(self.usage_details or {})
+            if usage_details:
+                for k, v in usage_details.items():
+                    try:
+                        merged[k] = float(v)
+                    except (TypeError, ValueError):
+                        continue
+            if cache_read_tokens is not None:
+                merged["cache_read"] = float(cache_read_tokens)
+            if cache_write_tokens is not None:
+                merged["cache_write"] = float(cache_write_tokens)
+            self.usage_details = merged
+        if cost_details:
+            merged_c: Dict[str, float] = dict(self.cost_details or {})
+            for k, v in cost_details.items():
+                try:
+                    merged_c[k] = float(v)
+                except (TypeError, ValueError):
+                    continue
+            self.cost_details = merged_c
 
     def set_tool(self, tool_name: str) -> None:
         self.tool_name = tool_name
@@ -388,9 +477,8 @@ class wrap_agent:
         ended_iso = _now_iso()
         duration_ms = int(time.time() * 1000.0 - self._started_ms)
         status = "error" if exc is not None else "ok"
-        error_summary = None
-        if exc is not None:
-            error_summary = _truncate(str(exc), 4_000)
+        einfo = describe_error(exc_type, exc, tb) if exc is not None else None
+        error_summary = einfo["error_message"] if einfo else None
 
         pending = self._processor.get_pending(self.handle.run_id)
         agg = _aggregate(pending)
@@ -402,12 +490,14 @@ class wrap_agent:
             conversation_id=self._conversation_id,
             parent_run_id=self._parent_run_id,
             status=status,
+            level="error" if exc is not None else None,
             input=self.handle.input,
             output=self.handle.output,
             started_at=self._started_iso,
             ended_at=ended_iso,
             duration_ms=duration_ms,
             error_summary=error_summary,
+            error_type=einfo["error_type"] if einfo else None,
             metadata={**(self._metadata or {}), **self.handle.metadata} or None,
             total_tokens_in=agg["total_tokens_in"],
             total_tokens_out=agg["total_tokens_out"],
@@ -553,8 +643,8 @@ class join_run:
         ended_iso = _now_iso()
         duration_ms = int(time.time() * 1000.0 - self._started_ms)
         status = "error" if exc is not None else "ok"
-        error_type = exc_type.__name__ if exc_type else None
-        error_message = _truncate(str(exc), 4_000) if exc else None
+        einfo = describe_error(exc_type, exc, tb) if exc is not None else None
+        level = self.handle.level or ("error" if exc is not None else None)
 
         trodo_span = TrodoSpan(
             span_id=self._span_id,
@@ -563,18 +653,23 @@ class join_run:
             kind=self._kind,
             name=self._name,
             status=status,
+            level=level,
             started_at=self._started_iso,
             ended_at=ended_iso,
             duration_ms=duration_ms,
             input=self.handle.input,
             output=self.handle.output,
-            error_type=error_type,
-            error_message=error_message,
+            error_type=einfo["error_type"] if einfo else None,
+            error_message=einfo["error_message"] if einfo else None,
+            status_code=einfo["status_code"] if einfo else None,
+            stack_trace=einfo["stack_trace"] if einfo else None,
             model=self.handle.model,
             provider=self.handle.provider,
             input_tokens=self.handle.input_tokens,
             output_tokens=self.handle.output_tokens,
             cost=self.handle.cost,
+            usage_details=self.handle.usage_details,
+            cost_details=self.handle.cost_details,
             temperature=self.handle.temperature,
             tool_name=self.handle.tool_name,
             attributes=self.handle.attributes or None,
@@ -643,8 +738,8 @@ class span:
         ended_iso = _now_iso()
         duration_ms = int(time.time() * 1000.0 - self._started_ms)
         status = "error" if exc is not None else "ok"
-        error_type = exc_type.__name__ if exc_type else None
-        error_message = _truncate(str(exc), 4_000) if exc else None
+        einfo = describe_error(exc_type, exc, tb) if exc is not None else None
+        level = self.handle.level or ("error" if exc is not None else None)
 
         trodo_span = TrodoSpan(
             span_id=self._span_id,
@@ -653,18 +748,23 @@ class span:
             kind=self._kind,
             name=self._name,
             status=status,
+            level=level,
             started_at=self._started_iso,
             ended_at=ended_iso,
             duration_ms=duration_ms,
             input=self.handle.input,
             output=self.handle.output,
-            error_type=error_type,
-            error_message=error_message,
+            error_type=einfo["error_type"] if einfo else None,
+            error_message=einfo["error_message"] if einfo else None,
+            status_code=einfo["status_code"] if einfo else None,
+            stack_trace=einfo["stack_trace"] if einfo else None,
             model=self.handle.model,
             provider=self.handle.provider,
             input_tokens=self.handle.input_tokens,
             output_tokens=self.handle.output_tokens,
             cost=self.handle.cost,
+            usage_details=self.handle.usage_details,
+            cost_details=self.handle.cost_details,
             temperature=self.handle.temperature,
             tool_name=self.handle.tool_name,
             attributes=self.handle.attributes or None,

{trodo_python-2.7.0.dist-info → trodo_python-2.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.7.0
+Version: 2.9.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side
@@ -274,6 +274,69 @@ with tracer.start_as_current_span('custom') as sp:
     sp.set_attribute('gen_ai.system', 'my-llm')
 ```
 
+### Cost & token reporting (v2.8.0+)
+
+Trodo computes per-span cost from whatever you report. **You don't have to send
+cost** — send tokens and Trodo prices them using the team's **Model Price** config
+(Configuration → Model Price), falling back to built-in defaults. Resolution per
+span, highest priority first:
+
+1. **Explicit `cost`** (a final USD number) — used as-is, never recomputed.
+2. **`cost_details`** (per-category USD breakdown) — authoritative.
+3. **Tokens** (`usage_details` map, or `input_tokens`/`output_tokens`) — priced by
+   the team's configured model price → global default → left unset if unknown.
+
+All token categories live in an open **`usage_details`** map. `input`/`output` are
+the defaults; add `cache_read`, `cache_write`, `reasoning`, `audio`, `image`, or any
+custom key. Raw provider field names are fine — the backend normalises them
+(`prompt_tokens`→`input`, `cache_read_input_tokens`→`cache_read`, …). Custom keys
+must match the category name you price in the UI.
+
+```python
+# (a) Tokens only — Trodo prices it from the model name. The llm() helper
+#     auto-forwards the FULL provider usage object, so cache/reasoning tokens
+#     are captured with zero config.
+answer = trodo.llm('answer', call_anthropic,
+                   model='claude-sonnet-4', provider='anthropic')
+
+# (b) Raw usage object via track_llm_call — same auto-normalisation.
+trodo.track_llm_call(
+    model='gpt-4o', provider='openai',
+    usage=resp['usage'],   # {prompt_tokens, completion_tokens, prompt_tokens_details:{cached_tokens}}
+    prompt=body, completion=resp,
+)
+
+# (c) Explicit usage map + cache shorthands.
+trodo.track_llm_call(
+    model='claude-sonnet-4', provider='anthropic',
+    usage_details={'input': 1000, 'output': 500},
+    cache_read_tokens=200, cache_write_tokens=80,   # → cache_read / cache_write
+)
+
+# (d) Pass cost straight through (skip server-side pricing).
+trodo.track_llm_call(model='gpt-4o', provider='openai', cost=0.0123)
+
+# (e) Per-category cost breakdown (authoritative).
+trodo.track_llm_call(
+    model='gpt-4o', provider='openai',
+    cost_details={'input': 0.0003, 'output': 0.0005, 'cache_read': 0.00001},
+)
+```
+
+Inside a `wrap_agent` / `span` block, set the same fields on the handle:
+
+```python
+s.set_llm(
+    model='gpt-4o', provider='openai',
+    usage_details={'input': 1000, 'output': 500},
+    cache_read_tokens=200,
+    # or: cost=0.0123  /  cost_details={'input': ..., 'output': ...}
+)
+```
+
+Override auto-extraction with `extract_usage` (scalar in/out) or `extract_usage_map`
+(open map) on `trodo.llm(name, fn, ...)`.
+
 ### Cross-service runs
 
 When one service calls another, the downstream service **joins** the

{trodo_python-2.7.0.dist-info → trodo_python-2.9.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-trodo/__init__.py,sha256=NapUF153zVbbqH45gud9g9M_UyQgxuqw_yAYERTGJlw,16678
+trodo/__init__.py,sha256=p9NGic9WzF53OYKtk-MSdQNcCTbXq8DNZeXYWl9OCUo,16678
 trodo/client.py,sha256=8DsKoLh_eaNxj93qkHynfeee-QsdomB_kXfUQjGnWDk,18607
 trodo/types.py,sha256=eySgUvCXROG2TxtxgiU0MNr5iH0DEcduK8bmYtTKG44,3138
 trodo/user_context.py,sha256=9la6azzwEanVmdP4ps_xMoufbeWVeIGU-M8ychmgajg,7859
@@ -12,20 +12,20 @@ trodo/managers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/managers/group_manager.py,sha256=ki3Se3qEoSZfREX63oeDeBmEfZF-ISHLE8azEtLg0tM,3542
 trodo/managers/people_manager.py,sha256=mMVnx40Mlifx6NGgChvohC9ViK6dQu2mkXNHbV8pK1E,2882
 trodo/otel/__init__.py,sha256=yiRFXWUU45bAM2CV37XeO7zf1hmnmjufdP4XO50yEyE,624
-trodo/otel/auto_instrument.py,sha256=7uKhir0o0Mo_od1H2oMf5PHZovcUocHtgV18mRm2Erc,11193
+trodo/otel/auto_instrument.py,sha256=gym90cYD6NzVDVsNtUjKHdKANy17t4AnU4lYGEGHyo8,12866
 trodo/otel/context.py,sha256=iJ1rE42-SbO8VZHAxhIl2ZJXgNwLIVps5xLg8GKgfFc,1165
-trodo/otel/helpers.py,sha256=IEAHxAEN-Bvv_ZODrmRzC6PCGGhGTXU7IPcp6iO2nbA,16405
-trodo/otel/processor.py,sha256=9y5gUMg7iQ1anXf2vGLbmgdT8iRXUGu7QivAqxg4JS4,6384
+trodo/otel/helpers.py,sha256=4HsjMOrE-7zuvaRSiGXxV7ZyfXQ5gLxtR3HdpLut9sk,20054
+trodo/otel/processor.py,sha256=aqcTmzTw9cESgIp829pu_XCa5_dG_2MaeJNsqJZeqQU,7495
 trodo/otel/register.py,sha256=YV2EnkUoa-_54YAuChOe-Mg28UUKg8JO7-qhVP9G6u4,7644
 trodo/otel/transport.py,sha256=hzZz8gwSMGJ8CxdijmLn1Ljt18owr9XTWy13DLbwYbw,2441
-trodo/otel/wrap_agent.py,sha256=T5pbD2iGE2B7oilKszPsFTRyRtEvdXe2cz20xpg20ik,25529
+trodo/otel/wrap_agent.py,sha256=Nvjj8CjIGHqfWNV_heHno9HKJbKU3lHqHInX1EyRhnw,30334
 trodo/queue/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/queue/batch_flusher.py,sha256=4Lg6T3Urwi9U0Q4FpFGPmjDYKg4ZliCTR-ND8BJvWaY,1298
 trodo/queue/event_queue.py,sha256=EVFZrhlq_kwC3jJ2GK0wMhHISf9UzLCZNDnT_aZ2I2A,872
 trodo/session/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/session/server_session.py,sha256=McsudEiq33XDq3nqxgzBcUvIjQxCMscwEuAPnYXrTjs,2136
 trodo/session/session_manager.py,sha256=JrgH1VeicmtlxPR4dXEuJbxhi23OelkgwW3-9Slv80o,2525
-trodo_python-2.7.0.dist-info/METADATA,sha256=K19DXcIe8jCHbOCEWXkyy0mxGhjCz_fH_VIdm0vuM9E,17882
-trodo_python-2.7.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-trodo_python-2.7.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
-trodo_python-2.7.0.dist-info/RECORD,,
+trodo_python-2.9.0.dist-info/METADATA,sha256=Ab8QIUgDMayOyTjdtrdFP_EMk5bCcLHtX4hZJaaKEac,20482
+trodo_python-2.9.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+trodo_python-2.9.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
+trodo_python-2.9.0.dist-info/RECORD,,