timbal 2.2.7__tar.gz → 2.2.8__tar.gz

{timbal-2.2.7 → timbal-2.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: timbal
-Version: 2.2.7
+Version: 2.2.8
 Summary: Simple, performant, battle-tested framework for building reliable AI applications
 Project-URL: Source, https://github.com/timbal-ai/timbal
 Author-email: Timbal <team@timbal.ai>

{timbal-2.2.7 → timbal-2.2.8}/python/timbal/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.2.7'
-__version_tuple__ = version_tuple = (2, 2, 7)
+__version__ = version = '2.2.8'
+__version_tuple__ = version_tuple = (2, 2, 8)
 
 __commit_id__ = commit_id = None

{timbal-2.2.7 → timbal-2.2.8}/python/timbal/codegen/cli_utils.py

@@ -3,10 +3,27 @@
 from __future__ import annotations
 
 import argparse
+import json
 import sys
 from pathlib import Path
 
 
+def parse_json_arg(raw: str, flag: str, *, hint: str = "") -> object:
+    """Parse a CLI argument as JSON, raising a clear ``ValueError`` on failure.
+
+    ``json.JSONDecodeError`` messages like ``Expecting value: line 1 column 1``
+    give no clue that the fix is quoting; this wraps them with the flag name,
+    the offending input, and an optional usage hint.
+    """
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as e:
+        message = f"{flag} must be a valid JSON literal (got {raw!r}): {e}."
+        if hint:
+            message = f"{message} {hint}"
+        raise ValueError(message) from e
+
+
 def arg_input(value: str) -> str:
     """argparse ``type`` callable supporting file and stdin redirection.
 

{timbal-2.2.7 → timbal-2.2.8}/python/timbal/codegen/cst_utils.py

@@ -190,6 +190,77 @@ def collect_step_names(
     return var_to_name
 
 
+def collect_chained_step_names(
+    tree: cst.Module,
+    entry_point: str,
+    assignments: dict[str, cst.Call],
+) -> dict[str, str]:
+    """Build a step variable → runtime name mapping for chained ``.step()`` calls.
+
+    Covers steps added in the entry point assignment itself, e.g.
+    ``workflow = Workflow(...).step(a).step(b)``. These steps exist in the
+    graph but cannot be modified by the standalone-statement transformers
+    (set-param, add-edge, remove-edge).
+    """
+    var_to_name: dict[str, str] = {}
+    for stmt in tree.body:
+        if not isinstance(stmt, cst.SimpleStatementLine):
+            continue
+        for item in stmt.body:
+            if not isinstance(item, cst.Assign):
+                continue
+            if not any(
+                isinstance(t.target, cst.Name) and t.target.value == entry_point
+                for t in item.targets
+            ):
+                continue
+            node = item.value
+            while isinstance(node, cst.Call) and isinstance(node.func, cst.Attribute):
+                if node.func.attr.value == "step" and node.args:
+                    first_arg = node.args[0].value
+                    resolved = resolve_runnable_name(first_arg, assignments)
+                    if isinstance(first_arg, cst.Name):
+                        var_to_name[first_arg.value] = resolved if resolved is not None else first_arg.value
+                    elif resolved is not None:
+                        var_to_name[resolved] = resolved
+                node = node.func.value
+    return var_to_name
+
+
+def require_step(
+    ref: str,
+    step_names: dict[str, str],
+    chained_step_names: dict[str, str] | None = None,
+    *,
+    kind: str = "Target",
+    operation: str,
+) -> str:
+    """Resolve *ref* (a step variable name or runtime name) to the runtime name.
+
+    ``step_names`` are the steps the operation can address. When *ref* only
+    matches ``chained_step_names`` (steps the operation cannot modify), or
+    matches nothing, a ``ValueError`` with an actionable message is raised.
+    """
+    if ref in step_names.values():
+        return ref
+    if ref in step_names:
+        return step_names[ref]
+
+    chained = chained_step_names or {}
+    if ref in chained or ref in chained.values():
+        raise ValueError(
+            f"{kind} step '{ref}' is added via a chained .step() call, which {operation} "
+            f"cannot modify. Rewrite it as a standalone '<workflow>.step(...)' statement first."
+        )
+
+    available = sorted(set(step_names.values()) | set(chained.values()))
+    if available:
+        raise ValueError(
+            f"{kind} step '{ref}' not found in workflow. Available steps: {', '.join(available)}."
+        )
+    raise ValueError(f"{kind} step '{ref}' not found in workflow. The workflow has no steps.")
+
+
 def is_bare_function_step(
     tree: cst.Module,
     entry_point: str,

{timbal-2.2.7 → timbal-2.2.8}/python/timbal/codegen/transformers/add_edge.py

@@ -5,8 +5,10 @@ import libcst as cst
 from ..cli_utils import arg_input
 from ..cst_utils import (
     collect_assignments,
+    collect_chained_step_names,
     collect_step_names,
     has_import,
+    require_step,
     resolve_entry_point_type,
 )
 
@@ -45,10 +47,16 @@ def run(entry_point: str, args: argparse.Namespace, *, tree: cst.Module | None =
         raise ValueError("add-edge requires a Workflow entry point.")
 
     when_expr = args.when if args.when else None
-    assignments = collect_assignments(tree) if tree else {}
-    step_names = collect_step_names(tree, entry_point, assignments) if tree else {}
+    assignments = collect_assignments(tree)
+    step_names = collect_step_names(tree, entry_point, assignments)
+    chained_step_names = collect_chained_step_names(tree, entry_point, assignments)
 
-    return EdgeAdder(entry_point, args.source, args.target, when_expr, assignments, step_names)
+    require_step(args.target, step_names, chained_step_names, kind="Target", operation="add-edge")
+    # Sources only need to exist in the graph — they are referenced by runtime
+    # name inside the target's depends_on list.
+    source = require_step(args.source, {**step_names, **chained_step_names}, kind="Source", operation="add-edge")
+
+    return EdgeAdder(entry_point, source, args.target, when_expr, assignments, step_names)
 
 
 class EdgeAdder(cst.CSTTransformer):

{timbal-2.2.7 → timbal-2.2.8}/python/timbal/codegen/transformers/add_step.py

@@ -1,9 +1,8 @@
 import argparse
-import json
 
 import libcst as cst
 
-from ..cli_utils import arg_input
+from ..cli_utils import arg_input, parse_json_arg
 from ..cst_utils import (
     build_cst_value,
     collect_assignments,
@@ -132,6 +131,19 @@ def _clean_position(position: dict[str, float]) -> dict[str, int | float]:
     }
 
 
+def _reject_non_name_config(config: dict, step_kind: str) -> None:
+    """Only Agent steps take constructor params via --config; for other step
+    kinds the only accepted key is 'name' (an alias for --name). Anything else
+    would previously be dropped silently — a common trap."""
+    unknown = set(config.keys()) - {"name"}
+    if unknown:
+        raise ValueError(
+            f"--config for {step_kind} steps only accepts 'name'; "
+            f"got: {', '.join(sorted(unknown))}. "
+            f"Use set-param to set the step's parameters, or set-config for its constructor."
+        )
+
+
 def register(subparsers: argparse._SubParsersAction) -> None:
     sp = subparsers.add_parser(
         "add-step",
@@ -160,6 +172,8 @@ def register(subparsers: argparse._SubParsersAction) -> None:
         type=arg_input,
         help=(
             'Agent constructor params as JSON. E.g. \'{"name": "agent_a", "model": "openai/gpt-4o-mini"}\'. '
+            "Framework tool and Custom steps only accept 'name' here (equivalent to --name); "
+            "use set-param for their step parameters. "
             "Use '@path' to read from file or '-' to read from stdin."
         ),
     )
@@ -175,7 +189,7 @@ def run(entry_point: str, args: argparse.Namespace, *, tree: cst.Module | None =
 
     assignments = collect_assignments(tree) if tree else {}
     step_type = args.step_type
-    config = json.loads(args.config) if args.config else {}
+    config = parse_json_arg(args.config, "--config") if args.config else {}
 
     if args.x is not None and args.y is not None:
         position = _clean_position({"x": args.x, "y": args.y})
@@ -199,6 +213,7 @@ def run(entry_point: str, args: argparse.Namespace, *, tree: cst.Module | None =
         )
 
     if step_type == "Custom":
+        _reject_non_name_config(config, "Custom")
         if not args.definition:
             raise ValueError("--definition is required for Custom steps.")
         func_tree = cst.parse_module(args.definition)
@@ -210,7 +225,7 @@ def run(entry_point: str, args: argparse.Namespace, *, tree: cst.Module | None =
         if func_def is None:
             raise ValueError("--definition must contain a function definition.")
         func_name = func_def.name.value
-        runtime_name = args.step_name if args.step_name else func_name
+        runtime_name = args.step_name or config.get("name") or func_name
         var_name = runtime_name
         # When the function name collides with the Tool variable name, add
         # a _fn suffix to the function to avoid shadowing.
@@ -258,9 +273,11 @@ def run(entry_point: str, args: argparse.Namespace, *, tree: cst.Module | None =
         )
 
     # Framework tool step.
+    _reject_non_name_config(config, "framework tool")
     framework_names = get_framework_tool_names()
-    var_name = args.step_name if args.step_name else framework_names[step_type]
-    runtime_name = args.step_name if args.step_name else framework_names[step_type]
+    step_name = args.step_name or config.get("name")
+    var_name = step_name if step_name else framework_names[step_type]
+    runtime_name = step_name if step_name else framework_names[step_type]
     return StepAdder(
         entry_point, assignments,
         step_type=step_type,
@@ -268,7 +285,7 @@ def run(entry_point: str, args: argparse.Namespace, *, tree: cst.Module | None =
         func_name=None,
         var_name=var_name,
         runtime_name=runtime_name,
-        step_name=args.step_name,
+        step_name=step_name,
         position=position,
     )
 

{timbal-2.2.7 → timbal-2.2.8}/python/timbal/codegen/transformers/add_tool.py

@@ -1,9 +1,8 @@
 import argparse
-import json
 
 import libcst as cst
 
-from ..cli_utils import arg_input
+from ..cli_utils import arg_input, parse_json_arg
 from ..cst_utils import (
     build_cst_value,
     collect_assignments,
@@ -99,7 +98,7 @@ def run(entry_point: str, args: argparse.Namespace, *, tree: cst.Module | None =
     if args.tool_name is not None and args.tool_name == "":
         raise ValueError("--name cannot be empty. Omit --name to use the default tool name.")
 
-    config = json.loads(args.config) if getattr(args, "config", None) else {}
+    config = parse_json_arg(args.config, "--config") if getattr(args, "config", None) else {}
     if config:
         # Reject keys that would collide with explicit flags / derived values.
         # Without this, the generated source has duplicate kwargs and ruff

{timbal-2.2.7 → timbal-2.2.8}/python/timbal/codegen/transformers/remove_edge.py

@@ -4,7 +4,9 @@ import libcst as cst
 
 from ..cst_utils import (
     collect_assignments,
+    collect_chained_step_names,
     collect_step_names,
+    require_step,
     resolve_entry_point_type,
 )
 
@@ -32,8 +34,15 @@ def run(entry_point: str, args: argparse.Namespace, *, tree: cst.Module | None =
     if ep_type != "Workflow":
         raise ValueError("remove-edge requires a Workflow entry point.")
 
-    assignments = collect_assignments(tree) if tree else {}
-    step_names = collect_step_names(tree, entry_point, assignments) if tree else {}
+    assignments = collect_assignments(tree)
+    step_names = collect_step_names(tree, entry_point, assignments)
+    chained_step_names = collect_chained_step_names(tree, entry_point, assignments)
+
+    # Only the target must be addressable — the source may already have been
+    # removed from the workflow, and remove-edge is how dangling references
+    # (stale depends_on entries, step_span kwargs) get cleaned up.
+    require_step(args.target, step_names, chained_step_names, kind="Target", operation="remove-edge")
+
     return EdgeRemover(entry_point, args.source, args.target, assignments, step_names)
 
 

{timbal-2.2.7 → timbal-2.2.8}/python/timbal/codegen/transformers/set_config.py

@@ -1,9 +1,8 @@
 import argparse
-import json
 
 import libcst as cst
 
-from ..cli_utils import arg_input
+from ..cli_utils import arg_input, parse_json_arg
 from ..cst_utils import (
     build_cst_value,
     collect_assignments,
@@ -53,7 +52,7 @@ def register(subparsers: argparse._SubParsersAction) -> None:
 def run(entry_point: str, args: argparse.Namespace, *, tree: cst.Module | None = None) -> cst.CSTTransformer:
     ep_type = resolve_entry_point_type(tree, entry_point) if tree else None
 
-    config = json.loads(args.config) if args.config else {}
+    config = parse_json_arg(args.config, "--config") if args.config else {}
 
     # --- Workflow entry point ---
     if ep_type == "Workflow":

{timbal-2.2.7 → timbal-2.2.8}/python/timbal/codegen/transformers/set_param.py

@@ -4,10 +4,13 @@ import re
 
 import libcst as cst
 
-from ..cli_utils import arg_input
+from ..cli_utils import arg_input, parse_json_arg
 from ..cst_utils import (
     collect_assignments,
+    collect_chained_step_names,
+    collect_step_names,
     has_import,
+    require_step,
     resolve_entry_point_type,
     resolve_runnable_name,
 )
@@ -108,7 +111,9 @@ def register(subparsers: argparse._SubParsersAction) -> None:
         default=None,
         type=arg_input,
         help=(
-            "Static value as a JSON literal (required for type=value). Use 'null' to remove the param. "
+            "Static value as a JSON literal (required for type=value). "
+            "Strings must include the JSON quotes, e.g. --value '\"is:unread\"'. "
+            "Use 'null' to remove the param. "
             "Use '@path' to read from file or '-' to read from stdin."
         ),
     )
@@ -120,32 +125,48 @@ def run(entry_point: str, args: argparse.Namespace, *, tree: cst.Module | None =
     if ep_type != "Workflow":
         raise ValueError("set-param requires a Workflow entry point.")
 
+    assignments = collect_assignments(tree)
+    step_names = collect_step_names(tree, entry_point, assignments)
+    chained_step_names = collect_chained_step_names(tree, entry_point, assignments)
+
+    require_step(args.target, step_names, chained_step_names, kind="Target", operation="set-param")
+
     param_type = args.param_type
 
     if param_type == "map":
         if not args.source:
             raise ValueError("--source is required for type=map.")
+        # Sources only need to exist in the graph (chained steps are fine) —
+        # they are referenced by runtime name inside step_span().
+        source = require_step(
+            args.source, {**step_names, **chained_step_names}, kind="Source", operation="set-param",
+        )
         return ParamSetter(
             entry_point=entry_point,
             target=args.target,
             param_name=args.name,
             param_type="map",
-            source=args.source,
+            source=source,
             key=args.key,
-            assignments=collect_assignments(tree) if tree else {},
+            assignments=assignments,
+            step_names=step_names,
         )
 
     if param_type == "value":
         if args.value is None:
             raise ValueError("--value is required for type=value.")
-        value = json.loads(args.value)
+        value = parse_json_arg(
+            args.value, "--value",
+            hint="String values must include the JSON quotes, e.g. --value '\"is:unread label:inbox\"'.",
+        )
         return ParamSetter(
             entry_point=entry_point,
             target=args.target,
             param_name=args.name,
             param_type="value",
             value=value,
-            assignments=collect_assignments(tree) if tree else {},
+            assignments=assignments,
+            step_names=step_names,
         )
 
     raise ValueError(f"Unknown param type: {param_type}")
@@ -164,6 +185,7 @@ class ParamSetter(cst.CSTTransformer):
         key: str | None = None,
         value: object = None,
         assignments: dict[str, cst.Call] | None = None,
+        step_names: dict[str, str] | None = None,
     ):
         self.entry_point = entry_point
         self.target = target
@@ -173,6 +195,7 @@ class ParamSetter(cst.CSTTransformer):
         self.key = key
         self.value = value
         self.assignments = assignments or {}
+        self.step_names = step_names or {}
         self.needs_reorder = param_type == "map"
 
     def _is_step_call(self, call: cst.Call) -> bool:
@@ -197,16 +220,19 @@ class ParamSetter(cst.CSTTransformer):
         return False
 
     def _matches_target(self, call: cst.Call) -> bool:
+        """Match by variable name or runtime name (mirrors add-edge)."""
         if not call.args:
             return False
         first_arg = call.args[0].value
         if isinstance(first_arg, cst.Name):
             var_name = first_arg.value
-            if var_name in self.assignments:
-                resolved = resolve_runnable_name(self.assignments[var_name])
-                if resolved is not None:
-                    return resolved == self.target
-            return var_name == self.target
+            if var_name == self.target:
+                return True
+            runtime_name = self.step_names.get(var_name)
+            if runtime_name is None and var_name in self.assignments:
+                runtime_name = resolve_runnable_name(self.assignments[var_name])
+            if runtime_name is not None and runtime_name == self.target:
+                return True
         return False
 
     def leave_Expr(self, original_node: cst.Expr, updated_node: cst.Expr) -> cst.Expr:

{timbal-2.2.7 → timbal-2.2.8}/python/timbal/codegen/transformers/set_position.py

@@ -5,7 +5,10 @@ import libcst as cst
 from ..cst_utils import (
     build_cst_value,
     collect_assignments,
+    collect_chained_step_names,
+    collect_step_names,
     is_bare_function_step,
+    require_step,
     resolve_entry_point_type,
     resolve_runnable_name,
     wrap_bare_function_step,
@@ -42,7 +45,14 @@ def run(entry_point: str, args: argparse.Namespace, *, tree: cst.Module | None =
             assignments = collect_assignments(tree)
             return StepPositionSetter(entry_point, args.name, position, assignments), tree
 
-        return StepPositionSetter(entry_point, args.name, position, assignments)
+        # Position lives on the step's constructor assignment, so chained
+        # steps are addressable too — validate against the full graph.
+        step_names = collect_step_names(tree, entry_point, assignments)
+        chained_step_names = collect_chained_step_names(tree, entry_point, assignments)
+        name = require_step(
+            args.name, {**step_names, **chained_step_names}, kind="Target", operation="set-position",
+        )
+        return StepPositionSetter(entry_point, name, position, assignments)
 
     # Agent (or unknown) entry point — set on the constructor directly.
     if args.name: