trodo-python 2.7.0__tar.gz → 2.9.0__tar.gz

{trodo_python-2.7.0 → trodo_python-2.9.0}/PKG-INFO

@@ -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 → trodo_python-2.9.0}/README.md

@@ -243,6 +243,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 → trodo_python-2.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trodo-python"
-version = "2.7.0"
+version = "2.9.0"
 description = "Trodo Analytics SDK for Python — server-side event tracking"
 readme = "README.md"
 license = { text = "ISC" }

trodo_python-2.9.0/tests/test_anon_distinct_id.py

@@ -0,0 +1,100 @@
+"""Anonymous distinct_id minting on agent surfaces.
+
+When the caller doesn't pass ``distinct_id``, the SDK mints an
+``anon_<ts>_python_<uuid>_<rand>`` id so:
+
+* the agent_runs row always lands with a non-null distinct_id,
+* the RunHandle exposes the same id so callers can bind
+  ``trodo.feedback(distinct_id=...)`` later,
+* older backends without identity-resolution still attribute the row.
+"""
+from __future__ import annotations
+
+import re
+
+from trodo.otel.wrap_agent import _mint_anon_distinct_id, start_run, wrap_agent
+
+
+ANON_RE = re.compile(r"^anon_\d+_python_")
+
+
+def test_mint_anon_distinct_id_shape():
+    a = _mint_anon_distinct_id()
+    assert ANON_RE.match(a)
+
+
+def test_mint_anon_distinct_id_unique_under_load():
+    ids = {_mint_anon_distinct_id() for _ in range(1000)}
+    assert len(ids) == 1000
+
+
+def test_wrap_agent_mints_anon_when_distinct_id_omitted(processor, http):
+    observed = {}
+    with wrap_agent(
+        processor=processor,
+        team_site_id="site-x",
+        agent_name="chat",
+    ) as run:
+        observed["distinct_id"] = run.distinct_id
+        run.set_output("done")
+
+    assert ANON_RE.match(observed["distinct_id"])
+    assert len(http.run_ingest) == 1
+    assert http.run_ingest[0]["run"]["distinct_id"] == observed["distinct_id"]
+
+
+def test_wrap_agent_respects_explicit_distinct_id(processor, http):
+    with wrap_agent(
+        processor=processor,
+        team_site_id="site-x",
+        agent_name="chat",
+        distinct_id="user-42",
+    ) as run:
+        assert run.distinct_id == "user-42"
+
+    assert http.run_ingest[0]["run"]["distinct_id"] == "user-42"
+
+
+def test_wrap_agent_mints_different_anon_ids_across_calls(processor, http):
+    seen = []
+    for _ in range(3):
+        with wrap_agent(
+            processor=processor,
+            team_site_id="site-x",
+            agent_name="chat",
+        ) as run:
+            seen.append(run.distinct_id)
+    assert len(set(seen)) == 3
+
+
+def test_wrap_agent_still_mints_anon_on_error(processor, http):
+    import pytest
+    with pytest.raises(ValueError):
+        with wrap_agent(
+            processor=processor,
+            team_site_id="site-x",
+            agent_name="chat",
+        ) as _run:
+            raise ValueError("boom")
+
+    assert len(http.run_ingest) == 1
+    payload = http.run_ingest[0]["run"]
+    assert payload["status"] == "error"
+    assert ANON_RE.match(payload["distinct_id"])
+
+
+def test_start_run_mints_anon_when_distinct_id_omitted(processor, http):
+    start_run(processor=processor, agent_name="external_session")
+    assert len(http.run_start) == 1
+    run = http.run_start[0]["run"]
+    assert ANON_RE.match(run["distinct_id"])
+
+
+def test_start_run_respects_explicit_distinct_id(processor, http):
+    start_run(
+        processor=processor,
+        agent_name="external_session",
+        distinct_id="user-7",
+    )
+    run = http.run_start[0]["run"]
+    assert run["distinct_id"] == "user-7"

trodo_python-2.9.0/tests/test_error_enrichment.py

@@ -0,0 +1,84 @@
+"""Rich error instrumentation (v2.9.0).
+
+Proves thrown errors surface error TYPE, HTTP/provider STATUS CODE, STACK
+TRACE, and severity LEVEL on both spans and runs — Langfuse parity — instead
+of only a status + message.
+"""
+from __future__ import annotations
+
+import pytest
+
+from trodo.otel.wrap_agent import wrap_agent, span, describe_error
+
+
+class RateLimitError(Exception):
+    """Stand-in for an OpenAI/Anthropic SDK error with an HTTP status + code."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.status = 429
+        self.code = "rate_limit_exceeded"
+
+
+def test_describe_error_extracts_type_status_and_stack():
+    try:
+        raise RateLimitError("rate limit exceeded")
+    except RateLimitError as e:
+        info = describe_error(type(e), e, e.__traceback__)
+    assert info["error_type"] == "RateLimitError"
+    assert info["error_message"] == "rate limit exceeded"
+    assert info["status_code"] == "429"  # HTTP status wins over .code
+    assert info["stack_trace"] and "RateLimitError" in info["stack_trace"]
+    assert info["level"] == "error"
+
+
+def test_describe_error_falls_back_to_response_status():
+    class Resp:
+        status_code = 503
+
+    try:
+        e = RuntimeError("upstream down")
+        e.response = Resp()  # type: ignore[attr-defined]
+        raise e
+    except RuntimeError as ex:
+        info = describe_error(type(ex), ex, ex.__traceback__)
+    assert info["error_type"] == "RuntimeError"
+    assert info["status_code"] == "503"
+
+
+def test_errored_span_and_run_carry_rich_error_fields(processor, http):
+    with pytest.raises(RateLimitError):
+        with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat") as run:
+            run.set_input("query")
+            with span("call-model", kind="llm"):
+                raise RateLimitError("rate limit exceeded")
+
+    ingest = http.run_ingest[0]
+    run_payload = ingest["run"]
+    spans = ingest.get("spans", [])
+    errored = next(s for s in spans if s["status"] == "error")
+
+    assert errored["error_type"] == "RateLimitError"
+    assert errored["error_message"] == "rate limit exceeded"
+    assert errored["status_code"] == "429"
+    assert "RateLimitError" in errored["stack_trace"]
+    assert errored["level"] == "error"
+
+    assert run_payload["status"] == "error"
+    assert run_payload["level"] == "error"
+    assert run_payload["error_type"] == "RateLimitError"
+    assert "rate limit exceeded" in run_payload["error_summary"]
+
+
+def test_healthy_span_omits_error_fields(processor, http):
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        with span("ok-step", kind="generic"):
+            pass
+
+    spans = http.run_ingest[0].get("spans", [])
+    ok = next(s for s in spans if s["name"] == "ok-step")
+    assert ok["status"] == "ok"
+    # to_dict() drops None fields, so error keys must be absent entirely.
+    assert "error_type" not in ok
+    assert "status_code" not in ok
+    assert "stack_trace" not in ok

trodo_python-2.9.0/tests/test_llm_usage_cost.py

@@ -0,0 +1,115 @@
+"""LLM usage + cost wire payloads (v2.8.0).
+
+Verifies every way a caller can report cost/tokens reaches the backend in the
+expected snake_case shape:
+  - explicit ``cost`` (highest priority)
+  - open ``usage_details`` map + ``cache_read_tokens``/``cache_write_tokens``
+  - raw provider ``usage`` object auto-extracted into usage_details
+  - ``cost_details`` per-category breakdown
+  - ``llm()`` helper auto-forwarding the full provider usage map (incl. cache)
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from trodo.otel.helpers import _default_usage_map, llm, track_llm_call
+from trodo.otel.wrap_agent import wrap_agent
+
+
+def _llm_spans(http) -> List[Dict[str, Any]]:
+    spans = http.run_ingest[0].get("spans", []) if http.run_ingest else []
+    return [s for s in spans if s.get("kind") == "llm"]
+
+
+def test_default_usage_map_flattens_openai_details():
+    out = _default_usage_map(
+        {"usage": {"prompt_tokens": 1000, "completion_tokens": 200,
+                   "prompt_tokens_details": {"cached_tokens": 300}}}
+    )
+    assert out == {"prompt_tokens": 1000, "completion_tokens": 200, "cached_tokens": 300}
+
+
+def test_default_usage_map_anthropic_cache_fields():
+    out = _default_usage_map(
+        {"usage": {"input_tokens": 50, "output_tokens": 25,
+                   "cache_read_input_tokens": 10, "cache_creation_input_tokens": 5}}
+    )
+    assert out == {
+        "input_tokens": 50, "output_tokens": 25,
+        "cache_read_input_tokens": 10, "cache_creation_input_tokens": 5,
+    }
+
+
+def test_default_usage_map_bare_usage_object():
+    out = _default_usage_map({"prompt_tokens": 12, "completion_tokens": 4})
+    assert out == {"prompt_tokens": 12, "completion_tokens": 4}
+
+
+def test_track_llm_call_explicit_cost_wins(processor, http):
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        track_llm_call(model="gpt-4o", provider="openai",
+                       input_tokens=100, output_tokens=50, cost=0.42)
+    span = _llm_spans(http)[0]
+    assert span["cost"] == 0.42
+    assert span["input_tokens"] == 100
+
+
+def test_track_llm_call_usage_details_and_cache_shorthands(processor, http):
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        track_llm_call(model="claude-sonnet-4", provider="anthropic",
+                       usage_details={"input": 1000, "output": 500},
+                       cache_read_tokens=200, cache_write_tokens=80)
+    span = _llm_spans(http)[0]
+    assert span["usage_details"] == {
+        "input": 1000, "output": 500, "cache_read": 200, "cache_write": 80,
+    }
+
+
+def test_track_llm_call_raw_usage_auto_extract(processor, http):
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        track_llm_call(
+            model="gpt-4o", provider="openai",
+            usage={"prompt_tokens": 800, "completion_tokens": 400,
+                   "prompt_tokens_details": {"cached_tokens": 100}},
+        )
+    span = _llm_spans(http)[0]
+    assert span["usage_details"] == {
+        "prompt_tokens": 800, "completion_tokens": 400, "cached_tokens": 100,
+    }
+
+
+def test_track_llm_call_cost_details(processor, http):
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        track_llm_call(model="gpt-4o", provider="openai", input_tokens=100,
+                       output_tokens=50, cost_details={"input": 0.0003, "output": 0.0005})
+    span = _llm_spans(http)[0]
+    assert span["cost_details"] == {"input": 0.0003, "output": 0.0005}
+
+
+def test_llm_helper_auto_forwards_usage_map(processor, http):
+    def call_model(*_a, **_k):
+        return {"text": "hi", "usage": {
+            "input_tokens": 1000, "output_tokens": 200, "cache_read_input_tokens": 300}}
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        wrapped = llm("answer", call_model, model="claude-sonnet-4", provider="anthropic")
+        wrapped()
+    span = _llm_spans(http)[0]
+    assert span["usage_details"] == {
+        "input_tokens": 1000, "output_tokens": 200, "cache_read_input_tokens": 300,
+    }
+    assert span["model"] == "claude-sonnet-4"
+
+
+def test_llm_helper_custom_scalar_extractor_backcompat(processor, http):
+    def call_model(*_a, **_k):
+        return {"weird": {"in": 7, "out": 3}}
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        wrapped = llm("answer", call_model, model="x", provider="y",
+                      extract_usage=lambda r: (r["weird"]["in"], r["weird"]["out"]))
+        wrapped()
+    span = _llm_spans(http)[0]
+    assert span["input_tokens"] == 7
+    assert span["output_tokens"] == 3
+    assert "usage_details" not in span

{trodo_python-2.7.0 → trodo_python-2.9.0}/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_python-2.7.0 → trodo_python-2.9.0}/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_python-2.7.0 → trodo_python-2.9.0}/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_python-2.7.0 → trodo_python-2.9.0}/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_python-2.7.0 → trodo_python-2.9.0}/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 → trodo_python-2.9.0}/trodo_python.egg-info/PKG-INFO

@@ -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 → trodo_python-2.9.0}/trodo_python.egg-info/SOURCES.txt

@@ -1,9 +1,12 @@
 README.md
 pyproject.toml
+tests/test_anon_distinct_id 2.py
 tests/test_anon_distinct_id.py
 tests/test_auto_instrument_fixes.py
 tests/test_cross_process_session.py
 tests/test_end_run.py
+tests/test_error_enrichment.py
+tests/test_llm_usage_cost.py
 tests/test_processor_methods.py
 tests/test_register_otel.py
 tests/test_start_run.py