trodo-python 2.19.0__tar.gz → 2.21.0__tar.gz

{trodo_python-2.19.0 → trodo_python-2.21.0}/PKG-INFO

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

{trodo_python-2.19.0 → trodo_python-2.21.0}/pyproject.toml

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

{trodo_python-2.19.0 → trodo_python-2.21.0}/tests/test_error_enrichment.py

@@ -70,6 +70,31 @@ def test_errored_span_and_run_carry_rich_error_fields(processor, http):
     assert "rate limit exceeded" in run_payload["error_summary"]
 
 
+def test_raised_exception_carries_the_recorded_run_id(processor, http):
+    # The run IS recorded when an agent raises; this is the JOIN -- the
+    # exception a developer's error tracker captures must reference it.
+    with pytest.raises(RateLimitError) as e:
+        with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+            raise RateLimitError("boom")
+
+    run_payload = http.run_ingest[0]["run"]
+    assert e.value.trodo_run_id == run_payload["run_id"]
+    assert run_payload["status"] == "error"
+
+
+def test_slotted_exception_still_propagates(processor, http):
+    # An exception that can't take attributes must not crash the error path --
+    # a failure inside error handling is the one unforgivable bug here.
+    class Slotted(Exception):
+        __slots__ = ()
+
+    with pytest.raises(Slotted):
+        with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat"):
+            raise Slotted("rigid")
+
+    assert http.run_ingest[0]["run"]["status"] == "error"
+
+
 def test_set_error_records_without_raising(processor, http):
     with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat") as run:
         with span("soft-step", kind="tool") as s:

{trodo_python-2.19.0 → trodo_python-2.21.0}/tests/test_prompts.py

@@ -86,7 +86,7 @@ PROMPT = {
     "response_format": None,
     "variables": [
         {"name": "persona", "type": "string", "default": "a greeter"},
-        {"name": "who", "type": "string", "required": True},
+        {"name": "who", "type": "string"},
     ],
 }
 
@@ -106,41 +106,43 @@ def test_compile_carries_model_and_tools():
     assert out.response_format is None
 
 
-def test_compile_raises_for_required_variable_with_no_value():
-    # `who` is required with no default. Catching it here is the point: the
-    # alternative is paying for a call to a prompt that says "Hello ".
-    with pytest.raises(CompileError, match="'who': required"):
-        compile_prompt(PROMPT, {})
-
-
-def test_compile_treats_none_and_empty_string_as_no_value():
-    # Both render as nothing, the exact outcome `required` exists to stop.
-    with pytest.raises(CompileError, match="'who': required"):
-        compile_prompt(PROMPT, {"who": None})
-    with pytest.raises(CompileError, match="'who': required"):
-        compile_prompt(PROMPT, {"who": ""})
+def test_compile_renders_missing_variable_empty():
+    # `who` has no value and no default. There is deliberately no way to make
+    # that a failure: the rule is caller value -> default -> empty, and it never
+    # needs a fourth case.
+    out = compile_prompt(PROMPT, {})
+    assert out.messages[1]["content"][0] == {"type": "text", "text": "Hello "}
 
 
-def test_compile_renders_missing_optional_variable_empty():
-    # `required` defaults to False, so a declaration that doesn't ask for it
-    # behaves exactly as before -- no stored prompt changes meaning.
-    optional = {**PROMPT, "variables": [
+def test_compile_ignores_a_legacy_required_flag():
+    # Versions in the wild still carry it. It must stay inert.
+    legacy = {**PROMPT, "variables": [
         {"name": "persona", "type": "string", "default": "a greeter"},
         {"name": "who", "type": "string"},
     ]}
-    out = compile_prompt(optional, {})
+    out = compile_prompt(legacy, {})
     assert out.messages[1]["content"][0] == {"type": "text", "text": "Hello "}
 
 
-def test_compile_lets_a_default_satisfy_required():
+def test_compile_applies_a_default_when_omitted():
     with_default = {**PROMPT, "variables": [
         {"name": "persona", "type": "string", "default": "a greeter"},
-        {"name": "who", "type": "string", "required": True, "default": "world"},
+        {"name": "who", "type": "string", "default": "world"},
     ]}
     out = compile_prompt(with_default, {})
     assert out.messages[1]["content"][0] == {"type": "text", "text": "Hello world"}
 
 
+def test_coercion_error_text_matches_node_byte_for_byte():
+    # Node formats the offending value with JSON.stringify; repr's single
+    # quotes were the ONE divergence a full cross-SDK parity run found. The
+    # double quotes here are the point of the test.
+    numeric = {**PROMPT, "variables": [{"name": "who", "type": "number"}]}
+    with pytest.raises(CompileError) as e:
+        compile_prompt(numeric, {"who": "not-a-number"})
+    assert 'variable \'who\': expected a number, got "not-a-number"' in str(e.value)
+
+
 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).
@@ -226,6 +228,8 @@ class FakeHttp:
         self.last = {"name": name, "label": label, "version": version}
         if self.fail:
             raise RuntimeError("API down")
+        if getattr(self, "error_body", None):
+            return dict(self.error_body)
         return {"prompt": self._prompt}
 
     def list_prompts(self):
@@ -297,6 +301,58 @@ def test_stale_cache_survives_an_outage():
     assert mgr.get("greeter", cache_ttl_seconds=0.01).version == 2
 
 
+def test_missing_prompt_with_fallback_serves_fallback():
+    # Deleting a prompt mid-deploy is exactly what the fallback exists for --
+    # plain prompt_not_found stays an availability failure.
+    http = FakeHttp()
+    http.error_body = {"__error": True, "status": 404, "error": "prompt_not_found"}
+    mgr = PromptManager(http)
+    p = mgr.get("gone", cache_ttl_seconds=0, max_retries=0,
+                fallback={"messages": [{"role": "user", "content": [{"type": "text", "text": "hi"}]}]})
+    assert p.is_fallback is True
+
+
+def test_bad_version_raises_through_the_fallback():
+    # A selector naming nothing is a CONFIG error, not an outage. Being quietly
+    # handed the fallback would hide the typo for as long as it ships.
+    http = FakeHttp()
+    http.error_body = {"__error": True, "status": 404, "error": "version_not_found"}
+    mgr = PromptManager(http)
+    with pytest.raises(LookupError, match="version 999 does not exist on prompt 'greeter'") as e:
+        mgr.get("greeter", version=999, cache_ttl_seconds=0, max_retries=0,
+                fallback={"messages": [{"role": "user", "content": [{"type": "text", "text": "hi"}]}]})
+    assert e.value.code == "version_not_found"
+
+
+def test_bad_label_raises_through_the_fallback():
+    http = FakeHttp()
+    http.error_body = {"__error": True, "status": 404, "error": "label_not_found"}
+    mgr = PromptManager(http)
+    with pytest.raises(LookupError) as e:
+        mgr.get("greeter", label="prod-ue", cache_ttl_seconds=0, max_retries=0,
+                fallback={"messages": [{"role": "user", "content": [{"type": "text", "text": "hi"}]}]})
+    assert e.value.code == "label_not_found"
+
+
+def test_versionless_prompt_says_what_to_do():
+    http = FakeHttp()
+    http.error_body = {"__error": True, "status": 404, "error": "no_versions"}
+    mgr = PromptManager(http)
+    with pytest.raises(LookupError, match="has no versions yet"):
+        mgr.get("empty", cache_ttl_seconds=0, max_retries=0)
+
+
+def test_config_error_not_masked_by_stale_cache():
+    # First fetch succeeds and caches; the label is then deleted server-side.
+    http = FakeHttp(prompt=WIRE)
+    mgr = PromptManager(http)
+    assert mgr.get("greeter", label="production", cache_ttl_seconds=0).version == 2
+    http.error_body = {"__error": True, "status": 404, "error": "label_not_found"}
+    with pytest.raises(LookupError) as e:
+        mgr.get("greeter", label="production", cache_ttl_seconds=0, max_retries=0)
+    assert e.value.code == "label_not_found"
+
+
 def test_fallback_used_when_api_down_and_nothing_cached():
     mgr = PromptManager(FakeHttp(fail=True))
     p = mgr.get(

{trodo_python-2.19.0 → trodo_python-2.21.0}/trodo/__init__.py

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

{trodo_python-2.19.0 → trodo_python-2.21.0}/trodo/managers/prompt_manager.py

@@ -38,6 +38,11 @@ __all__ = [
 DEFAULT_TTL_SECONDS = 60.0
 
 
+# 404 bodies that mean "your SELECTOR is wrong", not "the prompt is gone".
+# Mirrors backend/models/prompt.js missReason -- the wire contract's error half.
+_CONFIG_ERROR_CODES = frozenset({"version_not_found", "label_not_found", "no_versions"})
+
+
 def _cache_key(name: str, version: Optional[Union[int, str]], label: Optional[str]) -> str:
     # Resolution happens server-side on every fetch; the client only caches
     # under whatever selector was asked for. So a label flip propagates within
@@ -56,10 +61,12 @@ def _to_variables(raw: Any) -> List[PromptVariable]:
             out.append(v)
         elif isinstance(v, dict) and isinstance(v.get("name"), str):
             out.append(
+                # Named fields only — a stored version may carry keys this SDK
+                # no longer models (`required`, retired in 2.20.0), and fetching
+                # one must never raise.
                 PromptVariable(
                     name=v["name"],
                     type=v.get("type") or "string",
-                    required=bool(v.get("required")),
                     default=v.get("default"),
                     description=v.get("description"),
                 )
@@ -195,7 +202,14 @@ class PromptManager:
         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
+        the last rung.
+
+        The ladder is for AVAILABILITY failures only. A selector that names
+        nothing — a ``version`` or ``label`` that doesn't exist on a prompt
+        that does — is a config error in your code and raises immediately
+        (``e.code`` is ``version_not_found`` | ``label_not_found`` |
+        ``no_versions``), because being quietly handed the fallback would hide
+        the typo for as long as it ships. Pass ``cache_ttl_seconds=0`` to disable caching (handy in
         development).
 
         :raises ValueError: if *name* is empty, or both ``label`` and ``version``
@@ -222,6 +236,22 @@ class PromptManager:
             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
+                # The server distinguishes a selector that names nothing from a
+                # prompt that is missing. The first is a CONFIG error -- your
+                # code asks for a version or label that does not exist -- and
+                # must throw through the availability ladder below rather than
+                # be masked by stale content or the fallback.
+                if detail in _CONFIG_ERROR_CODES:
+                    if detail == "version_not_found":
+                        what = f"version {version!r} does not exist on prompt {name!r}"
+                    elif detail == "label_not_found":
+                        what = f"label {label!r} does not exist on prompt {name!r}"
+                    else:
+                        what = f"prompt {name!r} has no versions yet -- save one in the dashboard"
+                    err = LookupError(f"trodo: {what}" + (f" (HTTP {status})" if status else ""))
+                    err.code = detail  # type: ignore[attr-defined]
+                    err.prompt_config_error = True  # type: ignore[attr-defined]
+                    raise err
                 raise LookupError(
                     f"trodo: could not fetch prompt {name!r}"
                     + (f" (HTTP {status})" if status else "")
@@ -246,7 +276,12 @@ class PromptManager:
             if ttl > 0:
                 self._cache.set(key, raw, ttl)
             return _to_prompt(raw, trace_label=trace_label)
-        except Exception:
+        except Exception as e:
+            # A config error is not an outage: a typo'd label silently serving
+            # the fallback forever would hide the mistake for as long as it
+            # ships. Config errors surface.
+            if getattr(e, "prompt_config_error", False):
+                raise
             stale = self._cache.get_stale(key)
             if stale is not None:
                 return _to_prompt(stale, trace_label=trace_label)

{trodo_python-2.19.0 → trodo_python-2.21.0}/trodo/otel/wrap_agent.py

@@ -258,6 +258,26 @@ def _mint_anon_distinct_id() -> str:
     return f"anon_{ts}_python_{uuid.uuid4()}_{rand}"
 
 
+def _tag_error_with_run(exc: object, run_id: Optional[str]) -> None:
+    """Stamp the active run's id onto an exception about to propagate.
+
+    The run IS recorded server-side when an agent raises -- status, error type,
+    full message. What was missing is the join: the exception a developer's
+    error tracker captures had no reference to the recorded run, so the two
+    could only be matched by timestamp. ``exc.trodo_run_id`` is that join.
+
+    Guarded on purpose: exceptions can use ``__slots__`` or be otherwise
+    unwritable, and a crash inside error handling is the one unforgivable
+    failure mode here.
+    """
+    if exc is None or not run_id:
+        return
+    try:
+        exc.trodo_run_id = run_id  # type: ignore[attr-defined]
+    except Exception:  # noqa: BLE001 -- slots/frozen; the run is still recorded
+        pass
+
+
 class RunHandle:
     """Handle returned by wrap_agent for setting input/output and getting run_id."""
 
@@ -600,6 +620,7 @@ class wrap_agent:
             einfo = describe_error(exc_type, exc, tb)
             error_summary = einfo["error_message"]
             error_type = einfo["error_type"]
+            _tag_error_with_run(exc, self.handle.run_id)
         elif manual_run_error:
             status = "error"
             error_summary = self.handle.error_summary
@@ -704,6 +725,7 @@ class wrap_agent:
             for k, v in self.handle.metadata.items():
                 otel_span.set_attribute(f"trodo.metadata.{k}", _serialize_attr(v))
             if exc is not None:
+                _tag_error_with_run(exc, self.handle.run_id if self.handle else None)
                 otel_span.record_exception(exc)
                 _, status_cls, status_code = get_otel_helpers()
                 if status_cls is not None and status_code is not None:

{trodo_python-2.19.0 → trodo_python-2.21.0}/trodo/prompts/compile.py

@@ -8,6 +8,7 @@ or the prompt you tested is not the prompt you shipped.
 
 from __future__ import annotations
 
+import json
 from typing import Any, Dict, List, Optional
 
 from .template import render
@@ -26,6 +27,15 @@ class CompileError(Exception):
         self.details: List[str] = details or []
 
 
+def _q(value: Any) -> str:
+    """Format an offending value the way Node's JSON.stringify does, so the two
+    engines produce byte-identical error text. repr() was the one divergence a
+    full cross-SDK parity run found."""
+    try:
+        return json.dumps(value, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return repr(value)
+
 def _coerce(value: Any, type_: str, name: str, errors: List[str]) -> Any:
     """Coerce a caller value to the declared type.
 
@@ -36,15 +46,18 @@ def _coerce(value: Any, type_: str, name: str, errors: List[str]) -> Any:
         return value
 
     if type_ == "number":
+        # _q (json.dumps), not repr: the Node engine formats the offending
+        # value with JSON.stringify, and the two engines' error text is
+        # asserted byte-identical.
         if isinstance(value, bool):
-            errors.append(f"variable '{name}': expected a number, got {value!r}")
+            errors.append(f"variable '{name}': expected a number, got {_q(value)}")
             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}")
+            errors.append(f"variable '{name}': expected a number, got {_q(value)}")
             return value
 
     if type_ == "boolean":
@@ -54,7 +67,7 @@ def _coerce(value: Any, type_: str, name: str, errors: List[str]) -> Any:
             return True
         if value == "false":
             return False
-        errors.append(f"variable '{name}': expected a boolean, got {value!r}")
+        errors.append(f"variable '{name}': expected a boolean, got {_q(value)}")
         return value
 
     if type_ == "string":
@@ -74,12 +87,10 @@ def build_scope(
 ) -> 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.
+    Resolution order: caller value -> declared default -> empty.
 
-    `required` is enforced HERE, in your process, before the model call -- Trodo
-    only stores the declaration. A variable with a default can never fail this
-    check, because the default is itself a value.
+    A missing value never raises. The one thing this does reject is a value for
+    a variable the prompt does not declare, which is almost always a typo.
     """
     errors: List[str] = []
     scope: Dict[str, Any] = {}
@@ -104,24 +115,13 @@ def build_scope(
         has = name in values
         value = values.get(name) if has else None
 
-        # `required` asks a narrower question than default-substitution does:
-        # did the caller supply something that will actually render? None and ""
-        # both render as nothing, the very outcome the flag exists to prevent,
-        # so neither counts. (0 and False do -- they render.)
-        supplied = has and value is not None and value != ""
-
-        # Missing value -> the declared default, or empty.
+        # A missing value resolves, it never fails: the declared default, or
+        # empty. That IS the point of declaring a default -- there is no third
+        # case where the caller has to have supplied something, and adding one
+        # would turn an empty render into a crash for no gain.
         if not has or value is None:
             value = default if has_default else ([] if type_ == "messages" else "")
 
-        # A default always satisfies the requirement, so the two never both
-        # apply; the editor won't let you author both, but a hand-written
-        # declaration can.
-        required = v.get("required") if isinstance(v, dict) else getattr(v, "required", None)
-        if not supplied and required is True and not has_default:
-            errors.append(f"variable '{name}': required, but no value was provided")
-            continue
-
         scope[name] = _coerce(value, type_, name, errors)
 
     # Passing something the prompt doesn't declare is nearly always a rename

{trodo_python-2.19.0 → trodo_python-2.21.0}/trodo/prompts/types.py

@@ -26,24 +26,18 @@ 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.
-
-    ``required`` is enforced by ``compile()``, which runs in YOUR process —
-    Trodo only stores the declaration. Nothing server-side rejects a call for a
-    missing variable, and nothing rejects a version for declaring one.
-
-    Marking a variable required means the caller must pass a value that will
-    actually render: an omitted key, ``None`` and ``""`` all fail, since all
-    three render as nothing (``0`` and ``False`` pass). A variable with
-    a ``default`` can never fail the check — the default is a value — so the two
-    are mutually exclusive in practice.
+    regex, and with no defaults. Knowing the declared set is what lets
+    ``compile()`` catch a value passed for a variable that doesn't exist,
+    instead of silently rendering the wrong prompt.
+
+    A missing value never fails. It resolves to the declared ``default``, or to
+    empty — that is what declaring a default is FOR. There is deliberately no
+    ``required`` flag: it would give the author a decision to get wrong and the
+    caller a crash where an empty render would do.
     """
 
     name: str
     type: str = "string"
-    required: bool = False
     default: Any = None
     description: Optional[str] = None
 

{trodo_python-2.19.0 → trodo_python-2.21.0}/trodo_python.egg-info/PKG-INFO

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