trodo-python 2.14.0__py3-none-any.whl → 2.16.0__py3-none-any.whl

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.16.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -119,6 +119,9 @@ __all__ = [
     "TemplateError",
     "ManagedPrompt",
     "PromptSummary",
+    # Datasets & experiments ingest
+    "append_dataset",
+    "ingest_experiment",
 ]
 
 # ============================================================================
@@ -344,6 +347,64 @@ def render_template(
     return _render_template(template, merged, strict=strict)
 
 
+# ----------------------------------------------------------------------------
+# Datasets & experiments ingest
+# ----------------------------------------------------------------------------
+
+def append_dataset(
+    ref: str,
+    items: Union[Dict[str, Any], List[Dict[str, Any]]],
+    create: bool = True,
+) -> Dict[str, Any]:
+    """Append items to a dataset by UUID or name.
+
+    *items* is a list of dicts shaped ``{"input": {<var>: value, ...},
+    "expected_output"?: str, "metadata"?: dict, "source_trace_ref"?: dict}``;
+    a single dict is accepted and wrapped. When *ref* is a name that doesn't
+    exist, ``create=True`` (default) auto-creates the dataset::
+
+        trodo.append_dataset("support-eval", [
+            {"input": {"q": "where is my order"}, "expected_output": "tracking link"},
+        ])
+
+    Returns ``{"dataset_id", "dataset_name", "appended", "item_count"}``.
+    """
+    return _get_client().datasets.append(ref, items, create=create)
+
+
+def ingest_experiment(
+    dataset: str,
+    outputs: List[Dict[str, Any]],
+    name: Optional[str] = None,
+    task_name: Optional[str] = None,
+    judge: Optional[Dict[str, Any]] = None,
+    evaluator_ids: Optional[List[str]] = None,
+    dataset_version_no: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Ingest a batch of model *outputs* for *dataset* and grade them.
+
+    *outputs* is a list of dicts shaped ``{"item_position": int, "output": str,
+    "expected_output"?, "query"?, "context"?, "cost_usd"?, "latency_ms"?}``.
+    Configure grading with ``judge`` (``{"credential_id", "provider", "model"}``)
+    and/or ``evaluator_ids``::
+
+        exp = trodo.ingest_experiment("support-eval", [
+            {"item_position": 0, "output": "here is your tracking link"},
+        ], judge={"credential_id": "cred_1", "provider": "openai", "model": "gpt-4o"})
+
+    Returns the experiment dict.
+    """
+    return _get_client().experiments.ingest(
+        dataset,
+        outputs,
+        name=name,
+        task_name=task_name,
+        judge=judge,
+        evaluator_ids=evaluator_ids,
+        dataset_version_no=dataset_version_no,
+    )
+
+
 def enable_auto_events() -> None:
     _get_client().enable_auto_events()
 

trodo/api/endpoints.py

@@ -23,3 +23,6 @@ RUNS_INGEST = "/api/sdk/runs/ingest"
 RUNS_START = "/api/sdk/runs/start"
 RUNS_BASE = "/api/sdk/runs"  # /runs/{run_id}/end, /spans, /feedback
 OTLP_TRACES = "/api/sdk/otel/v1/traces"
+# Datasets & experiments ingest
+DATASETS_BASE = "/api/sdk/datasets"  # /datasets/{ref}/items
+EXPERIMENTS_INGEST = "/api/sdk/experiments/ingest"

trodo/api/http_client.py

@@ -133,6 +133,16 @@ class HttpClient:
     def list_prompts(self) -> ApiResult:
         return self._get("/api/sdk/prompts")
 
+    def append_dataset_items(self, ref: str, body: Dict[str, Any]) -> ApiResult:
+        """Append items to a dataset by UUID or name (name is URL-encoded)."""
+        from urllib.parse import quote
+        return self._request(
+            f"/api/sdk/datasets/{quote(str(ref), safe='')}/items", body
+        )
+
+    def ingest_experiment(self, body: Dict[str, Any]) -> ApiResult:
+        return self._request("/api/sdk/experiments/ingest", body)
+
     def post_track(self, session_data: Dict[str, Any]) -> ApiResult:
         return self._request("/api/sdk/track", {"sessionData": session_data})
 

trodo/client.py

@@ -77,6 +77,8 @@ class TrodoClient:
 
         self._session_manager = SessionManager()
         self._prompts = None  # lazily-built PromptManager
+        self._datasets = None  # lazily-built DatasetManager
+        self._experiments = None  # lazily-built ExperimentManager
 
         if batch_enabled:
             self._event_queue: Optional[EventQueue] = EventQueue(batch_size)
@@ -125,6 +127,22 @@ class TrodoClient:
             self._prompts = PromptManager(self._http)
         return self._prompts
 
+    @property
+    def datasets(self):
+        """Append items to the team's evaluation datasets."""
+        if self._datasets is None:
+            from .managers.dataset_manager import DatasetManager
+            self._datasets = DatasetManager(self._http)
+        return self._datasets
+
+    @property
+    def experiments(self):
+        """Ingest experiment result batches for server-side grading."""
+        if self._experiments is None:
+            from .managers.experiment_manager import ExperimentManager
+            self._experiments = ExperimentManager(self._http)
+        return self._experiments
+
     # --------------------------------------------------------------------------
     # Primary pattern: for_user()
     # --------------------------------------------------------------------------

trodo/managers/dataset_manager.py

@@ -0,0 +1,74 @@
+"""Dataset ingest — append evaluation items to a Trodo dataset.
+
+Datasets are the fixed inputs an experiment runs against: each item is a set of
+variable values (``input``) plus an optional gold answer (``expected_output``)
+and free-form ``metadata``. This manager appends items to a dataset addressed by
+UUID or by name; when a name is used and no such dataset exists it is
+auto-created (``create=True``, the default), so a first append bootstraps the
+dataset without a separate create call.
+
+Mirrors ``sdks/trodo-node-sdk/src/managers/DatasetManager.ts`` in shape.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Union
+
+__all__ = ["DatasetManager"]
+
+# The optional per-item fields, in wire order. ``input`` is always required.
+_ITEM_OPTIONAL = ("expected_output", "metadata", "source_trace_ref")
+
+
+def _clean_item(item: Dict[str, Any]) -> Dict[str, Any]:
+    if not isinstance(item, dict):
+        raise ValueError("trodo: each dataset item must be a dict")
+    if "input" not in item or item["input"] is None:
+        raise ValueError("trodo: each dataset item requires an 'input' dict")
+    out: Dict[str, Any] = {"input": item["input"]}
+    for key in _ITEM_OPTIONAL:
+        if item.get(key) is not None:
+            out[key] = item[key]
+    return out
+
+
+class DatasetManager:
+    """Append items to the team's evaluation datasets."""
+
+    def __init__(self, http_client: Any) -> None:
+        self._http = http_client
+
+    def append(
+        self,
+        ref: str,
+        items: Union[Dict[str, Any], List[Dict[str, Any]]],
+        create: bool = True,
+    ) -> Dict[str, Any]:
+        """Append one or more items to the dataset *ref* (a UUID or a name).
+
+        *items* is a list of dicts shaped ``{"input": {<var>: value, ...},
+        "expected_output"?: str, "metadata"?: dict, "source_trace_ref"?: dict}``;
+        a single dict is accepted and wrapped into a one-item list. ``None``
+        optional fields are dropped from the wire payload.
+
+        When *ref* is a name that doesn't exist yet, ``create=True`` (default)
+        auto-creates the dataset; pass ``create=False`` to require it to exist.
+
+        Returns the parsed response dict:
+        ``{"dataset_id", "dataset_name", "appended", "item_count"}``.
+
+        :raises ValueError: if *ref* is empty, *items* is empty, or an item has
+            no ``input``.
+        """
+        if not ref:
+            raise ValueError("trodo: append_dataset(ref) requires a dataset ref")
+        if isinstance(items, dict):
+            items = [items]
+        if not items:
+            raise ValueError("trodo: append_dataset(ref, items) requires items")
+
+        body = {
+            "items": [_clean_item(i) for i in items],
+            "create": bool(create),
+        }
+        return self._http.append_dataset_items(ref, body)

trodo/managers/experiment_manager.py

@@ -0,0 +1,105 @@
+"""Experiment ingest — record a batch of model outputs against a dataset.
+
+An experiment takes a dataset (the fixed inputs) and a set of *outputs* your
+model produced for each item, then grades them server-side using the judge
+and/or evaluators you name. You run the model yourself and hand Trodo the
+results; Trodo scores and stores them so runs are comparable over time.
+
+``outputs`` are matched to dataset items by ``item_position`` (0-based),
+carrying the produced ``output`` and optional per-row context (``query``,
+``context``), cost/latency telemetry, and a per-row ``expected_output`` override.
+
+Mirrors ``sdks/trodo-node-sdk/src/managers/ExperimentManager.ts`` in shape.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+__all__ = ["ExperimentManager"]
+
+# Optional per-output fields, in wire order. ``item_position`` + ``output`` are
+# always required.
+_OUTPUT_OPTIONAL = (
+    "expected_output",
+    "query",
+    "context",
+    "cost_usd",
+    "latency_ms",
+)
+
+
+def _clean_output(output: Dict[str, Any]) -> Dict[str, Any]:
+    if not isinstance(output, dict):
+        raise ValueError("trodo: each experiment output must be a dict")
+    if output.get("item_position") is None:
+        raise ValueError("trodo: each output requires an 'item_position' (int)")
+    if output.get("output") is None:
+        raise ValueError("trodo: each output requires an 'output' (str)")
+    out: Dict[str, Any] = {
+        "item_position": output["item_position"],
+        "output": output["output"],
+    }
+    for key in _OUTPUT_OPTIONAL:
+        if output.get(key) is not None:
+            out[key] = output[key]
+    return out
+
+
+class ExperimentManager:
+    """Ingest experiment result batches for server-side grading."""
+
+    def __init__(self, http_client: Any) -> None:
+        self._http = http_client
+
+    def ingest(
+        self,
+        dataset: str,
+        outputs: List[Dict[str, Any]],
+        name: Optional[str] = None,
+        task_name: Optional[str] = None,
+        judge: Optional[Dict[str, Any]] = None,
+        evaluator_ids: Optional[List[str]] = None,
+        dataset_version_no: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Ingest a batch of *outputs* for *dataset* and return the experiment.
+
+        *dataset* is a dataset name or UUID. *outputs* is a list of dicts shaped
+        ``{"item_position": int, "output": str, "expected_output"?, "query"?,
+        "context"?, "cost_usd"?, "latency_ms"?}``. ``None`` optional fields are
+        dropped from the wire payload.
+
+        Grading is configured server-side: pass ``judge`` (``{"credential_id",
+        "provider", "model"}``) for an LLM judge and/or ``evaluator_ids`` for
+        named evaluators. ``dataset_version_no`` pins the dataset version graded
+        against.
+
+        Returns the experiment dict from ``{"experiment": {...}}``.
+
+        :raises ValueError: if *dataset* is empty, *outputs* is empty, or an
+            output is missing ``item_position``/``output``.
+        """
+        if not dataset:
+            raise ValueError("trodo: ingest_experiment(dataset) requires a dataset")
+        if not outputs:
+            raise ValueError("trodo: ingest_experiment requires outputs")
+
+        body: Dict[str, Any] = {
+            "dataset": dataset,
+            "outputs": [_clean_output(o) for o in outputs],
+        }
+        if name is not None:
+            body["name"] = name
+        if task_name is not None:
+            body["task_name"] = task_name
+        if judge is not None:
+            body["judge"] = judge
+        if evaluator_ids is not None:
+            body["evaluator_ids"] = evaluator_ids
+        if dataset_version_no is not None:
+            body["dataset_version_no"] = dataset_version_no
+
+        res = self._http.ingest_experiment(body)
+        if isinstance(res, dict) and "experiment" in res:
+            return res["experiment"]
+        return res

trodo/managers/prompt_manager.py

@@ -67,7 +67,11 @@ 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"),
@@ -84,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,
     )
 
 
@@ -204,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(
@@ -223,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/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/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/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/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/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/prompts/types.py

@@ -73,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."""
@@ -80,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.14.0.dist-info → trodo_python-2.16.0.dist-info}/METADATA

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

{trodo_python-2.14.0.dist-info → trodo_python-2.16.0.dist-info}/RECORD

@@ -1,36 +1,39 @@
-trodo/__init__.py,sha256=9VvBIbahXhuKln5593dCq29dan1IN7xFHU0voW4SDqs,21167
-trodo/client.py,sha256=z2q1HZKQNENycv9CRD0kOfwEhmz3Ti9_B-uPsqpvY3U,19454
+trodo/__init__.py,sha256=V2vh8SxMkgOaBdowPlHzx_2hpX4T1lUlS2JmE6usz3M,23362
+trodo/client.py,sha256=syz4zzWokdBaFNnO5QhYnUKVNHf8KaunofVFc1ODohI,20187
 trodo/types.py,sha256=eySgUvCXROG2TxtxgiU0MNr5iH0DEcduK8bmYtTKG44,3138
 trodo/user_context.py,sha256=9la6azzwEanVmdP4ps_xMoufbeWVeIGU-M8ychmgajg,7859
 trodo/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/api/async_client.py,sha256=rZN4aJ2QiKyrHBK260bApCUB9JaMWU6BQtzoSJZh7xk,3408
-trodo/api/endpoints.py,sha256=HKQ3d_Mxf0y4HwlHor0XkSAwUVj-4Xvv--rzE9njxjM,1027
-trodo/api/http_client.py,sha256=gVYVqn-M4Mjd0zTjx_Zsr246BL_xvIHOa2w8YlpVvD4,7638
+trodo/api/endpoints.py,sha256=JVTn5l1U-7U2ibQoR9M_AjRgK6GMRgSx_DkV4opWouo,1171
+trodo/api/http_client.py,sha256=rWeRLqVXQ-iXgAIzg6701WtK5eSlPZTTJgKZFerLZhs,8085
 trodo/auto/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/auto/auto_event_manager.py,sha256=cztuRsRkNoJE5R4NfSfTrTJTGl4jx2Yb-Ncy0aVAPo8,4247
 trodo/managers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trodo/managers/dataset_manager.py,sha256=gx0S8ujG3cbw4IskBNMdceBjDbcEh_nebwKSzEvm7hE,2827
+trodo/managers/experiment_manager.py,sha256=9GO1JUuV7FykaPfZXI8NVvEBDS2CZuyw9I3ywCrZBTI,3916
 trodo/managers/group_manager.py,sha256=ki3Se3qEoSZfREX63oeDeBmEfZF-ISHLE8azEtLg0tM,3542
 trodo/managers/people_manager.py,sha256=mMVnx40Mlifx6NGgChvohC9ViK6dQu2mkXNHbV8pK1E,2882
-trodo/managers/prompt_manager.py,sha256=kyQFdty7l7w7ngzsHw6zs1bgL4oa1Lj3ugMPxakrMqM,10719
+trodo/managers/prompt_manager.py,sha256=jFHkdvDSxvvb9c53EQvBQygdDJ7X-ylNWEY_ag_SeC0,11227
 trodo/otel/__init__.py,sha256=yiRFXWUU45bAM2CV37XeO7zf1hmnmjufdP4XO50yEyE,624
-trodo/otel/auto_instrument.py,sha256=hJesQMOOp86U66PampcGNINmBVvwVuU_WHVrbUMauug,20895
-trodo/otel/context.py,sha256=iJ1rE42-SbO8VZHAxhIl2ZJXgNwLIVps5xLg8GKgfFc,1165
+trodo/otel/auto_instrument.py,sha256=Iae9A9lvh2PImE6gqnyEMXeRPRpjTxZcxx1zW2KDLac,21467
+trodo/otel/context.py,sha256=Jd0aTc0Q-1dM5kXXinhZD8YtnpdKgvneNiODyboVGKY,1418
 trodo/otel/helpers.py,sha256=XOMWcgZHaq5SQbkFxDaXPE4CDFjn01xjJmJ1vIxvwpw,20730
-trodo/otel/processor.py,sha256=aqcTmzTw9cESgIp829pu_XCa5_dG_2MaeJNsqJZeqQU,7495
+trodo/otel/processor.py,sha256=ffhrzPDUBwEzeUBa9k5oKnl6vw7NV0urAoco2Z2aiVY,7703
+trodo/otel/prompt_trace.py,sha256=BIrdLOpsR1_HoaCmWb_706GwZSs-UG3p76fjvX3CX3w,3391
 trodo/otel/register.py,sha256=bV_ePTfUvPugig2GZnylhzxi2QfoPWs96A9mGLPMrSQ,9387
 trodo/otel/transport.py,sha256=hzZz8gwSMGJ8CxdijmLn1Ljt18owr9XTWy13DLbwYbw,2441
-trodo/otel/wrap_agent.py,sha256=_nFDhxPyl0RlNKj29cBNeRc_zAY5FUiHvTiNUWxTt0M,39049
+trodo/otel/wrap_agent.py,sha256=9lsrt6o25dZ8RGdHXERRF-PbZ8RqIoX1dw_cXF_dBdQ,39724
 trodo/prompts/__init__.py,sha256=yunNc8WkTSfEEkRR-NZWXAt_ZB3Ee2INRh-4RE7uHj4,806
 trodo/prompts/compile.py,sha256=sEMl8EWdK0G9uOKGcgc39ujnA5RLCUtbk26TYVqK68Q,6345
 trodo/prompts/template.py,sha256=obQiivPCR6LEdz7q1cby7uL25tYHYui4aoEaiUNqWfs,9357
-trodo/prompts/types.py,sha256=RhvYSuXCrwnZHu5TftObIAs-TQa2E7v08alNmD62x4s,3327
+trodo/prompts/types.py,sha256=3oyrEDb1jfnC4gF02mM3izhNHstJ-bu-8TxoF7Yk6mQ,4425
 trodo/queue/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/queue/batch_flusher.py,sha256=4Lg6T3Urwi9U0Q4FpFGPmjDYKg4ZliCTR-ND8BJvWaY,1298
 trodo/queue/event_queue.py,sha256=EVFZrhlq_kwC3jJ2GK0wMhHISf9UzLCZNDnT_aZ2I2A,872
 trodo/session/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/session/server_session.py,sha256=McsudEiq33XDq3nqxgzBcUvIjQxCMscwEuAPnYXrTjs,2136
 trodo/session/session_manager.py,sha256=JrgH1VeicmtlxPR4dXEuJbxhi23OelkgwW3-9Slv80o,2525
-trodo_python-2.14.0.dist-info/METADATA,sha256=RCejgO9mpxqpdJhLGakkYLLVCzSB0ZJXwdFMQFrkXP8,23115
-trodo_python-2.14.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-trodo_python-2.14.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
-trodo_python-2.14.0.dist-info/RECORD,,
+trodo_python-2.16.0.dist-info/METADATA,sha256=i4J0WgohVDAcQi8OCVa_x6WpDhH9mWeYCEgX8BQ2lLs,23115
+trodo_python-2.16.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+trodo_python-2.16.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
+trodo_python-2.16.0.dist-info/RECORD,,