trodo-python 2.24.0__tar.gz → 2.25.0__tar.gz

{trodo_python-2.24.0 → trodo_python-2.25.0}/PKG-INFO

@@ -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 → trodo_python-2.25.0}/pyproject.toml

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

trodo_python-2.25.0/tests/test_prompt_fingerprint.py

@@ -0,0 +1,198 @@
+"""Exact-match prompt linking for AUTO-INSTRUMENTED provider spans.
+
+Mirrors the Node promptFingerprint.test.ts. compile() before the run plus a
+provider call made by an auto-instrumentor leaves no run context at compile
+time and no carrier on the span's serialised input; compile() therefore
+registers a content fingerprint, and a model span whose input has identical
+(role, text) content is linked. Exact or nothing.
+"""
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from trodo.managers.prompt_manager import PromptManager
+from trodo.otel import prompt_trace as pt
+from trodo.otel.auto_instrument import _OtelAdapter
+from trodo.otel.context import ActiveSpanContext, run_with_context
+
+RUN_ID = "11111111-1111-1111-1111-111111111111"
+ROOT = "22222222-2222-2222-2222-222222222222"
+
+WIRE = {
+    "name": "refund-agent",
+    "version": 3,
+    "version_hash": "a3f9c2e8d1b04756",
+    "content_hash": "ccccontent1234",
+    "labels": ["production"],
+    "tags": [],
+    "messages": [
+        {"role": "system", "content": [{"type": "text", "text": "You help with {{q}}"}]},
+        {"role": "user", "content": [{"type": "text", "text": "Hello {{q}}"}]},
+    ],
+    "model": {"provider": "openai", "model": "gpt-4o"},
+    "tools": [],
+    "response_format": None,
+    "variables": [{"name": "q", "type": "string"}],
+}
+
+
+class PromptHttp:
+    def __init__(self, fail=False):
+        self.fail = fail
+
+    def get_prompt(self, name, label=None, version=None):
+        if self.fail:
+            raise RuntimeError("unreachable")
+        return {"prompt": dict(WIRE)}
+
+
+@pytest.fixture(autouse=True)
+def _clean():
+    pt._reset_fingerprints_for_tests()
+    yield
+    pt._reset_fingerprints_for_tests()
+
+
+def provider_span(messages, extra=None):
+    attrs = {
+        "trodo.run_id": RUN_ID,
+        "trodo.parent_span_id": ROOT,
+        "gen_ai.request.model": "gpt-4o",
+        "gen_ai.system": "openai",
+        **(extra or {}),
+    }
+    for i, m in enumerate(messages):
+        attrs[f"gen_ai.prompt.{i}.role"] = m["role"]
+        attrs[f"gen_ai.prompt.{i}.content"] = m["content"]
+    span_context = SimpleNamespace(span_id=0xABCD1234ABCD1234)
+    return SimpleNamespace(
+        name="openai.chat",
+        get_span_context=lambda: span_context,
+        attributes=attrs,
+        start_time=1_000_000_000,
+        end_time=2_000_000_000,
+        status=None,
+        parent=None,
+    )
+
+
+def end_span(otel):
+    captured = []
+    proc = SimpleNamespace(enqueue_span=captured.append)
+    _OtelAdapter(proc).on_end(otel)
+    return captured[0] if captured else None
+
+
+def test_links_after_compile_before_run_with_identical_messages():
+    p = PromptManager(PromptHttp()).get("refund-agent", cache_ttl_seconds=0)
+    p.compile(q="my order")  # no run, no span
+    span = end_span(provider_span([
+        {"role": "system", "content": "You help with my order"},
+        {"role": "user", "content": "Hello my order"},
+    ]))
+    assert span.attributes["trodo.prompt.name"] == "refund-agent"
+    assert span.attributes["trodo.prompt.version_hash"] == "a3f9c2e8d1b04756"
+    assert span.attributes["trodo.prompt.label"] == "production"
+
+
+def test_matches_parts_arrays_and_anthropic_system_shape():
+    p = PromptManager(PromptHttp()).get("refund-agent", cache_ttl_seconds=0)
+    compiled = p.compile(q="x")
+    assert pt.prompt_ref_from_fingerprint(compiled.messages)["name"] == "refund-agent"
+    assert pt.prompt_ref_from_fingerprint({
+        "system": "You help with x",
+        "messages": [{"role": "user", "content": [{"type": "text", "text": "Hello x"}]}],
+    })["name"] == "refund-agent"
+
+
+def test_different_messages_do_not_link():
+    p = PromptManager(PromptHttp()).get("refund-agent", cache_ttl_seconds=0)
+    p.compile(q="my order")
+    span = end_span(provider_span([
+        {"role": "system", "content": "You help with my order"},
+        {"role": "user", "content": "Hello someone else"},
+    ]))
+    assert "trodo.prompt.name" not in (span.attributes or {})
+
+
+def test_fallback_is_never_linked():
+    mgr = PromptManager(PromptHttp(fail=True))
+    p = mgr.get(
+        "refund-agent",
+        cache_ttl_seconds=0,
+        fallback={"messages": [{"role": "user", "content": [{"type": "text", "text": "hi"}]}], "variables": []},
+    )
+    assert p.is_fallback
+    p.compile()
+    assert pt._fingerprint_count_for_tests() == 0
+    span = end_span(provider_span([{"role": "user", "content": "hi"}]))
+    assert "trodo.prompt.name" not in (span.attributes or {})
+
+
+def test_run_level_list_gets_the_prompt_via_on_start_state():
+    p = PromptManager(PromptHttp()).get("refund-agent", cache_ttl_seconds=0)
+    p.compile(q="a")
+    state = pt.new_prompt_state()
+    otel = provider_span([
+        {"role": "system", "content": "You help with a"},
+        {"role": "user", "content": "Hello a"},
+    ])
+    otel.set_attribute = lambda k, v: None
+    captured = []
+    adapter = _OtelAdapter(SimpleNamespace(enqueue_span=captured.append))
+    ctx = ActiveSpanContext(
+        run_id=RUN_ID, span_id=ROOT, parent_span_id=None,
+        team_site_id="site-x", processor=None, prompt_state=state,
+    )
+    with run_with_context(ctx):
+        adapter.on_start(otel)
+    adapter.on_end(otel)
+    assert captured[0].attributes["trodo.prompt.name"] == "refund-agent"
+    assert [r["name"] for r in state["all"]] == ["refund-agent"]
+
+
+def test_ttl_expiry(monkeypatch):
+    t = [1_000_000.0]
+    monkeypatch.setattr(pt, "_now", lambda: t[0])
+    ref = {"name": "p", "version_hash": "h1"}
+    msgs = [{"role": "user", "content": "hello"}]
+    pt.register_compiled_messages(msgs, ref)
+    assert pt.prompt_ref_from_fingerprint(msgs) == ref
+    t[0] += pt.FINGERPRINT_TTL_SECONDS + 1
+    assert pt.prompt_ref_from_fingerprint(msgs) is None
+    assert pt._fingerprint_count_for_tests() == 0
+
+
+def test_lru_eviction_beyond_cap():
+    for i in range(pt.FINGERPRINT_MAX_ENTRIES + 1):
+        pt.register_compiled_messages(
+            [{"role": "user", "content": f"m{i}"}], {"name": f"p{i}", "version_hash": f"h{i}"}
+        )
+    assert pt._fingerprint_count_for_tests() == pt.FINGERPRINT_MAX_ENTRIES
+    assert pt.prompt_ref_from_fingerprint([{"role": "user", "content": "m0"}]) is None
+    assert pt.prompt_ref_from_fingerprint([{"role": "user", "content": "m1"}])["name"] == "p1"
+
+
+def test_most_recent_compile_wins_on_identical_content():
+    msgs = [{"role": "user", "content": "same"}]
+    pt.register_compiled_messages(msgs, {"name": "p", "version_hash": "old"})
+    pt.register_compiled_messages(msgs, {"name": "p", "version_hash": "new"})
+    assert pt.prompt_ref_from_fingerprint(msgs)["version_hash"] == "new"
+    assert pt._fingerprint_count_for_tests() == 1
+
+
+def test_no_work_when_nothing_compiled(monkeypatch):
+    def boom(_):
+        raise AssertionError("should not fingerprint")
+
+    monkeypatch.setattr(pt, "fingerprint_messages", boom)
+    assert pt.prompt_ref_from_fingerprint([{"role": "user", "content": "x"}]) is None
+
+
+def test_role_and_text_exact():
+    a = pt.fingerprint_messages([{"role": "user", "content": "x"}])
+    assert a != pt.fingerprint_messages([{"role": "assistant", "content": "x"}])
+    assert a != pt.fingerprint_messages([{"role": "user", "content": "x "}])
+    assert a == pt.fingerprint_messages('[{"role":"user","content":"x"}]')

{trodo_python-2.24.0 → trodo_python-2.25.0}/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_python-2.25.0/trodo/_version.py

@@ -0,0 +1 @@
+SDK_VERSION = "2.25.0"

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

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

@@ -13,6 +13,7 @@ tests/test_instrumentor_resolution.py
 tests/test_llm_usage_cost.py
 tests/test_multi_agent_shape.py
 tests/test_processor_methods.py
+tests/test_prompt_fingerprint.py
 tests/test_prompt_trace.py
 tests/test_prompts.py
 tests/test_register_otel.py

trodo_python-2.24.0/trodo/_version.py

@@ -1 +0,0 @@
-SDK_VERSION = "2.24.0"