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

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

@@ -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 → trodo_python-2.12.0}/README.md

@@ -407,6 +407,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 → trodo_python-2.12.0}/pyproject.toml

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

trodo_python-2.12.0/tests/test_prompts.py

@@ -0,0 +1,325 @@
+"""Prompt management — template engine, compile, cache, PromptManager.
+
+Uses a fake HTTP client so no network is touched.
+
+Mirrors ``sdks/trodo-node-sdk/tests/prompts.test.ts`` test-for-test, and loads
+the SAME shared vector file the backend engine's tests use — that file is the
+only thing preventing the three implementations from drifting, and a playground
+that renders differently from the SDK is the worst bug this feature can ship.
+"""
+
+import json
+import os
+import time
+
+import pytest
+
+from trodo.managers.prompt_manager import PromptManager, _cache_key
+from trodo.prompts.compile import CompileError, compile_prompt
+from trodo.prompts.template import TemplateError, extract_names, render
+
+# ════════════════════════════════════════════════════════════════════════════
+# Shared vectors
+# ════════════════════════════════════════════════════════════════════════════
+
+_VECTORS_PATH = os.path.abspath(
+    os.path.join(
+        os.path.dirname(__file__),
+        "..", "..", "..", "backend", "services", "prompts", "template.vectors.json",
+    )
+)
+with open(_VECTORS_PATH, encoding="utf-8") as fh:
+    VECTORS = json.load(fh)
+
+_RENDER_OK = [c for c in VECTORS["cases"] if "expect" in c]
+_RENDER_THROWS = [c for c in VECTORS["cases"] if "throws" in c]
+
+
+@pytest.mark.parametrize("case", _RENDER_OK, ids=[c["name"] for c in _RENDER_OK])
+def test_render_vectors(case):
+    """Must match the backend and the Node SDK byte-for-byte."""
+    strict = case.get("strict", True)
+    assert render(case["template"], case["values"], strict=strict) == case["expect"]
+
+
+@pytest.mark.parametrize("case", _RENDER_THROWS, ids=[c["name"] for c in _RENDER_THROWS])
+def test_render_vectors_raise(case):
+    strict = case.get("strict", True)
+    with pytest.raises(TemplateError) as exc:
+        render(case["template"], case["values"], strict=strict)
+    assert case["throws"] in str(exc.value)
+
+
+@pytest.mark.parametrize(
+    "case",
+    VECTORS["extractNames"],
+    ids=[repr(c["template"]) for c in VECTORS["extractNames"]],
+)
+def test_extract_names_vectors(case):
+    assert extract_names(case["template"]) == case["expect"]
+
+
+def test_no_inherited_attribute_resolution():
+    """`{{items}}` must not resolve to dict.items.
+
+    A Python-specific hazard the JS ports don't have — guarded by using `in` on
+    dicts rather than getattr.
+    """
+    with pytest.raises(TemplateError):
+        render("{{items}}", {})
+    with pytest.raises(TemplateError):
+        render("{{keys}}", {})
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# compile
+# ════════════════════════════════════════════════════════════════════════════
+
+PROMPT = {
+    "name": "greeter",
+    "messages": [
+        {"role": "system", "content": [{"type": "text", "text": "You are {{persona}}."}]},
+        {"role": "user", "content": [{"type": "text", "text": "Hello {{who}}"}]},
+    ],
+    "model_config": {"provider": "openai", "model": "gpt-4o", "temperature": 0.3},
+    "tools": [],
+    "response_format": None,
+    "variables": [
+        {"name": "persona", "type": "string", "default": "a greeter"},
+        {"name": "who", "type": "string", "required": True},
+    ],
+}
+
+
+def test_compile_returns_structured_messages_not_a_string():
+    out = compile_prompt(PROMPT, {"who": "world"})
+    assert not isinstance(out, str)
+    assert len(out.messages) == 2
+    assert out.messages[0]["content"][0] == {"type": "text", "text": "You are a greeter."}
+    assert out.messages[1]["content"][0] == {"type": "text", "text": "Hello world"}
+
+
+def test_compile_carries_model_config_and_tools():
+    out = compile_prompt(PROMPT, {"who": "world"})
+    assert out.model == {"provider": "openai", "model": "gpt-4o", "temperature": 0.3}
+    assert out.tools == []
+    assert out.response_format is None
+
+
+def test_compile_renders_missing_variable_empty():
+    # `who` has no value and no default -> empty, not a raise. Nothing is required.
+    out = compile_prompt(PROMPT, {})
+    assert out.messages[1]["content"][0] == {"type": "text", "text": "Hello "}
+
+
+def test_compile_rejects_undeclared_variable():
+    # Passing a variable the prompt doesn't declare is the one variable mistake
+    # compile still catches (it's almost always a typo/rename).
+    with pytest.raises(CompileError, match="'extra' is not declared"):
+        compile_prompt(PROMPT, {"who": "x", "extra": "y"})
+
+
+def test_compile_applies_defaults():
+    out = compile_prompt(PROMPT, {"who": "w"})
+    assert out.messages[0]["content"][0]["text"] == "You are a greeter."
+
+
+def test_compile_treats_values_as_inert_data():
+    out = compile_prompt(PROMPT, {"persona": "{{who}}", "who": "SECRET"})
+    assert out.messages[0]["content"][0]["text"] == "You are {{who}}."
+
+
+def test_compile_coerces_declared_types():
+    p = {
+        "messages": [{"role": "user", "content": [{"type": "text", "text": "n={{n}}"}]}],
+        "model_config": {},
+        "tools": [],
+        "response_format": None,
+        "variables": [{"name": "n", "type": "number"}],
+    }
+    assert compile_prompt(p, {"n": "5"}).messages[0]["content"][0]["text"] == "n=5"
+    with pytest.raises(CompileError, match="expected a number"):
+        compile_prompt(p, {"n": "abc"})
+
+
+def test_compile_expands_placeholders_and_preserves_injected_messages():
+    p = {
+        "messages": [
+            {"role": "system", "content": [{"type": "text", "text": "sys"}]},
+            {"type": "placeholder", "name": "hist"},
+        ],
+        "model_config": {},
+        "tools": [],
+        "response_format": None,
+        "variables": [{"name": "hist", "type": "messages"}],
+    }
+    injected = {
+        "role": "assistant",
+        "content": [{"type": "tool_use", "id": "t1", "name": "search", "input": {"q": "x"}}],
+    }
+    out = compile_prompt(p, {"hist": [injected]})
+    assert len(out.messages) == 2
+    assert out.messages[1] == injected  # tool_use survives injection
+
+    assert len(compile_prompt(p, {"hist": []}).messages) == 1
+
+    # Refuse rather than coerce to a sentinel role that would reach the provider.
+    with pytest.raises(CompileError, match="expected an array of messages"):
+        compile_prompt(p, {"hist": "oops"})
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# PromptManager
+# ════════════════════════════════════════════════════════════════════════════
+
+WIRE = dict(
+    PROMPT,
+    version=2,
+    labels=["production"],
+    tags=["support"],
+    description="says hi",
+    updated_at="2026-06-29T00:00:00Z",
+)
+
+
+class FakeHttp:
+    """Records the last call so we can assert on it; mirrors the Node fakeApi."""
+
+    def __init__(self, prompt=None, prompts=None, fail=False):
+        self._prompt = prompt
+        self._prompts = prompts
+        self.fail = fail
+        self.calls = 0
+        self.last = None
+
+    def get_prompt(self, name, label=None, version=None):
+        self.calls += 1
+        self.last = {"name": name, "label": label, "version": version}
+        if self.fail:
+            raise RuntimeError("API down")
+        return {"prompt": self._prompt}
+
+    def list_prompts(self):
+        return {"prompts": self._prompts or []}
+
+
+def test_get_maps_wire_shape_and_binds_compile():
+    mgr = PromptManager(FakeHttp(prompt=WIRE))
+    p = mgr.get("greeter", cache_ttl_seconds=0)
+
+    assert p.name == "greeter"
+    assert p.version == 2
+    assert p.labels == ["production"]
+    assert p.tags == ["support"]
+    assert p.model_config["model"] == "gpt-4o"
+    assert p.is_fallback is False
+    assert p.compile(who="world").messages[1]["content"][0]["text"] == "Hello world"
+
+
+def test_get_passes_selector_through():
+    http = FakeHttp(prompt=WIRE)
+    PromptManager(http).get("greeter", label="staging", cache_ttl_seconds=0)
+    assert http.last == {"name": "greeter", "label": "staging", "version": None}
+
+
+def test_get_requires_a_name():
+    with pytest.raises(ValueError, match="requires a name"):
+        PromptManager(FakeHttp()).get("")
+
+
+def test_get_refuses_version_and_label_together():
+    with pytest.raises(ValueError, match="not both"):
+        PromptManager(FakeHttp()).get("greeter", label="production", version=1)
+
+
+def test_get_raises_when_prompt_missing():
+    class Missing:
+        def get_prompt(self, name, label=None, version=None):
+            return {"__error": True, "status": 404, "error": "prompt_not_found"}
+
+    with pytest.raises(LookupError, match="404"):
+        PromptManager(Missing()).get("nope", cache_ttl_seconds=0, max_retries=0)
+
+
+def test_cache_serves_fresh_without_refetching():
+    http = FakeHttp(prompt=WIRE)
+    mgr = PromptManager(http)
+    mgr.get("greeter")
+    mgr.get("greeter")
+    assert http.calls == 1
+
+
+def test_cache_ttl_zero_bypasses_cache():
+    http = FakeHttp(prompt=WIRE)
+    mgr = PromptManager(http)
+    mgr.get("greeter", cache_ttl_seconds=0)
+    mgr.get("greeter", cache_ttl_seconds=0)
+    assert http.calls == 2
+
+
+def test_stale_cache_survives_an_outage():
+    http = FakeHttp(prompt=WIRE)
+    mgr = PromptManager(http)
+    assert mgr.get("greeter", cache_ttl_seconds=0.01).version == 2
+
+    time.sleep(0.05)
+    http.fail = True
+    # Stale-while-revalidate: the caller gets the cached prompt, not an error.
+    assert mgr.get("greeter", cache_ttl_seconds=0.01).version == 2
+
+
+def test_fallback_used_when_api_down_and_nothing_cached():
+    mgr = PromptManager(FakeHttp(fail=True))
+    p = mgr.get(
+        "greeter",
+        cache_ttl_seconds=0,
+        max_retries=0,
+        fallback={
+            "messages": [{"role": "user", "content": [{"type": "text", "text": "Hi {{who}}"}]}],
+            "variables": [{"name": "who", "type": "string", "required": True}],
+        },
+    )
+    # The point of the ladder: a cold-start outage degrades the app rather than
+    # taking it down.
+    assert p.is_fallback is True
+    assert p.compile(who="world").messages[0]["content"][0]["text"] == "Hi world"
+
+
+def test_raises_when_api_down_with_no_cache_and_no_fallback():
+    mgr = PromptManager(FakeHttp(fail=True))
+    with pytest.raises(RuntimeError, match="API down"):
+        mgr.get("greeter", cache_ttl_seconds=0, max_retries=0)
+
+
+def test_cache_key_matches_the_node_sdk():
+    assert _cache_key("p", None, None) == "p::label:production"
+    assert _cache_key("p", None, "staging") == "p::label:staging"
+    assert _cache_key("p", 3, None) == "p::version:3"
+
+
+def test_list_maps_summaries():
+    mgr = PromptManager(
+        FakeHttp(
+            prompts=[
+                {
+                    "name": "a",
+                    "version": 1,
+                    "labels": ["production"],
+                    "updated_at": "2026-06-29T00:00:00Z",
+                },
+            ]
+        )
+    )
+    out = mgr.list()
+    assert len(out) == 1
+    assert out[0].name == "a"
+    assert out[0].labels == ["production"]
+    assert out[0].updated_at == "2026-06-29T00:00:00Z"
+
+
+def test_list_returns_empty_on_error():
+    class Err:
+        def list_prompts(self):
+            return {"__error": True}
+
+    assert PromptManager(Err()).list() == []

{trodo_python-2.11.0 → trodo_python-2.12.0}/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_python-2.11.0 → trodo_python-2.12.0}/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_python-2.11.0 → trodo_python-2.12.0}/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()
     # --------------------------------------------------------------------------