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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.21.0
+Version: 2.23.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.23.0}/pyproject.toml

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

trodo_python-2.23.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.23.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.23.0}/tests/test_prompts.py

@@ -408,3 +408,27 @@ def test_list_returns_empty_on_error():
             return {"__error": True}
 
     assert PromptManager(Err()).list() == []
+
+
+# ── Shared vectors: COMPILE layer ═══════════════════════════════════════════
+#
+# Declared-variable semantics (defaults, explicit null, per-type coercion) are
+# where the three engines actually drifted -- THIS engine substituted the
+# default for an explicit ``None`` and coerced string-typed values with
+# ``str()`` instead of JS ``String()``, so the same call rendered different
+# text in Python than in the playground. The backend and Node suites run the
+# SAME cases from the same file.
+
+with open(_VECTORS_PATH, encoding="utf-8") as _f:
+    _COMPILE_CASES = json.load(_f).get("compileCases", [])
+
+
+@pytest.mark.parametrize("case", _COMPILE_CASES, ids=lambda c: c["name"])
+def test_compile_vectors(case):
+    prompt = {
+        "messages": [{"role": "user", "content": [{"type": "text", "text": case["template"]}]}],
+        "model": {}, "tools": [], "response_format": None,
+        "variables": case["variables"],
+    }
+    out = compile_prompt(prompt, case["values"])
+    assert out.messages[0]["content"][0]["text"] == case["expect"]

{trodo_python-2.21.0 → trodo_python-2.23.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.23.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