trodo-python 2.4.0__tar.gz → 2.5.0__tar.gz

{trodo_python-2.4.0 → trodo_python-2.5.0}/PKG-INFO

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

{trodo_python-2.4.0 → trodo_python-2.5.0}/pyproject.toml

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

trodo_python-2.5.0/tests/test_anon_distinct_id.py

@@ -0,0 +1,100 @@
+"""Anonymous distinct_id minting on agent surfaces.
+
+When the caller doesn't pass ``distinct_id``, the SDK mints an
+``anon_<ts>_python_<uuid>_<rand>`` id so:
+
+* the agent_runs row always lands with a non-null distinct_id,
+* the RunHandle exposes the same id so callers can bind
+  ``trodo.feedback(distinct_id=...)`` later,
+* older backends without identity-resolution still attribute the row.
+"""
+from __future__ import annotations
+
+import re
+
+from trodo.otel.wrap_agent import _mint_anon_distinct_id, start_run, wrap_agent
+
+
+ANON_RE = re.compile(r"^anon_\d+_python_")
+
+
+def test_mint_anon_distinct_id_shape():
+    a = _mint_anon_distinct_id()
+    assert ANON_RE.match(a)
+
+
+def test_mint_anon_distinct_id_unique_under_load():
+    ids = {_mint_anon_distinct_id() for _ in range(1000)}
+    assert len(ids) == 1000
+
+
+def test_wrap_agent_mints_anon_when_distinct_id_omitted(processor, http):
+    observed = {}
+    with wrap_agent(
+        processor=processor,
+        team_site_id="site-x",
+        agent_name="chat",
+    ) as run:
+        observed["distinct_id"] = run.distinct_id
+        run.set_output("done")
+
+    assert ANON_RE.match(observed["distinct_id"])
+    assert len(http.run_ingest) == 1
+    assert http.run_ingest[0]["run"]["distinct_id"] == observed["distinct_id"]
+
+
+def test_wrap_agent_respects_explicit_distinct_id(processor, http):
+    with wrap_agent(
+        processor=processor,
+        team_site_id="site-x",
+        agent_name="chat",
+        distinct_id="user-42",
+    ) as run:
+        assert run.distinct_id == "user-42"
+
+    assert http.run_ingest[0]["run"]["distinct_id"] == "user-42"
+
+
+def test_wrap_agent_mints_different_anon_ids_across_calls(processor, http):
+    seen = []
+    for _ in range(3):
+        with wrap_agent(
+            processor=processor,
+            team_site_id="site-x",
+            agent_name="chat",
+        ) as run:
+            seen.append(run.distinct_id)
+    assert len(set(seen)) == 3
+
+
+def test_wrap_agent_still_mints_anon_on_error(processor, http):
+    import pytest
+    with pytest.raises(ValueError):
+        with wrap_agent(
+            processor=processor,
+            team_site_id="site-x",
+            agent_name="chat",
+        ) as _run:
+            raise ValueError("boom")
+
+    assert len(http.run_ingest) == 1
+    payload = http.run_ingest[0]["run"]
+    assert payload["status"] == "error"
+    assert ANON_RE.match(payload["distinct_id"])
+
+
+def test_start_run_mints_anon_when_distinct_id_omitted(processor, http):
+    start_run(processor=processor, agent_name="external_session")
+    assert len(http.run_start) == 1
+    run = http.run_start[0]["run"]
+    assert ANON_RE.match(run["distinct_id"])
+
+
+def test_start_run_respects_explicit_distinct_id(processor, http):
+    start_run(
+        processor=processor,
+        agent_name="external_session",
+        distinct_id="user-7",
+    )
+    run = http.run_start[0]["run"]
+    assert run["distinct_id"] == "user-7"

trodo_python-2.5.0/tests/test_auto_instrument_fixes.py

@@ -0,0 +1,111 @@
+"""Mirror of trodo-node 2.4.3 bridge fixes for the Python SDK.
+
+Covers:
+  1. duration_ms is rounded to an integer.
+  2. Active run is recovered from on_start-stamped attributes when
+     contextvars are empty at on_end (httpx async-context loss).
+  3. Internal trodo.* attributes are stripped from the persisted span.
+"""
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+
+from trodo.otel.auto_instrument import _OtelAdapter, otel_span_to_trodo_span
+from trodo.otel.context import (
+    ActiveSpanContext,
+    get_active_context,
+    run_with_context,
+)
+
+
+RUN_ID = "11111111-1111-1111-1111-111111111111"
+ROOT_SPAN_ID = "22222222-2222-2222-2222-222222222222"
+
+
+def _fake_otel_span(start_ns=None, end_ns=None, attrs=None, span_id_int=0xABCD1234ABCD1234, parent_span_id_int=None):
+    span_context = SimpleNamespace(span_id=span_id_int)
+    parent = SimpleNamespace(span_id=parent_span_id_int) if parent_span_id_int else None
+    return SimpleNamespace(
+        name="anthropic.messages.create",
+        get_span_context=lambda: span_context,
+        attributes=attrs or {},
+        start_time=start_ns,
+        end_time=end_ns,
+        status=None,
+        parent=parent,
+    )
+
+
+def _ctx():
+    return ActiveSpanContext(
+        run_id=RUN_ID,
+        span_id=ROOT_SPAN_ID,
+        parent_span_id=None,
+        team_site_id="site-1",
+        processor=None,  # type: ignore[arg-type]
+    )
+
+
+class TestDurationRounding:
+    def test_fractional_ns_delta_rounds_to_integer(self):
+        # 1000ms + 0.999888 fractional ms via nanos delta
+        otel = _fake_otel_span(start_ns=1_000_000_000, end_ns=2_000_999_888)
+        with run_with_context(_ctx()):
+            span = otel_span_to_trodo_span(otel)
+        assert span is not None
+        assert isinstance(span.duration_ms, int)
+        assert span.duration_ms == 1001
+
+    def test_missing_times_leaves_duration_none(self):
+        otel = _fake_otel_span(start_ns=None, end_ns=None)
+        with run_with_context(_ctx()):
+            span = otel_span_to_trodo_span(otel)
+        assert span.duration_ms is None
+
+
+class TestOnStartStamping:
+    def test_on_start_stamps_run_id_when_context_is_alive(self):
+        adapter = _OtelAdapter(processor=MagicMock())
+        live_span = MagicMock()
+        with run_with_context(_ctx()):
+            adapter.on_start(live_span, None)
+        live_span.set_attribute.assert_any_call("trodo.run_id", RUN_ID)
+        live_span.set_attribute.assert_any_call("trodo.parent_span_id", ROOT_SPAN_ID)
+
+    def test_recovers_run_from_stamped_attrs_when_contextvars_empty(self):
+        # Simulate the failure mode: span fires on_end outside any wrap_agent.
+        assert get_active_context() is None
+        otel = _fake_otel_span(
+            start_ns=1_000_000_000,
+            end_ns=2_000_000_000,
+            attrs={
+                "trodo.run_id": RUN_ID,
+                "trodo.parent_span_id": ROOT_SPAN_ID,
+                "gen_ai.request.model": "claude-3-7",
+            },
+        )
+        span = otel_span_to_trodo_span(otel)
+        assert span is not None
+        assert span.run_id == RUN_ID
+        assert span.parent_span_id == ROOT_SPAN_ID
+
+    def test_strips_trodo_attrs_from_persisted_span(self):
+        otel = _fake_otel_span(
+            start_ns=1_000_000_000,
+            end_ns=2_000_000_000,
+            attrs={
+                "trodo.run_id": RUN_ID,
+                "trodo.parent_span_id": ROOT_SPAN_ID,
+                "gen_ai.request.model": "gpt-4",
+            },
+        )
+        span = otel_span_to_trodo_span(otel)
+        assert "trodo.run_id" not in (span.attributes or {})
+        assert "trodo.parent_span_id" not in (span.attributes or {})
+        assert (span.attributes or {}).get("gen_ai.request.model") == "gpt-4"
+
+    def test_drops_span_when_no_run_id_anywhere(self):
+        otel = _fake_otel_span(start_ns=1, end_ns=2, attrs={})
+        assert otel_span_to_trodo_span(otel) is None

{trodo_python-2.4.0 → trodo_python-2.5.0}/trodo/otel/auto_instrument.py

@@ -34,11 +34,17 @@ def _infer_kind(attrs: Dict[str, Any]) -> str:
     return "generic"
 
 
+_ATTR_TRODO_RUN_ID = "trodo.run_id"
+_ATTR_TRODO_PARENT_SPAN_ID = "trodo.parent_span_id"
+
+
 def otel_span_to_trodo_span(otel_span: Any) -> Optional[TrodoSpan]:
-    """Translate an OTel ReadableSpan to our TrodoSpan using GenAI semconv."""
-    ctx = get_active_context()
-    if ctx is None:
-        return None  # span emitted outside of wrap_agent — drop
+    """Translate an OTel ReadableSpan to our TrodoSpan using GenAI semconv.
+
+    Recovers the active run from on_start-stamped attributes when contextvars
+    have been clobbered by httpx/asyncio context loss at span end. Mirrors
+    the trodo-node 2.4.3 bridge behaviour.
+    """
     try:
         span_ctx = (
             otel_span.get_span_context()
@@ -53,15 +59,36 @@ def otel_span_to_trodo_span(otel_span: Any) -> Optional[TrodoSpan]:
         return None
     span_id = f"{span_id_int:016x}" if isinstance(span_id_int, int) else str(span_id_int)
 
+    attrs = dict(getattr(otel_span, "attributes", {}) or {})
+
+    # Prefer on_start-stamped run/parent so async-context loss can't drop
+    # auto-instrumented LLM spans.
+    stamped_run_id = attrs.get(_ATTR_TRODO_RUN_ID)
+    stamped_parent_span_id = attrs.get(_ATTR_TRODO_PARENT_SPAN_ID)
+
+    ctx = get_active_context()
+    run_id = stamped_run_id if isinstance(stamped_run_id, str) else (ctx.run_id if ctx else None)
+    if not run_id:
+        return None  # emitted outside any wrap_agent — drop
+
     parent = getattr(otel_span, "parent", None)
-    parent_span_id: Optional[str] = None
+    otel_parent_span_id: Optional[str] = None
     if parent is not None:
         pid = getattr(parent, "span_id", None)
-        parent_span_id = f"{pid:016x}" if isinstance(pid, int) else str(pid) if pid else None
-    if parent_span_id is None:
-        parent_span_id = ctx.span_id
+        otel_parent_span_id = (
+            f"{pid:016x}" if isinstance(pid, int) else str(pid) if pid else None
+        )
 
-    attrs = dict(getattr(otel_span, "attributes", {}) or {})
+    if isinstance(stamped_parent_span_id, str):
+        parent_span_id: Optional[str] = stamped_parent_span_id
+    elif otel_parent_span_id:
+        parent_span_id = otel_parent_span_id
+    else:
+        parent_span_id = ctx.span_id if ctx else None
+
+    # Strip the internal attrs so they don't leak into the persisted span.
+    attrs.pop(_ATTR_TRODO_RUN_ID, None)
+    attrs.pop(_ATTR_TRODO_PARENT_SPAN_ID, None)
     kind = _infer_kind(attrs)
 
     start_time = getattr(otel_span, "start_time", None)
@@ -70,7 +97,9 @@ def otel_span_to_trodo_span(otel_span: Any) -> Optional[TrodoSpan]:
     ended_at = _hr_to_iso(end_time)
     duration_ms = None
     if start_time and end_time:
-        duration_ms = max(0, int((end_time - start_time) / 1e6))
+        # round-half-to-even semantics are fine here; the constraint is
+        # "integer ms" matching the agent_spans.duration_ms column.
+        duration_ms = max(0, round((end_time - start_time) / 1e6))
 
     status = getattr(otel_span, "status", None)
     status_code = getattr(status, "status_code", None)
@@ -104,7 +133,7 @@ def otel_span_to_trodo_span(otel_span: Any) -> Optional[TrodoSpan]:
 
     return TrodoSpan(
         span_id=span_id,
-        run_id=ctx.run_id,
+        run_id=run_id,
         parent_span_id=parent_span_id,
         kind=kind,
         name=getattr(otel_span, "name", kind),
@@ -131,7 +160,20 @@ class _OtelAdapter:
         self._processor = processor
 
     def on_start(self, span: Any, parent_context: Any = None) -> None:
-        pass
+        # Stamp active run/parent ids while contextvars are still alive.
+        # See otel_span_to_trodo_span() docstring for the failure mode this
+        # guards against (async-context loss across httpx await boundaries).
+        ctx = get_active_context()
+        if ctx is None:
+            return
+        try:
+            set_attr = getattr(span, "set_attribute", None)
+            if callable(set_attr):
+                set_attr(_ATTR_TRODO_RUN_ID, ctx.run_id)
+                if ctx.span_id:
+                    set_attr(_ATTR_TRODO_PARENT_SPAN_ID, ctx.span_id)
+        except Exception:
+            pass  # never break user code
 
     def on_end(self, span: Any) -> None:
         trodo_span = otel_span_to_trodo_span(span)

{trodo_python-2.4.0 → trodo_python-2.5.0}/trodo/otel/helpers.py

@@ -320,14 +320,19 @@ def track_mcp(
     span_id = str(_uuid.uuid4())
     conv_id = session_id or str(_uuid.uuid4())
 
+    # Coerce duration to a non-negative integer. agent_spans.duration_ms is an
+    # integer column and callers occasionally pass floats from time.perf_counter()
+    # deltas — without this, fractional values 500 the ingest.
+    if isinstance(duration_ms, (int, float)) and duration_ms > 0:
+        duration_ms = int(round(duration_ms))
+    else:
+        duration_ms = 0
+
     now = datetime.now(timezone.utc)
     if ended_at is None:
         ended_at = now.isoformat()
     if started_at is None:
-        offset_ms = duration_ms if isinstance(duration_ms, int) and duration_ms > 0 else 0
-        started_at = (now - timedelta(milliseconds=offset_ms)).isoformat()
-    if duration_ms is None:
-        duration_ms = 0
+        started_at = (now - timedelta(milliseconds=duration_ms)).isoformat()
 
     status = "error" if error else "ok"
     if error:

{trodo_python-2.4.0 → trodo_python-2.5.0}/trodo/otel/wrap_agent.py

@@ -114,12 +114,37 @@ def _aggregate(spans: list[TrodoSpan]) -> Dict[str, Any]:
     }
 
 
+def _mint_anon_distinct_id() -> str:
+    """Mint a server-side anonymous distinct_id for an agent run.
+
+    Mirrors UserIdentity.generateAnonymousDistinctId on the backend
+    (``anon_<ts>_<scope>_<uuid>_<rand>``) so server-SDK anon runs and
+    browser-SDK anon sessions share one prefix the dashboard already
+    filters on.
+
+    Minted client-side (not just server-side) so:
+      * the RunHandle / OTLP span attribute carries the id immediately and
+        downstream ``trodo.feedback(distinct_id=...)`` calls have something
+        to bind to,
+      * users running against an older backend still get a real attributable
+        distinct_id on every ``agent_runs`` row, instead of NULL.
+    """
+    import random
+    import string
+    ts = int(time.time() * 1000)
+    rand = "".join(random.choices(string.ascii_lowercase + string.digits, k=16))
+    return f"anon_{ts}_python_{uuid.uuid4()}_{rand}"
+
+
 class RunHandle:
     """Handle returned by wrap_agent for setting input/output and getting run_id."""
 
-    def __init__(self, run_id: str, agent_name: str) -> None:
+    def __init__(self, run_id: str, agent_name: str, distinct_id: str) -> 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[str] = None
         self.output: Optional[str] = None
         self.metadata: Dict[str, Any] = {}
@@ -209,10 +234,16 @@ def start_run(
     to add spans — they flush incrementally via ``append_spans``.
     """
     rid = run_id or str(uuid.uuid4())
+    # Mint anon when missing so the run row is attributable. The minted id
+    # is stamped onto the TrodoRun payload but is not surfaced to the caller —
+    # start_run's signature returns just run_id for backward compat. Callers
+    # who need the distinct_id should pass their own (or use wrap_agent,
+    # whose RunHandle exposes it via handle.distinct_id).
+    effective_distinct_id = distinct_id or _mint_anon_distinct_id()
     run = TrodoRun(
         run_id=rid,
         agent_name=agent_name,
-        distinct_id=distinct_id,
+        distinct_id=effective_distinct_id,
         conversation_id=conversation_id,
         parent_run_id=parent_run_id,
         status="running",
@@ -278,7 +309,11 @@ class wrap_agent:
         self._processor = processor
         self._team_site_id = team_site_id
         self._agent_name = agent_name
-        self._distinct_id = distinct_id
+        # Mint anon when caller didn't pass one. From this point on every
+        # internal path uses self._distinct_id, never the raw constructor
+        # argument, so the run row, OTLP span attribute, and RunHandle all
+        # agree on a single non-null value.
+        self._distinct_id = distinct_id or _mint_anon_distinct_id()
         self._conversation_id = conversation_id
         self._parent_run_id = parent_run_id
         self._metadata = metadata
@@ -312,7 +347,7 @@ class wrap_agent:
         self._started_iso = _now_iso()
         self._started_ms = time.time() * 1000.0
 
-        self.handle = RunHandle(run_id, self._agent_name)
+        self.handle = RunHandle(run_id, self._agent_name, self._distinct_id)
         ctx = ActiveSpanContext(
             run_id=run_id,
             span_id=root_span_id,
@@ -387,8 +422,9 @@ class wrap_agent:
         run_id = _hex_to_uuid(trace_id_hex)
 
         otel_span.set_attribute("trodo.agent_name", self._agent_name)
-        if self._distinct_id:
-            otel_span.set_attribute("trodo.distinct_id", str(self._distinct_id))
+        # self._distinct_id is always set (anon-minted in __init__ when caller
+        # didn't pass one), so the attribute always lands on the OTLP span.
+        otel_span.set_attribute("trodo.distinct_id", str(self._distinct_id))
         if self._conversation_id:
             otel_span.set_attribute("trodo.conversation_id", str(self._conversation_id))
         if self._parent_run_id:
@@ -398,7 +434,7 @@ 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.handle = RunHandle(run_id, self._agent_name, self._distinct_id)
         return self.handle
 
     def _exit_otel(self, exc_type, exc, tb) -> None:

{trodo_python-2.4.0 → trodo_python-2.5.0}/trodo_python.egg-info/PKG-INFO

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

{trodo_python-2.4.0 → trodo_python-2.5.0}/trodo_python.egg-info/SOURCES.txt

@@ -1,5 +1,7 @@
 README.md
 pyproject.toml
+tests/test_anon_distinct_id.py
+tests/test_auto_instrument_fixes.py
 tests/test_cross_process_session.py
 tests/test_end_run.py
 tests/test_processor_methods.py