timbal 2.2.3__tar.gz → 2.2.4__tar.gz

{timbal-2.2.3 → timbal-2.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: timbal
-Version: 2.2.3
+Version: 2.2.4
 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.3 → timbal-2.2.4}/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.3'
-__version_tuple__ = version_tuple = (2, 2, 3)
+__version__ = version = '2.2.4'
+__version_tuple__ = version_tuple = (2, 2, 4)
 
 __commit_id__ = commit_id = None

{timbal-2.2.3 → timbal-2.2.4}/python/timbal/codegen/flow.py

@@ -203,6 +203,24 @@ def _build_node(runnable: Any, *, include_tools: bool = True) -> dict[str, Any]:
     return node
 
 
+def _edge_kind(kinds: set[str] | None) -> str:
+    """Collapse a set of edge-origin kinds into a single label for JSON output.
+
+    A dependency can arise from several sources at once (e.g. an explicit
+    ``depends_on`` that also reads the step's output via a param map). Precedence
+    is ``ordering > when > param`` so explicit sequencing is never masked by
+    param wiring. Unknown/missing (e.g. edges from a direct ``_link``) default to
+    ``ordering`` — the safe choice, since ordering edges are never reduced away.
+    """
+    if not kinds:
+        return "ordering"
+    if "ordering" in kinds:
+        return "ordering"
+    if "when" in kinds:
+        return "when"
+    return "param"
+
+
 def get_flow(workspace_path: str | Path) -> dict[str, Any]:
     """Return a ReactFlow-compatible graph for the workspace entry point.
 
@@ -239,12 +257,14 @@ def get_flow(workspace_path: str | Path) -> dict[str, Any]:
 
         for _step_name, step in runnable._steps.items():
             when_source = _get_when_source(step) if step.when else None
+            kinds_map = getattr(step, "previous_steps_kinds", None) or {}
             for prev_name in step.previous_steps:
                 prev_step = runnable._steps[prev_name]
                 edge: dict[str, Any] = {
                     "id": f"{prev_step._path}->{step._path}",
                     "source": prev_step._path,
                     "target": step._path,
+                    "kind": _edge_kind(kinds_map.get(prev_name)),
                 }
                 if when_source is not None:
                     edge["when"] = when_source
@@ -390,6 +410,48 @@ def _fmt_node_lines(node: dict, indent: str) -> list[str]:
     return lines
 
 
+def _reduce_param_edges(edges: list[dict]) -> list[dict]:
+    """Drop param-induced edges that are transitively implied by another path.
+
+    A param dependency ``A → C`` (the handler/agent on C reads A's output) is a
+    real await-gate at runtime, but for an execution-order view it is redundant
+    when A already reaches C through some other path (e.g. ``A → B → C``). Left
+    in, such edges turn a linear pipeline into a misleading fan-out from the
+    first step.
+
+    Only edges whose single ``kind`` is ``param`` are eligible for removal —
+    explicit ordering (``depends_on`` / hooks) and ``when`` edges are always
+    kept so user-added structure never silently disappears from the compact
+    view. The full edge set (including these) is retained in the JSON output.
+    """
+    adj: dict[str, list[str]] = defaultdict(list)
+    for e in edges:
+        adj[e["source"]].append(e["target"])
+
+    def _reaches(start: str, goal: str, skip: tuple[str, str]) -> bool:
+        """True if ``goal`` is reachable from ``start`` without using the direct ``skip`` edge."""
+        stack = [start]
+        seen = {start}
+        while stack:
+            node = stack.pop()
+            for nxt in adj.get(node, []):
+                if (node, nxt) == skip:
+                    continue
+                if nxt == goal:
+                    return True
+                if nxt not in seen:
+                    seen.add(nxt)
+                    stack.append(nxt)
+        return False
+
+    kept: list[dict] = []
+    for e in edges:
+        if e.get("kind") == "param" and _reaches(e["source"], e["target"], (e["source"], e["target"])):
+            continue
+        kept.append(e)
+    return kept
+
+
 def _build_edge_lines(edges: list[dict]) -> list[str]:
     """Render edges grouped by source, one line per source node."""
     targets_of: dict[str, list[tuple[str, str | None]]] = defaultdict(list)
@@ -472,6 +534,7 @@ def format_compact(flow: dict) -> str:
             for line in _fmt_node_lines(node, indent="  "):
                 lines.append(line)
 
+    edges = _reduce_param_edges(edges)
     if edges:
         lines.append("")
         lines.append("EDGES")

{timbal-2.2.3 → timbal-2.2.4}/python/timbal/core/workflow.py

@@ -142,29 +142,53 @@ class Workflow(Runnable):
         self._steps[runnable.name] = runnable
         runnable.previous_steps = set()
         runnable.next_steps = set()
+        # Per-source edge kinds: maps a previous step name -> set of kinds
+        # ("ordering" | "when" | "param"). Used by introspection (get_flow) to
+        # distinguish explicit sequencing from param/when-induced dependencies.
+        # Runtime sequencing only ever looks at ``previous_steps``.
+        runnable.previous_steps_kinds = {}
         runnable.when = None
 
         # Explicit dependencies
         if depends_on and not isinstance(depends_on, list):
             raise ValueError("depends_on must be a list of step names")
-        depends_on = set(depends_on or [])  # Deduplicate here to avoid duplicate _is_dag calls
 
-        depends_on.update(runnable._dependencies)
-        depends_on.update(runnable._pre_hook_dependencies)
-        depends_on.update(runnable._post_hook_dependencies)
+        # Track dependency origins so introspection can tell explicit ordering
+        # (depends_on / hooks) apart from param- and when-induced wiring. These
+        # all merge into ``previous_steps`` for execution, but the distinction is
+        # lossy once merged (a step can be both an explicit dep and a param dep),
+        # so we record it here while the sources are still separate.
+        ordering_deps = set(depends_on or [])
+        # Hooks read sibling outputs via step_span(); treat as ordering so they
+        # are never silently collapsed in compact views.
+        ordering_deps.update(runnable._pre_hook_dependencies)
+        ordering_deps.update(runnable._post_hook_dependencies)
+        # Handler-body step_span() references are data wiring, not explicit ordering.
+        param_deps = set(runnable._dependencies)
+        when_deps: set[str] = set()
 
         # Optional handler to determine whether to execute the step, and inspect it to automatically link steps
         if when:
             inspect_result = runnable._inspect_callable(when)
             runnable.when = {"callable": when, **inspect_result}
-            depends_on.update(inspect_result["dependencies"])
+            when_deps.update(inspect_result["dependencies"])
 
         # Use kwargs as default params for the runnable, and inspect callables to automatically link steps
         runnable._prepare_default_params(kwargs)
         for v in runnable._default_runtime_params.values():
-            depends_on.update(v["dependencies"])
-
-        for dep in depends_on:
+            param_deps.update(v["dependencies"])
+
+        edge_kinds: dict[str, set[str]] = {}
+        for dep in ordering_deps:
+            edge_kinds.setdefault(dep, set()).add("ordering")
+        for dep in when_deps:
+            edge_kinds.setdefault(dep, set()).add("when")
+        for dep in param_deps:
+            edge_kinds.setdefault(dep, set()).add("param")
+        runnable.previous_steps_kinds = edge_kinds
+
+        # Deduplicate (set union) to avoid duplicate _is_dag calls per shared dep.
+        for dep in edge_kinds:
             logger.info("Linking steps", previous_step=dep, next_step=runnable.name)
             self._link(dep, runnable.name)