trodo-python 2.6.0__tar.gz → 2.8.0__tar.gz

{trodo_python-2.6.0 → trodo_python-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.6.0
+Version: 2.8.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.6.0 → trodo_python-2.8.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.6.0 → trodo_python-2.8.0}/pyproject.toml

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

trodo_python-2.8.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.6.0 → trodo_python-2.8.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.4.0"
+__version__ = "2.8.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 

{trodo_python-2.6.0 → trodo_python-2.8.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
@@ -387,6 +442,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 +457,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 +496,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.6.0 → trodo_python-2.8.0}/trodo/otel/processor.py

@@ -59,6 +59,14 @@ class TrodoSpan:
     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.6.0 → trodo_python-2.8.0}/trodo/otel/wrap_agent.py

@@ -197,6 +197,11 @@ 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
 
@@ -217,6 +222,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 +240,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
@@ -575,6 +606,8 @@ class join_run:
             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,
@@ -665,6 +698,8 @@ class span:
             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.6.0 → trodo_python-2.8.0}/trodo/session/server_session.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import time
-import uuid
 from datetime import datetime, timezone
 from typing import Any, Dict, Optional
 
@@ -14,13 +13,24 @@ def now_iso() -> str:
     return datetime.now(timezone.utc).isoformat()
 
 
+def server_session_id(distinct_id: str) -> str:
+    """Deterministic, "backend consistent" session id for a backend user.
+
+    Backend SDKs are stateless: the same distinct_id must resolve to the SAME
+    session across processes and restarts. Using ``server:{distinct_id}`` instead
+    of a per-process ``uuid4()`` produces exactly one session row per backend
+    user (no per-process bloat) and is idempotent server-side.
+    """
+    return f"server:{distinct_id}"
+
+
 def create_server_session(
     site_id: str,
     distinct_id: str,
     session_id: Optional[str] = None,
 ) -> ServerSession:
     return ServerSession(
-        session_id=session_id or str(uuid.uuid4()),
+        session_id=session_id or server_session_id(distinct_id),
         site_id=site_id,
         distinct_id=distinct_id,
         start_time=now_iso(),
@@ -30,6 +40,15 @@ def create_server_session(
 
 
 def build_session_payload(session: ServerSession) -> Dict[str, Any]:
+    """Minimal server-session payload.
+
+    Backend SDKs cannot know browser-only signals (geo, device, browser, UTM,
+    referrer, wallet), so those fields are OMITTED rather than sent as ~30
+    explicit nulls — ingestion defaults missing fields to null. This saves
+    ingestion bandwidth and is more accurate. Only the markers ingestion keys
+    on are retained: ``is_server_session`` (drives identity-level browser-field
+    guards) and ``device_type='server'`` (server-origin fallback detector).
+    """
     return {
         "session_id": session.session_id,
         "site_id": session.site_id,
@@ -37,39 +56,9 @@ def build_session_payload(session: ServerSession) -> Dict[str, Any]:
         "distinct_id": session.distinct_id,
         "team_id": None,
         "start_time": session.start_time,
-        "end_time": None,
         "last_activity": int(session.last_activity * 1000),
-        "duration": 0,
-        "pages_viewed": 0,
         "is_bounce": False,
-        "previous_session_id": None,
-        "time_since_last_session": None,
-        "entry_page": None,
-        "exit_page": None,
         "referrer": "server",
-        "ip_address": None,
-        "city": None,
-        "region": None,
-        "country": None,
-        "browser_name": None,
-        "browser_version": None,
         "device_type": "server",
-        "os": None,
-        "resolution": None,
-        "user_agent": None,
-        "language": None,
-        "wallet_address": None,
-        "wallet_type": None,
-        "chain_name": None,
-        "is_web3_user": False,
-        "wallet_connected": False,
-        "utm_source": None,
-        "utm_medium": None,
-        "utm_campaign": None,
-        "utm_term": None,
-        "utm_content": None,
-        "utm_id": None,
-        "visited_pages": [],
-        "active_time_ms": 0,
         "is_server_session": True,
     }

{trodo_python-2.6.0 → trodo_python-2.8.0}/trodo_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.6.0
+Version: 2.8.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.6.0 → trodo_python-2.8.0}/trodo_python.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ 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_llm_usage_cost.py
 tests/test_processor_methods.py
 tests/test_register_otel.py
 tests/test_start_run.py