trodo-python 2.13.0__tar.gz → 2.15.0__tar.gz

{trodo_python-2.13.0 → trodo_python-2.15.0}/PKG-INFO

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

{trodo_python-2.13.0 → trodo_python-2.15.0}/pyproject.toml

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

trodo_python-2.15.0/tests/test_prompt_trace.py

@@ -0,0 +1,107 @@
+"""Prompt -> span traceability (mirrors the Node promptTrace.test.ts).
+
+Compiling a managed prompt inside a wrap_agent/span scope must stamp the exact
+version (by immutable hash) onto the emitted span, and aggregate every prompt
+used onto the run. Outside a run, it's a silent no-op.
+"""
+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"]

{trodo_python-2.13.0 → trodo_python-2.15.0}/trodo/__init__.py

@@ -41,7 +41,7 @@ Downstream microservice (join the caller's run instead of making a new one):
 
 from __future__ import annotations
 
-__version__ = "2.13.0"
+__version__ = "2.15.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 

{trodo_python-2.13.0 → trodo_python-2.15.0}/trodo/managers/prompt_manager.py

@@ -16,7 +16,7 @@ from __future__ import annotations
 
 import threading
 import time
-from typing import Any, Callable, Dict, List, Optional, Set
+from typing import Any, Callable, Dict, List, Optional, Set, Union
 
 from ..prompts.compile import CompileError, compile_prompt
 from ..prompts.template import TemplateError, render
@@ -38,7 +38,7 @@ __all__ = [
 DEFAULT_TTL_SECONDS = 60.0
 
 
-def _cache_key(name: str, version: Optional[int], label: Optional[str]) -> str:
+def _cache_key(name: str, version: Optional[Union[int, str]], label: Optional[str]) -> str:
     # Resolution happens server-side on every fetch; the client only caches
     # under whatever selector was asked for. So a label flip propagates within
     # one TTL without the client knowing anything about labels.
@@ -67,12 +67,19 @@ def _to_variables(raw: Any) -> List[PromptVariable]:
     return out
 
 
-def _to_prompt(raw: Dict[str, Any], is_fallback: bool = False) -> ManagedPrompt:
+def _to_prompt(
+    raw: Dict[str, Any],
+    is_fallback: bool = False,
+    trace_label: Optional[str] = None,
+) -> ManagedPrompt:
     return ManagedPrompt(
         name=str(raw.get("name") or ""),
         description=raw.get("description"),
         tags=list(raw.get("tags") or []),
         version=int(raw.get("version") or 0),
+        version_hash=raw.get("version_hash"),
+        content_hash=raw.get("content_hash"),
+        parent_hash=raw.get("parent_hash"),
         labels=list(raw.get("labels") or []),
         messages=list(raw.get("messages") or []),
         model=dict(raw.get("model") or {}),
@@ -81,6 +88,7 @@ def _to_prompt(raw: Dict[str, Any], is_fallback: bool = False) -> ManagedPrompt:
         variables=_to_variables(raw.get("variables")),
         updated_at=raw.get("updated_at") or raw.get("updatedAt"),
         is_fallback=is_fallback,
+        trace_label=trace_label,
     )
 
 
@@ -172,7 +180,7 @@ class PromptManager:
         self,
         name: str,
         label: Optional[str] = None,
-        version: Optional[int] = None,
+        version: Optional[Union[int, str]] = None,
         cache_ttl_seconds: Optional[float] = None,
         fallback: Optional[Dict[str, Any]] = None,
         max_retries: int = 2,
@@ -181,7 +189,8 @@ class PromptManager:
 
         Without arguments you get the version labelled ``production``; pass
         ``label`` to follow a different deploy label, or ``version`` to pin
-        exactly.
+        exactly. ``version`` may be the integer ``version_no`` or a
+        ``version_hash`` (full, or an unambiguous short prefix like ``a3f9c2``).
 
         Availability ladder — fresh cache -> stale cache -> ``fallback`` ->
         raise. A prompt fetch is on your hot path, so a Trodo outage degrades
@@ -200,6 +209,10 @@ class PromptManager:
 
         key = _cache_key(name, version, label)
         ttl = DEFAULT_TTL_SECONDS if cache_ttl_seconds is None else float(cache_ttl_seconds)
+        # The deploy label this fetch followed, for prompt traceability. Explicit
+        # label wins; with neither label nor version pinned the SDK follows
+        # ``production``; a version pin has no label (the hash is the identity).
+        trace_label = label if label else ("production" if version is None else None)
 
         def fetcher() -> Dict[str, Any]:
             res = _with_retry(
@@ -219,24 +232,24 @@ class PromptManager:
         if ttl > 0:
             fresh = self._cache.get_fresh(key)
             if fresh is not None:
-                return _to_prompt(fresh)
+                return _to_prompt(fresh, trace_label=trace_label)
 
             stale = self._cache.get_stale(key)
             if stale is not None:
                 # Serve immediately, refresh behind the caller's back. A slow or
                 # dead API costs latency on nobody's request.
                 self._cache.revalidate(key, fetcher, ttl)
-                return _to_prompt(stale)
+                return _to_prompt(stale, trace_label=trace_label)
 
         try:
             raw = fetcher()
             if ttl > 0:
                 self._cache.set(key, raw, ttl)
-            return _to_prompt(raw)
+            return _to_prompt(raw, trace_label=trace_label)
         except Exception:
             stale = self._cache.get_stale(key)
             if stale is not None:
-                return _to_prompt(stale)
+                return _to_prompt(stale, trace_label=trace_label)
             if fallback:
                 return _to_prompt(
                     {

{trodo_python-2.13.0 → trodo_python-2.15.0}/trodo/otel/auto_instrument.py

@@ -14,6 +14,7 @@ from datetime import datetime, timezone
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
 from .context import get_active_context
+from .prompt_trace import prompt_attributes
 from .processor import TrodoSpan, TrodoSpanProcessor
 
 # Always-on, one-shot warnings. Silent skips (missing opentelemetry-sdk) are the
@@ -376,6 +377,14 @@ class _OtelAdapter(_SpanProcessorBase):  # type: ignore[valid-type,misc]
                 set_attr(_ATTR_TRODO_RUN_ID, ctx.run_id)
                 if ctx.span_id:
                     set_attr(_ATTR_TRODO_PARENT_SPAN_ID, ctx.span_id)
+                # Prompt traceability: stamp the exact managed-prompt version
+                # compiled just before this (auto-instrumented) provider call.
+                # Pinned by immutable version_hash, so a later label move never
+                # rewrites what a past span ran.
+                state = getattr(ctx, "prompt_state", None)
+                current = state.get("current") if isinstance(state, dict) else None
+                for k, v in prompt_attributes(current).items():
+                    set_attr(k, v)
         except Exception:
             pass  # never break user code
 

{trodo_python-2.13.0 → trodo_python-2.15.0}/trodo/otel/context.py

@@ -16,6 +16,10 @@ class ActiveSpanContext:
     parent_span_id: Optional[str]
     team_site_id: str
     processor: object  # TrodoSpanProcessor — avoid circular import
+    # Per-run prompt-traceability accumulator ({"current", "all"}), shared by
+    # reference across the run's whole span tree. Records which managed prompt
+    # version each span used. See otel/prompt_trace.py.
+    prompt_state: Optional[dict] = None
 
 
 _active: contextvars.ContextVar[Optional[ActiveSpanContext]] = contextvars.ContextVar(

{trodo_python-2.13.0 → trodo_python-2.15.0}/trodo/otel/processor.py

@@ -33,6 +33,9 @@ class TrodoRun:
     # free-text error_summary).
     error_type: Optional[str] = None
     metadata: Optional[Dict[str, Any]] = None
+    # Free-form run-level attributes (e.g. {"trodo.prompts": [...]} — the set of
+    # managed-prompt versions used across the run, for prompt traceability).
+    attributes: Optional[Dict[str, Any]] = None
     # Aggregates summed from child spans at finalisation.
     total_tokens_in: Optional[int] = None
     total_tokens_out: Optional[int] = None

trodo_python-2.15.0/trodo/otel/prompt_trace.py

@@ -0,0 +1,94 @@
+"""Prompt -> span traceability.
+
+When a managed prompt is compiled inside a ``wrap_agent`` / ``span`` scope, we
+record which exact version was used so every span emitted in that scope carries
+it. The identity is the immutable ``version_hash`` — so a span always shows the
+exact version that ran, even if a deploy label (e.g. ``production``) is later
+moved to a different version.
+
+The link is best-effort and never raises: if there is no active run context
+(the prompt was compiled outside ``wrap_agent``), recording is a silent no-op.
+
+Mirrors ``sdks/trodo-node-sdk/src/otel/promptTrace.ts``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .context import get_active_context
+
+# A PromptRef is a plain dict: {name, version_hash?, content_hash?, label?}.
+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": []}
+
+
+def _ref_key(ref: PromptRef) -> str:
+    return ref.get("version_hash") or ref.get("name") or ""
+
+
+def record_compiled_prompt(ref: PromptRef) -> None:
+    """Record that a prompt was just compiled.
+
+    Updates the active run's prompt state (most-recent + the deduped set) and,
+    in OTLP mode where a real OpenTelemetry span is current, stamps that span.
+    """
+    if not ref or not ref.get("name"):
+        return
+    active = get_active_context()
+    state = getattr(active, "prompt_state", None) if active is not None else None
+    if isinstance(state, dict):
+        state["current"] = ref
+        key = _ref_key(ref)
+        used: List[PromptRef] = state["all"]
+        if not any(_ref_key(r) == key for r in used):
+            used.append(ref)
+    _stamp_active_otel_span(ref)
+
+
+def prompt_attributes(ref: Optional[PromptRef]) -> Dict[str, str]:
+    """Flatten a PromptRef to primitive span attributes (None values omitted)."""
+    out: Dict[str, str] = {}
+    if not ref or not ref.get("name"):
+        return out
+    out["trodo.prompt.name"] = ref["name"]
+    if ref.get("version_hash"):
+        out["trodo.prompt.version_hash"] = ref["version_hash"]
+    if ref.get("label"):
+        out["trodo.prompt.label"] = ref["label"]
+    if ref.get("content_hash"):
+        out["trodo.prompt.content_hash"] = ref["content_hash"]
+    return out
+
+
+def merge_prompt_attrs(
+    active: Any, attrs: Optional[Dict[str, Any]]
+) -> Optional[Dict[str, Any]]:
+    """Merge the active run's most-recently-compiled prompt into span attributes."""
+    merged: Dict[str, Any] = dict(attrs or {})
+    state = getattr(active, "prompt_state", None) if active is not None else None
+    if isinstance(state, dict):
+        merged.update(prompt_attributes(state.get("current")))
+    return merged or None
+
+
+def _stamp_active_otel_span(ref: PromptRef) -> None:
+    """OTLP mode only: stamp the current real OTel span, if one exists.
+
+    Wrapped in try/except — ``opentelemetry`` is an optional dependency present
+    only when the user runs in OTLP mode.
+    """
+    try:
+        from opentelemetry import trace  # type: ignore
+
+        span = trace.get_current_span()
+        if span is None:
+            return
+        for k, v in prompt_attributes(ref).items():
+            span.set_attribute(k, v)
+    except Exception:  # noqa: BLE001
+        pass  # not in OTLP mode / opentelemetry not installed — no-op

{trodo_python-2.13.0 → trodo_python-2.15.0}/trodo/otel/wrap_agent.py

@@ -32,6 +32,7 @@ from datetime import datetime, timezone
 from typing import Any, Callable, Dict, List, Optional, Union
 
 from .context import ActiveSpanContext, get_active_context, run_with_context
+from .prompt_trace import merge_prompt_attrs, new_prompt_state
 from .processor import TrodoSpanProcessor, TrodoRun, TrodoSpan
 from .transport import get_transport_mode, get_otel_tracer, get_otel_helpers
 
@@ -515,6 +516,7 @@ class wrap_agent:
         self._parent_run_id = parent_run_id
         self._metadata = metadata
         self._ctx_mgr: Optional[run_with_context] = None
+        self._ctx: Optional[ActiveSpanContext] = None
         self._started_ms: float = 0.0
         self._started_iso: str = ""
         self.handle: Optional[RunHandle] = None
@@ -551,7 +553,9 @@ class wrap_agent:
             parent_span_id=None,
             team_site_id=self._team_site_id,
             processor=self._processor,
+            prompt_state=new_prompt_state(),
         )
+        self._ctx = ctx
         self._ctx_mgr = run_with_context(ctx)
         self._ctx_mgr.__enter__()
         return self.handle
@@ -596,6 +600,13 @@ class wrap_agent:
             error_summary=error_summary,
             error_type=error_type,
             metadata={**(self._metadata or {}), **self.handle.metadata} or None,
+            attributes=(
+                {"trodo.prompts": self._ctx.prompt_state["all"]}
+                if self._ctx is not None
+                and self._ctx.prompt_state
+                and self._ctx.prompt_state["all"]
+                else None
+            ),
             total_tokens_in=agg["total_tokens_in"],
             total_tokens_out=agg["total_tokens_out"],
             total_cost=agg["total_cost"],
@@ -709,6 +720,7 @@ class join_run:
         self._input = _prepare_value(input) if input is not None else None
         self._attributes = attributes
         self._ctx_mgr: Optional[run_with_context] = None
+        self._ctx: Optional[ActiveSpanContext] = None
         self._started_ms: float = 0.0
         self._started_iso: str = ""
         self._span_id: str = ""
@@ -731,7 +743,9 @@ class join_run:
             parent_span_id=self._parent_span_id,
             team_site_id=self._team_site_id,
             processor=self._processor,
+            prompt_state=new_prompt_state(),
         )
+        self._ctx = ctx
         self._ctx_mgr = run_with_context(ctx)
         self._ctx_mgr.__enter__()
         return self.handle
@@ -771,7 +785,7 @@ class join_run:
             cost_details=self.handle.cost_details,
             temperature=self.handle.temperature,
             tool_name=self.handle.tool_name,
-            attributes=self.handle.attributes or None,
+            attributes=merge_prompt_attrs(self._ctx, self.handle.attributes),
         )
         try:
             self._processor.append_spans(self._run_id, [trodo_span])
@@ -833,6 +847,7 @@ class span:
             parent_span_id=self._active.span_id,
             team_site_id=self._active.team_site_id,
             processor=self._active.processor,
+            prompt_state=self._active.prompt_state,
         )
         self._ctx_mgr = run_with_context(child)
         self._ctx_mgr.__enter__()
@@ -877,7 +892,7 @@ class span:
             cost_details=self.handle.cost_details,
             temperature=self.handle.temperature,
             tool_name=self.handle.tool_name,
-            attributes=self.handle.attributes or None,
+            attributes=merge_prompt_attrs(self._active, self.handle.attributes),
         )
         processor: TrodoSpanProcessor = self._active.processor  # type: ignore[assignment]
         processor.enqueue_span(trodo_span)

{trodo_python-2.13.0 → trodo_python-2.15.0}/trodo/prompts/types.py

@@ -59,6 +59,13 @@ class ManagedPrompt:
     response_format: Optional[ResponseFormat] = None
     variables: List[PromptVariable] = field(default_factory=list)
     version: int = 0
+    #: Git-style commit id of this version (content + parent + message + author
+    #: + time). Stable and immutable — the recommended way to reference a version.
+    version_hash: Optional[str] = None
+    #: sha256 of the content; identical content shares it.
+    content_hash: Optional[str] = None
+    #: The preceding version's ``version_hash`` (None for the first).
+    parent_hash: Optional[str] = None
     labels: List[str] = field(default_factory=list)
     tags: List[str] = field(default_factory=list)
     description: Optional[str] = None
@@ -66,6 +73,10 @@ class ManagedPrompt:
     #: True when this came from the ``fallback`` argument because the API was
     #: unreachable and nothing was cached.
     is_fallback: bool = False
+    #: The deploy label this fetch followed (for prompt traceability). Set by
+    #: PromptManager.get(); not part of the wire contract. ``repr=False`` /
+    #: ``compare=False`` so it never affects equality or reprs.
+    trace_label: Optional[str] = field(default=None, repr=False, compare=False)
 
     def compile(self, variables: Optional[Dict[str, Any]] = None, **kwargs: Any) -> CompiledPrompt:
         """Compile with variable values, as a dict or as keyword arguments."""
@@ -73,7 +84,25 @@ class ManagedPrompt:
 
         values = dict(variables or {})
         values.update(kwargs)
-        return compile_prompt(self, values)
+        compiled = compile_prompt(self, values)
+        # Prompt traceability: record the exact version compiled so any span
+        # emitted in the surrounding wrap_agent/span scope carries it. No-op
+        # outside a run context. Never records a fallback (no real hash).
+        if not self.is_fallback:
+            try:
+                from ..otel.prompt_trace import record_compiled_prompt
+
+                record_compiled_prompt(
+                    {
+                        "name": self.name,
+                        "version_hash": self.version_hash,
+                        "content_hash": self.content_hash,
+                        "label": self.trace_label,
+                    }
+                )
+            except Exception:  # noqa: BLE001
+                pass  # traceability must never break compile
+        return compiled
 
 
 @dataclass

{trodo_python-2.13.0 → trodo_python-2.15.0}/trodo_python.egg-info/PKG-INFO

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

{trodo_python-2.13.0 → trodo_python-2.15.0}/trodo_python.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ tests/test_end_run.py
 tests/test_error_enrichment.py
 tests/test_llm_usage_cost.py
 tests/test_processor_methods.py
+tests/test_prompt_trace.py
 tests/test_prompts.py
 tests/test_register_otel.py
 tests/test_start_run.py
@@ -30,6 +31,7 @@ trodo/otel/auto_instrument.py
 trodo/otel/context.py
 trodo/otel/helpers.py
 trodo/otel/processor.py
+trodo/otel/prompt_trace.py
 trodo/otel/register.py
 trodo/otel/transport.py
 trodo/otel/wrap_agent.py