trodo-python 2.24.0__py3-none-any.whl → 2.25.0__py3-none-any.whl

trodo/__init__.py

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

trodo/_version.py

@@ -1 +1 @@
-SDK_VERSION = "2.24.0"
+SDK_VERSION = "2.25.0"

trodo/otel/auto_instrument.py

@@ -14,7 +14,11 @@ from datetime import datetime, timezone
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
 from .context import get_active_context
-from .prompt_trace import prompt_attributes
+from .prompt_trace import (
+    prompt_attributes,
+    prompt_ref_from_fingerprint,
+    remember_prompt,
+)
 from .processor import TrodoSpan, TrodoSpanProcessor
 
 # Always-on, one-shot warnings. Silent skips (missing opentelemetry-sdk) are the
@@ -313,7 +317,7 @@ def otel_span_to_trodo_span(otel_span: Any) -> Optional[TrodoSpan]:
     if temperature is None:
         temperature = attrs.get("ai.settings.temperature")
 
-    return TrodoSpan(
+    trodo_span = TrodoSpan(
         span_id=span_id,
         run_id=run_id,
         parent_span_id=parent_span_id,
@@ -338,6 +342,26 @@ def otel_span_to_trodo_span(otel_span: Any) -> Optional[TrodoSpan]:
         output=completion,
         attributes=attrs or None,
     )
+    # Exact-match prompt link for auto-instrumented model calls. compile()
+    # before the run leaves no run context and no carrier on this serialised
+    # input, so compare the input's content fingerprint with what compile()
+    # registered. Overrides the on_start "most recent in this run" guess, which
+    # an exact match is strictly better than. No match changes nothing.
+    if kind == "llm" and prompt:
+        ref = prompt_ref_from_fingerprint(prompt)
+        if ref:
+            trodo_span.attributes = {**(trodo_span.attributes or {}), **prompt_attributes(ref)}
+            state = _span_prompt_state.pop(id(otel_span), None)
+            if state is None and ctx is not None:
+                state = getattr(ctx, "prompt_state", None)
+            remember_prompt(state, ref)
+    return trodo_span
+
+
+# Run prompt state captured at on_start (contextvars are often gone by on_end),
+# keyed by id(span) and bounded so spans that never end cannot leak.
+_SPAN_STATE_MAX = 1024
+_span_prompt_state: "Dict[int, Any]" = {}
 
 
 # Subclass the REAL SpanProcessor when the sdk is importable (it always is on
@@ -385,11 +409,16 @@ class _OtelAdapter(_SpanProcessorBase):  # type: ignore[valid-type,misc]
                 current = state.get("current") if isinstance(state, dict) else None
                 for k, v in prompt_attributes(current).items():
                     set_attr(k, v)
+                if isinstance(state, dict):
+                    if len(_span_prompt_state) >= _SPAN_STATE_MAX:
+                        _span_prompt_state.pop(next(iter(_span_prompt_state)), None)
+                    _span_prompt_state[id(span)] = state
         except Exception:
             pass  # never break user code
 
     def on_end(self, span: Any) -> None:
         trodo_span = otel_span_to_trodo_span(span)
+        _span_prompt_state.pop(id(span), None)
         if trodo_span is not None:
             self._processor.enqueue_span(trodo_span)
 
@@ -401,6 +430,48 @@ class _OtelAdapter(_SpanProcessorBase):  # type: ignore[valid-type,misc]
         return True
 
 
+class OtlpPromptLinker(_SpanProcessorBase):  # type: ignore[valid-type,misc]
+    """OTLP mode: link provider spans to a managed prompt by exact fingerprint.
+
+    In OTLP mode finished spans go straight to the exporter, so there is no
+    TrodoSpan to enrich. ``on_ending`` (opentelemetry-sdk >= 1.43) is the last
+    point where the span is still writable. Register this BEFORE the batch
+    processor. On older SDKs ``on_ending`` is never called and this is inert.
+    """
+
+    def __init__(self) -> None:
+        try:
+            super().__init__()
+        except TypeError:
+            pass
+
+    def on_start(self, span: Any, parent_context: Any = None) -> None:
+        return None
+
+    def on_ending(self, span: Any) -> None:
+        try:
+            attrs = dict(getattr(span, "attributes", None) or {})
+            if _infer_kind(attrs) != "llm":
+                return
+            inp = _extract_input(attrs)
+            ref = prompt_ref_from_fingerprint(inp) if inp else None
+            if not ref:
+                return
+            for k, v in prompt_attributes(ref).items():
+                span.set_attribute(k, v)
+        except Exception:
+            pass  # never break the export pipeline
+
+    def on_end(self, span: Any) -> None:
+        return None
+
+    def shutdown(self) -> None:
+        return None
+
+    def force_flush(self, timeout_millis: int = 30_000) -> bool:
+        return True
+
+
 def _instrument(module_name: str, *preferred: str) -> None:
     """Import ``module_name`` and call ``instrument()`` on its Instrumentor.
 

trodo/otel/prompt_trace.py

@@ -9,13 +9,25 @@ moved to a different version.
 The link is best-effort and never raises: if there is no active run context
 (the prompt was compiled outside ``wrap_agent``), recording is a silent no-op.
 
+A third route covers compile-before-run followed by a model call made by an
+AUTO-INSTRUMENTED provider SDK (no run context at compile time, no carrier on
+the span's serialised input): compile() registers a sha256 fingerprint of the
+rendered (role, text) list in a small bounded registry, and a model span whose
+input normalises to the same fingerprint is linked. Exact match or nothing --
+never a "last compiled prompt wins" guess. Only hashes are retained, never
+message text. Providers that rewrite the messages will not match, by design.
+
 Mirrors ``sdks/trodo-node-sdk/src/otel/promptTrace.ts``.
 """
 
 from __future__ import annotations
 
+import hashlib
+import json
+import threading
+import time
 from collections import OrderedDict
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 
 from .context import get_active_context
 
@@ -176,3 +188,175 @@ def _stamp_active_otel_span(ref: PromptRef) -> None:
             span.set_attribute(k, v)
     except Exception:  # noqa: BLE001
         pass  # not in OTLP mode / opentelemetry not installed — no-op
+
+
+# ---------------------------------------------------------------------------
+# Content-fingerprint registry
+# ---------------------------------------------------------------------------
+
+#: Max fingerprints kept process-wide (LRU). Keep in sync with the Node SDK.
+FINGERPRINT_MAX_ENTRIES = 256
+#: How long a fingerprint stays matchable. Keep in sync with the Node SDK.
+FINGERPRINT_TTL_SECONDS = 10 * 60
+
+# fingerprint -> (ref, registered_at). Insertion order == age order.
+_fingerprints: "OrderedDict[str, Tuple[PromptRef, float]]" = OrderedDict()
+_fp_lock = threading.Lock()
+
+
+def _now() -> float:
+    return time.time()
+
+
+def _text_of_content(content: Any) -> Optional[str]:
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return None
+    out = ""
+    for part in content:
+        if isinstance(part, str):
+            out += part
+        elif isinstance(part, dict):
+            # {type:'text', text} (OpenAI/Anthropic/compiled), {content} (OTel GenAI parts)
+            if isinstance(part.get("text"), str):
+                out += part["text"]
+            elif part.get("type") == "text" and isinstance(part.get("content"), str):
+                out += part["content"]
+    return out
+
+
+def _normalise_message(m: Any) -> Optional[Tuple[str, str]]:
+    if not isinstance(m, dict):
+        return None
+    # OpenInference indexed messages nest as {message: {role, content}}.
+    if isinstance(m.get("message"), dict):
+        m = m["message"]
+    role = m.get("role")
+    if not isinstance(role, str):
+        return None
+    content = m.get("content")
+    text = _text_of_content(content if content is not None else m.get("parts"))
+    if text is None:
+        return None
+    role = role.lower()
+    return ("system" if role == "developer" else role, text)
+
+
+def normalise_messages(value: Any) -> Optional[List[Tuple[str, str]]]:
+    """Normalise a provider request's messages into a list of (role, text).
+
+    Handles an OpenAI-style list, Anthropic ``{system, messages}`` (system
+    becomes a leading 'system' message), a CompiledPrompt, and the JSON string
+    form provider instrumentations record. None when not message-shaped.
+    """
+    v = value
+    if hasattr(v, "messages") and not isinstance(v, (dict, list, str)):
+        v = getattr(v, "messages")  # CompiledPrompt
+    if isinstance(v, (bytes, bytearray)):
+        return None
+    if isinstance(v, str):
+        t = v.strip()
+        if not t or t[0] not in "[{":
+            return None
+        try:
+            v = json.loads(t)
+        except Exception:  # noqa: BLE001
+            return None
+    out: List[Tuple[str, str]] = []
+    if isinstance(v, dict):
+        items = v.get("messages")
+        if not isinstance(items, list):
+            return None
+        if v.get("system") is not None:
+            sys_text = _text_of_content(v["system"])
+            if sys_text is not None:
+                out.append(("system", sys_text))
+    elif isinstance(v, list):
+        items = v
+    else:
+        return None
+    for m in items:
+        n = _normalise_message(m)
+        if n is None:
+            return None  # any non-message item: not a messages list, no guessing
+        out.append(n)
+    return out or None
+
+
+def fingerprint_messages(value: Any) -> Optional[str]:
+    """sha256 over the normalised (role, text) list; length-prefixed."""
+    norm = normalise_messages(value)
+    if norm is None:
+        return None
+    h = hashlib.sha256()
+    for role, text in norm:
+        rb = text.encode("utf-8", "surrogatepass")
+        h.update(f"{len(role)}:{role}|{len(rb)}:".encode("utf-8"))
+        h.update(rb)
+        h.update(b";")
+    return h.hexdigest()
+
+
+def _prune(now: float) -> None:
+    while _fingerprints:
+        key = next(iter(_fingerprints))
+        if now - _fingerprints[key][1] > FINGERPRINT_TTL_SECONDS:
+            del _fingerprints[key]
+        else:
+            break  # insertion order == age order, so the rest are younger
+
+
+def register_compiled_messages(messages: Any, ref: PromptRef) -> None:
+    """Register the rendered messages of a just-compiled prompt.
+
+    Best-effort, never raises, retains only a hash. Two prompt versions that
+    render byte-identical content collide on purpose (the messages cannot tell
+    them apart); the most recent compile wins.
+    """
+    try:
+        if not ref or not ref.get("name"):
+            return
+        fp = fingerprint_messages(messages)
+        if fp is None:
+            return
+        now = _now()
+        with _fp_lock:
+            _prune(now)
+            _fingerprints.pop(fp, None)
+            _fingerprints[fp] = (ref, now)
+            while len(_fingerprints) > FINGERPRINT_MAX_ENTRIES:
+                _fingerprints.popitem(last=False)
+    except Exception:  # noqa: BLE001
+        pass  # traceability must never break compile
+
+
+def prompt_ref_from_fingerprint(value: Any) -> Optional[PromptRef]:
+    """Exact-match lookup for a provider span's input.
+
+    Zero cost when nothing has been compiled: the input is never parsed.
+    """
+    if not _fingerprints or value is None:
+        return None
+    try:
+        with _fp_lock:
+            _prune(_now())
+            if not _fingerprints:
+                return None
+        fp = fingerprint_messages(value)
+        if fp is None:
+            return None
+        with _fp_lock:
+            hit = _fingerprints.get(fp)
+        return hit[0] if hit else None
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _reset_fingerprints_for_tests() -> None:
+    with _fp_lock:
+        _fingerprints.clear()
+
+
+def _fingerprint_count_for_tests() -> int:
+    return len(_fingerprints)

trodo/otel/register.py

@@ -44,6 +44,12 @@ _registered: Optional[RegisterOtelResult] = None
 _otlp_processor: Optional[Any] = None
 
 
+def _prompt_linker() -> Any:
+    from .auto_instrument import OtlpPromptLinker
+
+    return OtlpPromptLinker()
+
+
 def flush_otlp_pipeline() -> None:
     """Force-flush the 'otlp'-mode export pipeline. No-op in 'trodo' mode."""
     if _otlp_processor is not None:
@@ -172,6 +178,7 @@ def _setup_otlp_mode(
     if existing_class not in ("ProxyTracerProvider", "NoOpTracerProvider"):
         # User's pipeline owns the provider — just attach our processor.
         if hasattr(existing, "add_span_processor"):
+            existing.add_span_processor(_prompt_linker())
             existing.add_span_processor(batch_processor)
         # Auto-instrumentations are presumably already wired by the existing
         # pipeline. We still set the transport so wrap_agent dispatches.
@@ -189,6 +196,7 @@ def _setup_otlp_mode(
         "trodo.sdk.mode": "otlp",
     })
     provider = TracerProvider(resource=resource)
+    provider.add_span_processor(_prompt_linker())
     provider.add_span_processor(batch_processor)
     otel_trace.set_tracer_provider(provider)
 

trodo/prompts/types.py

@@ -95,6 +95,7 @@ class ManagedPrompt:
             try:
                 from ..otel.prompt_trace import (
                     record_compiled_prompt,
+                    register_compiled_messages,
                     tag_carrier_with_prompt,
                 )
 
@@ -113,6 +114,11 @@ class ManagedPrompt:
                 #     since callers pass one or the other.
                 tag_carrier_with_prompt(compiled, ref)
                 tag_carrier_with_prompt(getattr(compiled, "messages", None), ref)
+                # (3) a content fingerprint, so an auto-instrumented provider
+                #     span handed exactly these messages (compiled before the
+                #     run; no carrier on the serialised input) links by exact
+                #     match.
+                register_compiled_messages(getattr(compiled, "messages", None), ref)
             except Exception:  # noqa: BLE001
                 pass  # traceability must never break compile
         return compiled

{trodo_python-2.24.0.dist-info → trodo_python-2.25.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.24.0
+Version: 2.25.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side

{trodo_python-2.24.0.dist-info → trodo_python-2.25.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
-trodo/__init__.py,sha256=ahX3Z2VcSDifpb6xg4RNUJzLe64Oka2TY2vNLey2f8M,27913
-trodo/_version.py,sha256=fSs1-zmlRM8V2BkYDf5P5v8U0xEG-QAN-jPcvTDYQLU,23
+trodo/__init__.py,sha256=ftnDcQvvOi9VnJoynkzzZCNwqHRhC7pbXS836bTwizo,27913
+trodo/_version.py,sha256=50fFgmf3lAeDxqh-LvVujTqoWvZoG7fTVAY5gKvc-yQ,23
 trodo/client.py,sha256=6k6HeKrGV2720kK17--u6BjbhAUFZNUzpd9yEYiaQOs,24137
 trodo/types.py,sha256=eySgUvCXROG2TxtxgiU0MNr5iH0DEcduK8bmYtTKG44,3138
 trodo/user_context.py,sha256=uHCI2WYoOI3cNwdIUEuZdX4VYSu14pzm348ksn6hn_c,8195
@@ -20,18 +20,18 @@ trodo/managers/people_manager.py,sha256=mMVnx40Mlifx6NGgChvohC9ViK6dQu2mkXNHbV8p
 trodo/managers/prompt_manager.py,sha256=qFVHgh7PW-SlgHp62ybirdYsJBg-fcQVMTTU3jPqFvo,13435
 trodo/managers/user_manager.py,sha256=faJYX3CHrD7ulYiShV7FhThSMX9aJ3kdOgU4Qtdy5FM,2844
 trodo/otel/__init__.py,sha256=yiRFXWUU45bAM2CV37XeO7zf1hmnmjufdP4XO50yEyE,624
-trodo/otel/auto_instrument.py,sha256=I_F3NCvc0JML2UpX9PaxFM3OGzMSuEYYfxZYTwkQDuo,26224
+trodo/otel/auto_instrument.py,sha256=M5YVpFoPqn9bQohDFM7yyADrVGJPqFBToJLnBO7nOSA,29029
 trodo/otel/context.py,sha256=Jd0aTc0Q-1dM5kXXinhZD8YtnpdKgvneNiODyboVGKY,1418
 trodo/otel/helpers.py,sha256=XOMWcgZHaq5SQbkFxDaXPE4CDFjn01xjJmJ1vIxvwpw,20730
 trodo/otel/processor.py,sha256=WgtLdXT9gpR4TZ_9iuoX-kBP4UN4nelCtoDnogtW_Qc,8289
-trodo/otel/prompt_trace.py,sha256=d2A6UhlWAgHZLIKtU0NxgGUpHk_z3F2Nm4u4QTAC3tA,7332
-trodo/otel/register.py,sha256=bV_ePTfUvPugig2GZnylhzxi2QfoPWs96A9mGLPMrSQ,9387
+trodo/otel/prompt_trace.py,sha256=-kywRBU0Q2gWntS9HU-P5i7Kc5U-IJU7UVLjkdC2jw4,13593
+trodo/otel/register.py,sha256=7X3AfFQ5YvHGOUmdq8J38LQGvOJFPD907yT3uAp90lI,9607
 trodo/otel/transport.py,sha256=hzZz8gwSMGJ8CxdijmLn1Ljt18owr9XTWy13DLbwYbw,2441
 trodo/otel/wrap_agent.py,sha256=qx2jnuVIMZTv-PpRt-qFWqMWz1YO4jqY5pwgBQirVDo,44519
 trodo/prompts/__init__.py,sha256=yunNc8WkTSfEEkRR-NZWXAt_ZB3Ee2INRh-4RE7uHj4,806
 trodo/prompts/compile.py,sha256=XoKDKz6Yaofhrk-87AVW-SnwbiXLvfp161AL2bAFzNY,8802
 trodo/prompts/template.py,sha256=eGO2ZVNOw6JK7Ffj1UCYDMJFYyX5qQW2POlmFJSQpAo,9975
-trodo/prompts/types.py,sha256=OYpaLi1H9pJjeq0gsJo8eb-bWoF8rw2u_7pdukudtqo,5258
+trodo/prompts/types.py,sha256=Mjn6x6f7dI3TIVHSvzM2xs_gchuh5sCwUfBsW-YLVm0,5654
 trodo/queue/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/queue/batch_flusher.py,sha256=4Lg6T3Urwi9U0Q4FpFGPmjDYKg4ZliCTR-ND8BJvWaY,1298
 trodo/queue/event_queue.py,sha256=EVFZrhlq_kwC3jJ2GK0wMhHISf9UzLCZNDnT_aZ2I2A,872
@@ -40,7 +40,7 @@ trodo/session/server_session.py,sha256=McsudEiq33XDq3nqxgzBcUvIjQxCMscwEuAPnYXrT
 trodo/session/session_manager.py,sha256=7ht5LeeZX1HLLfPeNV_a8NkXGbHl3up0CRtCGr3EzjQ,2995
 trodo/util/__init__.py,sha256=Z9c4rPPdKg06Kk3byKheDqksSgR4WNvS475oQ5sNljc,54
 trodo/util/lru.py,sha256=QIsM7s6J_E9ZjiXatSyReZIEeGypTAcgrPWWy8YsRa4,2465
-trodo_python-2.24.0.dist-info/METADATA,sha256=zDBPYuJWTElYQQgr1S8qeDzl1chRfwbNtESdc-PFe1M,25308
-trodo_python-2.24.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-trodo_python-2.24.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
-trodo_python-2.24.0.dist-info/RECORD,,
+trodo_python-2.25.0.dist-info/METADATA,sha256=_e2LmqFYjaZQdhh6Nr-Uj9wr_f88ZYLZDlD17N431as,25308
+trodo_python-2.25.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+trodo_python-2.25.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
+trodo_python-2.25.0.dist-info/RECORD,,