otelzero 0.2.0__py3-none-any.whl

otelzero/hooks/_native.py

@@ -0,0 +1,517 @@
+"""Shared plumbing for frameworks whose *own* OpenTelemetry otelzero switches on.
+
+Some frameworks already trace themselves in the GenAI semantic conventions:
+an ``invoke_agent {name}`` span per run, with ``chat`` / ``execute_tool`` (and
+framework-specific) spans nested under it. For those, wrapping a method from
+the outside sees less than the framework records, so their hooks wrap nothing.
+Each one configures the framework's native instrumentation and attaches one
+:class:`NativeRunProcessor` to the tracer provider the spans go through.
+The processor does two things:
+
+* **Identity.** It stamps otelzero's run identity (``gen_ai.conversation.id``,
+  ``user.name`` and ``otelzero.session.name``) on every span the framework
+  starts, and on any other instrumentation's span nested inside one of them
+  (an HTTP client's span under a model call, say). That way a trace can be
+  filtered by session the same way the wrapping hooks' spans can.
+* **Events.** It turns each native ``invoke_agent`` span into the
+  ``agent_start`` / ``agent_end`` / ``agent_error`` HTTP events the wrapping
+  hooks send, so the dashboard's event feed doesn't change.
+
+Frameworks fill in a span at different points. Pydantic AI passes its
+attributes when it starts a span. Strands, Agent Framework and ADK start an
+empty span and set the attributes afterwards, so ``on_start`` sees only the
+span's name. Because of that, a run is recognised by its ``invoke_agent``
+operation *or* its ``invoke_agent {name}`` span name. ``agent_start`` carries
+what is known at that point. ``agent_end`` carries what the run recorded by the
+time it finished: the model, the tools offered, and token usage, taken from the
+run span itself or, where the framework records them only on its model-call
+spans, from those spans.
+
+Each framework gets one processor per provider (a provider cannot drop a
+processor). A reinstall retargets the processor at the new client, and an
+uninstall makes it dormant. Processors are scoped by instrumentation-scope
+name, so two native frameworks in one process don't report each other's runs.
+"""
+
+import json
+import re
+import threading
+from typing import Any, Dict, Iterable, Optional, Tuple
+
+from otelzero import otel, semconv
+from otelzero.telemetry import TelemetryClient
+
+try:
+    from opentelemetry.sdk.trace import SpanProcessor as _SpanProcessor
+except ImportError:  # pragma: no cover - 'otel' extra absent; install raises
+    _SpanProcessor = object  # type: ignore[assignment,misc]
+
+# Model-call operations whose spans may carry the model, tools and usage when
+# the agent span itself does not (ADK records them only there).
+_MODEL_CALL_OPERATIONS = frozenset(
+    {semconv.OP_CHAT, semconv.OP_TEXT_COMPLETION, semconv.OP_GENERATE_CONTENT}
+)
+
+# Where frameworks put the model on a span: the convention's attribute, then
+# Pydantic AI's own ``model_name`` (set on its agent span at start).
+_MODEL_KEYS = (semconv.GEN_AI_REQUEST_MODEL, semconv.GEN_AI_RESPONSE_MODEL, "model_name")
+
+# Token usage: Pydantic AI's per-run totals live under its own
+# ``gen_ai.aggregated_usage.*`` namespace; everyone else uses ``gen_ai.usage.*``.
+_USAGE_PREFIXES = ("gen_ai.aggregated_usage.", "gen_ai.usage.")
+_USAGE_KEYS = {
+    "input_tokens": "input_tokens",
+    "output_tokens": "output_tokens",
+    "reasoning_tokens": "reasoning.output_tokens",
+    "cache_read_tokens": "cache_read.input_tokens",
+}
+
+# Strands lists the agent's tool *names* here (a JSON array) on every agent
+# span, whereas ``gen_ai.tool.definitions`` is opt-in there.
+_AGENT_TOOLS = "gen_ai.agent.tools"
+
+_SPAN_NAME = re.compile(r"^invoke_agent(?:\s+(?P<name>.+))?$")
+
+
+def marker(framework: str) -> str:
+    """The provider attribute holding *framework*'s processor."""
+    return "_otelzero_native_" + re.sub(r"\W+", "_", framework.lower()).strip("_")
+
+
+def usage_from(attributes: Any) -> Optional[dict]:
+    """otelzero's normalized usage dict from a span's attributes, or ``None``.
+
+    Same per-field shape :mod:`otelzero.hooks._usage` produces for the
+    wrapping hooks.
+    """
+    for prefix in _USAGE_PREFIXES:
+        usage = {key: attributes.get(prefix + attr) for key, attr in _USAGE_KEYS.items()}
+        if usage["input_tokens"] is None and usage["output_tokens"] is None:
+            continue
+        usage["input_tokens"] = usage["input_tokens"] or 0
+        usage["output_tokens"] = usage["output_tokens"] or 0
+        usage["total_tokens"] = usage["input_tokens"] + usage["output_tokens"]
+        return usage
+    return None
+
+
+def _add_usage(total: Optional[dict], more: Optional[dict]) -> Optional[dict]:
+    if more is None:
+        return total
+    if total is None:
+        return dict(more)
+    for key, value in more.items():
+        if value is not None:
+            total[key] = (total.get(key) or 0) + value
+    return total
+
+
+def tool_names(attributes: Any) -> list:
+    """Tool names a span says the agent was offered.
+
+    Read from ``gen_ai.tool.definitions`` (a JSON array of definitions) and
+    from Strands' ``gen_ai.agent.tools`` (a JSON array of names).
+    """
+    names = []
+    for key in (semconv.GEN_AI_TOOL_DEFINITIONS, _AGENT_TOOLS):
+        raw = attributes.get(key)
+        if not raw:
+            continue
+        try:
+            entries = json.loads(raw) if isinstance(raw, str) else list(raw)
+        except (TypeError, ValueError):
+            continue
+        if not isinstance(entries, list):
+            continue
+        for entry in entries:
+            if isinstance(entry, str) and entry:
+                names.append(entry)
+            elif isinstance(entry, dict) and entry.get("name"):
+                names.append(entry["name"])
+    return names
+
+
+def model_from(attributes: Any) -> Optional[str]:
+    for key in _MODEL_KEYS:
+        value = attributes.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return None
+
+
+def exception_of(span: Any) -> Tuple[str, Optional[str]]:
+    """``(message, traceback)`` from the span's last ``exception`` event.
+
+    A framework that records only the exception type (Pydantic AI or Agent
+    Framework without content capture) gets the type as the message.
+    """
+    for event in reversed(span.events or ()):
+        if event.name == "exception":
+            attrs = event.attributes or {}
+            message = attrs.get("exception.message") or attrs.get("exception.type")
+            return message, attrs.get("exception.stacktrace")
+    # Agent Framework records neither the event nor a description without
+    # sensitive data enabled, only the convention's ``error.type``.
+    description = getattr(span.status, "description", None)
+    error_type = (span.attributes or {}).get(semconv.ERROR_TYPE)
+    return description or error_type or "Agent run failed", None
+
+
+def _run_agent_name(span: Any, attributes: Any) -> Optional[str]:
+    """The agent's name when *span* is an agent run, else ``None``.
+
+    A span counts as a run if its ``gen_ai.operation.name`` says
+    ``invoke_agent``, or (for frameworks that set attributes only after the
+    span starts) if its name is ``invoke_agent`` / ``invoke_agent {agent}``.
+    The name then comes from ``gen_ai.agent.name`` or, failing that, from the
+    span name. An empty string means it's a run but has no name.
+    """
+    operation = attributes.get(semconv.GEN_AI_OPERATION_NAME)
+    match = _SPAN_NAME.match(span.name or "")
+    if operation is not None and operation != semconv.OP_INVOKE_AGENT:
+        return None
+    if operation is None and match is None:
+        return None
+    return attributes.get(semconv.GEN_AI_AGENT_NAME) or (
+        match.group("name") if match and match.group("name") else ""
+    )
+
+
+class NativeRunProcessor(_SpanProcessor):
+    """Run identity on native spans; lifecycle events from ``invoke_agent``.
+
+    Args:
+        telemetry: The client events go out on (``None`` = dormant).
+        framework: Label for log messages.
+        scopes: Instrumentation-scope name prefixes this framework's spans
+            use. Spans from other scopes are only touched when they are
+            nested inside one of this framework's spans.
+        default_agent_name: Name for a run whose span names no agent.
+        send_events: Derive ``agent_*`` events from ``invoke_agent`` spans.
+            Off for LangSmith, whose spans arrive in batches after the fact;
+            its hook sends the events from LangChain's callbacks instead.
+        native_conversation_id: Keep the framework's own
+            ``gen_ai.conversation.id`` instead of replacing it with otelzero's
+            session, and file the run's events under it too. Use this for a
+            framework whose conversation id is a real, caller-chosen session
+            (ADK) and which writes that id after a span starts, past the point
+            where the processor could replace it.
+    """
+
+    def __init__(
+        self,
+        telemetry: Optional[TelemetryClient],
+        *,
+        framework: str,
+        scopes: Iterable[str],
+        default_agent_name: str,
+        native_conversation_id: bool = False,
+        send_events: bool = True,
+    ):
+        self.telemetry = telemetry
+        self.send_events = send_events
+        self.framework = framework
+        self.scopes = tuple(scopes)
+        self.default_agent_name = default_agent_name
+        self.native_conversation_id = native_conversation_id
+        # span id -> id of the run span it belongs to (None: one of ours, but
+        # not inside a run -- an ADK workflow span, say).
+        self._owner: Dict[int, Optional[int]] = {}
+        # run span id -> what the run's spans revealed so far.
+        self._runs: Dict[int, dict] = {}
+        # trace id -> the framework's own conversation id, when adopted, and
+        # how many of the trace's tracked spans are still open (the entry goes
+        # when the last one ends, whatever span the trace's root is).
+        self._conversations: Dict[int, str] = {}
+        self._open_in_trace: Dict[int, int] = {}
+        self._lock = threading.Lock()
+
+    # -- helpers ------------------------------------------------------------
+
+    def _is_ours(self, span: Any) -> bool:
+        scope = getattr(span, "instrumentation_scope", None)
+        name = getattr(scope, "name", None) or ""
+        return any(name.startswith(prefix) for prefix in self.scopes)
+
+    def _send(self, telemetry: TelemetryClient, run: dict, **fields: Any) -> None:
+        if run.get("conversation_id"):
+            fields["session"] = run["conversation_id"]
+        telemetry.send_log(**fields)
+
+    # -- SpanProcessor ------------------------------------------------------
+
+    def on_start(self, span: Any, parent_context: Any = None) -> None:
+        telemetry = self.telemetry
+        if telemetry is None:
+            return
+        span_id = span.context.span_id
+        parent_id = span.parent.span_id if span.parent else None
+        with self._lock:
+            inherited = parent_id in self._owner
+            parent_run = self._owner.get(parent_id) if inherited else None
+        ours = self._is_ours(span)
+        if not (inherited or ours):
+            return
+
+        attributes = span.attributes or {}
+        trace_id = span.context.trace_id
+        native_conversation = None
+        if self.native_conversation_id:
+            native_conversation = attributes.get(semconv.GEN_AI_CONVERSATION_ID)
+            with self._lock:
+                if native_conversation:
+                    self._conversations.setdefault(trace_id, native_conversation)
+                native_conversation = self._conversations.get(trace_id)
+
+        user, session, session_name = telemetry.run_identity()
+        if self.native_conversation_id:
+            # Spans the framework leaves without one (ADK's execute_tool) get
+            # the trace's id, so every span still filters by session.
+            if native_conversation and not attributes.get(semconv.GEN_AI_CONVERSATION_ID):
+                span.set_attribute(semconv.GEN_AI_CONVERSATION_ID, native_conversation)
+        elif session:
+            span.set_attribute(semconv.GEN_AI_CONVERSATION_ID, session)
+        if session_name:
+            span.set_attribute(semconv.OTELZERO_SESSION_NAME, session_name)
+        if user:
+            span.set_attribute(semconv.USER_NAME, user)
+
+        with self._lock:
+            self._open_in_trace[trace_id] = self._open_in_trace.get(trace_id, 0) + 1
+        agent_name = _run_agent_name(span, attributes) if ours and self.send_events else None
+        if agent_name is None:
+            with self._lock:
+                self._owner[span_id] = parent_run
+            return
+
+        agent_name = agent_name or self.default_agent_name
+        model = model_from(attributes)
+        run = {
+            "agent_name": agent_name,
+            "model": model,
+            "tools": set(tool_names(attributes)),
+            "child_model": None,
+            "child_usage": None,
+            "conversation_id": native_conversation,
+        }
+        with self._lock:
+            self._owner[span_id] = span_id
+            self._runs[span_id] = run
+        self._send(
+            telemetry,
+            run,
+            event_type="agent_start",
+            agent_name=agent_name,
+            agent_role=agent_name,
+            model=model,
+            details={"model": model},
+        )
+
+    def on_end(self, span: Any) -> None:
+        span_id = span.context.span_id
+        with self._lock:
+            if span_id not in self._owner:
+                return
+            owner = self._owner.pop(span_id)
+            run = self._runs.pop(span_id, None) if owner == span_id else None
+            trace_id = span.context.trace_id
+            remaining = self._open_in_trace.get(trace_id, 1) - 1
+            if remaining > 0:
+                self._open_in_trace[trace_id] = remaining
+            else:
+                self._open_in_trace.pop(trace_id, None)
+                self._conversations.pop(trace_id, None)
+        attributes = span.attributes or {}
+
+        if run is None:
+            # A span inside a run: harvest what the agent span may not carry.
+            if owner is None:
+                return
+            if attributes.get(semconv.GEN_AI_OPERATION_NAME) not in _MODEL_CALL_OPERATIONS:
+                return
+            with self._lock:
+                parent_run = self._runs.get(owner)
+                if parent_run is None:
+                    return
+                parent_run["tools"].update(tool_names(attributes))
+                parent_run["child_model"] = parent_run["child_model"] or model_from(attributes)
+                parent_run["child_usage"] = _add_usage(
+                    parent_run["child_usage"], usage_from(attributes)
+                )
+            return
+
+        telemetry = self.telemetry
+        if telemetry is None:
+            return
+        run["tools"].update(tool_names(attributes))
+        model = model_from(attributes) or run["child_model"] or run["model"]
+        usage = usage_from(attributes) or run["child_usage"]
+        fields = {
+            "agent_name": run["agent_name"],
+            "agent_role": run["agent_name"],
+            "model": model,
+        }
+        if not span.status.is_ok:
+            error, traceback = exception_of(span)
+            self._send(
+                telemetry,
+                run,
+                event_type="agent_error",
+                error=error,
+                traceback=traceback,
+                details={"usage": usage} if usage else None,
+                **fields,
+            )
+            return
+        details: dict = {"status": "success"}
+        if run["tools"]:
+            details["tools"] = sorted(run["tools"])
+        if usage:
+            details["usage"] = usage
+        self._send(telemetry, run, event_type="agent_end", details=details, **fields)
+
+
+def attach_processor(
+    provider: Any,
+    telemetry: TelemetryClient,
+    *,
+    framework: str,
+    scopes: Iterable[str],
+    default_agent_name: str,
+    native_conversation_id: bool = False,
+    send_events: bool = True,
+    key: Optional[str] = None,
+) -> NativeRunProcessor:
+    """Attach (or retarget) *framework*'s processor on *provider*.
+
+    *key* names the processor slot when several install functions share one
+    processor (LangChain and LangGraph both report LangSmith's spans).
+    """
+    key = marker(key or framework)
+    existing = getattr(provider, key, None)
+    if existing is not None:
+        existing.telemetry = telemetry
+        existing.framework = framework
+        return existing
+    processor = NativeRunProcessor(
+        telemetry,
+        framework=framework,
+        scopes=scopes,
+        default_agent_name=default_agent_name,
+        native_conversation_id=native_conversation_id,
+        send_events=send_events,
+    )
+    provider.add_span_processor(processor)
+    setattr(provider, key, processor)
+    return processor
+
+
+def start_tracing(framework: str, telemetry: TelemetryClient, server_url: str) -> Any:
+    """Force otelzero's OTLP provider on; raise if the SDK is missing.
+
+    Native instrumentation is the only channel these hooks report through, so
+    ``OTELZERO_OTEL=0`` cannot switch them off.
+    """
+    provider = otel.init_tracing(
+        server_url,
+        service_name=framework,
+        service_version=telemetry.framework_version,
+        api_key=telemetry.api_key,
+        force=True,
+    )
+    if provider is None:
+        raise RuntimeError(
+            f"{framework} monitoring reports only over OpenTelemetry; install the "
+            "'otel' extra: uv pip install 'otelzero[otel]'"
+        )
+    return provider
+
+
+def global_provider(provider: Any, framework: str) -> Any:
+    """The provider a framework that traces through the *global* one will use.
+
+    Normally that's otelzero's own provider. If the application installed its
+    own SDK provider first, OpenTelemetry keeps that one global, the
+    framework's spans go there, and the processor has to be attached there to
+    see them. The spans then export to the application's exporters, not to the
+    registry. The events still reach it, which a warning points out.
+    """
+    from opentelemetry import trace
+
+    current = trace.get_tracer_provider()
+    if current is provider or not hasattr(current, "add_span_processor"):
+        return provider
+    print(
+        f"[MONITOR] {framework}: a global OpenTelemetry tracer provider was "
+        "already configured, so the framework's spans export through it rather "
+        "than to the registry; otelzero's agent events are unaffected."
+    )
+    return current
+
+
+def detach(framework: str, provider: Any) -> None:
+    """Make *framework*'s processor on *provider* dormant (no-op if absent)."""
+    processor = getattr(provider, marker(framework), None) if provider else None
+    if processor is not None:
+        processor.telemetry = None
+
+
+_OPT_IN_ENV = "OTEL_SEMCONV_STABILITY_OPT_IN"
+
+# token -> frameworks currently relying on it. Tokens the user had set before
+# any hook added them are never in here, so they are never removed.
+_opt_in_users: Dict[str, set] = {}
+
+
+def _read_opt_in() -> list:
+    import os
+
+    return [t.strip() for t in os.environ.get(_OPT_IN_ENV, "").split(",") if t.strip()]
+
+
+def _write_opt_in(tokens: list) -> None:
+    import os
+
+    if tokens:
+        os.environ[_OPT_IN_ENV] = ",".join(tokens)
+    else:
+        os.environ.pop(_OPT_IN_ENV, None)
+
+
+def opt_in_tokens(
+    framework: str, tokens: Iterable[str], *, skip_prefixes: Iterable[str] = ()
+) -> None:
+    """Add *tokens* to ``OTEL_SEMCONV_STABILITY_OPT_IN`` on *framework*'s behalf.
+
+    Tokens already present stay as they are. A token is also skipped when the
+    variable already holds an entry starting with one of *skip_prefixes*, so a
+    choice the user made explicitly is kept. Each added token is
+    reference-counted per framework, so :func:`release_opt_in` removes only what
+    no installed hook still needs, and never a token the user set.
+    """
+    current = _read_opt_in()
+    skip = tuple(skip_prefixes)
+    for token in tokens:
+        users = _opt_in_users.get(token)
+        if users is not None:
+            users.add(framework)
+            continue
+        if token in current:
+            continue  # the user's own token
+        if any(t.startswith(p) for t in current for p in skip if token.startswith(p)):
+            continue
+        current.append(token)
+        _opt_in_users[token] = {framework}
+    _write_opt_in(current)
+
+
+def release_opt_in(framework: str) -> None:
+    """Drop *framework*'s claim on the tokens it added; remove the orphans."""
+    current = _read_opt_in()
+    for token, users in list(_opt_in_users.items()):
+        users.discard(framework)
+        if not users:
+            del _opt_in_users[token]
+            if token in current:
+                current.remove(token)
+    _write_opt_in(current)

otelzero/hooks/_usage.py

@@ -0,0 +1,166 @@
+"""Normalized LLM token-usage extraction shared by all framework hooks.
+
+Every framework reports token usage under its own spelling (Anthropic's
+``input_tokens``, OpenAI's ``prompt_tokens``, Gemini's ``prompt_token_count``,
+Bedrock's ``inputTokens``, ...). :func:`extract_usage` folds any of them into
+one normalized dict that the hooks attach to their terminal telemetry events::
+
+    {
+        "input_tokens": int,            # 0 if only output known
+        "output_tokens": int,
+        "total_tokens": int,            # reported total, else input + output
+        "reasoning_tokens": int | None, # None when the provider doesn't report
+        "cache_read_tokens": int | None,
+    }
+
+All reads are dict-or-attr based and coercion-tolerant, so a framework version
+drift degrades to "no usage" — never a crash in the wrapper.
+"""
+
+from typing import Any, Optional
+
+
+def _field(obj: Any, key: str) -> Any:
+    """Read ``key`` off a dict or an object attribute; ``None`` when absent."""
+    if isinstance(obj, dict):
+        return obj.get(key)
+    return getattr(obj, key, None)
+
+
+def _int(value: Any) -> Optional[int]:
+    """Coerce to int, tolerating floats/strings; ``None`` on bools or junk."""
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _first(obj: Any, *keys: str) -> Optional[int]:
+    """First key of ``keys`` that reads as an int off ``obj``."""
+    for key in keys:
+        val = _int(_field(obj, key))
+        if val is not None:
+            return val
+    return None
+
+
+def _nested(obj: Any, outer_keys, inner_keys) -> Optional[int]:
+    """First ``outer.inner`` int found across the given key spellings."""
+    for outer in outer_keys:
+        detail = _field(obj, outer)
+        if detail is not None:
+            val = _first(detail, *inner_keys)
+            if val is not None:
+                return val
+    return None
+
+
+# Alias tables covering every framework this repo instruments:
+#   Anthropic / Claude SDK: input_tokens / output_tokens / cache_read_input_tokens
+#   OpenAI chat: prompt_tokens / completion_tokens
+#       (+ completion_tokens_details.reasoning_tokens, prompt_tokens_details.cached_tokens)
+#   OpenAI Responses / MLflow ResponsesAgent: input_tokens / output_tokens
+#       (+ output_tokens_details.reasoning_tokens, input_tokens_details.cached_tokens)
+#   Google GenAI / ADK: prompt_token_count / candidates_token_count /
+#       thoughts_token_count / cached_content_token_count / total_token_count
+#   Microsoft agent_framework: input_token_count / output_token_count / total_token_count
+#   Bedrock / Strands: inputTokens / outputTokens / totalTokens / cacheReadInputTokens
+#   LangChain / LangGraph usage_metadata: input_tokens / output_tokens /
+#       total_tokens (+ output_token_details.reasoning, input_token_details.cache_read)
+#   CrewAI UsageMetrics: prompt_tokens / completion_tokens / cached_prompt_tokens
+#   OpenAI Agents SDK Usage: input_tokens / output_tokens / total_tokens
+#   Pydantic AI RunUsage: input_tokens / output_tokens / cache_read_tokens
+#   smolagents TokenUsage: input_tokens / output_tokens / total_tokens
+_INPUT = (
+    "input_tokens",
+    "prompt_tokens",
+    "prompt_token_count",
+    "input_token_count",
+    "inputTokens",
+)
+_OUTPUT = (
+    "output_tokens",
+    "completion_tokens",
+    "candidates_token_count",
+    "output_token_count",
+    "outputTokens",
+)
+_TOTAL = ("total_tokens", "total_token_count", "totalTokens")
+_REASONING_FLAT = ("thoughts_token_count", "reasoning_tokens")
+_REASONING_NESTED = (
+    ("output_token_details", "output_tokens_details", "completion_tokens_details"),
+    ("reasoning", "reasoning_tokens"),
+)
+_CACHE_FLAT = (
+    "cache_read_input_tokens",
+    "cached_prompt_tokens",
+    "cached_content_token_count",
+    "cacheReadInputTokens",
+    # Pydantic AI's RunUsage spelling. It is also the key this module's own
+    # output uses, which makes extract_usage idempotent on a normalized dict.
+    "cache_read_tokens",
+)
+_CACHE_NESTED = (
+    ("input_token_details", "input_tokens_details", "prompt_tokens_details"),
+    ("cache_read", "cached_tokens"),
+)
+
+
+def extract_usage(raw: Any) -> Optional[dict]:
+    """Normalize a framework usage object/dict; ``None`` when unrecognizable."""
+    if raw is None:
+        return None
+    input_t = _first(raw, *_INPUT)
+    output_t = _first(raw, *_OUTPUT)
+    if input_t is None and output_t is None:
+        return None
+    reasoning = _first(raw, *_REASONING_FLAT)
+    if reasoning is None:
+        reasoning = _nested(raw, *_REASONING_NESTED)
+    cache_read = _first(raw, *_CACHE_FLAT)
+    if cache_read is None:
+        cache_read = _nested(raw, *_CACHE_NESTED)
+    input_t, output_t = input_t or 0, output_t or 0
+    total = _first(raw, *_TOTAL)
+    return {
+        "input_tokens": input_t,
+        "output_tokens": output_t,
+        "total_tokens": total if total is not None else input_t + output_t,
+        "reasoning_tokens": reasoning,
+        "cache_read_tokens": cache_read,
+    }
+
+
+class UsageAccumulator:
+    """Sum normalized usage across streamed messages/events.
+
+    Each streamed event's usage is treated as per-LLM-call and summed; if a
+    framework ever repeats one call's usage across partial events the sum
+    overcounts (accepted v1 tradeoff). ``result()`` is ``None`` until at least
+    one recognizable usage was added, so hooks never report fabricated zeros.
+    """
+
+    def __init__(self):
+        self._seen = False
+        self._totals = {
+            "input_tokens": 0,
+            "output_tokens": 0,
+            "total_tokens": 0,
+            "reasoning_tokens": None,
+            "cache_read_tokens": None,
+        }
+
+    def add(self, usage: Optional[dict]) -> None:
+        if not usage:
+            return
+        self._seen = True
+        for key in ("input_tokens", "output_tokens", "total_tokens"):
+            self._totals[key] += usage.get(key) or 0
+        for key in ("reasoning_tokens", "cache_read_tokens"):
+            if usage.get(key) is not None:
+                self._totals[key] = (self._totals[key] or 0) + usage[key]
+
+    def result(self) -> Optional[dict]:
+        return dict(self._totals) if self._seen else None