adk-graph-workflow 0.1.0__py3-none-any.whl

adk_graph_workflow-0.1.0.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: adk-graph-workflow
+Version: 0.1.0
+Summary: YAML-defined graph workflows for Google ADK agents
+Requires-Python: >=3.10
+Requires-Dist: google-adk>=1.0.0
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'

adk_graph_workflow-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+graph_workflow/__init__.py,sha256=4VUu4k-oOWSAXUrZLm7VCVDW9ptYug-2GY_Y4ebHatc,3132
+graph_workflow/compiler.py,sha256=PMHcqUM0nDeuQRT8h6AYdzm0ujFyGWQof2b-h4gfVDI,14661
+graph_workflow/errors.py,sha256=jVSuPAJbTdIOO5enhNcuUAwVUH1JsuR-bWfNR8zmnZI,1166
+graph_workflow/evaluator.py,sha256=Lg3T3Lmvf_uqV6qUJ9guJpSkn-2Pl5YcFgolN13VNVA,4562
+graph_workflow/models.py,sha256=1FC6LBqViWD4-g7asohhNdrB1QOIYd_t1vsvHLUVsvA,2819
+graph_workflow/resolver.py,sha256=_Nv9DA-ORbiJxzdzRjdoGU33k4nYyUiQfsG2UNgBJKw,3030
+graph_workflow/runner.py,sha256=wzsvIfgl9lRSmYCP45bjxa9lDWQnx3X9t5hpENBTWUs,4935
+graph_workflow/schema.py,sha256=DwsKUBq1IYNhVg9NNWEVJGrVhSa3n-EcX4g0w5fuKps,922
+graph_workflow/validator.py,sha256=Rg2cZM4rYct8jLJP7pnGRzGJtWLrv12TSetXC2Jkpjc,5866
+graph_workflow/data/schema.json,sha256=6Ex4IYzDW9DKRBFXOEw6Jy48OczBD4TrMkUTsCkljCQ,3840
+adk_graph_workflow-0.1.0.dist-info/METADATA,sha256=IV5sW40bH1tA4CpiJxWvguqx3ZYLkPSllP-w6UTdNaQ,428
+adk_graph_workflow-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+adk_graph_workflow-0.1.0.dist-info/RECORD,,

adk_graph_workflow-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

graph_workflow/__init__.py

@@ -0,0 +1,104 @@
+"""ADK Graph Workflow — YAML-defined graph workflows for Google ADK agents."""
+
+import importlib
+from pathlib import Path
+
+import yaml
+
+from graph_workflow.compiler import CompiledEdge, CompiledGraph, CompiledNode, GraphCompiler
+from graph_workflow.errors import (
+    ConditionEvalError,
+    FunctionResolutionError,
+    GraphCompilationError,
+    GraphExecutionError,
+    GraphValidationError,
+    GraphWorkflowError,
+)
+from graph_workflow.evaluator import ConditionEvaluator
+from graph_workflow.models import (
+    EdgeDef,
+    FnRef,
+    FunctionDef,
+    FunctionNodeDef,
+    GraphWorkflowDef,
+    LanggraphAgentNodeDef,
+    LoopAgentNodeDef,
+    LlmAgentNodeDef,
+    NodeDef,
+    ParallelAgentNodeDef,
+    SequentialAgentNodeDef,
+    ToolRef,
+)
+from graph_workflow.resolver import FunctionResolver
+from graph_workflow.runner import GraphRunnerAgent
+from graph_workflow.schema import SchemaValidator
+from graph_workflow.validator import GraphValidator
+
+
+def _auto_resolve_langgraph_refs(workflow: GraphWorkflowDef, registry: dict) -> None:
+    """Resolve langgraph_agent graph references not already in the registry."""
+    for _key, node_def in workflow.nodes.items():
+        if not isinstance(node_def, LanggraphAgentNodeDef):
+            continue
+        graph_ref = node_def.graph
+        if graph_ref in registry:
+            continue
+        module_path, _, attr_name = graph_ref.rpartition(".")
+        if not module_path:
+            continue
+        try:
+            module = importlib.import_module(module_path)
+            registry[graph_ref] = getattr(module, attr_name)
+        except (ImportError, AttributeError):
+            pass
+
+
+def from_config(config_path: str) -> GraphRunnerAgent:
+    """Load a graph workflow from a YAML config file and return a ready-to-run agent."""
+    path = Path(config_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {config_path}")
+    raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    SchemaValidator().validate(raw)
+    workflow = GraphWorkflowDef.model_validate(raw)
+    GraphValidator().validate(workflow)
+    resolver = FunctionResolver(workflow.functions)
+    registry = {name: resolver.resolve(name) for name in workflow.functions}
+    _auto_resolve_langgraph_refs(workflow, registry)
+    compiled = GraphCompiler(registry).compile(workflow)
+    return GraphRunnerAgent(name=workflow.name, graph=compiled)
+
+__all__ = [
+    # Convenience
+    "from_config",
+    # Models
+    "EdgeDef",
+    "FnRef",
+    "FunctionDef",
+    "FunctionNodeDef",
+    "GraphWorkflowDef",
+    "LanggraphAgentNodeDef",
+    "LoopAgentNodeDef",
+    "LlmAgentNodeDef",
+    "NodeDef",
+    "ParallelAgentNodeDef",
+    "SequentialAgentNodeDef",
+    "ToolRef",
+    # Errors
+    "ConditionEvalError",
+    "FunctionResolutionError",
+    "GraphCompilationError",
+    "GraphExecutionError",
+    "GraphValidationError",
+    "GraphWorkflowError",
+    # Core
+    "CompiledEdge",
+    "CompiledGraph",
+    "CompiledNode",
+    "ConditionEvaluator",
+    "FunctionResolver",
+    "GraphCompiler",
+    "GraphRunnerAgent",
+    "GraphValidator",
+    "SchemaValidator",
+]

graph_workflow/compiler.py

@@ -0,0 +1,405 @@
+"""Graph compiler — compiles workflow definitions into ADK agents."""
+from __future__ import annotations
+
+import importlib
+import inspect
+from dataclasses import dataclass
+from typing import Any, AsyncGenerator, Callable
+
+from google.adk.agents import (
+    BaseAgent,
+    LlmAgent,
+    LoopAgent,
+    ParallelAgent,
+    SequentialAgent,
+)
+from google.adk.events import Event
+from google.adk.tools.base_tool import BaseTool
+from google.adk.tools.base_toolset import BaseToolset
+
+try:
+    from google.adk.agents import LanggraphAgent
+except ImportError:
+    LanggraphAgent = None  # type: ignore[misc, assignment]
+
+from graph_workflow.errors import GraphCompilationError
+from graph_workflow.models import (
+    EdgeDef,
+    FunctionNodeDef,
+    GraphWorkflowDef,
+    LanggraphAgentNodeDef,
+    LlmAgentNodeDef,
+    LoopAgentNodeDef,
+    ParallelAgentNodeDef,
+    SequentialAgentNodeDef,
+    ToolRef,
+)
+from graph_workflow.resolver import interpolate_value
+
+
+@dataclass
+class CompiledNode:
+    """A node that has been compiled and is ready for execution."""
+
+    key: str
+    callable: Callable[..., Any] | None = None
+    agent: BaseAgent | None = None
+    output_key: str | None = None
+
+    @property
+    def is_function(self) -> bool:
+        return self.callable is not None
+
+    @property
+    def is_agent(self) -> bool:
+        return self.agent is not None
+
+
+@dataclass
+class CompiledEdge:
+    """A compiled edge with resolved target and condition."""
+
+    to_key: str
+    condition: str | None = None
+
+
+@dataclass
+class CompiledGraph:
+    """A fully compiled graph ready for execution."""
+
+    entry: str
+    exit: str | None
+    nodes: dict[str, CompiledNode]
+    adjacency: dict[str, list[CompiledEdge]]
+
+
+class _InlineFunctionAgent(BaseAgent):
+    """Wraps a function node so it can act as a sub-agent in containers."""
+
+    def __init__(
+        self,
+        name: str,
+        fn: Callable[..., Any],
+        output_key: str | None = None,
+    ):
+        super().__init__(name=name)
+        self._fn = fn
+        self._output_key = output_key
+
+    async def _run_async_impl(
+        self, ctx
+    ) -> AsyncGenerator[Event, None]:
+        state = dict(ctx.session.state)
+        result = self._fn(state)
+        if inspect.isawaitable(result):
+            result = await result
+        if self._output_key and result is not None:
+            ctx.session.state[self._output_key] = result
+        yield Event(author=self.name)
+
+
+def _interpolate_tool_args(
+    args: dict[str, Any] | None,
+) -> dict[str, Any] | None:
+    """Interpolate ${ENV_VAR} references in tool args."""
+    if args is None:
+        return None
+    return {k: interpolate_value(v) for k, v in args.items()}
+
+
+class GraphCompiler:
+    """Compiles a GraphWorkflowDef into a CompiledGraph.
+
+    Uses two-pass compilation:
+    1. Non-container nodes (FunctionNodeDef, LlmAgentNodeDef, LanggraphAgentNodeDef)
+    2. Container nodes (SequentialAgentNodeDef, ParallelAgentNodeDef, LoopAgentNodeDef)
+
+    Container nodes are compiled second so that their sub_agents have
+    already been compiled and can be resolved from ``_compiled``.
+    """
+
+    def __init__(self, func_registry: dict[str, Callable[..., Any]]):
+        self._func_registry = func_registry
+        self._compiled: dict[str, CompiledNode] = {}
+        self._workflow: GraphWorkflowDef | None = None
+        self._compiling: set[str] = set()
+
+    def compile(self, workflow: GraphWorkflowDef) -> CompiledGraph:
+        """Compile *workflow* into a :class:`CompiledGraph`."""
+        self._compiled = {}
+        self._compiling = set()
+        self._workflow = workflow
+
+        # First pass: non-container nodes
+        for key, node_def in workflow.nodes.items():
+            if not isinstance(
+                node_def,
+                (SequentialAgentNodeDef, ParallelAgentNodeDef, LoopAgentNodeDef),
+            ):
+                self._compiled[key] = self._compile_node(key, node_def)
+
+        # Second pass: container nodes (sub_agents now available)
+        for key, node_def in workflow.nodes.items():
+            if isinstance(
+                node_def,
+                (SequentialAgentNodeDef, ParallelAgentNodeDef, LoopAgentNodeDef),
+            ):
+                if key not in self._compiled:
+                    self._compiled[key] = self._compile_node(key, node_def)
+
+        adjacency = self._build_adjacency(workflow.edges)
+        return CompiledGraph(
+            entry=workflow.entry,
+            exit=workflow.exit,
+            nodes=dict(self._compiled),
+            adjacency=adjacency,
+        )
+
+    # -- node compilation ----------------------------------------------------
+
+    def _compile_node(self, key: str, node_def: Any) -> CompiledNode:
+        if isinstance(node_def, FunctionNodeDef):
+            return self._compile_function_node(key, node_def)
+        if isinstance(node_def, LlmAgentNodeDef):
+            return self._compile_llm_agent(key, node_def)
+        if isinstance(node_def, SequentialAgentNodeDef):
+            return self._compile_sequential_agent(key, node_def)
+        if isinstance(node_def, ParallelAgentNodeDef):
+            return self._compile_parallel_agent(key, node_def)
+        if isinstance(node_def, LoopAgentNodeDef):
+            return self._compile_loop_agent(key, node_def)
+        if isinstance(node_def, LanggraphAgentNodeDef):
+            return self._compile_langgraph_agent(key, node_def)
+        node_type = getattr(node_def, "type", type(node_def).__name__)
+        raise GraphCompilationError(
+            f"Unknown node type: {node_type}",
+            node_id=key,
+        )
+
+    def _compile_function_node(
+        self, key: str, node_def: FunctionNodeDef
+    ) -> CompiledNode:
+        func = self._func_registry.get(node_def.function)
+        if func is None:
+            raise GraphCompilationError(
+                f"Function '{node_def.function}' not found in registry",
+                node_id=key,
+            )
+        return CompiledNode(key=key, callable=func, output_key=node_def.output_key)
+
+    def _compile_llm_agent(
+        self, key: str, node_def: LlmAgentNodeDef
+    ) -> CompiledNode:
+        resolved_tools = self._resolve_tools(node_def.tools, key)
+        kwargs: dict[str, Any] = {
+            "name": key,
+            "model": node_def.model,
+            "instruction": node_def.instruction,
+            "tools": resolved_tools,
+            "output_key": node_def.output_key,
+        }
+        if node_def.output_schema is not None:
+            kwargs["output_schema"] = node_def.output_schema
+        try:
+            agent = LlmAgent(**kwargs)
+        except Exception as exc:
+            raise GraphCompilationError(
+                f"Failed to create LlmAgent: {exc}",
+                node_id=key,
+            ) from exc
+        return CompiledNode(key=key, agent=agent, output_key=node_def.output_key)
+
+    def _resolve_tools(self, tools: list[ToolRef], key: str) -> list[Any]:
+        """Resolve tool references to actual tool objects.
+
+        Follows ADK's native _resolve_tools pattern:
+        1. No dot in name - built-in tool from google.adk.tools
+        2. Dot in name - dotted path import
+        3. Dispatch by type: instance, class, factory function, or plain callable
+        """
+        resolved: list[Any] = []
+        for tool_ref in tools:
+            obj = self._import_tool(tool_ref.name, key)
+            args = _interpolate_tool_args(tool_ref.args)
+
+            if isinstance(obj, BaseTool | BaseToolset):
+                resolved.append(obj)
+            elif inspect.isclass(obj) and issubclass(obj, BaseTool | BaseToolset):
+                try:
+                    resolved.append(obj(**(args or {})))
+                except Exception as exc:
+                    raise GraphCompilationError(
+                        f"Failed to instantiate tool class '{tool_ref.name}': {exc}",
+                        node_id=key,
+                    ) from exc
+            elif callable(obj):
+                if args is not None:
+                    resolved.append(obj(args))
+                else:
+                    resolved.append(obj)
+            else:
+                raise GraphCompilationError(
+                    f"Tool '{tool_ref.name}' is not a valid tool "
+                    f"(expected Callable, BaseTool, or BaseToolset, "
+                    f"got {type(obj).__name__})",
+                    node_id=key,
+                )
+        return resolved
+
+    def _import_tool(self, name: str, key: str) -> Any:
+        """Import a tool by name — built-in or dotted path."""
+        if "." not in name:
+            try:
+                module = importlib.import_module("google.adk.tools")
+            except ImportError as exc:
+                raise GraphCompilationError(
+                    f"Cannot import google.adk.tools for built-in tool '{name}': {exc}",
+                    node_id=key,
+                ) from exc
+            try:
+                return getattr(module, name)
+            except AttributeError as exc:
+                raise GraphCompilationError(
+                    f"Built-in tool '{name}' not found in google.adk.tools",
+                    node_id=key,
+                ) from exc
+
+        module_path, _, obj_name = name.rpartition(".")
+        try:
+            module = importlib.import_module(module_path)
+        except ImportError as exc:
+            raise GraphCompilationError(
+                f"Cannot import module '{module_path}' for tool '{name}'",
+                node_id=key,
+            ) from exc
+        try:
+            return getattr(module, obj_name)
+        except AttributeError as exc:
+            raise GraphCompilationError(
+                f"Tool '{obj_name}' not found in module '{module_path}'",
+                node_id=key,
+            ) from exc
+
+    def _compile_sequential_agent(
+        self, key: str, node_def: SequentialAgentNodeDef
+    ) -> CompiledNode:
+        sub_agents = self._resolve_sub_agents(node_def.sub_agents, key)
+        try:
+            agent = SequentialAgent(name=key, sub_agents=sub_agents)
+        except Exception as exc:
+            raise GraphCompilationError(
+                f"Failed to create SequentialAgent: {exc}",
+                node_id=key,
+            ) from exc
+        return CompiledNode(key=key, agent=agent)
+
+    def _compile_parallel_agent(
+        self, key: str, node_def: ParallelAgentNodeDef
+    ) -> CompiledNode:
+        sub_agents = self._resolve_sub_agents(node_def.sub_agents, key)
+        try:
+            agent = ParallelAgent(name=key, sub_agents=sub_agents)
+        except Exception as exc:
+            raise GraphCompilationError(
+                f"Failed to create ParallelAgent: {exc}",
+                node_id=key,
+            ) from exc
+        return CompiledNode(key=key, agent=agent)
+
+    def _compile_loop_agent(
+        self, key: str, node_def: LoopAgentNodeDef
+    ) -> CompiledNode:
+        sub_agents = self._resolve_sub_agents(node_def.sub_agents, key)
+        try:
+            agent = LoopAgent(
+                name=key,
+                sub_agents=sub_agents,
+                max_iterations=node_def.max_iterations,
+            )
+        except Exception as exc:
+            raise GraphCompilationError(
+                f"Failed to create LoopAgent: {exc}",
+                node_id=key,
+            ) from exc
+        return CompiledNode(key=key, agent=agent)
+
+    def _compile_langgraph_agent(
+        self, key: str, node_def: LanggraphAgentNodeDef
+    ) -> CompiledNode:
+        graph = self._func_registry.get(node_def.graph)
+        if graph is None:
+            raise GraphCompilationError(
+                f"Graph function '{node_def.graph}' not found in registry",
+                node_id=key,
+            )
+        if LanggraphAgent is None:
+            raise GraphCompilationError(
+                "LanggraphAgent is not available — install langchain-core and langgraph packages",
+                node_id=key,
+            )
+        try:
+            agent = LanggraphAgent(
+                name=key, graph=graph, instruction=node_def.instruction
+            )
+        except Exception as exc:
+            raise GraphCompilationError(
+                f"Failed to create LanggraphAgent: {exc}",
+                node_id=key,
+            ) from exc
+        return CompiledNode(key=key, agent=agent)
+
+    # -- helpers -------------------------------------------------------------
+
+    def _resolve_sub_agents(
+        self, sub_agent_keys: list[str], parent_key: str
+    ) -> list[BaseAgent]:
+        agents: list[BaseAgent] = []
+        for k in sub_agent_keys:
+            compiled = self._compiled.get(k)
+            # If not compiled yet (nested container), try recursive compilation
+            if compiled is None and self._workflow is not None:
+                if k in self._compiling:
+                    raise GraphCompilationError(
+                        f"Circular sub-agent reference detected: '{k}'",
+                        node_id=parent_key,
+                    )
+                node_def = self._workflow.nodes.get(k)
+                if node_def is not None and k not in self._compiled:
+                    self._compiling.add(k)
+                    try:
+                        self._compiled[k] = self._compile_node(k, node_def)
+                    finally:
+                        self._compiling.discard(k)
+                    compiled = self._compiled[k]
+            if compiled is None:
+                raise GraphCompilationError(
+                    f"Sub-agent '{k}' has not been compiled",
+                    node_id=parent_key,
+                    detail=f"Compiled keys: {sorted(self._compiled.keys())}",
+                )
+            if compiled.agent is not None:
+                agents.append(compiled.agent)
+            elif compiled.callable is not None:
+                # Wrap function nodes so they can be used as sub-agents
+                agents.append(
+                    _InlineFunctionAgent(
+                        name=k,
+                        fn=compiled.callable,
+                        output_key=compiled.output_key,
+                    )
+                )
+            else:
+                raise GraphCompilationError(
+                    f"Sub-agent '{k}' is not an agent or function",
+                    node_id=parent_key,
+                )
+        return agents
+
+    @staticmethod
+    def _build_adjacency(edges: list[EdgeDef]) -> dict[str, list[CompiledEdge]]:
+        adj: dict[str, list[CompiledEdge]] = {}
+        for edge in edges:
+            adj.setdefault(edge.from_, []).append(
+                CompiledEdge(to_key=edge.to, condition=edge.condition)
+            )
+        return adj

graph_workflow/data/schema.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GraphWorkflow",
+  "type": "object",
+  "required": ["version", "name", "entry", "nodes"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "2.0"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "entry": {
+      "type": "string",
+      "minLength": 1
+    },
+    "exit": {
+      "type": "string"
+    },
+    "nodes": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "$ref": "#/definitions/NodeDef"
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/EdgeDef"
+      }
+    },
+    "functions": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/FunctionDef"
+      }
+    }
+  },
+  "definitions": {
+    "EdgeDef": {
+      "type": "object",
+      "required": ["from", "to"],
+      "additionalProperties": false,
+      "properties": {
+        "from": {"type": "string", "minLength": 1},
+        "to": {"type": "string", "minLength": 1},
+        "condition": {"type": "string"}
+      }
+    },
+    "FunctionDef": {
+      "type": "object",
+      "required": ["callable"],
+      "additionalProperties": false,
+      "properties": {
+        "callable": {"type": "string", "minLength": 1},
+        "args": {"type": "object"}
+      }
+    },
+    "NodeDef": {
+      "oneOf": [
+        {"$ref": "#/definitions/FunctionNodeDef"},
+        {"$ref": "#/definitions/LlmAgentNodeDef"},
+        {"$ref": "#/definitions/SequentialAgentNodeDef"},
+        {"$ref": "#/definitions/ParallelAgentNodeDef"},
+        {"$ref": "#/definitions/LoopAgentNodeDef"},
+        {"$ref": "#/definitions/LanggraphAgentNodeDef"}
+      ]
+    },
+    "FunctionNodeDef": {
+      "type": "object",
+      "required": ["type", "function"],
+      "properties": {
+        "type": {"type": "string", "const": "function"},
+        "function": {"type": "string", "minLength": 1},
+        "output_key": {"type": "string"}
+      }
+    },
+    "LlmAgentNodeDef": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": {"type": "string", "const": "llm_agent"},
+        "model": {"type": "string"},
+        "instruction": {"type": "string"},
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "additionalProperties": false,
+            "properties": {
+              "name": {"type": "string", "minLength": 1},
+              "args": {"type": "object"}
+            }
+          }
+        },
+        "output_key": {"type": "string"},
+        "output_schema": {"type": "object"}
+      }
+    },
+    "SequentialAgentNodeDef": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": {"type": "string", "const": "sequential_agent"},
+        "sub_agents": {"type": "array", "items": {"type": "string"}}
+      }
+    },
+    "ParallelAgentNodeDef": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": {"type": "string", "const": "parallel_agent"},
+        "sub_agents": {"type": "array", "items": {"type": "string"}}
+      }
+    },
+    "LoopAgentNodeDef": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": {"type": "string", "const": "loop_agent"},
+        "sub_agents": {"type": "array", "items": {"type": "string"}},
+        "max_iterations": {"type": "integer", "minimum": 1}
+      }
+    },
+    "LanggraphAgentNodeDef": {
+      "type": "object",
+      "required": ["type", "graph"],
+      "properties": {
+        "type": {"type": "string", "const": "langgraph_agent"},
+        "graph": {"type": "string", "minLength": 1},
+        "instruction": {"type": "string"}
+      }
+    }
+  }
+}

graph_workflow/errors.py

@@ -0,0 +1,38 @@
+"""Error types for graph workflow."""
+
+
+class GraphWorkflowError(Exception):
+    """Base exception for all graph workflow errors."""
+
+    def __init__(self, message: str, *, node_id: str | None = None, detail: str | None = None):
+        super().__init__(message)
+        self.node_id = node_id
+        self.detail = detail
+
+    def __str__(self) -> str:
+        parts = [super().__str__()]
+        if self.node_id:
+            parts.append(f"node_id={self.node_id}")
+        if self.detail:
+            parts.append(f"detail={self.detail}")
+        return " | ".join(parts)
+
+
+class GraphValidationError(GraphWorkflowError):
+    """Raised when a graph definition fails structural validation."""
+
+
+class GraphCompilationError(GraphWorkflowError):
+    """Raised when a graph definition cannot be compiled into agents."""
+
+
+class GraphExecutionError(GraphWorkflowError):
+    """Raised when a graph execution encounters a runtime error."""
+
+
+class ConditionEvalError(GraphWorkflowError):
+    """Raised when a condition expression cannot be evaluated."""
+
+
+class FunctionResolutionError(GraphWorkflowError):
+    """Raised when a function reference cannot be resolved."""

graph_workflow/evaluator.py

@@ -0,0 +1,137 @@
+"""AST-based safe condition evaluation for graph edges."""
+from __future__ import annotations
+
+import ast
+from typing import Any
+
+from graph_workflow.errors import ConditionEvalError
+
+_ALLOWED_NODES = (
+    ast.Expression,
+    ast.Constant,
+    ast.Name,
+    ast.Attribute,
+    ast.Compare,
+    ast.BoolOp,
+    ast.UnaryOp,
+    ast.And,
+    ast.Or,
+    ast.Not,
+    ast.Eq,
+    ast.NotEq,
+    ast.Lt,
+    ast.LtE,
+    ast.Gt,
+    ast.GtE,
+    ast.In,
+    ast.NotIn,
+    ast.Is,
+    ast.IsNot,
+    ast.Load,
+)
+
+
+class ConditionEvaluator:
+    """Safely evaluates condition expressions against a state dict using an AST whitelist."""
+
+    def evaluate(self, expression: str, state: dict[str, Any]) -> bool:
+        try:
+            tree = ast.parse(expression, mode="eval")
+        except SyntaxError as exc:
+            raise ConditionEvalError(
+                f"Syntax error in condition: {expression}",
+                detail=str(exc),
+            ) from exc
+
+        self._validate_tree(tree)
+        try:
+            result = self._eval_node(tree.body, state)
+        except Exception as exc:
+            if isinstance(exc, ConditionEvalError):
+                raise
+            raise ConditionEvalError(
+                f"Error evaluating condition: {expression}",
+                detail=str(exc),
+            ) from exc
+
+        return bool(result)
+
+    def _validate_tree(self, tree: ast.Expression) -> None:
+        for node in ast.walk(tree):
+            if not isinstance(node, _ALLOWED_NODES):
+                raise ConditionEvalError(
+                    f"Disallowed AST node in condition: {type(node).__name__}",
+                    detail=f"Node {type(node).__name__} is not in the allowed whitelist",
+                )
+
+    def _eval_node(self, node: ast.AST, state: dict[str, Any]) -> Any:
+        if isinstance(node, ast.Constant):
+            return node.value
+        if isinstance(node, ast.Name):
+            if node.id not in state:
+                raise ConditionEvalError(
+                    f"Undefined variable: {node.id}",
+                    detail=f"Available keys: {sorted(state.keys())}",
+                )
+            return state[node.id]
+        if isinstance(node, ast.Attribute):
+            value = self._eval_node(node.value, state)
+            try:
+                return getattr(value, node.attr)
+            except AttributeError:
+                if isinstance(value, dict):
+                    return value[node.attr]
+                raise
+        if isinstance(node, ast.Compare):
+            left = self._eval_node(node.left, state)
+            for op, comparator in zip(node.ops, node.comparators):
+                right = self._eval_node(comparator, state)
+                if not self._eval_compare(op, left, right):
+                    return False
+                left = right
+            return True
+        if isinstance(node, ast.BoolOp):
+            if isinstance(node.op, ast.And):
+                result = True
+                for value in node.values:
+                    result = self._eval_node(value, state)
+                    if not result:
+                        return result
+                return result
+            else:  # ast.Or
+                result = False
+                for value in node.values:
+                    result = self._eval_node(value, state)
+                    if result:
+                        return result
+                return result
+        if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.Not):
+            return not self._eval_node(node.operand, state)
+
+        raise ConditionEvalError(
+            f"Unsupported node type during evaluation: {type(node).__name__}"
+        )
+
+    @staticmethod
+    def _eval_compare(op: ast.cmpop, left: Any, right: Any) -> bool:
+        if isinstance(op, ast.Eq):
+            return left == right
+        if isinstance(op, ast.NotEq):
+            return left != right
+        if isinstance(op, ast.Lt):
+            return left < right
+        if isinstance(op, ast.LtE):
+            return left <= right
+        if isinstance(op, ast.Gt):
+            return left > right
+        if isinstance(op, ast.GtE):
+            return left >= right
+        if isinstance(op, ast.In):
+            return left in right
+        if isinstance(op, ast.NotIn):
+            return left not in right
+        if isinstance(op, ast.Is):
+            return left is right
+        if isinstance(op, ast.IsNot):
+            return left is not right
+        raise ConditionEvalError(f"Unsupported comparison operator: {type(op).__name__}")

graph_workflow/models.py

@@ -0,0 +1,112 @@
+"""Pydantic data models for graph workflow definitions."""
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal, Union
+
+from pydantic import BaseModel, Field
+
+
+class FnRef(BaseModel):
+    """Reference to a function in the functions registry via $fn key."""
+
+    fn_name: str = Field(alias="$fn")
+
+    model_config = {"populate_by_name": True}
+
+
+class EdgeDef(BaseModel):
+    """An edge connecting two nodes, optionally with a condition."""
+
+    from_: str = Field(alias="from")
+    to: str
+    condition: str | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class FunctionDef(BaseModel):
+    """Definition of a Python function to be resolved at compile time."""
+
+    callable: str
+    args: dict[str, Any] = Field(default_factory=dict)
+
+
+class FunctionNodeDef(BaseModel):
+    """A node that executes a Python function directly."""
+
+    type: Literal["function"] = "function"
+    function: str
+    output_key: str | None = None
+
+
+class ToolRef(BaseModel):
+    """Reference to a tool — mirrors ADK's ToolConfig."""
+
+    name: str
+    args: dict[str, Any] | None = None
+
+
+class LlmAgentNodeDef(BaseModel):
+    """A node that wraps an LLM agent."""
+
+    type: Literal["llm_agent"] = "llm_agent"
+    model: str = "gemini-2.0-flash"
+    instruction: str = ""
+    tools: list[ToolRef] = Field(default_factory=list)
+    output_key: str | None = None
+    output_schema: dict[str, Any] | None = None
+
+
+class SequentialAgentNodeDef(BaseModel):
+    """A node that runs sub-agents sequentially."""
+
+    type: Literal["sequential_agent"] = "sequential_agent"
+    sub_agents: list[str] = Field(default_factory=list)
+
+
+class ParallelAgentNodeDef(BaseModel):
+    """A node that runs sub-agents in parallel."""
+
+    type: Literal["parallel_agent"] = "parallel_agent"
+    sub_agents: list[str] = Field(default_factory=list)
+
+
+class LoopAgentNodeDef(BaseModel):
+    """A node that runs sub-agents in a loop."""
+
+    type: Literal["loop_agent"] = "loop_agent"
+    sub_agents: list[str] = Field(default_factory=list)
+    max_iterations: int = 10
+
+
+class LanggraphAgentNodeDef(BaseModel):
+    """A node that wraps a LangGraph graph."""
+
+    type: Literal["langgraph_agent"] = "langgraph_agent"
+    graph: str
+    instruction: str = ""
+
+
+NodeDef = Annotated[
+    Union[
+        FunctionNodeDef,
+        LlmAgentNodeDef,
+        SequentialAgentNodeDef,
+        ParallelAgentNodeDef,
+        LoopAgentNodeDef,
+        LanggraphAgentNodeDef,
+    ],
+    Field(discriminator="type"),
+]
+
+
+class GraphWorkflowDef(BaseModel):
+    """Top-level graph workflow definition."""
+
+    version: str = "2.0"
+    name: str
+    entry: str
+    exit: str | None = None
+    nodes: dict[str, NodeDef]
+    edges: list[EdgeDef] = Field(default_factory=list)
+    functions: dict[str, FunctionDef] = Field(default_factory=dict)

graph_workflow/resolver.py

@@ -0,0 +1,87 @@
+"""Dynamic function resolution for graph workflow nodes."""
+from __future__ import annotations
+
+import importlib
+import os
+import re
+from typing import Any, Callable
+
+from graph_workflow.errors import FunctionResolutionError
+from graph_workflow.models import FunctionDef
+
+_VAR_PATTERN = re.compile(r"\$\{(\w+)\}")
+
+
+def interpolate_value(value: Any) -> Any:
+    """Recursively interpolate ${ENV_VAR} references in config values."""
+    if isinstance(value, str):
+        return _VAR_PATTERN.sub(
+            lambda m: os.environ.get(m.group(1), m.group(0)), value
+        )
+    if isinstance(value, dict):
+        return {k: interpolate_value(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [interpolate_value(v) for v in value]
+    return value
+
+
+class FunctionResolver:
+    """Resolves function references to actual Python callables."""
+
+    def __init__(self, functions: dict[str, FunctionDef] | None = None):
+        self._functions = functions or {}
+
+    def resolve(self, name: str) -> Callable[..., Any]:
+        if name not in self._functions:
+            raise FunctionResolutionError(
+                f"Function not found in registry: {name}",
+                detail=f"Available functions: {sorted(self._functions.keys())}",
+            )
+        func_def = self._functions[name]
+        return self._resolve_callable(func_def.callable, func_def.args)
+
+    def _resolve_callable(self, dotted_path: str, args: dict[str, Any]) -> Callable[..., Any]:
+        module_path, _, attr_name = dotted_path.rpartition(".")
+        if not module_path:
+            raise FunctionResolutionError(
+                f"Invalid callable path (missing module): {dotted_path}",
+                detail="Expected format: module.path.callable",
+            )
+
+        try:
+            module = importlib.import_module(module_path)
+        except ImportError as exc:
+            raise FunctionResolutionError(
+                f"Cannot import module: {module_path}",
+                detail=str(exc),
+            ) from exc
+
+        try:
+            callable_obj = getattr(module, attr_name)
+        except AttributeError as exc:
+            raise FunctionResolutionError(
+                f"Attribute '{attr_name}' not found in module '{module_path}'",
+                detail=str(exc),
+            ) from exc
+
+        if not callable(callable_obj):
+            raise FunctionResolutionError(
+                f"'{dotted_path}' is not callable",
+            )
+
+        resolved_args = self._interpolate_args(args)
+        if resolved_args:
+
+            def _bound_callable(*fn_args: Any, **fn_kwargs: Any) -> Any:
+                merged = {**resolved_args, **fn_kwargs}
+                return callable_obj(*fn_args, **merged)
+
+            return _bound_callable
+
+        return callable_obj
+
+    def _interpolate_args(self, args: dict[str, Any]) -> dict[str, Any]:
+        resolved: dict[str, Any] = {}
+        for key, value in args.items():
+            resolved[key] = interpolate_value(value)
+        return resolved

graph_workflow/runner.py

@@ -0,0 +1,136 @@
+"""GraphRunnerAgent — runtime graph executor for ADK."""
+from __future__ import annotations
+
+from typing import AsyncGenerator
+
+from pydantic import PrivateAttr
+from google.adk.agents import BaseAgent, InvocationContext
+from google.adk.events import Event
+
+from graph_workflow.compiler import CompiledGraph, CompiledNode
+from graph_workflow.errors import GraphExecutionError
+from graph_workflow.evaluator import ConditionEvaluator
+
+
+class GraphRunnerAgent(BaseAgent):
+    """An ADK BaseAgent that executes a compiled graph workflow at runtime."""
+
+    _graph: CompiledGraph = PrivateAttr()
+    _evaluator: ConditionEvaluator = PrivateAttr()
+
+    def __init__(
+        self,
+        name: str,
+        graph: CompiledGraph,
+        description: str = "",
+    ):
+        super().__init__(name=name, description=description)
+        self._graph = graph
+        self._evaluator = ConditionEvaluator()
+
+    async def _run_async_impl(
+        self, ctx: InvocationContext
+    ) -> AsyncGenerator[Event, None]:
+        # Store user message in session state so LLM agents can access it
+        user_content = getattr(ctx, "user_content", None)
+        if user_content and user_content.parts:
+            user_text = "".join(
+                p.text for p in user_content.parts if p.text
+            ).strip()
+            if user_text and "user_message" not in ctx.session.state:
+                ctx.session.state["user_message"] = user_text
+                # Also add as a user event so LlmAgent sees it in conversation history
+                from google.adk.events import Event
+                user_event = Event(
+                    author="user",
+                    content=user_content,
+                )
+                ctx.session.events.append(user_event)
+
+        current_key = self._graph.entry
+        visited: set[str] = set()
+        max_steps = len(self._graph.nodes) * 2  # Safety bound
+        steps = 0
+
+        while current_key is not None:
+            if steps >= max_steps:
+                raise GraphExecutionError(
+                    f"Graph execution exceeded max steps ({max_steps})",
+                    node_id=current_key,
+                    detail="Possible infinite loop in graph",
+                )
+
+            if current_key in visited and not self._has_condition_from(current_key):
+                raise GraphExecutionError(
+                    f"Revisiting node '{current_key}' without conditional edges",
+                    node_id=current_key,
+                    detail="Possible cycle in graph",
+                )
+
+            steps += 1
+            visited.add(current_key)
+
+            node = self._graph.nodes.get(current_key)
+            if node is None:
+                raise GraphExecutionError(
+                    f"Node '{current_key}' not found in compiled graph",
+                    node_id=current_key,
+                )
+
+            # Execute the node
+            if node.is_function:
+                await self._execute_function(node, ctx)
+            elif node.is_agent:
+                async for event in node.agent.run_async(ctx):
+                    # Merge state deltas from agent events into session state
+                    if event.actions and event.actions.state_delta:
+                        ctx.session.state.update(event.actions.state_delta)
+                    yield event
+
+            # Check if we've reached the exit
+            if current_key == self._graph.exit:
+                break
+
+            # Find next node via edges
+            current_key = self._find_next(current_key, ctx)
+
+    async def _execute_function(
+        self, node: CompiledNode, ctx: InvocationContext
+    ) -> None:
+        try:
+            import inspect
+            state = dict(ctx.session.state)
+            result = node.callable(state)
+            if inspect.isawaitable(result):
+                result = await result
+            if node.output_key and result is not None:
+                ctx.session.state[node.output_key] = result
+        except Exception as exc:
+            raise GraphExecutionError(
+                f"Function execution failed for node '{node.key}'",
+                node_id=node.key,
+                detail=str(exc),
+            ) from exc
+
+    def _find_next(
+        self, current_key: str, ctx: InvocationContext
+    ) -> str | None:
+        edges = self._graph.adjacency.get(current_key, [])
+        if not edges:
+            return None
+
+        state = {
+            k: v.strip() if isinstance(v, str) else v
+            for k, v in ctx.session.state.items()
+        }
+        for edge in edges:
+            if edge.condition is None:
+                return edge.to_key
+            if self._evaluator.evaluate(edge.condition, state):
+                return edge.to_key
+
+        return None
+
+    def _has_condition_from(self, key: str) -> bool:
+        edges = self._graph.adjacency.get(key, [])
+        return any(e.condition is not None for e in edges)

graph_workflow/schema.py

@@ -0,0 +1,33 @@
+"""JSON Schema validation for graph workflow definitions."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import jsonschema
+
+from graph_workflow.errors import GraphValidationError
+
+_SCHEMA_DIR = Path(__file__).parent / "data"
+_SCHEMA_PATH = _SCHEMA_DIR / "schema.json"
+
+
+def _load_schema() -> dict:
+    with open(_SCHEMA_PATH) as f:
+        return json.load(f)
+
+
+class SchemaValidator:
+    """Validates raw workflow dicts against the JSON Schema."""
+
+    def __init__(self, schema: dict | None = None):
+        self._schema = schema or _load_schema()
+
+    def validate(self, data: dict) -> None:
+        try:
+            jsonschema.validate(instance=data, schema=self._schema)
+        except jsonschema.ValidationError as exc:
+            raise GraphValidationError(
+                f"JSON Schema validation failed: {exc.message}",
+                detail=exc.json_path,
+            ) from exc

graph_workflow/validator.py

@@ -0,0 +1,141 @@
+"""Structural validation for graph workflow definitions."""
+from __future__ import annotations
+
+from graph_workflow.errors import GraphValidationError
+from graph_workflow.models import (
+    FunctionNodeDef,
+    GraphWorkflowDef,
+    LoopAgentNodeDef,
+    ParallelAgentNodeDef,
+    SequentialAgentNodeDef,
+)
+
+
+class GraphValidator:
+    """Validates structural properties of a GraphWorkflowDef beyond JSON Schema."""
+
+    def validate(self, workflow: GraphWorkflowDef) -> list[str]:
+        warnings: list[str] = []
+        self._check_entry_node(workflow)
+        self._check_exit_node(workflow, warnings)
+        self._check_edge_nodes_exist(workflow)
+        self._check_self_loops(workflow)
+        self._check_exit_no_out_edges(workflow)
+        self._check_entry_no_in_edges(workflow)
+        self._check_single_default_edge(workflow)
+        self._check_container_sub_agents(workflow)
+        self._check_function_references(workflow)
+        self._check_reachable_nodes(workflow, warnings)
+        return warnings
+
+    def _check_entry_node(self, workflow: GraphWorkflowDef) -> None:
+        if workflow.entry not in workflow.nodes:
+            raise GraphValidationError(
+                f"Entry node '{workflow.entry}' not found in nodes",
+                node_id=workflow.entry,
+            )
+
+    def _check_exit_node(self, workflow: GraphWorkflowDef, warnings: list[str]) -> None:
+        if workflow.exit is None:
+            warnings.append("No exit node defined — graph may run indefinitely")
+            return
+        if workflow.exit not in workflow.nodes:
+            raise GraphValidationError(
+                f"Exit node '{workflow.exit}' not found in nodes",
+                node_id=workflow.exit,
+            )
+
+    def _check_edge_nodes_exist(self, workflow: GraphWorkflowDef) -> None:
+        node_ids = set(workflow.nodes.keys())
+        for edge in workflow.edges:
+            if edge.from_ not in node_ids:
+                raise GraphValidationError(
+                    f"Edge source '{edge.from_}' not found in nodes",
+                    node_id=edge.from_,
+                )
+            if edge.to not in node_ids:
+                raise GraphValidationError(
+                    f"Edge target '{edge.to}' not found in nodes",
+                    node_id=edge.to,
+                )
+
+    def _check_container_sub_agents(self, workflow: GraphWorkflowDef) -> None:
+        node_ids = set(workflow.nodes.keys())
+        for nid, node in workflow.nodes.items():
+            sub_agents: list[str] = []
+            if isinstance(node, (SequentialAgentNodeDef, ParallelAgentNodeDef, LoopAgentNodeDef)):
+                sub_agents = node.sub_agents
+            for child_id in sub_agents:
+                if child_id not in node_ids:
+                    raise GraphValidationError(
+                        f"Sub-agent '{child_id}' of container node '{nid}' not found in nodes",
+                        node_id=nid,
+                        detail=f"Missing sub-agent: {child_id}",
+                    )
+
+    def _check_self_loops(self, workflow: GraphWorkflowDef) -> None:
+        for edge in workflow.edges:
+            if edge.from_ == edge.to:
+                raise GraphValidationError(
+                    f"Self-loop detected on node '{edge.from_}'",
+                    node_id=edge.from_,
+                )
+
+    def _check_exit_no_out_edges(self, workflow: GraphWorkflowDef) -> None:
+        if workflow.exit is None:
+            return
+        for edge in workflow.edges:
+            if edge.from_ == workflow.exit:
+                raise GraphValidationError(
+                    f"Exit node '{workflow.exit}' has outgoing edge",
+                    node_id=workflow.exit,
+                )
+
+    def _check_entry_no_in_edges(self, workflow: GraphWorkflowDef) -> None:
+        for edge in workflow.edges:
+            if edge.to == workflow.entry:
+                raise GraphValidationError(
+                    f"Entry node '{workflow.entry}' has incoming edge",
+                    node_id=workflow.entry,
+                )
+
+    def _check_single_default_edge(self, workflow: GraphWorkflowDef) -> None:
+        from_groups: dict[str, int] = {}
+        for edge in workflow.edges:
+            if edge.condition is None:
+                count = from_groups.get(edge.from_, 0) + 1
+                from_groups[edge.from_] = count
+                if count > 1:
+                    raise GraphValidationError(
+                        f"Multiple default (unconditional) edges from node '{edge.from_}'",
+                        node_id=edge.from_,
+                    )
+
+    def _check_function_references(self, workflow: GraphWorkflowDef) -> None:
+        func_names = set(workflow.functions.keys())
+        for nid, node in workflow.nodes.items():
+            if isinstance(node, FunctionNodeDef):
+                if node.function not in func_names:
+                    raise GraphValidationError(
+                        f"Function node '{nid}' references undefined function '{node.function}'",
+                        node_id=nid,
+                        detail=f"Available functions: {sorted(func_names)}",
+                    )
+
+    def _check_reachable_nodes(self, workflow: GraphWorkflowDef, warnings: list[str]) -> None:
+        reachable: set[str] = {workflow.entry}
+        edge_map: dict[str, list[str]] = {}
+        for edge in workflow.edges:
+            edge_map.setdefault(edge.from_, []).append(edge.to)
+
+        queue = [workflow.entry]
+        while queue:
+            current = queue.pop(0)
+            for target in edge_map.get(current, []):
+                if target not in reachable:
+                    reachable.add(target)
+                    queue.append(target)
+
+        for nid in workflow.nodes:
+            if nid not in reachable:
+                warnings.append(f"Node '{nid}' is not reachable from entry")