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

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

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

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

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

trodo_python-2.19.0/tests/test_get_prompt_version_types.py

@@ -0,0 +1,54 @@
+"""The public get_prompt must accept a version_hash, not just an int.
+
+The manager has always taken ``Union[int, str]`` and documents hash support —
+the hash is the stable identity the dashboard shows and the SDK returns. But
+the top-level ``trodo.get_prompt`` wrapper narrowed the hint to ``int``, so a
+type checker flagged the documented usage, and the dashboard's own "Use this
+prompt" snippet emits ``version="<hash>"`` for Python.
+
+Checked by signature rather than by a network call: the wrapper only forwards,
+so the contract IS the signature.
+"""
+import inspect
+import typing
+
+import trodo
+from trodo.managers.prompt_manager import PromptManager
+
+
+def _version_annotation(fn):
+    return typing.get_type_hints(fn)["version"]
+
+
+def test_public_get_prompt_accepts_int_or_str():
+    ann = _version_annotation(trodo.get_prompt)
+    args = typing.get_args(ann)
+    assert int in args, f"version should accept int, got {ann}"
+    assert str in args, f"version should accept a version_hash (str), got {ann}"
+
+
+def test_matches_the_manager_it_forwards_to():
+    assert _version_annotation(trodo.get_prompt) == _version_annotation(PromptManager.get)
+
+
+def test_forwards_version_through_untouched():
+    """A hash must reach the manager as-is — not coerced, not dropped."""
+    seen = {}
+
+    class _Stub:
+        def get(self, name, **kwargs):
+            seen.update(kwargs, name=name)
+            return "sentinel"
+
+    class _Client:
+        prompts = _Stub()
+
+    original = trodo._get_client
+    trodo._get_client = lambda: _Client()
+    try:
+        assert trodo.get_prompt("p", version="a3f9c2") == "sentinel"
+    finally:
+        trodo._get_client = original
+
+    assert seen["version"] == "a3f9c2"
+    assert seen["label"] is None

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

@@ -106,12 +106,41 @@ def test_compile_carries_model_and_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, {})
+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_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": [
+        {"name": "persona", "type": "string", "default": "a greeter"},
+        {"name": "who", "type": "string"},
+    ]}
+    out = compile_prompt(optional, {})
     assert out.messages[1]["content"][0] == {"type": "text", "text": "Hello "}
 
 
+def test_compile_lets_a_default_satisfy_required():
+    with_default = {**PROMPT, "variables": [
+        {"name": "persona", "type": "string", "default": "a greeter"},
+        {"name": "who", "type": "string", "required": True, "default": "world"},
+    ]}
+    out = compile_prompt(with_default, {})
+    assert out.messages[1]["content"][0] == {"type": "text", "text": "Hello world"}
+
+
 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).

{trodo_python-2.18.1 → trodo_python-2.19.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.18.0"
+__version__ = "2.19.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -322,7 +322,7 @@ def reset(distinct_id: str) -> ResetResult:
 def get_prompt(
     name: str,
     label: Optional[str] = None,
-    version: Optional[int] = None,
+    version: Optional[Union[int, str]] = None,
     cache_ttl_seconds: Optional[float] = None,
     fallback: Optional[Dict[str, Any]] = None,
     max_retries: int = 2,
@@ -330,7 +330,9 @@ def get_prompt(
     """Fetch a managed prompt by name.
 
     Follows the ``production`` label by default; pass ``label`` for a different
-    one or ``version`` to pin exactly.
+    one or ``version`` to pin exactly. ``version`` may be the integer
+    ``version_no`` or a ``version_hash`` (full, or an unambiguous short prefix
+    like ``a3f9c2``) — the hash is the stable identity, so prefer it.
 
     Cached for 60s with stale-while-revalidate, so a Trodo outage degrades
     instead of taking your app down. Pass ``fallback`` to cover cold start::

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

@@ -74,8 +74,12 @@ 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 -> required-and-absent
+    raises -> optional-and-absent renders 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.
     """
     errors: List[str] = []
     scope: Dict[str, Any] = {}
@@ -100,11 +104,24 @@ def build_scope(
         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.
+        # `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.
         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.18.1 → trodo_python-2.19.0}/trodo/prompts/types.py

@@ -29,6 +29,16 @@ class PromptVariable:
     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.
     """
 
     name: str

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

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

{trodo_python-2.18.1 → trodo_python-2.19.0}/trodo_python.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ tests/test_datasets.py
 tests/test_end_run.py
 tests/test_error_enrichment.py
 tests/test_experiments.py
+tests/test_get_prompt_version_types.py
 tests/test_llm_usage_cost.py
 tests/test_multi_agent_shape.py
 tests/test_processor_methods.py