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

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

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

{trodo_python-2.23.0 → trodo_python-2.23.2}/pyproject.toml

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

{trodo_python-2.23.0 → trodo_python-2.23.2}/tests/test_instrumentor_resolution.py

@@ -107,3 +107,82 @@ 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')
+
+
+# ── Version conflicts must not be reported as active ────────────────────────
+#
+# An instrumentor whose target library is the wrong VERSION does not raise:
+# OpenTelemetry logs a DependencyConflict and returns without patching. We then
+# appended it to `active` and reported auto-capture that was not happening.
+# Found live: cohere 7.0.9 against the instrumentor's ">=4.2.7, <6" was listed
+# as active while producing no spans — the same lie as Node listing `openai`
+# for a version its instrumentation cannot patch.
+
+@pytest.fixture
+def fake_conflict_checker():
+    """Stand in for opentelemetry.instrumentation.dependencies.
+
+    OpenTelemetry is an OPTIONAL dependency of this SDK, so the suite must not
+    require it to be installed — injecting the module is how these tests stay
+    runnable in a bare environment.
+    """
+    made = []
+
+    def install(result):
+        for mod in ('opentelemetry', 'opentelemetry.instrumentation',
+                    'opentelemetry.instrumentation.dependencies'):
+            if mod not in sys.modules:
+                sys.modules[mod] = types.ModuleType(mod)
+                made.append(mod)
+        sys.modules['opentelemetry.instrumentation.dependencies'].get_dependency_conflicts = (
+            lambda deps: result
+        )
+    yield install
+    for m in made:
+        sys.modules.pop(m, None)
+
+
+def test_a_version_conflict_is_raised_not_swallowed(_clean, fake_conflict_checker):
+    name = 'fake_instr_conflict'
+    _clean.append(name)
+
+    class Conflicted(_Recorder):
+        instrumented = False
+
+        def instrumentation_dependencies(self):
+            return ('somelib >=1, <2',)
+
+    _fake_module(name, ConflictedInstrumentor=Conflicted)
+    fake_conflict_checker('DependencyConflict: requested "somelib >=1, <2" but found "somelib 3.0"')
+    from trodo.otel.auto_instrument import _IncompatibleInstrumentation
+
+    with pytest.raises(_IncompatibleInstrumentation, match='somelib 3.0'):
+        _instrument(name, 'ConflictedInstrumentor')
+    assert Conflicted.instrumented is False   # and it never patched
+
+
+def test_no_conflict_instruments_normally(_clean, fake_conflict_checker):
+    name = 'fake_instr_ok'
+    _clean.append(name)
+
+    class Fine(_Recorder):
+        instrumented = False
+
+        def instrumentation_dependencies(self):
+            return ('somelib >=1',)
+
+    _fake_module(name, FineInstrumentor=Fine)
+    fake_conflict_checker(None)
+    _instrument(name, 'FineInstrumentor')
+    assert Fine.instrumented is True
+
+
+def test_unknowable_conflict_state_fails_open(_clean):
+    """No dependency helper, or an instrumentor that declares nothing, must not
+    be condemned — falsely reporting a working setup as broken is worse."""
+    name = 'fake_instr_nodeps'
+    _clean.append(name)
+    cls = type('NoDepsInstrumentor', (_Recorder,), {'instrumented': False})
+    _fake_module(name, NoDepsInstrumentor=cls)
+    _instrument(name, 'NoDepsInstrumentor')
+    assert cls.instrumented is True

{trodo_python-2.23.0 → trodo_python-2.23.2}/tests/test_prompt_trace.py

@@ -259,3 +259,80 @@ def test_run_set_input_with_ordinary_input_records_nothing(processor, http):
 
     attrs = http.run_ingest[0]["run"].get("attributes") or {}
     assert "trodo.prompts" not in attrs
+
+
+# ── Prompts are SPAN-level, not run-level ───────────────────────────────────
+#
+# One run's spans routinely use different prompts, different versions, or none.
+# The run's "most recently compiled" prompt is a fallback, and applying it to
+# every span meant compiling anywhere in a run attributed that prompt to every
+# LATER span. Caught in production: a span named 'no-prompt' was labelled with
+# whichever prompt had been compiled last.
+
+
+def test_does_not_leak_last_prompt_onto_a_later_unrelated_span(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("used-it", kind="llm"):
+            p.compile(q="x")
+        with span("unrelated"):
+            pass
+
+    spans = http.run_ingest[0]["spans"]
+    attrs = next(s for s in spans if s["name"] == "unrelated").get("attributes") or {}
+    assert "trodo.prompt.name" not in attrs
+
+
+def test_still_labels_a_model_span_following_a_compile(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)
+        p.compile(q="x")
+        with span("model-call", kind="llm"):
+            pass
+
+    spans = http.run_ingest[0]["spans"]
+    attrs = next(s for s in spans if s["name"] == "model-call")["attributes"]
+    assert attrs["trodo.prompt.name"] == "refund-agent"
+
+
+def test_labels_the_span_the_prompt_was_compiled_inside(processor, http):
+    """A plain span wrapping a hand-rolled model call plainly used the prompt
+    it compiled; gating purely on kind would have lost it."""
+    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("hand-rolled"):
+            p.compile(q="x")
+
+    spans = http.run_ingest[0]["spans"]
+    attrs = next(s for s in spans if s["name"] == "hand-rolled")["attributes"]
+    assert attrs["trodo.prompt.name"] == "refund-agent"
+
+
+def test_each_span_gets_its_own_prompt_and_the_run_rolls_up_both(processor, http):
+    other = dict(PROMPT_WIRE, name="other-agent", version_hash="bbbb2222")
+
+    class Two:
+        def get_prompt(self, name, label=None, version=None):
+            return {"prompt": dict(other if name == "other-agent" else PROMPT_WIRE)}
+
+    mgr = PromptManager(Two())
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+        a = mgr.get("refund-agent", cache_ttl_seconds=0)
+        b = mgr.get("other-agent", cache_ttl_seconds=0)
+        with span("span-a", kind="llm"):
+            a.compile(q="x")
+        with span("span-b", kind="llm"):
+            b.compile(q="y")
+        with span("span-c"):
+            pass
+
+    spans = http.run_ingest[0]["spans"]
+    at = lambda n: (next(s for s in spans if s["name"] == n).get("attributes") or {})
+    assert at("span-a")["trodo.prompt.name"] == "refund-agent"
+    assert at("span-b")["trodo.prompt.name"] == "other-agent"
+    assert "trodo.prompt.name" not in at("span-c")
+    used = http.run_ingest[0]["run"]["attributes"]["trodo.prompts"]
+    assert sorted(r["name"] for r in used) == ["other-agent", "refund-agent"]

{trodo_python-2.23.0 → trodo_python-2.23.2}/trodo/otel/auto_instrument.py

@@ -438,7 +438,44 @@ def _instrument(module_name: str, *preferred: str) -> None:
             )
     if cls is None:
         raise ImportError(f"no Instrumentor class exported by {module_name}")
-    cls().instrument()
+
+    instr = cls()
+
+    # An instrumentor whose target library is the wrong VERSION does not raise:
+    # OpenTelemetry logs a DependencyConflict and returns without patching
+    # anything. We would then append it to `active` and report auto-capture that
+    # is not happening -- the same lie as listing a framework whose
+    # instrumentation cannot patch the installed SDK. Ask first, and let the
+    # caller report it honestly.
+    conflict = _dependency_conflict(instr)
+    if conflict is not None:
+        raise _IncompatibleInstrumentation(str(conflict))
+
+    instr.instrument()
+
+
+class _IncompatibleInstrumentation(ImportError):
+    """The instrumentor loaded, but its target library is an unsupported version."""
+
+
+def _dependency_conflict(instr: Any) -> Any:
+    """The version conflict OpenTelemetry would hit, or None.
+
+    Returns None when we cannot tell -- an older OTel without the helper, or an
+    instrumentor that declares nothing. Falsely reporting a working setup as
+    broken is worse than the silence this replaces.
+    """
+    try:
+        from opentelemetry.instrumentation.dependencies import (  # type: ignore
+            get_dependency_conflicts,
+        )
+
+        deps = instr.instrumentation_dependencies()
+        if not deps:
+            return None
+        return get_dependency_conflicts(deps)
+    except Exception:  # noqa: BLE001
+        return None
 
 
 _INSTRUMENTORS: List[tuple[str, Callable[[], Any]]] = []
@@ -556,6 +593,17 @@ def enable_auto_instrument(
         try:
             register()
             active.append(name)
+        except _IncompatibleInstrumentation as e:
+            # Loud, because this is the case where everything LOOKS installed:
+            # the package is present, the import worked, and no spans will ever
+            # appear. Silence here is what costs people an afternoon.
+            _warn_once(
+                f"version-{name}",
+                f"auto-instrument: {name} will NOT be auto-captured and is not "
+                f"reported as active -- {e}. Wrap the call with trodo.llm(...) "
+                f"to capture it, or pin the library to a supported version.",
+            )
+            continue
         except Exception:
             continue
     return active

{trodo_python-2.23.0 → trodo_python-2.23.2}/trodo/otel/prompt_trace.py

@@ -25,7 +25,7 @@ PromptRef = Dict[str, Any]
 
 def new_prompt_state() -> Dict[str, Any]:
     """Per-run accumulator, shared by reference across the run's span tree."""
-    return {"current": None, "all": []}
+    return {"current": None, "current_span_id": None, "all": []}
 
 
 # Compiled prompt (or its messages list) -> the version it came from.
@@ -93,6 +93,7 @@ def record_compiled_prompt(ref: PromptRef) -> None:
     state = getattr(active, "prompt_state", None) if active is not None else None
     if isinstance(state, dict):
         state["current"] = ref
+        state["current_span_id"] = getattr(active, "span_id", None)
         key = _ref_key(ref)
         used: List[PromptRef] = state["all"]
         if not any(_ref_key(r) == key for r in used):
@@ -116,7 +117,11 @@ def prompt_attributes(ref: Optional[PromptRef]) -> Dict[str, str]:
 
 
 def merge_prompt_attrs(
-    active: Any, attrs: Optional[Dict[str, Any]], from_input: Optional[PromptRef] = None
+    active: Any,
+    attrs: Optional[Dict[str, Any]],
+    from_input: Optional[PromptRef] = None,
+    kind: Optional[str] = None,
+    span_id: Optional[str] = None,
 ) -> Optional[Dict[str, Any]]:
     """Merge the prompt this span used into its attributes.
 
@@ -134,7 +139,24 @@ def merge_prompt_attrs(
         remember_prompt(state, from_input)
         merged.update(prompt_attributes(from_input))
     elif isinstance(state, dict):
-        merged.update(prompt_attributes(state.get("current")))
+        # The run's "most recently compiled" prompt is a FALLBACK, used only
+        # where it is defensible. Applying it to every span meant compiling a
+        # prompt anywhere in a run attributed it to every LATER span -- a tool,
+        # a retrieval, a bit of plain work all claiming a prompt they never ran.
+        # Prompts belong to SPANS: one run's spans routinely use different
+        # prompts, different versions, or none at all.
+        #
+        # Two cases survive: a MODEL call (kind 'llm'), the only thing that runs
+        # a prompt and the one shape whose input we cannot read when it comes
+        # from a provider instrumentation; and the very span the prompt was
+        # compiled INSIDE, which plainly used it whatever its kind.
+        compiled_here = (
+            state.get("current") is not None
+            and span_id is not None
+            and state.get("current_span_id") == span_id
+        )
+        if kind == "llm" or compiled_here:
+            merged.update(prompt_attributes(state.get("current")))
     return merged or None
 
 

{trodo_python-2.23.0 → trodo_python-2.23.2}/trodo/otel/wrap_agent.py

@@ -876,7 +876,8 @@ class join_run:
             temperature=self.handle.temperature,
             tool_name=self.handle.tool_name,
             attributes=merge_prompt_attrs(
-                self._ctx, self.handle.attributes, self.handle.prompt_ref
+                self._ctx, self.handle.attributes, self.handle.prompt_ref,
+                self._kind, self._span_id,
             ),
         )
         try:
@@ -988,7 +989,8 @@ class span:
             temperature=self.handle.temperature,
             tool_name=self.handle.tool_name,
             attributes=merge_prompt_attrs(
-                self._active, self.handle.attributes, self.handle.prompt_ref
+                self._active, self.handle.attributes, self.handle.prompt_ref,
+                self._kind, self._span_id,
             ),
         )
         processor: TrodoSpanProcessor = self._active.processor  # type: ignore[assignment]

{trodo_python-2.23.0 → trodo_python-2.23.2}/trodo_python.egg-info/PKG-INFO

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