adk-graph-workflow 0.1.0__tar.gz

adk_graph_workflow-0.1.0/.claude/settings.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python -m pytest --version)",
+      "Bash(python -m pytest --collect-only -q)",
+      "Bash(python -c ' *)",
+      "Read(//home/rowan/Projects/million-agents-workflow-builder/**)",
+      "mcp__plugin_everything-claude-code_sequential-thinking__sequentialthinking",
+      "Read(//home/rowan/Projects/adk-python/**)",
+      "Bash(python -m pytest tests/test_models.py tests/test_compiler.py tests/test_validator.py -x -q)",
+      "Bash(python -m pytest tests/test_compiler.py -v -x)",
+      "Bash(python -m pytest --cov=src --cov-report=term-missing -q)",
+      "Bash(python -c \"import google.adk.tools as t; print\\([x for x in dir\\(t\\) if not x.startswith\\('_'\\)]\\)\")",
+      "Bash(python -m pytest tests/test_examples_end_to_end.py -v -q)",
+      "Bash(python -m pytest tests/test_examples_end_to_end.py -v -x)",
+      "Bash(python -c \"import ast; ast.parse\\(open\\('src/graph_workflow/compiler.py'\\).read\\(\\)\\); print\\('Syntax OK'\\)\")",
+      "Bash(python -m pytest tests/test_compiler.py tests/test_examples_end_to_end.py -x -q)",
+      "Bash(python -m pytest tests/test_compiler.py -x -q)",
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)"
+    ]
+  }
+}

adk_graph_workflow-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store

adk_graph_workflow-0.1.0/CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+YAML-defined graph workflows for Google ADK agents. Users write workflow graphs in YAML, and the library compiles them into executable ADK agent graphs. The core entry point is `from_config("workflow.yaml")` which returns a `GraphRunnerAgent` (an ADK `BaseAgent`).
+
+## Commands
+
+```bash
+# Install (editable, with dev deps)
+pip install -e ".[dev]"
+
+# Run all tests (pytest with async_mode=auto)
+pytest
+
+# Run with coverage
+pytest --cov=src --cov-report=term-missing
+
+# Run a single test file
+pytest tests/test_compiler.py
+
+# Run a single test by name
+pytest tests/test_validator.py -k "test_cycle_detection"
+```
+
+## Architecture
+
+### Validation Pipeline (3 layers, in order)
+
+1. **SchemaValidator** — JSON Schema structural validation against `src/graph_workflow/data/schema.json`
+2. **GraphWorkflowDef.model_validate()** — Pydantic discriminated unions for type-safe parsing
+3. **GraphValidator** — Graph structure checks: entry/exit nodes, edge references, container sub-agents, function references, node reachability
+
+### Compilation Pipeline
+
+`GraphCompiler` performs a two-pass compilation: first validates all node references and detects cycles, then converts YAML node definitions into ADK agent instances. Function nodes are wrapped into inline agents. Container nodes (`sequential`, `parallel`, `loop`) are built recursively.
+
+### Runtime Execution
+
+`GraphRunnerAgent` (extends ADK `BaseAgent`) traverses the compiled graph. It evaluates edge conditions via `ConditionEvaluator` (safe AST-based Python subset) against session state, and propagates state deltas between nodes.
+
+### Key Module Responsibilities
+
+| Module | Purpose |
+|--------|---------|
+| `models.py` | Pydantic models with discriminated unions for 6 node types |
+| `schema.py` | JSON Schema validation (structural, IDE-friendly) |
+| `validator.py` | Graph structure validation (edges, cycles, reachability) |
+| `compiler.py` | Two-pass YAML→ADK agent compilation |
+| `runner.py` | Runtime graph executor with state management |
+| `resolver.py` | Dynamic function import, `${ENV_VAR}` interpolation, arg pre-binding |
+| `evaluator.py` | Safe AST-based condition evaluation against session state |
+| `errors.py` | Error hierarchy: `GraphWorkflowError` → 5 subclasses |
+
+### Node Types
+
+`function`, `llm_agent`, `sequential_agent`, `parallel_agent`, `loop_agent`, `langgraph_agent`. Container nodes accept both agent and function nodes as `sub_agents`. Nested containers are supported; circular references between containers are detected at compile time.
+
+### Public API
+
+Everything is exported from `graph_workflow.__init__`. The convenience function `from_config(path)` runs the full pipeline (load → schema validate → pydantic validate → graph validate → resolve functions → compile → return runner). For fine-grained control, each pipeline step can be called individually.
+
+## Key Patterns
+
+- **Discriminated unions** in Pydantic models (`NodeDef` uses `type` field to dispatch)
+- **Function resolution** at compile time via dotted module paths with static arg pre-binding
+- **Condition evaluation** uses safe AST walking (not `eval`) — supports comparisons, boolean ops, attribute access with dict fallback
+- **LLM agents** support custom models via LiteLLM with provider prefixes (e.g., `openai/`, `deepseek/`, `ollama/`)
+
+## Testing
+
+206 tests with 97%+ coverage. Tests are in `tests/` organized by component. `test_examples_end_to_end.py` validates all 6 example YAML workflows compile correctly. pytest runs with `asyncio_mode = "auto"`.

adk_graph_workflow-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,296 @@
+# adk-graph-workflow
+
+YAML-defined graph workflows for Google ADK agents. Load a YAML file, compile it into an executable ADK agent graph, and run it.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.10+, `google-adk>=1.0.0`, `pydantic>=2.0`, `pyyaml>=6.0`, `jsonschema>=4.0`.
+
+## Quick Start
+
+```python
+from graph_workflow import from_config
+
+agent = from_config("workflow.yaml")
+```
+
+That's it. `from_config()` handles loading, validation, function resolution, and compilation in one call. The returned `GraphRunnerAgent` is an ADK `BaseAgent` ready to use with any ADK `Runner`.
+
+### Running the Agent
+
+```python
+import asyncio
+import uuid
+from google.adk.agents import InvocationContext, RunConfig
+from google.adk.sessions import InMemorySessionService
+from graph_workflow import from_config
+
+async def main():
+    agent = from_config("workflow.yaml")
+
+    session_service = InMemorySessionService()
+    session = await session_service.create_session(
+        app_name="my_app", user_id="user1", session_id=str(uuid.uuid4())
+    )
+    ctx = InvocationContext(
+        invocation_id=str(uuid.uuid4()),
+        agent=agent,
+        session=session,
+        session_service=session_service,
+        run_config=RunConfig(),
+    )
+
+    async for event in agent.run_async(ctx):
+        print(event)
+
+asyncio.run(main())
+```
+
+### Advanced Usage
+
+If you need fine-grained control over individual steps:
+
+```python
+import yaml
+from graph_workflow import (
+    SchemaValidator,
+    GraphWorkflowDef,
+    GraphValidator,
+    FunctionResolver,
+    GraphCompiler,
+    GraphRunnerAgent,
+)
+
+with open("workflow.yaml") as f:
+    data = yaml.safe_load(f)
+
+SchemaValidator().validate(data)
+workflow = GraphWorkflowDef.model_validate(data)
+GraphValidator().validate(workflow)
+
+resolver = FunctionResolver(workflow.functions)
+registry = {name: resolver.resolve(name) for name in workflow.functions}
+compiled = GraphCompiler(registry).compile(workflow)
+runner = GraphRunnerAgent(name=workflow.name, graph=compiled)
+```
+
+## YAML Format
+
+```yaml
+version: "2.0"
+name: my_workflow
+entry: start_node
+exit: end_node
+
+nodes:
+  start_node:
+    type: function
+    function: my_func
+    output_key: result
+
+  classifier:
+    type: llm_agent
+    model: gemini-2.0-flash
+    instruction: "Classify the input."
+    output_key: category
+
+  parallel_analysis:
+    type: parallel_agent
+    sub_agents: [agent_a, agent_b]
+
+  sequential_steps:
+    type: sequential_agent
+    sub_agents: [step_1, step_2, step_3]
+
+  retry_loop:
+    type: loop_agent
+    sub_agents: [try_action, check_result]
+    max_iterations: 5
+
+  reasoner:
+    type: langgraph_agent
+    graph: myapp.graphs.reasoning_graph
+    instruction: "Perform structured reasoning."
+
+  end_node:
+    type: function
+    function: cleanup
+
+edges:
+  - from: start_node
+    to: classifier
+  - from: classifier
+    to: path_a
+    condition: category == "A"
+  - from: classifier
+    to: path_b
+    condition: category == "B"
+  - from: classifier
+    to: end_node          # default (no condition)
+
+functions:
+  my_func:
+    callable: myapp.functions.do_something
+    args:
+      timeout: 30
+  cleanup:
+    callable: myapp.functions.cleanup
+```
+
+## Node Types
+
+| Type | YAML `type` | Description |
+|------|-------------|-------------|
+| Function | `function` | Executes a Python callable. Takes session state as positional arg. |
+| LLM Agent | `llm_agent` | Wraps an ADK `LlmAgent`. Supports `model`, `instruction`, `tools`, `output_key`, `output_schema`. |
+| Sequential | `sequential_agent` | Runs sub-agents in order. `sub_agents` lists node keys. |
+| Parallel | `parallel_agent` | Runs sub-agents concurrently. |
+| Loop | `loop_agent` | Repeats sub-agents up to `max_iterations` (default: 10). |
+| LangGraph | `langgraph_agent` | Wraps an ADK `LanggraphAgent`. Requires `langchain-core` and `langgraph` packages. `graph` is a dotted path resolved via `FunctionResolver`. |
+
+## Container Sub-agents
+
+Container nodes (`sequential_agent`, `parallel_agent`, `loop_agent`) accept both agent nodes and function nodes as `sub_agents`. Function nodes are automatically wrapped into inline agents at compile time.
+
+Nested containers are supported (e.g., a `sequential_agent` containing a `parallel_agent`). Circular references between containers are detected and raise `GraphCompilationError`.
+
+## Condition Expressions
+
+Edge conditions use a safe AST-evaluated subset of Python:
+
+- **Comparisons**: `==`, `!=`, `<`, `<=`, `>`, `>=`, `in`, `not in`
+- **Boolean ops**: `and`, `or`, `not`
+- **Attribute access**: `obj.attr` (dict fallback: `{a: {b: 1}}` allows `a.b == 1`)
+- **Literals**: strings (`"text"`), numbers (`42`, `3.14`), booleans (`True`, `False`)
+
+Conditions are evaluated against session state. Use `True`/`False` (not `true`/`false`).
+
+## Function Resolution
+
+Functions defined in the `functions` section are resolved at compile time:
+
+- `callable` — dotted module path (e.g., `myapp.utils.process`)
+- `args` — static arguments pre-bound to the callable
+- `${ENV_VAR}` — environment variable interpolation in argument values
+
+At runtime, the function receives session state as its first positional argument, followed by pre-bound keyword arguments.
+
+## Validation Pipeline
+
+Three-layer validation:
+
+1. **JSON Schema** (`SchemaValidator`) — structural validation, IDE-friendly
+2. **Pydantic** (`GraphWorkflowDef.model_validate`) — type-safe parsing with discriminated unions
+3. **GraphValidator** — checks entry/exit nodes, edge references, container sub-agents, function references, node reachability
+
+## Error Hierarchy
+
+```
+GraphWorkflowError (base)
+  +-- GraphValidationError   # Schema/structural issues
+  +-- GraphCompilationError  # Compilation failures
+  +-- GraphExecutionError    # Runtime errors
+  +-- ConditionEvalError     # Bad condition expressions
+  +-- FunctionResolutionError # Import/callable resolution failures
+```
+
+## Custom Models
+
+LLM agent nodes support any OpenAI-compatible API (NewAPI, OneAPI, etc.) through ADK's LiteLlm integration. Set environment variables and use the `openai/` prefix:
+
+```yaml
+nodes:
+  my_agent:
+    type: llm_agent
+    model: openai/your-model-name    # Routes through LiteLLM
+    instruction: "..."
+```
+
+```python
+import os
+os.environ["OPENAI_API_KEY"] = "sk-your-key"
+os.environ["OPENAI_API_BASE"] = "https://your-api-domain/v1"
+
+agent = from_config("workflow.yaml")
+```
+
+Supported prefixes include: `openai/`, `anthropic/`, `deepseek/`, `groq/`, `ollama/`, and 100+ more via [LiteLLM](https://docs.litellm.ai/docs/providers). Install with `pip install google-adk[extensions]`.
+
+## Examples
+
+All examples can be loaded with `from_config()`:
+
+```python
+from graph_workflow import from_config
+
+agent = from_config("examples/customer_service.yaml")  # 5 nodes
+```
+
+| File | Nodes | Description |
+|------|-------|-------------|
+| `customer_service.yaml` | 5 | Intent classification with conditional routing |
+| `data_analysis_pipeline.yaml` | 21 | Full pipeline: load, validate, parallel analysis, loop optimization, report |
+| `multi_agent_research.yaml` | 24 | Multi-source research with fact-checking, iterative refinement, quality gate |
+| `content_moderation.yaml` | 26 | Parallel multi-dimensional analysis, appeal loop, structured reasoning |
+| `ecommerce_order_flow.yaml` | 30 | Fraud detection, payment retry, warehouse fulfillment, split orders |
+| `custom_model_demo.yaml` | 3 | **Runnable** — translate (deepseek) → summarize (doubao) via NewAPI |
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+206 tests, 97%+ coverage.
+
+## Architecture: Job Executor Engine for million-agents-workflow-builder
+
+`adk-graph-workflow` serves as the core execution engine for [million-agents-workflow-builder](https://gitlab.zhejianglab.com/dev426/million-agents-workflow-builder), a multi-agent orchestration platform with FastAPI backend, Kafka dispatch, and Kubernetes Job isolation.
+
+### Design Decision: Standalone Package
+
+`adk-graph-workflow` remains an independent pip-installable package rather than being merged into the platform project.
+
+**Rationale:**
+
+- **Clean separation of concerns** — This library is a pure compile/execute engine (YAML → ADK graph) with zero infrastructure dependencies (no K8s, Kafka, DB). The platform layer handles scheduling, isolation, and monitoring.
+- **Low coupling** — The platform only depends on this package in two places: YAML validation in the workflow builder module, and `from_config()` inside K8s Job Pod entrypoints.
+- **Independent evolution** — Engine can be versioned, tested (206 tests / 97% coverage), and released independently of platform changes.
+
+### Integration Architecture
+
+```
+million-agents-workflow-builder (platform layer)
+│
+├─ Scheduler (Kafka) ──→ Orchestrator (K8s Job)
+│                              │
+│                              ▼
+│                         Job Pod
+│                         ┌─────────────────────┐
+│                         │ executor/entrypoint  │
+│                         │   ↓                  │
+│                         │ adk-graph-workflow   │  ← pip dependency
+│                         │   from_config(yaml)  │
+│                         │   GraphRunnerAgent   │
+│                         └─────────────────────┘
+│                              │
+│                              ▼
+│                         Kafka (results)
+│
+└─ Workflow Builder (NL→YAML, validates via SchemaValidator/GraphValidator)
+```
+
+### Deployment
+
+Install as a pip dependency in the platform's Job Pod environment:
+
+```bash
+pip install adk-graph-workflow
+# or from private PyPI / git source
+pip install git+https://gitlab.zhejianglab.com/dev426/adk-graph-workflow.git
+```

adk_graph_workflow-0.1.0/examples/__init__.py

@@ -0,0 +1 @@
+"""Stub functions for graph_workflow examples."""

adk_graph_workflow-0.1.0/examples/analysis.py

@@ -0,0 +1,34 @@
+"""Data analysis pipeline example stubs."""
+
+
+def create_visualizations(state, **kwargs):
+    return {"chart_path": "/tmp/chart.png"}
+def load_data_source(state, **kwargs):
+    return {"loaded": True, "rows": 1000}
+
+def validate_schema(state, **kwargs):
+    return {"valid": True}
+
+def clean_missing_values(state, **kwargs):
+    return {"cleaned": True}
+
+def encode_categories(state, **kwargs):
+    return {"encoded": True}
+
+def normalize_features(state, **kwargs):
+    return {"normalized": True}
+
+def compute_statistics(state, **kwargs):
+    return {"mean": 0.5, "std": 0.1}
+
+def detect_anomalies(state, **kwargs):
+    return {"anomalies": []}
+
+def train_model_step(state, **kwargs):
+    return {"accuracy": 0.95}
+
+def evaluate_model(state, **kwargs):
+    return {"f1_score": 0.93}
+
+def export_report(state, **kwargs):
+    return {"report_path": "/tmp/report.pdf"}