trodo-python 2.4.1__tar.gz → 2.6.0__tar.gz

{trodo_python-2.4.1 → trodo_python-2.6.0}/PKG-INFO

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

{trodo_python-2.4.1 → trodo_python-2.6.0}/pyproject.toml

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

trodo_python-2.6.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.4.1 → trodo_python-2.6.0}/trodo/otel/processor.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 import threading
 from dataclasses import dataclass, asdict
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
 
 
 @dataclass
@@ -20,8 +20,8 @@ class TrodoRun:
     conversation_id: Optional[str] = None
     parent_run_id: Optional[str] = None
     status: str = "ok"  # 'running' | 'ok' | 'error'
-    input: Optional[str] = None
-    output: Optional[str] = None
+    input: Optional[Union[str, Dict[str, Any]]] = None
+    output: Optional[Union[str, Dict[str, Any]]] = None
     started_at: Optional[str] = None
     ended_at: Optional[str] = None
     duration_ms: Optional[int] = None
@@ -50,8 +50,8 @@ class TrodoSpan:
     started_at: Optional[str] = None
     ended_at: Optional[str] = None
     duration_ms: Optional[int] = None
-    input: Optional[str] = None
-    output: Optional[str] = None
+    input: Optional[Union[str, Dict[str, Any]]] = None
+    output: Optional[Union[str, Dict[str, Any]]] = None
     error_type: Optional[str] = None
     error_message: Optional[str] = None
     model: Optional[str] = None

{trodo_python-2.4.1 → trodo_python-2.6.0}/trodo/otel/wrap_agent.py

@@ -28,7 +28,7 @@ import json
 import time
 import uuid
 from datetime import datetime, timezone
-from typing import Any, Callable, Dict, Optional
+from typing import Any, Callable, Dict, Optional, Union
 
 from .context import ActiveSpanContext, get_active_context, run_with_context
 from .processor import TrodoSpanProcessor, TrodoRun, TrodoSpan
@@ -62,7 +62,11 @@ def _now_iso() -> str:
     return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
 
 
-def _truncate(value: Any, max_len: int = 64_000) -> Optional[str]:
+_MAX_VALUE_LEN = 1_000_000  # 1 MB
+
+
+def _truncate(value: Any, max_len: int = _MAX_VALUE_LEN) -> Optional[str]:
+    """Coerce to string and truncate. Use for string-only contexts (OTel attrs, error summaries)."""
     if value is None:
         return None
     if isinstance(value, str):
@@ -75,6 +79,26 @@ def _truncate(value: Any, max_len: int = 64_000) -> Optional[str]:
     return s[:max_len] if len(s) > max_len else s
 
 
+def _prepare_value(value: Any, max_len: int = _MAX_VALUE_LEN) -> Optional[Union[str, Dict[str, Any]]]:
+    """Prepare a value for storage in the JSONB input/output column.
+
+    Dicts/lists pass through as-is (stored as JSONB objects/arrays).
+    Strings are truncated at max_len.
+    Everything else is JSON-serialised then truncated.
+    """
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return value
+    if isinstance(value, str):
+        return value[:max_len] if len(value) > max_len else value
+    try:
+        s = json.dumps(value, default=str)
+    except Exception:
+        s = str(value)
+    return s[:max_len] if len(s) > max_len else s
+
+
 def current_run_id() -> Optional[str]:
     """Return the run_id of the currently active agent run, if any."""
     ctx = get_active_context()
@@ -114,21 +138,46 @@ 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
-        self.input: Optional[str] = None
-        self.output: Optional[str] = None
+        # 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
+        self.output: Optional[Union[str, Dict[str, Any]]] = None
         self.metadata: Dict[str, Any] = {}
 
     def set_input(self, value: Any) -> None:
-        self.input = _truncate(value)
+        self.input = _prepare_value(value)
 
     def set_output(self, value: Any) -> None:
-        self.output = _truncate(value)
+        self.output = _prepare_value(value)
 
     def set_metadata(self, **kwargs: Any) -> None:
         self.metadata.update(kwargs)
@@ -140,8 +189,8 @@ class SpanHandle:
     def __init__(self, span_id: str, name: str) -> None:
         self.span_id = span_id
         self.name = name
-        self.input: Optional[str] = None
-        self.output: Optional[str] = None
+        self.input: Optional[Union[str, Dict[str, Any]]] = None
+        self.output: Optional[Union[str, Dict[str, Any]]] = None
         self.attributes: Dict[str, Any] = {}
         self.model: Optional[str] = None
         self.provider: Optional[str] = None
@@ -152,10 +201,10 @@ class SpanHandle:
         self.tool_name: Optional[str] = None
 
     def set_input(self, value: Any) -> None:
-        self.input = _truncate(value)
+        self.input = _prepare_value(value)
 
     def set_output(self, value: Any) -> None:
-        self.output = _truncate(value)
+        self.output = _prepare_value(value)
 
     def set_attribute(self, key: str, value: Any) -> None:
         self.attributes[key] = value
@@ -209,14 +258,20 @@ 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",
-        input=_truncate(input),
+        input=_prepare_value(input),
         started_at=_now_iso(),
         metadata=metadata,
     )
@@ -248,7 +303,7 @@ def end_run(
         **agg,
     }
     if output is not None:
-        payload["output"] = _truncate(output)
+        payload["output"] = _prepare_value(output)
     if error_summary is not None:
         payload["error_summary"] = _truncate(error_summary, 4_000)
     if metadata is not None:
@@ -278,7 +333,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 +371,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 +446,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 +458,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:
@@ -457,7 +517,7 @@ class join_run:
         self._parent_span_id = parent_span_id
         self._name = name
         self._kind = kind
-        self._input = _truncate(input) if input is not None else None
+        self._input = _prepare_value(input) if input is not None else None
         self._attributes = attributes
         self._ctx_mgr: Optional[run_with_context] = None
         self._started_ms: float = 0.0
@@ -544,7 +604,7 @@ class span:
     ) -> None:
         self._name = name
         self._kind = kind
-        self._input = _truncate(input) if input is not None else None
+        self._input = _prepare_value(input) if input is not None else None
         self._attributes = attributes
         self._ctx_mgr: Optional[run_with_context] = None
         self._started_ms: float = 0.0

{trodo_python-2.4.1 → trodo_python-2.6.0}/trodo_python.egg-info/PKG-INFO

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

{trodo_python-2.4.1 → trodo_python-2.6.0}/trodo_python.egg-info/SOURCES.txt

@@ -1,5 +1,6 @@
 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