trodo-python 2.21.0__tar.gz → 2.22.0__tar.gz

{trodo_python-2.21.0 → trodo_python-2.22.0}/PKG-INFO

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

{trodo_python-2.21.0 → trodo_python-2.22.0}/pyproject.toml

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

trodo_python-2.22.0/tests/test_instrumentor_resolution.py

@@ -0,0 +1,109 @@
+"""Instrumentor class resolution must survive upstream renames.
+
+Every per-framework instrumentor is loaded by name, and the loader in
+``enable_auto_instrument`` swallows failures so a missing optional package
+never breaks user code. The cost of that tolerance: a RENAMED export is
+indistinguishable from an absent package. The user installs exactly the
+package we documented, gets zero spans, and gets no error explaining why.
+
+That is not hypothetical — it happened twice. ``google-generativeai`` renamed
+its class, and ``opentelemetry-instrumentation-langchain`` ships
+``LangchainInstrumentor`` while we imported ``LangChainInstrumentor``, which
+silently disabled LangChain tracing for every Python user on a current version.
+
+So resolution tries the known spellings and then falls back to whatever single
+``*Instrumentor`` the module exports.
+"""
+import sys
+import types
+
+import pytest
+
+from trodo.otel.auto_instrument import _instrument
+
+
+def _fake_module(name, **attrs):
+    mod = types.ModuleType(name)
+    for k, v in attrs.items():
+        setattr(mod, k, v)
+    sys.modules[name] = mod
+    return mod
+
+
+class _Recorder:
+    instrumented = False
+
+    def instrument(self):
+        type(self).instrumented = True
+
+
+@pytest.fixture(autouse=True)
+def _clean():
+    made = []
+    yield made
+    for n in made:
+        sys.modules.pop(n, None)
+
+
+def test_uses_the_preferred_name_when_present(_clean):
+    name = 'fake_instr_preferred'
+    _clean.append(name)
+    cls = type('WantedInstrumentor', (_Recorder,), {'instrumented': False})
+    _fake_module(name, WantedInstrumentor=cls, OtherInstrumentor=type('OtherInstrumentor', (_Recorder,), {}))
+    _instrument(name, 'WantedInstrumentor')
+    assert cls.instrumented is True
+
+
+def test_tries_each_spelling_in_order(_clean):
+    """The real LangChain case: we ask for both casings, upstream ships one."""
+    name = 'fake_instr_langchain'
+    _clean.append(name)
+    cls = type('LangchainInstrumentor', (_Recorder,), {'instrumented': False})
+    _fake_module(name, LangchainInstrumentor=cls)
+    # 'LangChainInstrumentor' (capital C) does not exist here — must not raise.
+    _instrument(name, 'LangchainInstrumentor', 'LangChainInstrumentor')
+    assert cls.instrumented is True
+
+
+def test_falls_back_to_the_only_exported_instrumentor(_clean):
+    """An unforeseen rename still works, which is the whole point."""
+    name = 'fake_instr_renamed'
+    _clean.append(name)
+    cls = type('SomethingWeNeverHeardOfInstrumentor', (_Recorder,), {'instrumented': False})
+    _fake_module(name, SomethingWeNeverHeardOfInstrumentor=cls)
+    _instrument(name, 'ExpectedInstrumentor')
+    assert cls.instrumented is True
+
+
+def test_refuses_to_guess_between_several_candidates(_clean):
+    """Picking arbitrarily could instrument the wrong thing — say so instead."""
+    name = 'fake_instr_ambiguous'
+    _clean.append(name)
+    _fake_module(name,
+                 AInstrumentor=type('AInstrumentor', (_Recorder,), {}),
+                 BInstrumentor=type('BInstrumentor', (_Recorder,), {}))
+    with pytest.raises(ImportError, match='several Instrumentor classes'):
+        _instrument(name, 'NopeInstrumentor')
+
+
+def test_reports_when_nothing_is_exported(_clean):
+    name = 'fake_instr_empty'
+    _clean.append(name)
+    _fake_module(name)
+    with pytest.raises(ImportError, match='no Instrumentor class'):
+        _instrument(name, 'AnyInstrumentor')
+
+
+def test_base_instrumentor_is_never_the_fallback(_clean):
+    """Modules re-export BaseInstrumentor; instrumenting it would be wrong."""
+    name = 'fake_instr_baseonly'
+    _clean.append(name)
+    _fake_module(name, BaseInstrumentor=type('BaseInstrumentor', (_Recorder,), {}))
+    with pytest.raises(ImportError, match='no Instrumentor class'):
+        _instrument(name, 'AnyInstrumentor')
+
+
+def test_a_missing_module_still_raises_importerror(_clean):
+    """The caller relies on ImportError to mean "skip this framework"."""
+    with pytest.raises(ImportError):
+        _instrument('module_that_does_not_exist_xyz', 'AnyInstrumentor')

trodo_python-2.22.0/tests/test_prompt_trace.py

@@ -0,0 +1,261 @@
+"""Prompt -> span traceability (mirrors the Node promptTrace.test.ts).
+
+Compiling a managed prompt must stamp the exact version (by immutable hash)
+onto the spans that used it, and aggregate every prompt used onto the run.
+
+Two routes get it there, and both are load-bearing:
+  - the RUN SCOPE, when compile() runs inside wrap_agent/span. The only route
+    that reaches auto-instrumented spans, whose input we never see.
+  - the COMPILED VALUE, when those messages are passed to a span as ``input``.
+    The only route that survives compiling outside the run, which is an
+    ordinary shape and used to produce no link at all.
+"""
+from __future__ import annotations
+
+from trodo.managers.prompt_manager import PromptManager
+from trodo.otel.wrap_agent import span, wrap_agent
+
+PROMPT_WIRE = {
+    "name": "refund-agent",
+    "version": 3,
+    "version_hash": "a3f9c2e8d1b04756",
+    "content_hash": "ccccontent1234",
+    "parent_hash": "pppparent5678",
+    "labels": ["production"],
+    "tags": [],
+    "messages": [{"role": "system", "content": [{"type": "text", "text": "Help {{q}}"}]}],
+    "model": {"provider": "openai", "model": "gpt-4o"},
+    "tools": [],
+    "response_format": None,
+    "variables": [{"name": "q", "type": "string"}],
+    "updated_at": "2026-07-01T00:00:00Z",
+}
+
+
+class PromptHttp:
+    def __init__(self, prompt=None, fail=False):
+        self._prompt = prompt
+        self.fail = fail
+
+    def get_prompt(self, name, label=None, version=None):
+        if self.fail:
+            raise RuntimeError("unreachable")
+        return {"prompt": dict(self._prompt)}
+
+
+def test_stamps_version_hash_on_span_and_aggregates_on_run(processor, http):
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        p = mgr.get("refund-agent", cache_ttl_seconds=0)
+        with span("llm", kind="llm"):
+            p.compile(q="my order")
+
+    ingest = http.run_ingest[0]
+    spans = ingest["spans"]
+    llm = next(s for s in spans if s["name"] == "llm")
+    attrs = llm["attributes"]
+    assert attrs["trodo.prompt.name"] == "refund-agent"
+    assert attrs["trodo.prompt.version_hash"] == "a3f9c2e8d1b04756"
+    assert attrs["trodo.prompt.label"] == "production"  # default selector
+    assert attrs["trodo.prompt.content_hash"] == "ccccontent1234"
+
+    used = ingest["run"]["attributes"]["trodo.prompts"]
+    assert len(used) == 1
+    assert used[0]["version_hash"] == "a3f9c2e8d1b04756"
+
+
+def test_records_label_and_omits_it_for_version_pin(processor, http):
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        staged = mgr.get("refund-agent", label="staging", cache_ttl_seconds=0)
+        with span("s1"):
+            staged.compile(q="x")
+        pinned = mgr.get("refund-agent", version="a3f9c2", cache_ttl_seconds=0)
+        with span("s2"):
+            pinned.compile(q="y")
+
+    spans = http.run_ingest[0]["spans"]
+    s1 = next(s for s in spans if s["name"] == "s1")["attributes"]
+    s2 = next(s for s in spans if s["name"] == "s2")["attributes"]
+    assert s1["trodo.prompt.label"] == "staging"
+    assert "trodo.prompt.label" not in s2  # pinned by hash -> no label
+    assert s2["trodo.prompt.version_hash"] == "a3f9c2e8d1b04756"
+
+
+def test_no_op_outside_a_run(processor, http):
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    p = mgr.get("refund-agent", cache_ttl_seconds=0)
+    # Must not raise despite there being no active run context.
+    p.compile(q="z")
+    assert len(http.run_ingest) == 0
+
+
+def test_fallback_prompt_is_not_traced(processor, http):
+    mgr = PromptManager(PromptHttp(fail=True))
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        p = mgr.get(
+            "refund-agent",
+            cache_ttl_seconds=0,
+            max_retries=0,
+            fallback={
+                "messages": [{"role": "user", "content": [{"type": "text", "text": "hi {{q}}"}]}],
+                "variables": [{"name": "q"}],
+            },
+        )
+        assert p.is_fallback is True
+        with span("llm"):
+            p.compile(q="x")
+
+    spans = http.run_ingest[0]["spans"]
+    attrs = next(s for s in spans if s["name"] == "llm").get("attributes") or {}
+    assert "trodo.prompt.name" not in attrs
+    # to_dict() drops None, so an untraced run has no 'attributes' key at all.
+    assert "attributes" not in http.run_ingest[0]["run"]
+
+
+# ── compiled OUTSIDE the run ────────────────────────────────────────────────
+#
+# Fetch and compile up front, open the run around just the model call. Under the
+# run-scope mechanism alone this produced no link whatsoever.
+
+
+def test_links_span_whose_input_was_compiled_outside_the_run(processor, http):
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    p = mgr.get("refund-agent", cache_ttl_seconds=0)
+    compiled = p.compile(q="z")  # OUTSIDE any run
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        with span("llm", kind="llm", input=compiled.messages):
+            pass
+
+    attrs = next(s for s in http.run_ingest[0]["spans"] if s["name"] == "llm")["attributes"]
+    assert attrs["trodo.prompt.name"] == "refund-agent"
+    assert attrs["trodo.prompt.version_hash"] == "a3f9c2e8d1b04756"
+
+
+def test_outside_compiled_prompt_reaches_the_run_level_list(processor, http):
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    p = mgr.get("refund-agent", cache_ttl_seconds=0)
+    compiled = p.compile(q="z")
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        with span("llm", kind="llm", input=compiled.messages):
+            pass
+
+    used = http.run_ingest[0]["run"]["attributes"]["trodo.prompts"]
+    assert [r["name"] for r in used] == ["refund-agent"]
+
+
+def test_the_compiled_wrapper_works_as_input_too(processor, http):
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    p = mgr.get("refund-agent", cache_ttl_seconds=0)
+    compiled = p.compile(q="z")
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        with span("llm", kind="llm", input=compiled):
+            pass
+
+    attrs = next(s for s in http.run_ingest[0]["spans"] if s["name"] == "llm")["attributes"]
+    assert attrs["trodo.prompt.name"] == "refund-agent"
+
+
+def test_span_input_beats_the_runs_most_recent_prompt(processor, http):
+    """Specificity: a span holding prompt A must say A, not whatever came last."""
+    other = dict(PROMPT_WIRE, name="other-agent", version_hash="bbbb2222", content_hash="ccc2")
+
+    class TwoPrompts:
+        def get_prompt(self, name, label=None, version=None):
+            return {"prompt": dict(other if name == "other-agent" else PROMPT_WIRE)}
+
+    mgr = PromptManager(TwoPrompts())
+    a = mgr.get("refund-agent", cache_ttl_seconds=0).compile(q="first")
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        # Compiling B inside the run makes B the run's "current" prompt.
+        mgr.get("other-agent", cache_ttl_seconds=0).compile(q="second")
+        with span("llm", kind="llm", input=a.messages):
+            pass
+
+    attrs = next(s for s in http.run_ingest[0]["spans"] if s["name"] == "llm")["attributes"]
+    assert attrs["trodo.prompt.name"] == "refund-agent"
+    assert attrs["trodo.prompt.version_hash"] == "a3f9c2e8d1b04756"
+
+
+def test_a_span_that_never_saw_a_prompt_is_not_labelled(processor, http):
+    """False-positive guard: attribution must not leak to sibling spans."""
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    p = mgr.get("refund-agent", cache_ttl_seconds=0)
+    compiled = p.compile(q="z")
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        with span("llm", kind="llm", input=compiled.messages):
+            pass
+        with span("unrelated", input={"some": "payload"}):
+            pass
+
+    attrs = next(s for s in http.run_ingest[0]["spans"] if s["name"] == "unrelated").get("attributes") or {}
+    assert "trodo.prompt.name" not in attrs
+
+
+def test_hand_written_messages_are_not_carriers(processor, http):
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        with span("llm", kind="llm", input=[{"role": "user", "content": "hand-written"}]):
+            pass
+
+    attrs = next(s for s in http.run_ingest[0]["spans"] if s["name"] == "llm").get("attributes") or {}
+    assert "trodo.prompt.name" not in attrs
+
+
+def test_a_fallback_is_never_tagged_via_the_input_route(processor, http):
+    mgr = PromptManager(PromptHttp(fail=True))
+    p = mgr.get(
+        "refund-agent",
+        fallback={"messages": [{"role": "user", "content": [{"type": "text", "text": "hi {{q}}"}]}],
+                  "variables": [{"name": "q"}]},
+        cache_ttl_seconds=0,
+    )
+    assert p.is_fallback
+    compiled = p.compile(q="x")
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        with span("llm", kind="llm", input=compiled.messages):
+            pass
+
+    attrs = next(s for s in http.run_ingest[0]["spans"] if s["name"] == "llm").get("attributes") or {}
+    assert "trodo.prompt.name" not in attrs
+
+
+def test_carrier_table_is_bounded(processor, http):
+    """It must not grow without limit in a long-lived process."""
+    from trodo.otel import prompt_trace
+
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    p = mgr.get("refund-agent", cache_ttl_seconds=0)
+    for _ in range(prompt_trace._MAX_CARRIERS + 200):
+        p.compile(q="x")
+
+    assert len(prompt_trace._carrier_refs) <= prompt_trace._MAX_CARRIERS
+    assert len(prompt_trace._carrier_keepalive) <= prompt_trace._MAX_CARRIERS
+
+
+def test_run_set_input_records_the_prompt_on_the_run(processor, http):
+    """The shape that still leaves auto-instrumented spans unlabelled: compile
+    up front, hand the messages to the RUN, let a framework make the call. The
+    run can at least say which prompt it ran."""
+    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
+    p = mgr.get("refund-agent", cache_ttl_seconds=0)
+    compiled = p.compile(q="z")
+
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat") as run:
+        run.set_input(compiled.messages)
+
+    used = http.run_ingest[0]["run"]["attributes"]["trodo.prompts"]
+    assert [r["name"] for r in used] == ["refund-agent"]
+
+
+def test_run_set_input_with_ordinary_input_records_nothing(processor, http):
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat") as run:
+        run.set_input({"query": "hello"})
+
+    attrs = http.run_ingest[0]["run"].get("attributes") or {}
+    assert "trodo.prompts" not in attrs

{trodo_python-2.21.0 → trodo_python-2.22.0}/trodo/otel/auto_instrument.py

@@ -401,6 +401,46 @@ class _OtelAdapter(_SpanProcessorBase):  # type: ignore[valid-type,misc]
         return True
 
 
+def _instrument(module_name: str, *preferred: str) -> None:
+    """Import ``module_name`` and call ``instrument()`` on its Instrumentor.
+
+    Upstream renames the exported class often enough that pinning one exact
+    spelling is a silent-failure generator: the import raises, the caller's
+    ``except Exception`` treats it as "package not installed", and the user who
+    installed exactly what we told them to gets no spans and no error. That is
+    how ``LangChainInstrumentor`` (upstream ships ``LangchainInstrumentor``) and
+    ``GoogleGenerativeAIInstrumentor`` both went dark.
+
+    So: try the known spellings in order, then fall back to whatever single
+    ``*Instrumentor`` the module exports. Mirrors ``instrCtor`` in the Node SDK.
+    Raises ImportError if nothing usable is found, which the caller reports.
+    """
+    import importlib
+
+    mod = importlib.import_module(module_name)
+    cls = None
+    for name in preferred:
+        cls = getattr(mod, name, None)
+        if cls is not None:
+            break
+    if cls is None:
+        found = [
+            n for n in dir(mod)
+            if n.endswith("Instrumentor") and n != "BaseInstrumentor"
+            and isinstance(getattr(mod, n, None), type)
+        ]
+        if len(found) == 1:
+            cls = getattr(mod, found[0])
+        elif found:
+            raise ImportError(
+                f"{module_name} exports several Instrumentor classes {found}; "
+                f"none matched the expected names {list(preferred)}"
+            )
+    if cls is None:
+        raise ImportError(f"no Instrumentor class exported by {module_name}")
+    cls().instrument()
+
+
 _INSTRUMENTORS: List[tuple[str, Callable[[], Any]]] = []
 
 
@@ -416,84 +456,49 @@ def _register_instrumentors() -> None:
         return
 
     def _anthropic() -> Any:
-        from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor  # type: ignore
-
-        AnthropicInstrumentor().instrument()
+        _instrument("opentelemetry.instrumentation.anthropic", "AnthropicInstrumentor")
 
     def _openai() -> Any:
-        from opentelemetry.instrumentation.openai import OpenAIInstrumentor  # type: ignore
-
-        OpenAIInstrumentor().instrument()
+        _instrument("opentelemetry.instrumentation.openai", "OpenAIInstrumentor")
 
     def _openai_v2() -> Any:
-        from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor  # type: ignore
-
-        OpenAIInstrumentor().instrument()
+        _instrument("opentelemetry.instrumentation.openai_v2", "OpenAIInstrumentor")
 
     def _langchain() -> Any:
-        from opentelemetry.instrumentation.langchain import LangChainInstrumentor  # type: ignore
-
-        LangChainInstrumentor().instrument()
+        _instrument("opentelemetry.instrumentation.langchain", "LangchainInstrumentor", "LangChainInstrumentor")
 
     def _llama_index() -> Any:
-        from opentelemetry.instrumentation.llama_index import LlamaIndexInstrumentor  # type: ignore
-
-        LlamaIndexInstrumentor().instrument()
+        _instrument("opentelemetry.instrumentation.llama_index", "LlamaIndexInstrumentor")
 
     def _google_generativeai() -> Any:
-        import opentelemetry.instrumentation.google_generativeai as _m  # type: ignore
-
-        # The exported class name varies by version: GoogleGenerativeAiInstrumentor
-        # (current — note the lowercase 'i'), GoogleGenerativeAIInstrumentor, or
-        # GenAIInstrumentor. Importing the wrong casing silently disabled Gemini
-        # auto-instrumentation. (This instrumentation patches the new @google/genai
-        # SDK, i.e. the `google-genai` package, not legacy google-generativeai.)
-        instr = (
-            getattr(_m, "GoogleGenerativeAiInstrumentor", None)
-            or getattr(_m, "GoogleGenerativeAIInstrumentor", None)
-            or getattr(_m, "GenAIInstrumentor", None)
+        # Patches the new google-genai SDK, not legacy google-generativeai.
+        _instrument(
+            "opentelemetry.instrumentation.google_generativeai",
+            "GoogleGenerativeAiInstrumentor",
+            "GoogleGenerativeAIInstrumentor",
+            "GenAIInstrumentor",
         )
-        if instr is None:
-            raise ImportError(
-                "no GoogleGenerativeAi/GenAI Instrumentor in "
-                "opentelemetry.instrumentation.google_generativeai"
-            )
-        instr().instrument()
 
     def _vertexai() -> Any:
-        from opentelemetry.instrumentation.vertexai import VertexAIInstrumentor  # type: ignore
-
-        VertexAIInstrumentor().instrument()
+        _instrument("opentelemetry.instrumentation.vertexai", "VertexAIInstrumentor")
 
     def _bedrock() -> Any:
-        from opentelemetry.instrumentation.bedrock import BedrockInstrumentor  # type: ignore
-
-        BedrockInstrumentor().instrument()
+        _instrument("opentelemetry.instrumentation.bedrock", "BedrockInstrumentor")
 
     def _cohere() -> Any:
-        from opentelemetry.instrumentation.cohere import CohereInstrumentor  # type: ignore
-
-        CohereInstrumentor().instrument()
+        _instrument("opentelemetry.instrumentation.cohere", "CohereInstrumentor")
 
     def _mistralai() -> Any:
-        from opentelemetry.instrumentation.mistralai import MistralAiInstrumentor  # type: ignore
-
-        MistralAiInstrumentor().instrument()
+        _instrument("opentelemetry.instrumentation.mistralai", "MistralAiInstrumentor")
 
     def _haystack() -> Any:
-        from opentelemetry.instrumentation.haystack import HaystackInstrumentor  # type: ignore
-
-        HaystackInstrumentor().instrument()
+        _instrument("opentelemetry.instrumentation.haystack", "HaystackInstrumentor")
 
     def _httpx() -> Any:
-        from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor  # type: ignore
-
-        HTTPXClientInstrumentor().instrument()
+        _instrument("opentelemetry.instrumentation.httpx", "HTTPXClientInstrumentor")
 
     def _requests() -> Any:
-        from opentelemetry.instrumentation.requests import RequestsInstrumentor  # type: ignore
-
-        RequestsInstrumentor().instrument()
+        _instrument("opentelemetry.instrumentation.requests", "RequestsInstrumentor")
 
     _INSTRUMENTORS = [
         ("anthropic", _anthropic),

{trodo_python-2.21.0 → trodo_python-2.22.0}/trodo/otel/prompt_trace.py

@@ -14,6 +14,7 @@ Mirrors ``sdks/trodo-node-sdk/src/otel/promptTrace.ts``.
 
 from __future__ import annotations
 
+from collections import OrderedDict
 from typing import Any, Dict, List, Optional
 
 from .context import get_active_context
@@ -27,6 +28,55 @@ def new_prompt_state() -> Dict[str, Any]:
     return {"current": None, "all": []}
 
 
+# Compiled prompt (or its messages list) -> the version it came from.
+#
+# Mirrors the Node SDK. The run-scope mechanism below only fires when compile()
+# runs inside a run, which leaves the ordinary "fetch and compile up front, open
+# the run around the model call" shape with no link at all. Tagging the compiled
+# value means a span handed those messages as ``input`` recovers the version
+# wherever compile() happened.
+#
+# Keyed by id() with a weak-ish discipline: lists are unhashable and cannot go
+# in a WeakValueDictionary, so entries are bounded and evicted FIFO rather than
+# held forever. The link is best-effort — losing an old entry costs one span's
+# label, never correctness.
+_MAX_CARRIERS = 4096
+_carrier_refs: "OrderedDict[int, PromptRef]" = OrderedDict()
+_carrier_keepalive: "OrderedDict[int, Any]" = OrderedDict()
+
+
+def tag_carrier_with_prompt(carrier: Any, ref: PromptRef) -> None:
+    """Attach a prompt identity to a value the caller will pass to a span."""
+    if carrier is None or isinstance(carrier, (str, bytes, int, float, bool)):
+        return
+    key = id(carrier)
+    _carrier_refs[key] = ref
+    # Hold a reference so the id cannot be recycled by another object while the
+    # mapping still names it — that would mislabel an unrelated span.
+    _carrier_keepalive[key] = carrier
+    _carrier_refs.move_to_end(key)
+    _carrier_keepalive.move_to_end(key)
+    while len(_carrier_refs) > _MAX_CARRIERS:
+        old, _ = _carrier_refs.popitem(last=False)
+        _carrier_keepalive.pop(old, None)
+
+
+def prompt_ref_from_carrier(carrier: Any) -> Optional[PromptRef]:
+    """Recover the prompt identity from a span's input, if it carries one."""
+    if carrier is None or isinstance(carrier, (str, bytes, int, float, bool)):
+        return None
+    return _carrier_refs.get(id(carrier))
+
+
+def remember_prompt(state: Any, ref: PromptRef) -> None:
+    """Add a ref to the run's deduped set if it isn't already there."""
+    if not isinstance(state, dict) or not ref or not ref.get("name"):
+        return
+    key = _ref_key(ref)
+    if not any(_ref_key(r) == key for r in state.get("all", [])):
+        state.setdefault("all", []).append(ref)
+
+
 def _ref_key(ref: PromptRef) -> str:
     return ref.get("version_hash") or ref.get("name") or ""
 
@@ -66,12 +116,24 @@ def prompt_attributes(ref: Optional[PromptRef]) -> Dict[str, str]:
 
 
 def merge_prompt_attrs(
-    active: Any, attrs: Optional[Dict[str, Any]]
+    active: Any, attrs: Optional[Dict[str, Any]], from_input: Optional[PromptRef] = None
 ) -> Optional[Dict[str, Any]]:
-    """Merge the active run's most-recently-compiled prompt into span attributes."""
+    """Merge the prompt this span used into its attributes.
+
+    The span's own INPUT wins over the run's most-recently-compiled prompt: it
+    is more specific (in a run using two prompts, a span holding prompt A's
+    messages must report A even if B was compiled later), and it is the only
+    signal available when compile() ran outside the run.
+
+    A prompt found this way is also folded into the run's deduped set so the
+    run-level ``trodo.prompts`` list stays complete either way.
+    """
     merged: Dict[str, Any] = dict(attrs or {})
     state = getattr(active, "prompt_state", None) if active is not None else None
-    if isinstance(state, dict):
+    if from_input is not None:
+        remember_prompt(state, from_input)
+        merged.update(prompt_attributes(from_input))
+    elif isinstance(state, dict):
         merged.update(prompt_attributes(state.get("current")))
     return merged or None
 

{trodo_python-2.21.0 → trodo_python-2.22.0}/trodo/otel/wrap_agent.py

@@ -32,7 +32,12 @@ from datetime import datetime, timezone
 from typing import Any, Callable, Dict, List, Optional, Union
 
 from .context import ActiveSpanContext, get_active_context, run_with_context
-from .prompt_trace import merge_prompt_attrs, new_prompt_state
+from .prompt_trace import (
+    merge_prompt_attrs,
+    new_prompt_state,
+    prompt_ref_from_carrier,
+    remember_prompt,
+)
 from .processor import TrodoSpanProcessor, TrodoRun, TrodoSpan
 from .transport import get_transport_mode, get_otel_tracer, get_otel_helpers
 
@@ -281,13 +286,21 @@ def _tag_error_with_run(exc: object, run_id: Optional[str]) -> None:
 class RunHandle:
     """Handle returned by wrap_agent for setting input/output and getting run_id."""
 
-    def __init__(self, run_id: str, agent_name: str, distinct_id: str) -> None:
+    def __init__(
+        self,
+        run_id: str,
+        agent_name: str,
+        distinct_id: str,
+        prompt_state: Optional[Dict[str, Any]] = None,
+    ) -> None:
         self.run_id = run_id
         self.agent_name = agent_name
         # Always populated — wrap_agent mints anon if caller didn't pass one
         # so downstream ``trodo.feedback(distinct_id=...)`` always has a target.
         self.distinct_id = distinct_id
         self.input: Optional[Union[str, Dict[str, Any]]] = None
+        #: The run's prompt accumulator, so set_input can register a prompt.
+        self._prompt_state = prompt_state
         self.output: Optional[Union[str, Dict[str, Any]]] = None
         self.metadata: Dict[str, Any] = {}
         # Manually-recorded run-level error (via set_error_summary). When set
@@ -298,7 +311,16 @@ class RunHandle:
     def set_input(self, value: Any) -> None:
         """Set the run input. Prefer a chat-message list
         ``[{"role": "user", "content": ...}, ...]`` — the backend embeds the
-        user messages as the run's semantic input."""
+        user messages as the run's semantic input.
+
+        Handing this the messages from a managed prompt also records that
+        prompt on the run: ``run.set_input(compiled.messages)`` is a common
+        shape, and the run demonstrably used that prompt, so the run-level
+        ``trodo.prompts`` list should say so even when compile() ran outside
+        the run."""
+        ref = prompt_ref_from_carrier(value)
+        if ref is not None:
+            remember_prompt(self._prompt_state, ref)
         self.input = _prepare_value(value)
 
     def set_output(self, value: Any) -> None:
@@ -330,6 +352,10 @@ class SpanHandle:
         self.span_id = span_id
         self.name = name
         self.input: Optional[Union[str, Dict[str, Any]]] = None
+        #: Prompt this span used, recovered from the value passed as input.
+        #: Captured from the ORIGINAL object: _prepare_value JSON-serialises
+        #: anything that isn't a dict/list, and identity cannot survive that.
+        self.prompt_ref: Optional[Dict[str, Any]] = None
         self.output: Optional[Union[str, Dict[str, Any]]] = None
         self.attributes: Dict[str, Any] = {}
         self.model: Optional[str] = None
@@ -393,6 +419,7 @@ class SpanHandle:
         ``context`` for RAG docs, any order, multiple per role) — each role is
         embedded separately and powers the AI-score detectors. Anything else
         is stored as one opaque input."""
+        self.prompt_ref = prompt_ref_from_carrier(value) or self.prompt_ref
         self.input = _prepare_value(value)
 
     def set_output(self, value: Any) -> None:
@@ -594,7 +621,6 @@ class wrap_agent:
         self._started_iso = _now_iso()
         self._started_ms = time.time() * 1000.0
 
-        self.handle = RunHandle(run_id, self._agent_name, self._distinct_id)
         ctx = ActiveSpanContext(
             run_id=run_id,
             span_id=root_span_id,
@@ -603,6 +629,9 @@ class wrap_agent:
             processor=self._processor,
             prompt_state=new_prompt_state(),
         )
+        self.handle = RunHandle(
+            run_id, self._agent_name, self._distinct_id, ctx.prompt_state
+        )
         self._ctx = ctx
         self._ctx_mgr = run_with_context(ctx)
         self._ctx_mgr.__enter__()
@@ -708,7 +737,12 @@ class wrap_agent:
                 otel_span.set_attribute(f"trodo.metadata.{k}", _serialize_attr(v))
 
         self._otel_span = otel_span
-        self.handle = RunHandle(run_id, self._agent_name, self._distinct_id)
+        # OTLP mode builds no Trodo run context (documented limitation), so
+        # the handle gets a standalone accumulator — enough for set_input() to
+        # register a prompt even here.
+        self.handle = RunHandle(
+            run_id, self._agent_name, self._distinct_id, new_prompt_state()
+        )
         return self.handle
 
     def _exit_otel(self, exc_type, exc, tb) -> None:
@@ -770,6 +804,7 @@ class join_run:
         self._parent_span_id = parent_span_id
         self._name = name
         self._kind = kind
+        self._prompt_ref = prompt_ref_from_carrier(input)
         self._input = _prepare_value(input) if input is not None else None
         self._attributes = attributes
         self._ctx_mgr: Optional[run_with_context] = None
@@ -786,6 +821,8 @@ class join_run:
         self.handle = SpanHandle(self._span_id, self._name)
         if self._input is not None:
             self.handle.input = self._input
+        if self._prompt_ref is not None:
+            self.handle.prompt_ref = self._prompt_ref
         if self._attributes:
             self.handle.attributes.update(self._attributes)
 
@@ -838,7 +875,9 @@ class join_run:
             cost_details=self.handle.cost_details,
             temperature=self.handle.temperature,
             tool_name=self.handle.tool_name,
-            attributes=merge_prompt_attrs(self._ctx, self.handle.attributes),
+            attributes=merge_prompt_attrs(
+                self._ctx, self.handle.attributes, self.handle.prompt_ref
+            ),
         )
         try:
             self._processor.append_spans(self._run_id, [trodo_span])
@@ -865,6 +904,7 @@ class span:
     ) -> None:
         self._name = name
         self._kind = kind
+        self._prompt_ref = prompt_ref_from_carrier(input)
         self._input = _prepare_value(input) if input is not None else None
         self._attributes = attributes
         self._ctx_mgr: Optional[run_with_context] = None
@@ -889,6 +929,8 @@ class span:
         self.handle = SpanHandle(self._span_id, self._name)
         if self._input is not None:
             self.handle.input = self._input
+        if self._prompt_ref is not None:
+            self.handle.prompt_ref = self._prompt_ref
         if self._attributes:
             self.handle.attributes.update(self._attributes)
         if self._active is None:
@@ -945,7 +987,9 @@ class span:
             cost_details=self.handle.cost_details,
             temperature=self.handle.temperature,
             tool_name=self.handle.tool_name,
-            attributes=merge_prompt_attrs(self._active, self.handle.attributes),
+            attributes=merge_prompt_attrs(
+                self._active, self.handle.attributes, self.handle.prompt_ref
+            ),
         )
         processor: TrodoSpanProcessor = self._active.processor  # type: ignore[assignment]
         processor.enqueue_span(trodo_span)
@@ -971,6 +1015,8 @@ class span:
         self.handle = SpanHandle(self._span_id, self._name)
         if self._input is not None:
             self.handle.input = self._input
+        if self._prompt_ref is not None:
+            self.handle.prompt_ref = self._prompt_ref
         if self._attributes:
             self.handle.attributes.update(self._attributes)
         return self.handle

{trodo_python-2.21.0 → trodo_python-2.22.0}/trodo/prompts/types.py

@@ -89,21 +89,30 @@ class ManagedPrompt:
         values = dict(variables or {})
         values.update(kwargs)
         compiled = compile_prompt(self, values)
-        # Prompt traceability: record the exact version compiled so any span
-        # emitted in the surrounding wrap_agent/span scope carries it. No-op
-        # outside a run context. Never records a fallback (no real hash).
+        # Prompt traceability. Never records a fallback — it has no real hash,
+        # so a link to it would name a version that does not exist.
         if not self.is_fallback:
             try:
-                from ..otel.prompt_trace import record_compiled_prompt
-
-                record_compiled_prompt(
-                    {
-                        "name": self.name,
-                        "version_hash": self.version_hash,
-                        "content_hash": self.content_hash,
-                        "label": self.trace_label,
-                    }
+                from ..otel.prompt_trace import (
+                    record_compiled_prompt,
+                    tag_carrier_with_prompt,
                 )
+
+                ref = {
+                    "name": self.name,
+                    "version_hash": self.version_hash,
+                    "content_hash": self.content_hash,
+                    "label": self.trace_label,
+                }
+                # (1) the surrounding run scope, if any — the only route that
+                #     reaches auto-instrumented spans, whose input we never see.
+                record_compiled_prompt(ref)
+                # (2) the compiled value itself, so a span handed these messages
+                #     as ``input`` recovers the version even when compile() ran
+                #     outside the run. Both the wrapper and the list are tagged,
+                #     since callers pass one or the other.
+                tag_carrier_with_prompt(compiled, ref)
+                tag_carrier_with_prompt(getattr(compiled, "messages", None), ref)
             except Exception:  # noqa: BLE001
                 pass  # traceability must never break compile
         return compiled

{trodo_python-2.21.0 → trodo_python-2.22.0}/trodo_python.egg-info/PKG-INFO

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

{trodo_python-2.21.0 → trodo_python-2.22.0}/trodo_python.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ tests/test_end_run.py
 tests/test_error_enrichment.py
 tests/test_experiments.py
 tests/test_get_prompt_version_types.py
+tests/test_instrumentor_resolution.py
 tests/test_llm_usage_cost.py
 tests/test_multi_agent_shape.py
 tests/test_processor_methods.py

trodo_python-2.21.0/tests/test_prompt_trace.py

@@ -1,107 +0,0 @@
-"""Prompt -> span traceability (mirrors the Node promptTrace.test.ts).
-
-Compiling a managed prompt inside a wrap_agent/span scope must stamp the exact
-version (by immutable hash) onto the emitted span, and aggregate every prompt
-used onto the run. Outside a run, it's a silent no-op.
-"""
-from __future__ import annotations
-
-from trodo.managers.prompt_manager import PromptManager
-from trodo.otel.wrap_agent import span, wrap_agent
-
-PROMPT_WIRE = {
-    "name": "refund-agent",
-    "version": 3,
-    "version_hash": "a3f9c2e8d1b04756",
-    "content_hash": "ccccontent1234",
-    "parent_hash": "pppparent5678",
-    "labels": ["production"],
-    "tags": [],
-    "messages": [{"role": "system", "content": [{"type": "text", "text": "Help {{q}}"}]}],
-    "model": {"provider": "openai", "model": "gpt-4o"},
-    "tools": [],
-    "response_format": None,
-    "variables": [{"name": "q", "type": "string"}],
-    "updated_at": "2026-07-01T00:00:00Z",
-}
-
-
-class PromptHttp:
-    def __init__(self, prompt=None, fail=False):
-        self._prompt = prompt
-        self.fail = fail
-
-    def get_prompt(self, name, label=None, version=None):
-        if self.fail:
-            raise RuntimeError("unreachable")
-        return {"prompt": dict(self._prompt)}
-
-
-def test_stamps_version_hash_on_span_and_aggregates_on_run(processor, http):
-    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
-    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
-        p = mgr.get("refund-agent", cache_ttl_seconds=0)
-        with span("llm", kind="llm"):
-            p.compile(q="my order")
-
-    ingest = http.run_ingest[0]
-    spans = ingest["spans"]
-    llm = next(s for s in spans if s["name"] == "llm")
-    attrs = llm["attributes"]
-    assert attrs["trodo.prompt.name"] == "refund-agent"
-    assert attrs["trodo.prompt.version_hash"] == "a3f9c2e8d1b04756"
-    assert attrs["trodo.prompt.label"] == "production"  # default selector
-    assert attrs["trodo.prompt.content_hash"] == "ccccontent1234"
-
-    used = ingest["run"]["attributes"]["trodo.prompts"]
-    assert len(used) == 1
-    assert used[0]["version_hash"] == "a3f9c2e8d1b04756"
-
-
-def test_records_label_and_omits_it_for_version_pin(processor, http):
-    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
-    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
-        staged = mgr.get("refund-agent", label="staging", cache_ttl_seconds=0)
-        with span("s1"):
-            staged.compile(q="x")
-        pinned = mgr.get("refund-agent", version="a3f9c2", cache_ttl_seconds=0)
-        with span("s2"):
-            pinned.compile(q="y")
-
-    spans = http.run_ingest[0]["spans"]
-    s1 = next(s for s in spans if s["name"] == "s1")["attributes"]
-    s2 = next(s for s in spans if s["name"] == "s2")["attributes"]
-    assert s1["trodo.prompt.label"] == "staging"
-    assert "trodo.prompt.label" not in s2  # pinned by hash -> no label
-    assert s2["trodo.prompt.version_hash"] == "a3f9c2e8d1b04756"
-
-
-def test_no_op_outside_a_run(processor, http):
-    mgr = PromptManager(PromptHttp(prompt=PROMPT_WIRE))
-    p = mgr.get("refund-agent", cache_ttl_seconds=0)
-    # Must not raise despite there being no active run context.
-    p.compile(q="z")
-    assert len(http.run_ingest) == 0
-
-
-def test_fallback_prompt_is_not_traced(processor, http):
-    mgr = PromptManager(PromptHttp(fail=True))
-    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
-        p = mgr.get(
-            "refund-agent",
-            cache_ttl_seconds=0,
-            max_retries=0,
-            fallback={
-                "messages": [{"role": "user", "content": [{"type": "text", "text": "hi {{q}}"}]}],
-                "variables": [{"name": "q"}],
-            },
-        )
-        assert p.is_fallback is True
-        with span("llm"):
-            p.compile(q="x")
-
-    spans = http.run_ingest[0]["spans"]
-    attrs = next(s for s in spans if s["name"] == "llm").get("attributes") or {}
-    assert "trodo.prompt.name" not in attrs
-    # to_dict() drops None, so an untraced run has no 'attributes' key at all.
-    assert "attributes" not in http.run_ingest[0]["run"]