trodo-python 2.11.0__py3-none-any.whl → 2.12.0__py3-none-any.whl

trodo/__init__.py

@@ -41,13 +41,21 @@ Downstream microservice (join the caller's run instead of making a new one):
 
 from __future__ import annotations
 
-__version__ = "2.11.0"
+__version__ = "2.12.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
 from .client import TrodoClient
 from .user_context import UserContext
 from .managers.group_manager import GroupProfile
+from .managers.prompt_manager import ManagedPrompt, PromptSummary
+from .prompts import (
+    CompiledPrompt,
+    CompileError,
+    PromptVariable,
+    TemplateError,
+    render as _render_template,
+)
 from .otel.wrap_agent import (
     wrap_agent as _wrap_agent_ctx,
     span as _span_ctx,
@@ -100,6 +108,17 @@ __all__ = [
     "propagation_headers",
     "current_run_id",
     "current_span_id",
+    # Prompt management
+    "get_prompt",
+    "list_prompts",
+    "compile_prompt",
+    "render_template",
+    "CompiledPrompt",
+    "PromptVariable",
+    "CompileError",
+    "TemplateError",
+    "ManagedPrompt",
+    "PromptSummary",
 ]
 
 # ============================================================================
@@ -249,6 +268,82 @@ def reset(distinct_id: str) -> ResetResult:
     return _get_client().reset(distinct_id)
 
 
+# ----------------------------------------------------------------------------
+# Prompt management
+# ----------------------------------------------------------------------------
+
+def get_prompt(
+    name: str,
+    label: Optional[str] = None,
+    version: Optional[int] = None,
+    cache_ttl_seconds: Optional[float] = None,
+    fallback: Optional[Dict[str, Any]] = None,
+    max_retries: int = 2,
+) -> ManagedPrompt:
+    """Fetch a managed prompt by name.
+
+    Follows the ``production`` label by default; pass ``label`` for a different
+    one or ``version`` to pin exactly.
+
+    Cached for 60s with stale-while-revalidate, so a Trodo outage degrades
+    instead of taking your app down. Pass ``fallback`` to cover cold start::
+
+        p = trodo.get_prompt("support-triage", fallback={
+            "messages": [{"role": "user", "content": [{"type": "text", "text": "Help with {{q}}"}]}],
+            "variables": [{"name": "q", "type": "string", "required": True}],
+        })
+        compiled = p.compile(q="where is my order")
+        # compiled.messages / compiled.model / compiled.tools
+
+    :raises LookupError: if the prompt cannot be fetched and nothing is cached
+        and no ``fallback`` was given
+    """
+    return _get_client().prompts.get(
+        name,
+        label=label,
+        version=version,
+        cache_ttl_seconds=cache_ttl_seconds,
+        fallback=fallback,
+        max_retries=max_retries,
+    )
+
+
+def list_prompts() -> List[PromptSummary]:
+    """List prompts available to this site's team (names + labels, no body)."""
+    return _get_client().prompts.list()
+
+
+def compile_prompt(
+    prompt: ManagedPrompt,
+    variables: Optional[Dict[str, Any]] = None,
+    **kwargs: Any,
+) -> CompiledPrompt:
+    """Compile a managed prompt with variable values.
+
+    Returns ``CompiledPrompt(messages, model, tools, response_format)`` — hand it
+    straight to your provider client.
+    """
+    merged = dict(variables or {})
+    merged.update(kwargs)
+    return prompt.compile(merged)
+
+
+def render_template(
+    template: str,
+    variables: Optional[Dict[str, Any]] = None,
+    strict: bool = True,
+    **kwargs: Any,
+) -> str:
+    """Render a template string with ``{{variables}}`` (no client required).
+
+    Strict by default: an unknown variable raises rather than silently leaving a
+    literal ``{{typo}}`` in the text you send to a model.
+    """
+    merged = dict(variables or {})
+    merged.update(kwargs)
+    return _render_template(template, merged, strict=strict)
+
+
 def enable_auto_events() -> None:
     _get_client().enable_auto_events()
 

trodo/api/http_client.py

@@ -80,6 +80,59 @@ class HttpClient:
                 self.on_error(exc)
             return {}
 
+    def _get(
+        self, path: str, params: Optional[Dict[str, Any]] = None, attempt: int = 0
+    ) -> ApiResult:
+        """GET helper for read endpoints (prompt management). Surfaces a non-2xx
+        as {"__error": True, "status": <code>, ...} so callers can tell
+        "not found" apart from a successful empty body."""
+        url = f"{self.api_base}{path}"
+        self._log(f"GET {url}")
+        try:
+            resp = self._session.get(url, params=params or {}, timeout=self.timeout)
+            if resp.status_code >= 500 and attempt < self.retries:
+                delay = 2 ** attempt
+                self._log(f"Retry {attempt + 1} after {delay}s (status {resp.status_code})")
+                time.sleep(delay)
+                return self._get(path, params, attempt + 1)
+            try:
+                data = resp.json()
+            except Exception:
+                data = {}
+            if resp.status_code >= 400:
+                base = {"__error": True, "status": resp.status_code}
+                if isinstance(data, dict):
+                    base.update(data)
+                return base
+            return data
+        except Exception as exc:
+            if attempt < self.retries:
+                delay = 2 ** attempt
+                self._log(f"Retry {attempt + 1} after {delay}s (network error)")
+                time.sleep(delay)
+                return self._get(path, params, attempt + 1)
+            self._log(f"Error: {exc}")
+            if self.on_error:
+                self.on_error(exc)
+            return {"__error": True}
+
+    def get_prompt(
+        self,
+        name: str,
+        label: Optional[str] = None,
+        version: Optional[Any] = None,
+    ) -> ApiResult:
+        from urllib.parse import quote
+        params: Dict[str, Any] = {}
+        if label:
+            params["label"] = label
+        if version is not None and version != "":
+            params["version"] = version
+        return self._get(f"/api/sdk/prompts/{quote(str(name), safe='')}", params)
+
+    def list_prompts(self) -> ApiResult:
+        return self._get("/api/sdk/prompts")
+
     def post_track(self, session_data: Dict[str, Any]) -> ApiResult:
         return self._request("/api/sdk/track", {"sessionData": session_data})
 

trodo/client.py

@@ -76,6 +76,7 @@ class TrodoClient:
         )
 
         self._session_manager = SessionManager()
+        self._prompts = None  # lazily-built PromptManager
 
         if batch_enabled:
             self._event_queue: Optional[EventQueue] = EventQueue(batch_size)
@@ -116,6 +117,14 @@ class TrodoClient:
         the public surface; subject to change between minors."""
         return self._span_processor
 
+    @property
+    def prompts(self):
+        """Read-only access to the team's managed prompt registry."""
+        if self._prompts is None:
+            from .managers.prompt_manager import PromptManager
+            self._prompts = PromptManager(self._http)
+        return self._prompts
+
     # --------------------------------------------------------------------------
     # Primary pattern: for_user()
     # --------------------------------------------------------------------------

trodo/managers/prompt_manager.py

@@ -0,0 +1,286 @@
+"""Prompt management — read managed prompts from the Trodo registry.
+
+Prompts are authored and versioned in the Trodo dashboard; the SDK fetches them
+at runtime by name + optional label/version so application code never hard-codes
+prompt text. A deploy label (e.g. ``production``) points at one version, so you
+ship a new prompt by moving the label rather than redeploying.
+
+``compile()`` returns a structured :class:`CompiledPrompt` — ``{messages, model,
+tools, response_format}``, not a string. A string has nowhere to put model
+config or tools, which is why every product that returns one cannot carry them.
+
+Mirrors ``sdks/trodo-node-sdk/src/managers/PromptManager.ts`` test-for-test.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Callable, Dict, List, Optional, Set
+
+from ..prompts.compile import CompileError, compile_prompt
+from ..prompts.template import TemplateError, render
+from ..prompts.types import CompiledPrompt, ManagedPrompt, PromptSummary, PromptVariable
+
+__all__ = [
+    "PromptManager",
+    "ManagedPrompt",
+    "PromptSummary",
+    "PromptVariable",
+    "CompiledPrompt",
+    "CompileError",
+    "TemplateError",
+    "compile_prompt",
+    "render",
+    "DEFAULT_TTL_SECONDS",
+]
+
+DEFAULT_TTL_SECONDS = 60.0
+
+
+def _cache_key(name: str, version: Optional[int], 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.
+    if version is not None:
+        return f"{name}::version:{version}"
+    if label:
+        return f"{name}::label:{label}"
+    return f"{name}::label:production"
+
+
+def _to_variables(raw: Any) -> List[PromptVariable]:
+    out: List[PromptVariable] = []
+    for v in raw or []:
+        if isinstance(v, PromptVariable):
+            out.append(v)
+        elif isinstance(v, dict) and isinstance(v.get("name"), str):
+            out.append(
+                PromptVariable(
+                    name=v["name"],
+                    type=v.get("type") or "string",
+                    required=bool(v.get("required")),
+                    default=v.get("default"),
+                    description=v.get("description"),
+                )
+            )
+    return out
+
+
+def _to_prompt(raw: Dict[str, Any], is_fallback: bool = False) -> 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),
+        labels=list(raw.get("labels") or []),
+        messages=list(raw.get("messages") or []),
+        model_config=dict(raw.get("model_config") or {}),
+        tools=list(raw.get("tools") or []),
+        response_format=raw.get("response_format"),
+        variables=_to_variables(raw.get("variables")),
+        updated_at=raw.get("updated_at") or raw.get("updatedAt"),
+        is_fallback=is_fallback,
+    )
+
+
+class _Cache:
+    """Prompt cache with stale-while-revalidate.
+
+    An LLM app must never hard-fail because the prompt service blinked. The
+    ladder, in order:
+
+        fresh cache  ->  stale cache  ->  caller's fallback  ->  raise
+
+    A prompt fetch sits on the hot path of every request an app makes. Without
+    this, adding Trodo prompt management would make an app strictly *less*
+    reliable than hardcoding the string — which is a good reason not to adopt it.
+    """
+
+    def __init__(self) -> None:
+        self._store: Dict[str, Any] = {}
+        self._expires: Dict[str, float] = {}
+        self._refreshing: Set[str] = set()
+        self._lock = threading.Lock()
+
+    def get_fresh(self, key: str) -> Optional[Any]:
+        with self._lock:
+            if key in self._store and self._expires.get(key, 0.0) > time.time():
+                return self._store[key]
+        return None
+
+    def get_stale(self, key: str) -> Optional[Any]:
+        with self._lock:
+            return self._store.get(key)
+
+    def set(self, key: str, value: Any, ttl: float) -> None:
+        with self._lock:
+            self._store[key] = value
+            self._expires[key] = time.time() + ttl
+
+    def revalidate(self, key: str, fetcher: Callable[[], Any], ttl: float) -> None:
+        with self._lock:
+            if key in self._refreshing:
+                return
+            self._refreshing.add(key)
+
+        def _run() -> None:
+            try:
+                self.set(key, fetcher(), ttl)
+            except Exception:  # noqa: BLE001
+                # Deliberately swallowed. The caller already has a usable stale
+                # value; a background refresh failing is not their problem and
+                # must never surface. It retries on the next request.
+                pass
+            finally:
+                with self._lock:
+                    self._refreshing.discard(key)
+
+        threading.Thread(target=_run, daemon=True).start()
+
+    def clear(self) -> None:
+        with self._lock:
+            self._store.clear()
+            self._expires.clear()
+            self._refreshing.clear()
+
+
+def _with_retry(fn: Callable[[], Any], max_retries: int) -> Any:
+    """Retry with exponential backoff, capped. Mirrors the Node SDK."""
+    attempts = max(0, min(max_retries, 4))
+    last: Optional[BaseException] = None
+    for i in range(attempts + 1):
+        try:
+            return fn()
+        except Exception as e:  # noqa: BLE001
+            last = e
+            if i == attempts:
+                break
+            time.sleep(min(2**i * 0.2, 10.0))
+    assert last is not None
+    raise last
+
+
+class PromptManager:
+    """Read-only access to the team's managed prompt registry."""
+
+    def __init__(self, http_client: Any) -> None:
+        self._http = http_client
+        self._cache = _Cache()
+
+    def get(
+        self,
+        name: str,
+        label: Optional[str] = None,
+        version: Optional[int] = None,
+        cache_ttl_seconds: Optional[float] = None,
+        fallback: Optional[Dict[str, Any]] = None,
+        max_retries: int = 2,
+    ) -> ManagedPrompt:
+        """Fetch a managed prompt by name.
+
+        Without arguments you get the version labelled ``production``; pass
+        ``label`` to follow a different deploy label, or ``version`` to pin
+        exactly.
+
+        Availability ladder — fresh cache -> stale cache -> ``fallback`` ->
+        raise. A prompt fetch is on your hot path, so a Trodo outage degrades
+        rather than takes your app down. Check ``prompt.is_fallback`` to detect
+        the last rung. Pass ``cache_ttl_seconds=0`` to disable caching (handy in
+        development).
+
+        :raises ValueError: if *name* is empty, or both ``label`` and ``version``
+        :raises LookupError: if the prompt cannot be fetched and nothing is
+            cached and no ``fallback`` was given
+        """
+        if not name:
+            raise ValueError("trodo: get_prompt(name) requires a name")
+        if version is not None and label:
+            raise ValueError("trodo: pass either version or label, not both")
+
+        key = _cache_key(name, version, label)
+        ttl = DEFAULT_TTL_SECONDS if cache_ttl_seconds is None else float(cache_ttl_seconds)
+
+        def fetcher() -> Dict[str, Any]:
+            res = _with_retry(
+                lambda: self._http.get_prompt(name, label=label, version=version),
+                max_retries,
+            )
+            if not res or res.get("__error") or not res.get("prompt"):
+                status = res.get("status") if isinstance(res, dict) else None
+                detail = res.get("error") if isinstance(res, dict) else None
+                raise LookupError(
+                    f"trodo: could not fetch prompt {name!r}"
+                    + (f" (HTTP {status})" if status else "")
+                    + (f": {detail}" if detail else "")
+                )
+            return res["prompt"]
+
+        if ttl > 0:
+            fresh = self._cache.get_fresh(key)
+            if fresh is not None:
+                return _to_prompt(fresh)
+
+            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)
+
+        try:
+            raw = fetcher()
+            if ttl > 0:
+                self._cache.set(key, raw, ttl)
+            return _to_prompt(raw)
+        except Exception:
+            stale = self._cache.get_stale(key)
+            if stale is not None:
+                return _to_prompt(stale)
+            if fallback:
+                return _to_prompt(
+                    {
+                        "name": name,
+                        "version": 0,
+                        "labels": [],
+                        "tags": [],
+                        "messages": fallback.get("messages") or [],
+                        "model_config": fallback.get("model_config") or {},
+                        "tools": [],
+                        "response_format": None,
+                        "variables": fallback.get("variables") or [],
+                    },
+                    is_fallback=True,
+                )
+            raise
+
+    def list(self) -> List[PromptSummary]:
+        """List the prompts available to this site's team (names + labels)."""
+        res = self._http.list_prompts()
+        if not res or res.get("__error") or not isinstance(res.get("prompts"), list):
+            return []
+        return [
+            PromptSummary(
+                name=str(p.get("name") or ""),
+                description=p.get("description"),
+                version=int(p.get("version") or 0),
+                labels=list(p.get("labels") or []),
+                updated_at=p.get("updated_at") or p.get("updatedAt"),
+            )
+            for p in res["prompts"]
+        ]
+
+    def compile(
+        self,
+        prompt: ManagedPrompt,
+        variables: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> CompiledPrompt:
+        """Compile a managed prompt with variable values."""
+        values = dict(variables or {})
+        values.update(kwargs)
+        return prompt.compile(values)
+
+    def clear_cache(self) -> None:
+        """Drop everything cached. Mostly useful in tests."""
+        self._cache.clear()

trodo/prompts/__init__.py

@@ -0,0 +1,37 @@
+"""Managed prompt support: template rendering, compilation, and types."""
+
+from .compile import CompileError, build_scope, compile_prompt
+from .template import TemplateError, extract_names, parse, render, render_with_report
+from .types import (
+    CompiledPrompt,
+    ContentBlock,
+    ManagedPrompt,
+    ModelConfig,
+    PromptMessage,
+    PromptNode,
+    PromptSummary,
+    PromptTool,
+    PromptVariable,
+    ResponseFormat,
+)
+
+__all__ = [
+    "CompileError",
+    "CompiledPrompt",
+    "ContentBlock",
+    "ManagedPrompt",
+    "ModelConfig",
+    "PromptMessage",
+    "PromptNode",
+    "PromptSummary",
+    "PromptTool",
+    "PromptVariable",
+    "ResponseFormat",
+    "TemplateError",
+    "build_scope",
+    "compile_prompt",
+    "extract_names",
+    "parse",
+    "render",
+    "render_with_report",
+]

trodo/prompts/compile.py

@@ -0,0 +1,181 @@
+"""Compile a managed prompt into a ready-to-send payload.
+
+Mirrors ``backend/services/prompts/compile.js`` and the Node SDK's
+``src/prompts/compile.ts`` exactly. The backend compiles for the playground and
+the hosted ``/run`` path; this compiles in the caller's process. They must agree,
+or the prompt you tested is not the prompt you shipped.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .template import render
+from .types import CompiledPrompt, PromptVariable
+
+
+class CompileError(Exception):
+    """Raised when a prompt cannot be compiled with the supplied values.
+
+    Carries ``details`` — every problem found, not just the first, so a caller
+    can surface them all at once.
+    """
+
+    def __init__(self, message: str, details: Optional[List[str]] = None) -> None:
+        super().__init__(message)
+        self.details: List[str] = details or []
+
+
+def _coerce(value: Any, type_: str, name: str, errors: List[str]) -> Any:
+    """Coerce a caller value to the declared type.
+
+    Values arrive over HTTP and from application code, so ``"5"`` for a number
+    variable is normal, not an error — but ``"abc"`` is.
+    """
+    if value is None:
+        return value
+
+    if type_ == "number":
+        if isinstance(value, bool):
+            errors.append(f"variable '{name}': expected a number, got {value!r}")
+            return value
+        if isinstance(value, (int, float)):
+            return value
+        try:
+            return float(value) if "." in str(value) else int(value)
+        except (TypeError, ValueError):
+            errors.append(f"variable '{name}': expected a number, got {value!r}")
+            return value
+
+    if type_ == "boolean":
+        if isinstance(value, bool):
+            return value
+        if value == "true":
+            return True
+        if value == "false":
+            return False
+        errors.append(f"variable '{name}': expected a boolean, got {value!r}")
+        return value
+
+    if type_ == "string":
+        return value if isinstance(value, str) else str(value)
+
+    if type_ == "messages":
+        if not isinstance(value, list):
+            errors.append(f"variable '{name}': expected an array of messages")
+        return value
+
+    return value
+
+
+def build_scope(
+    variables: Optional[List[PromptVariable]],
+    values: Optional[Dict[str, Any]],
+) -> Dict[str, Any]:
+    """Build the render scope from declarations + caller values.
+
+    Resolution order: caller value → declared default → required-and-absent
+    raises → optional-and-absent renders empty.
+    """
+    errors: List[str] = []
+    scope: Dict[str, Any] = {}
+    declared = set()
+    values = values or {}
+
+    for v in variables or []:
+        name = getattr(v, "name", None) if not isinstance(v, dict) else v.get("name")
+        if not isinstance(name, str):
+            continue
+        declared.add(name)
+
+        if isinstance(v, dict):
+            type_ = v.get("type") or "string"
+            has_default = "default" in v and v.get("default") is not None
+            default = v.get("default")
+        else:
+            type_ = getattr(v, "type", None) or "string"
+            default = getattr(v, "default", None)
+            has_default = default is not None
+
+        has = name in values
+        value = values.get(name) if has else None
+
+        # Missing value -> the declared default, or empty. Nothing is
+        # "required": compile always succeeds with whatever the caller provides.
+        if not has or value is None:
+            value = default if has_default else ([] if type_ == "messages" else "")
+
+        scope[name] = _coerce(value, type_, name, errors)
+
+    # Passing something the prompt doesn't declare is nearly always a rename
+    # that didn't propagate. Fail loudly rather than render a prompt nobody
+    # intended.
+    for k in values:
+        if k not in declared:
+            errors.append(f"variable '{k}' is not declared on this prompt")
+
+    if errors:
+        raise CompileError("Cannot compile prompt: " + "; ".join(errors), errors)
+    return scope
+
+
+def _render_block(block: Dict[str, Any], scope: Dict[str, Any]) -> Dict[str, Any]:
+    if block.get("type") == "text":
+        out = dict(block)
+        out["text"] = render(block.get("text"), scope, strict=True)
+        return out
+    return block
+
+
+def _resolve_placeholder(
+    node: Dict[str, Any], scope: Dict[str, Any], errors: List[str]
+) -> List[Dict[str, Any]]:
+    name = node.get("name")
+    value = scope.get(name)
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        # Langfuse coerces a non-list into {"role": "NOT_GIVEN", ...} plus a
+        # warning, and that sentinel role then reaches the provider. Refuse.
+        errors.append(
+            f"placeholder '{name}': expected an array of messages, got {type(value).__name__}"
+        )
+        return []
+    for i, m in enumerate(value):
+        if not isinstance(m, dict) or not isinstance(m.get("role"), str):
+            errors.append(f"placeholder '{name}'[{i}]: each item must be a message with a role")
+    return value
+
+
+def compile_prompt(prompt: Any, values: Optional[Dict[str, Any]] = None) -> CompiledPrompt:
+    """Compile *prompt* with *values*.
+
+    Returns a :class:`CompiledPrompt` — ``{messages, model, tools,
+    response_format}``, not a string. A string has nowhere to put model config
+    or tools, which is why every product that returns one cannot carry them.
+    """
+    get = (lambda k, d=None: prompt.get(k, d)) if isinstance(prompt, dict) else (
+        lambda k, d=None: getattr(prompt, k, d)
+    )
+
+    scope = build_scope(get("variables") or [], values or {})
+    errors: List[str] = []
+    out: List[Dict[str, Any]] = []
+
+    for node in get("messages") or []:
+        if isinstance(node, dict) and node.get("type") == "placeholder":
+            out.extend(_resolve_placeholder(node, scope, errors))
+            continue
+        msg = dict(node)
+        msg["content"] = [_render_block(b, scope) for b in (node.get("content") or [])]
+        out.append(msg)
+
+    if errors:
+        raise CompileError("Cannot compile prompt: " + "; ".join(errors), errors)
+
+    return CompiledPrompt(
+        messages=out,
+        model=get("model_config") or {},
+        tools=get("tools") or [],
+        response_format=get("response_format"),
+    )

trodo/prompts/template.py

@@ -0,0 +1,280 @@
+"""Trodo prompt template engine — Python SDK port.
+
+MUST stay byte-identical to:
+    backend/services/prompts/template.js          (source of truth)
+    sdks/trodo-node-sdk/src/prompts/template.ts
+
+All three are pinned by ``backend/services/prompts/template.vectors.json``,
+which this package's tests load directly. If you change behaviour here without
+adding a vector and updating the other two, the suites will disagree — which is
+the point. Divergence between what the playground renders and what the SDK
+renders is the single worst bug this feature can have.
+
+Zero dependencies, deliberately: this SDK ships with only ``requests`` and that
+is a feature for something embedded in customer apps. Notably we do NOT use
+jinja2 here — it has no faithful JavaScript implementation, and cross-language
+fidelity matters more than expressiveness. See docs/prompt-management-v2-plan.md §5.
+
+Supported:
+    {{name}}            interpolate (raw — we emit prompts, not HTML)
+    {{a.b.c}}           dot-path resolution
+    {{#name}}...{{/name}}  section: truthy renders once, list renders per item
+    {{^name}}...{{/name}}  inverted section
+    {{.}}               current item inside a list section
+    {{! comment }}      comment
+
+Not supported (raises, never silently ignored): partials, lambdas, set-delimiters.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Dict, List, Optional, Sequence, Set, Tuple
+
+_OPEN = "{{"
+_CLOSE = "}}"
+
+_NAME_RE = re.compile(r"^(\.|[A-Za-z_$][A-Za-z0-9_$]*(\.[A-Za-z_$][A-Za-z0-9_$]*)*)$")
+
+
+class TemplateError(Exception):
+    """Raised for malformed templates and (in strict mode) unknown variables."""
+
+
+# Tokens are dicts to mirror the JS ports exactly:
+#   {"t": "text", "v": str}
+#   {"t": "var", "v": str}
+#   {"t": "section", "v": str, "inverted": bool, "children": [...]}
+Token = Dict[str, Any]
+
+
+def _assert_name(name: str, pos: int) -> None:
+    if not _NAME_RE.match(name):
+        raise TemplateError(f"Invalid variable name '{name}' at position {pos}")
+
+
+def parse(template: Optional[str]) -> List[Token]:
+    """Parse a template into a token tree."""
+    src = "" if template is None else str(template)
+    root: List[Token] = []
+    stack: List[Tuple[Optional[str], List[Token]]] = [(None, root)]
+    i = 0
+
+    def push(tok: Token) -> None:
+        stack[-1][1].append(tok)
+
+    while i < len(src):
+        open_at = src.find(_OPEN, i)
+        if open_at == -1:
+            if i < len(src):
+                push({"t": "text", "v": src[i:]})
+            break
+        if open_at > i:
+            push({"t": "text", "v": src[i:open_at]})
+
+        close_at = src.find(_CLOSE, open_at + len(_OPEN))
+        if close_at == -1:
+            raise TemplateError(f"Unclosed '{{{{' at position {open_at}")
+
+        body = src[open_at + len(_OPEN) : close_at].strip()
+        i = close_at + len(_CLOSE)
+
+        if not body:
+            raise TemplateError(f"Empty tag '{{{{}}}}' at position {open_at}")
+
+        sigil = body[0]
+        rest = body[1:].strip()
+
+        if sigil == "!":
+            continue
+
+        if sigil in (">", "<"):
+            raise TemplateError(
+                f"Partials ({{{{>{rest}}}}}) are not supported. Inline the content instead."
+            )
+        if sigil == "=":
+            raise TemplateError("Set-delimiter tags ({{=...=}}) are not supported.")
+        if sigil == "&":
+            raise TemplateError(
+                f"Unescaped tags ({{{{&{rest}}}}}) are not supported: "
+                f"{{{{{rest}}}}} is already raw."
+            )
+
+        if sigil in ("#", "^"):
+            if not rest:
+                raise TemplateError(f"Section tag missing a name at position {open_at}")
+            _assert_name(rest, open_at)
+            tok: Token = {"t": "section", "v": rest, "inverted": sigil == "^", "children": []}
+            push(tok)
+            stack.append((rest, tok["children"]))
+            continue
+
+        if sigil == "/":
+            top_name, _ = stack[-1]
+            if top_name is None:
+                raise TemplateError(f"Unexpected closing tag {{{{/{rest}}}}} — no open section")
+            if top_name != rest:
+                raise TemplateError(
+                    f"Mismatched closing tag: expected {{{{/{top_name}}}}} "
+                    f"but found {{{{/{rest}}}}}"
+                )
+            stack.pop()
+            continue
+
+        _assert_name(body, open_at)
+        push({"t": "var", "v": body})
+
+    if len(stack) > 1:
+        raise TemplateError(f"Unclosed section {{{{#{stack[-1][0]}}}}}")
+    return root
+
+
+def _lookup(path: str, scopes: Sequence[Any]) -> Tuple[bool, Any]:
+    """Resolve a dot-path against a scope chain (innermost first).
+
+    This is the piece every competitor gets wrong: Langfuse's parser lexes
+    ``{{user.name}}`` as a name but then does a flat key lookup, so the dot-path
+    only resolves if you literally pass a ``"user.name"`` key. We walk it.
+    """
+    if path == ".":
+        return (True, scopes[0]) if scopes else (False, None)
+
+    parts = path.split(".")
+    for scope in scopes:
+        if not isinstance(scope, dict):
+            continue
+        if parts[0] not in scope:
+            continue
+
+        cur: Any = scope
+        ok = True
+        for part in parts:
+            if not isinstance(cur, dict) or part not in cur:
+                ok = False
+                break
+            cur = cur[part]
+        if ok:
+            return True, cur
+    return False, None
+
+
+def _stringify(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, bool):
+        # Must match JS: `true` / `false`, not Python's `True` / `False`.
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        # Match JS number formatting: 5.0 renders as "5", not "5.0".
+        if isinstance(value, float) and value.is_integer():
+            return str(int(value))
+        return str(value)
+    try:
+        return json.dumps(value, separators=(",", ":"))
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def _is_falsy(value: Any) -> bool:
+    if value is None or value is False or value == "":
+        return True
+    if isinstance(value, (list, tuple)) and len(value) == 0:
+        return True
+    return False
+
+
+def _render_tokens(tokens: List[Token], scopes: List[Any], strict: bool, missing: Set[str]) -> str:
+    out: List[str] = []
+    for tok in tokens:
+        kind = tok["t"]
+
+        if kind == "text":
+            out.append(tok["v"])
+            continue
+
+        if kind == "var":
+            found, value = _lookup(tok["v"], scopes)
+            if not found:
+                if strict:
+                    raise TemplateError(
+                        f"Unknown variable '{{{{{tok['v']}}}}}'. "
+                        "Declare it on the prompt or pass a value."
+                    )
+                missing.add(tok["v"])
+                continue
+            out.append(_stringify(value))
+            continue
+
+        # section
+        found, value = _lookup(tok["v"], scopes)
+        if not found and strict and not tok["inverted"]:
+            raise TemplateError(
+                f"Unknown section '{{{{#{tok['v']}}}}}'. "
+                "Declare it on the prompt or pass a value."
+            )
+        if not found:
+            missing.add(tok["v"])
+
+        falsy = _is_falsy(value)
+        if tok["inverted"]:
+            if falsy:
+                out.append(_render_tokens(tok["children"], scopes, strict, missing))
+            continue
+        if falsy:
+            continue
+
+        if isinstance(value, (list, tuple)):
+            for item in value:
+                out.append(_render_tokens(tok["children"], [item, *scopes], strict, missing))
+        elif isinstance(value, dict):
+            out.append(_render_tokens(tok["children"], [value, *scopes], strict, missing))
+        else:
+            out.append(_render_tokens(tok["children"], scopes, strict, missing))
+
+    return "".join(out)
+
+
+def render(
+    template: Optional[str],
+    values: Optional[Dict[str, Any]] = None,
+    strict: bool = True,
+) -> str:
+    """Render *template* with *values*.
+
+    Strict by default: an unknown variable raises rather than leaving a literal
+    ``{{typo}}`` in the text you send to a model.
+    """
+    return _render_tokens(parse(template), [values or {}], strict, set())
+
+
+def render_with_report(
+    template: Optional[str],
+    values: Optional[Dict[str, Any]] = None,
+    strict: bool = False,
+) -> Tuple[str, List[str]]:
+    """Render, also reporting which names were missing. Returns (text, missing)."""
+    missing: Set[str] = set()
+    text = _render_tokens(parse(template), [values or {}], strict, missing)
+    return text, list(missing)
+
+
+def extract_names(template: Optional[str]) -> List[str]:
+    """Names referenced by a template, first-appearance order, de-duplicated."""
+    seen: List[str] = []
+
+    def walk(tokens: List[Token]) -> None:
+        for tok in tokens:
+            if tok["t"] == "text":
+                continue
+            if tok["v"] != ".":
+                root = tok["v"].split(".")[0]
+                if root not in seen:
+                    seen.append(root)
+            if tok["t"] == "section":
+                walk(tok["children"])
+
+    walk(parse(template))
+    return seen

trodo/prompts/types.py

@@ -0,0 +1,87 @@
+"""Public types for managed prompts.
+
+Mirrors the wire contract in ``backend/controllers/sdkPromptController.js`` and
+the Node SDK's ``src/prompts/types.ts``. All three move together.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+# A message is a plain dict on the wire:
+#   {"role": "system", "content": [{"type": "text", "text": "..."}]}
+# A placeholder — a slot where the caller injects a list of messages:
+#   {"type": "placeholder", "name": "chat_history"}
+PromptMessage = Dict[str, Any]
+PromptNode = Dict[str, Any]
+ContentBlock = Dict[str, Any]
+ModelConfig = Dict[str, Any]
+PromptTool = Dict[str, Any]
+ResponseFormat = Dict[str, Any]
+
+
+@dataclass
+class PromptVariable:
+    """A declared variable.
+
+    Every competitor leaves variables undeclared and untyped — discovered by
+    regex, with no defaults and no required-ness. The declaration is what lets
+    ``compile()`` fail before the model call rather than shipping a literal
+    ``{{typo}}`` and finding out from the bill.
+    """
+
+    name: str
+    type: str = "string"
+    required: bool = False
+    default: Any = None
+    description: Optional[str] = None
+
+
+@dataclass
+class CompiledPrompt:
+    """The result of compiling a prompt — ready to hand to a provider client."""
+
+    messages: List[PromptMessage]
+    model: ModelConfig = field(default_factory=dict)
+    tools: List[PromptTool] = field(default_factory=list)
+    response_format: Optional[ResponseFormat] = None
+
+
+@dataclass
+class ManagedPrompt:
+    """A managed prompt resolved from the Trodo registry."""
+
+    name: str
+    messages: List[PromptNode] = field(default_factory=list)
+    model_config: ModelConfig = field(default_factory=dict)
+    tools: List[PromptTool] = field(default_factory=list)
+    response_format: Optional[ResponseFormat] = None
+    variables: List[PromptVariable] = field(default_factory=list)
+    version: int = 0
+    labels: List[str] = field(default_factory=list)
+    tags: List[str] = field(default_factory=list)
+    description: Optional[str] = None
+    updated_at: Optional[str] = None
+    #: True when this came from the ``fallback`` argument because the API was
+    #: unreachable and nothing was cached.
+    is_fallback: bool = False
+
+    def compile(self, variables: Optional[Dict[str, Any]] = None, **kwargs: Any) -> CompiledPrompt:
+        """Compile with variable values, as a dict or as keyword arguments."""
+        from .compile import compile_prompt  # local import avoids a cycle
+
+        values = dict(variables or {})
+        values.update(kwargs)
+        return compile_prompt(self, values)
+
+
+@dataclass
+class PromptSummary:
+    """Lightweight prompt entry returned by ``list_prompts()``."""
+
+    name: str
+    version: int = 0
+    labels: List[str] = field(default_factory=list)
+    description: Optional[str] = None
+    updated_at: Optional[str] = None

{trodo_python-2.11.0.dist-info → trodo_python-2.12.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.11.0
+Version: 2.12.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side
@@ -438,6 +438,44 @@ Runnable scenarios that double as integration tests live in
 
 ---
 
+## Prompt Management (v2.9.0+)
+
+Author and version prompts in the Trodo dashboard, then fetch them at runtime so
+your application never hard-codes prompt text. A deploy **label** (e.g.
+`production`) points at one version; ship a new prompt by moving the label — no
+redeploy.
+
+```python
+import trodo
+trodo.init(site_id="your-site-id")
+
+# Latest version (default), a label, or a pinned version number:
+prompt = trodo.get_prompt("refund-agent", label="production")
+
+# Fill {{variables}} — unknown tokens are left intact so a missing value shows.
+system = prompt.compile(company="Acme", customer_name="Ada")
+
+resp = openai.chat.completions.create(
+    model=prompt.config.get("model", "gpt-4o-mini"),
+    temperature=prompt.config.get("temperature", 0.2),
+    messages=[{"role": "system", "content": system},
+              {"role": "user", "content": query}],
+)
+```
+
+`get_prompt()` returns a `ManagedPrompt` with `name`, `version`, `labels`,
+`template`, `config`, `variables`, and a `.compile(**vars)` method. It raises
+`LookupError` if the prompt can't be found (you can't run without it).
+
+```python
+trodo.get_prompt("refund-agent")                # latest version
+trodo.get_prompt("refund-agent", version=3)     # pinned version
+trodo.list_prompts()                            # [PromptSummary(name=..., labels=...), ...]
+trodo.compile_prompt(template_or_prompt, {...}) # standalone {{var}} substitution
+```
+
+---
+
 ## Agent Analytics (legacy event-based API)
 
 The older per-event API below is still supported but superseded by

{trodo_python-2.11.0.dist-info → trodo_python-2.12.0.dist-info}/RECORD

@@ -1,16 +1,17 @@
-trodo/__init__.py,sha256=fZ9qn_ObzXX7WLpEnhnlivN6sASv-u9vYXw_IWGNkf0,18229
-trodo/client.py,sha256=dhGiOJmxdWmXDDDabHN865_cAxttJs9LWPeDwEFbAwI,19107
+trodo/__init__.py,sha256=F5asTaDmKcWtk6NJ_DVr4wo1S4HoYMWFiiyqHHDNSvE,21167
+trodo/client.py,sha256=z2q1HZKQNENycv9CRD0kOfwEhmz3Ti9_B-uPsqpvY3U,19454
 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=6DsRCeojxPSYUDe7SbTVHcg6YXlKbM81kb670qXyb_4,5535
+trodo/api/http_client.py,sha256=gVYVqn-M4Mjd0zTjx_Zsr246BL_xvIHOa2w8YlpVvD4,7638
 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/group_manager.py,sha256=ki3Se3qEoSZfREX63oeDeBmEfZF-ISHLE8azEtLg0tM,3542
 trodo/managers/people_manager.py,sha256=mMVnx40Mlifx6NGgChvohC9ViK6dQu2mkXNHbV8pK1E,2882
+trodo/managers/prompt_manager.py,sha256=Ub7rlg3dVVllr6qBf6sXLGvunnP_7FLeGEOal6sYFPY,10448
 trodo/otel/__init__.py,sha256=yiRFXWUU45bAM2CV37XeO7zf1hmnmjufdP4XO50yEyE,624
 trodo/otel/auto_instrument.py,sha256=hJesQMOOp86U66PampcGNINmBVvwVuU_WHVrbUMauug,20895
 trodo/otel/context.py,sha256=iJ1rE42-SbO8VZHAxhIl2ZJXgNwLIVps5xLg8GKgfFc,1165
@@ -19,13 +20,17 @@ trodo/otel/processor.py,sha256=aqcTmzTw9cESgIp829pu_XCa5_dG_2MaeJNsqJZeqQU,7495
 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/prompts/__init__.py,sha256=yunNc8WkTSfEEkRR-NZWXAt_ZB3Ee2INRh-4RE7uHj4,806
+trodo/prompts/compile.py,sha256=Jqy1yaSE1j931KIHP1opMpEEmBKHv-I4BUq-1xaNVWA,6352
+trodo/prompts/template.py,sha256=obQiivPCR6LEdz7q1cby7uL25tYHYui4aoEaiUNqWfs,9357
+trodo/prompts/types.py,sha256=iCNoJk6_kk0JvEblGsDm6c9lEdQW6ixOOv6aCG6IP-k,2924
 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.11.0.dist-info/METADATA,sha256=kfO84FYYYUexa79fxuSjkj3ou4NJU1xTVeFAHYewz7M,21698
-trodo_python-2.11.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-trodo_python-2.11.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
-trodo_python-2.11.0.dist-info/RECORD,,
+trodo_python-2.12.0.dist-info/METADATA,sha256=pvC-YSCsk3GkCPdxnNGUkbgT-ZLBWIgO-MWLxqzzcrA,23115
+trodo_python-2.12.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+trodo_python-2.12.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
+trodo_python-2.12.0.dist-info/RECORD,,