trodo-python 2.10.11__tar.gz → 2.11.0__tar.gz

{trodo_python-2.10.11 → trodo_python-2.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.10.11
+Version: 2.11.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side
@@ -250,6 +250,30 @@ search = trodo.retrieval('vector_search', vector_search)
 docs = search(query)
 ```
 
+### LLM span input: the chat-message list
+
+For LLM spans, set the input to the **same messages you send to the model** —
+a chat-message list, not one blob:
+
+```python
+span.set_input([
+    {"role": "system", "content": system_prompt},        # rules & role
+    {"role": "context", "content": retrieved_docs},      # RAG docs (Trodo extension)
+    {"role": "user", "content": "Where is my order?"},
+    {"role": "assistant", "content": None, "tool_calls": [...]},
+    {"role": "tool", "content": '{"status": "shipped"}', "tool_call_id": "c1"},
+    {"role": "user", "content": "When will it arrive?"},  # multiple turns are fine
+])
+```
+
+Roles: the standard `system` / `user` / `assistant` / `tool` plus `context` —
+a Trodo extension for RAG / retrieved documents. Any order, any number per
+role; aliases `developer` / `model` / `function` normalise automatically.
+Trodo embeds the input as a whole **and each role separately**, which powers
+the AI-score detectors (system → rule adherence; user → trajectory/echo;
+context else tool+assistant → grounding, contradiction, factual retention).
+A plain string still works and is embedded as one vector.
+
 ### Raw-HTTP escape hatches
 
 If your LLM client isn't OTel-instrumented and you can't wrap it as a
@@ -261,7 +285,8 @@ trodo.track_llm_call(
     model='gemini-2.5-flash', provider='google',
     input_tokens=resp['usageMetadata']['promptTokenCount'],
     output_tokens=resp['usageMetadata']['candidatesTokenCount'],
-    prompt=body, completion=resp,
+    prompt=body['messages'],  # the chat-message list sent to the model
+    completion=resp,
 )
 ```
 

{trodo_python-2.10.11 → trodo_python-2.11.0}/README.md

@@ -219,6 +219,30 @@ search = trodo.retrieval('vector_search', vector_search)
 docs = search(query)
 ```
 
+### LLM span input: the chat-message list
+
+For LLM spans, set the input to the **same messages you send to the model** —
+a chat-message list, not one blob:
+
+```python
+span.set_input([
+    {"role": "system", "content": system_prompt},        # rules & role
+    {"role": "context", "content": retrieved_docs},      # RAG docs (Trodo extension)
+    {"role": "user", "content": "Where is my order?"},
+    {"role": "assistant", "content": None, "tool_calls": [...]},
+    {"role": "tool", "content": '{"status": "shipped"}', "tool_call_id": "c1"},
+    {"role": "user", "content": "When will it arrive?"},  # multiple turns are fine
+])
+```
+
+Roles: the standard `system` / `user` / `assistant` / `tool` plus `context` —
+a Trodo extension for RAG / retrieved documents. Any order, any number per
+role; aliases `developer` / `model` / `function` normalise automatically.
+Trodo embeds the input as a whole **and each role separately**, which powers
+the AI-score detectors (system → rule adherence; user → trajectory/echo;
+context else tool+assistant → grounding, contradiction, factual retention).
+A plain string still works and is embedded as one vector.
+
 ### Raw-HTTP escape hatches
 
 If your LLM client isn't OTel-instrumented and you can't wrap it as a
@@ -230,7 +254,8 @@ trodo.track_llm_call(
     model='gemini-2.5-flash', provider='google',
     input_tokens=resp['usageMetadata']['promptTokenCount'],
     output_tokens=resp['usageMetadata']['candidatesTokenCount'],
-    prompt=body, completion=resp,
+    prompt=body['messages'],  # the chat-message list sent to the model
+    completion=resp,
 )
 ```
 

{trodo_python-2.10.11 → trodo_python-2.11.0}/pyproject.toml

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

{trodo_python-2.10.11 → trodo_python-2.11.0}/tests/test_wrap_agent_unchanged.py

@@ -47,3 +47,25 @@ def test_wrap_agent_records_error_on_exception(processor, http):
     run_payload = http.run_ingest[0]["run"]
     assert run_payload["status"] == "error"
     assert "kaboom" in run_payload["error_summary"]
+
+
+def test_set_input_passes_chat_message_list_through(processor, http):
+    messages = [
+        {"role": "system", "content": "be terse"},
+        {"role": "context", "content": ["doc chunk"]},
+        {"role": "user", "content": "q1"},
+        {"role": "assistant", "content": None, "tool_calls": [{"id": "c1", "function": {"name": "f", "arguments": "{}"}}]},
+        {"role": "tool", "content": '{"ok": true}', "tool_call_id": "c1"},
+        {"role": "user", "content": "q2"},
+    ]
+    with wrap_agent(
+        processor=processor,
+        team_site_id="site-x",
+        agent_name="chat",
+    ) as run:
+        run.set_input(messages)
+        run.set_output("done")
+
+    run_payload = http.run_ingest[0]["run"]
+    # The list must arrive as-is — no JSON stringification, no envelope.
+    assert run_payload["input"] == messages

{trodo_python-2.10.11 → trodo_python-2.11.0}/trodo/__init__.py

@@ -19,7 +19,8 @@ Raw-HTTP LLM caller (no OTel integration for your client):
         model='gemini-2.5-flash', provider='google',
         input_tokens=resp['usageMetadata']['promptTokenCount'],
         output_tokens=resp['usageMetadata']['candidatesTokenCount'],
-        prompt=body, completion=resp,
+        prompt=body['messages'],  # the chat-message list sent to the model
+        completion=resp,
     )
 
 Custom tool:
@@ -40,7 +41,7 @@ Downstream microservice (join the caller's run instead of making a new one):
 
 from __future__ import annotations
 
-__version__ = "2.10.11"
+__version__ = "2.11.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 

{trodo_python-2.10.11 → trodo_python-2.11.0}/trodo/otel/helpers.py

@@ -297,6 +297,12 @@ def llm(
     fall back to scalar-only extraction, or ``extract_usage_map=lambda r: {..}``
     to build the map yourself.
 
+    The wrapped function's arguments become the span input. For the AI-score
+    detectors to see per-role content, pass the model call's chat-message list
+    (``[{"role", "content"}, ...]`` — roles system/user/assistant/tool +
+    ``context`` for RAG docs) so the span input is exactly what the model
+    receives.
+
     Usage::
 
         answer = trodo.llm(
@@ -470,12 +476,18 @@ def track_llm_call(
     ``usage_details`` map, or a raw provider ``usage`` object to auto-extract
     from (e.g. ``resp['usage']`` or ``resp['usageMetadata']``).
 
+    ``prompt`` — prefer the chat-message list you sent to the model
+    (``[{"role", "content"}, ...]``, roles system/user/assistant/tool +
+    ``context`` for RAG docs, any order, multiple per role). The backend
+    embeds each role separately, which powers the AI-score detectors. A plain
+    string or dict is stored as one opaque input.
+
     Usage:
         resp = httpx.post(url, json=body).json()
         trodo.track_llm_call(
             model='claude-sonnet-4', provider='anthropic',
             usage=resp['usage'],          # cache fields captured automatically
-            prompt=body, completion=resp,
+            prompt=body['messages'], completion=resp,
         )
     """
     if get_active_context() is None:

{trodo_python-2.10.11 → trodo_python-2.11.0}/trodo/otel/wrap_agent.py

@@ -29,7 +29,7 @@ import time
 import traceback
 import uuid
 from datetime import datetime, timezone
-from typing import Any, Callable, Dict, Optional, Union
+from typing import Any, Callable, Dict, List, Optional, Union
 
 from .context import ActiveSpanContext, get_active_context, run_with_context
 from .processor import TrodoSpanProcessor, TrodoRun, TrodoSpan
@@ -149,16 +149,19 @@ def _resolve_error(handle, exc_type, exc, tb) -> Dict[str, Optional[str]]:
             "status_code": None, "stack_trace": None, "level": None}
 
 
-def _prepare_value(value: Any, max_len: int = _MAX_VALUE_LEN) -> Optional[Union[str, Dict[str, Any]]]:
+def _prepare_value(value: Any, max_len: int = _MAX_VALUE_LEN) -> Optional[Union[str, Dict[str, Any], List[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.
+    Dicts/lists pass through as-is (stored as JSONB objects/arrays). For LLM
+    span inputs, prefer a chat-message list ``[{"role", "content"}, ...]``
+    (roles system/user/assistant/tool + ``context`` for RAG docs, any order,
+    multiple per role) — the backend embeds each role separately and the
+    AI-score detectors key on them. Strings are truncated at max_len.
     Everything else is JSON-serialised then truncated.
     """
     if value is None:
         return None
-    if isinstance(value, dict):
+    if isinstance(value, (dict, list)):
         return value
     if isinstance(value, str):
         return value[:max_len] if len(value) > max_len else value
@@ -248,6 +251,9 @@ class RunHandle:
         self.error_type: Optional[str] = None
 
     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."""
         self.input = _prepare_value(value)
 
     def set_output(self, value: Any) -> None:
@@ -337,6 +343,11 @@ class SpanHandle:
         return self.error_message is not None or self.error_type is not None
 
     def set_input(self, value: Any) -> None:
+        """Set the span input. For LLM spans prefer a chat-message list
+        ``[{"role", "content"}, ...]`` (roles system/user/assistant/tool +
+        ``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.input = _prepare_value(value)
 
     def set_output(self, value: Any) -> None:

{trodo_python-2.10.11 → trodo_python-2.11.0}/trodo_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.10.11
+Version: 2.11.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side
@@ -250,6 +250,30 @@ search = trodo.retrieval('vector_search', vector_search)
 docs = search(query)
 ```
 
+### LLM span input: the chat-message list
+
+For LLM spans, set the input to the **same messages you send to the model** —
+a chat-message list, not one blob:
+
+```python
+span.set_input([
+    {"role": "system", "content": system_prompt},        # rules & role
+    {"role": "context", "content": retrieved_docs},      # RAG docs (Trodo extension)
+    {"role": "user", "content": "Where is my order?"},
+    {"role": "assistant", "content": None, "tool_calls": [...]},
+    {"role": "tool", "content": '{"status": "shipped"}', "tool_call_id": "c1"},
+    {"role": "user", "content": "When will it arrive?"},  # multiple turns are fine
+])
+```
+
+Roles: the standard `system` / `user` / `assistant` / `tool` plus `context` —
+a Trodo extension for RAG / retrieved documents. Any order, any number per
+role; aliases `developer` / `model` / `function` normalise automatically.
+Trodo embeds the input as a whole **and each role separately**, which powers
+the AI-score detectors (system → rule adherence; user → trajectory/echo;
+context else tool+assistant → grounding, contradiction, factual retention).
+A plain string still works and is embedded as one vector.
+
 ### Raw-HTTP escape hatches
 
 If your LLM client isn't OTel-instrumented and you can't wrap it as a
@@ -261,7 +285,8 @@ trodo.track_llm_call(
     model='gemini-2.5-flash', provider='google',
     input_tokens=resp['usageMetadata']['promptTokenCount'],
     output_tokens=resp['usageMetadata']['candidatesTokenCount'],
-    prompt=body, completion=resp,
+    prompt=body['messages'],  # the chat-message list sent to the model
+    completion=resp,
 )
 ```
 

{trodo_python-2.10.11 → trodo_python-2.11.0}/trodo_python.egg-info/SOURCES.txt

@@ -1,6 +1,5 @@
 README.md
 pyproject.toml
-tests/test_anon_distinct_id 2.py
 tests/test_anon_distinct_id.py
 tests/test_auto_instrument_fixes.py
 tests/test_cross_process_session.py

trodo_python-2.10.11/tests/test_anon_distinct_id 2.py

@@ -1,100 +0,0 @@
-"""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"