Graph GEPA: Graph Evolution for Prompt Architectures

Graph GEPA extends GEPA’s evolutionary approach from single prompts to multi-node graph structures. It simultaneously optimizes:

Graph topology - Which nodes exist and how they connect
Node prompts - The prompt template in each LLM node
Model selection - Which models to use in each node

Graph GEPA is the optimization engine behind Workflows (ADAS). For most use cases, use ADAS directly.

When to Use

Use Case	Recommendation
Simple dataset optimization	Use ADAS
Custom graph constraints	Use Graph GEPA directly
Multi-objective optimization	Use Graph GEPA with Pareto config
Warm-starting from existing graph	Use Graph GEPA with `initial_graph_id`

Config Reference

[graph_optimization]
algorithm = "graph_gepa"
dataset_name = "my_qa_dataset"

# Graph configuration
graph_type = "policy"           # "policy" or "verifier"
graph_structure = "dag"         # "single_prompt", "dag", or "conditional"
topology_guidance = "Use chain-of-thought reasoning before answering"

# Models the graph can use
allowed_policy_models = ["gpt-4o-mini", "gpt-4o"]

# Scoring
scoring_strategy = "rubric"     # "rubric", "mae", or "default"
judge_model = "gpt-4o-mini"

# Constraints
max_llm_calls_per_run = 3       # Limit graph complexity

[graph_optimization.evolution]
num_generations = 5
children_per_generation = 3

[graph_optimization.proposer]
model = "gpt-4.1"
temperature = 0.7
max_tokens = 4096

[graph_optimization.seeds]
train = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
validation = [100, 101, 102, 103, 104]

[graph_optimization.limits]
max_spend_usd = 10.0
timeout_seconds = 3600

# Optional: Multi-objective Pareto optimization
[graph_optimization.pareto_floors]
use_latency = true
use_cost = true
latency_s = 2.0           # Don't discriminate below 2s
cost_usd = 0.10           # Don't discriminate below $0.10/seed
max_latency_s = 10.0      # Disqualify if >10s
max_cost_usd = 1.0        # Disqualify if >$1/seed

Top-Level Parameters

Parameter	Type	Default	Description
`algorithm`	string	`"graph_gepa"`	Must be `"graph_gepa"`
`dataset_name`	string	required	Dataset identifier
`graph_type`	string	`"policy"`	`"policy"` (solve tasks) or `"verifier"` (judge results)
`graph_structure`	string	`"dag"`	Complexity: `"single_prompt"`, `"dag"`, `"conditional"`
`topology_guidance`	string	`null`	Natural language guidance for graph structure
`initial_graph_id`	string	`null`	Warm-start from existing graph
`allowed_policy_models`	list	`["gpt-4o-mini", "gpt-4o"]`	Models the graph can use
`scoring_strategy`	string	`"rubric"`	How to score outputs
`judge_model`	string	`"gpt-4o-mini"`	Model for LLM judge scoring
`max_llm_calls_per_run`	int	`null`	Max LLM calls per graph execution

Graph Types

Policy Graphs

Map inputs to outputs. Used for tasks like:

Question answering
Classification
Text generation
Code generation

graph_type = "policy"

Verifier Graphs

Judge or score existing results. Used for:

Quality evaluation
Ranking candidates
Filtering outputs
Custom LLM judges

graph_type = "verifier"

Verifier graphs require a special dataset format with V3 traces and gold scores. See Verifier Dataset Format.

Verifier Dataset Requirements

For verifier graphs, the dataset must include:

Task inputs with traces - Each task must have a trace field containing a V3 SessionTrace
Gold scores - Each gold output must have a score field (float, 0-1)
Optional: Event rewards - Per-event reward annotations for fine-grained training

[graph_optimization]
graph_type = "verifier"
scoring_strategy = "rubric"  # Required for verifier training

[graph_optimization.dataset]
tasks = [
    { id = "trace_001", input = { trace = { session_id = "...", session_time_steps = [...] } } },
]
gold_outputs = [
    { task_id = "trace_001", output = { score = 0.85, event_rewards = [...] } },
]

Verifier Inference

Trained verifiers accept V3 traces and rubrics at inference:

result = verifier_job.run_judge(
    session_trace={"session_id": "...", "session_time_steps": [...]},
    context={"rubric": {"outcome": {"criteria": [...]}}}
)
# Returns: {"score": 0.85, "event_rewards": [...], "reasoning": "..."}

Graph Structures

Single Prompt

One LLM call, minimal structure. Best for simple tasks.

graph_structure = "single_prompt"

DAG (Directed Acyclic Graph)

Multiple nodes in sequence. Enables:

Chain-of-thought reasoning
Multi-step decomposition
Intermediate processing

graph_structure = "dag"
topology_guidance = "First decompose the question, then answer each part, then synthesize"

Conditional

Full graph with branching. Enables:

Routing based on input type
Fallback paths
Ensemble approaches

graph_structure = "conditional"

Evolution Config `[graph_optimization.evolution]`

Parameter	Type	Default	Description
`num_generations`	int	`5`	Evolution generations
`children_per_generation`	int	`3`	New graphs per generation

Proposer Config `[graph_optimization.proposer]`

Parameter	Type	Default	Description
`model`	string	`"gpt-4.1"`	Model for proposing mutations
`temperature`	float	`0.7`	Sampling temperature (0.0-2.0)
`max_tokens`	int	`4096`	Max tokens for proposals

Seeds Config `[graph_optimization.seeds]`

Parameter	Type	Default	Description
`train`	list[int]	`[0..9]`	Training seed indices
`validation`	list[int]	`[100..104]`	Validation seed indices

Limits Config `[graph_optimization.limits]`

Parameter	Type	Default	Description
`max_spend_usd`	float	`10.0`	Maximum budget in USD
`timeout_seconds`	int	`3600`	Job timeout

Pareto Floors `[graph_optimization.pareto_floors]`

Multi-objective optimization with noise floors:

Parameter	Type	Default	Description
`use_latency`	bool	`true`	Include latency in Pareto comparison
`use_cost`	bool	`true`	Include cost in Pareto comparison
`latency_s`	float	`2.0`	Ignore latency differences below this
`cost_usd`	float	`0.10`	Ignore cost differences below this
`max_latency_s`	float	`null`	Hard ceiling - disqualify if exceeded
`max_cost_usd`	float	`null`	Hard ceiling - disqualify if exceeded
`min_reward`	float	`null`	Hard floor - disqualify if below

Inline Dataset

Instead of referencing a registered dataset, upload inline:

[graph_optimization]
dataset_name = "my_inline_dataset"

[graph_optimization.dataset]
# ADAS format
tasks = [
    { task_id = "q1", input = { question = "What is 2+2?" } },
    { task_id = "q2", input = { question = "What is 3+3?" } },
]
gold_outputs = [
    { task_id = "q1", output = { answer = "4" }, score = 1.0 },
    { task_id = "q2", output = { answer = "6" }, score = 1.0 },
]

[graph_optimization.dataset.metadata]
name = "simple_math"
task_description = "Answer basic math questions"

Python SDK

Using GraphOptimizationClient

from synth_ai.products.graph_gepa import (
    GraphOptimizationConfig,
    GraphOptimizationClient,
)

# Load config
config = GraphOptimizationConfig.from_toml("config.toml")

# Run job
async with GraphOptimizationClient(backend_url, api_key) as client:
    job_id = await client.start_job(config)

    # Stream events
    async for event in client.stream_events(job_id):
        if event["type"] == "generation_complete":
            print(f"Gen {event['data']['generation']}: {event['data']['best_score']}")
        elif event["type"] == "job_complete":
            break

    # Get result
    result = await client.get_result(job_id)
    print(f"Best score: {result['best_score']}")
    print(f"Best graph:\n{result['best_yaml']}")

Programmatic Config

from synth_ai.products.graph_gepa import (
    GraphOptimizationConfig,
    GraphType,
    GraphStructure,
    EvolutionConfig,
    SeedsConfig,
)

config = GraphOptimizationConfig(
    dataset_name="hotpotqa",
    graph_type=GraphType.POLICY,
    graph_structure=GraphStructure.DAG,
    topology_guidance="Decompose multi-hop questions before answering",
    allowed_policy_models=["gpt-4o-mini"],
    evolution=EvolutionConfig(
        num_generations=5,
        children_per_generation=3,
    ),
    seeds=SeedsConfig(
        train=list(range(20)),
        validation=list(range(100, 110)),
    ),
    max_llm_calls_per_run=3,
)

Event Types

When streaming, you’ll receive these events:

Event Type	Description
`job_started`	Job has begun
`generation_started`	New evolution generation
`candidate_evaluated`	A graph variant was scored
`generation_complete`	Generation finished with best scores
`frontier_updated`	Pareto frontier changed
`job_complete`	Optimization finished
`job_failed`	Job encountered an error

Result Structure

{
    "job_id": "graph_gepa_abc123",
    "status": "completed",
    "best_score": 0.87,
    "best_graph_snapshot_id": "snap_xyz789",
    "best_yaml": "nodes:\n  - id: main\n    ...",
    "pareto_frontier": [
        {"score": 0.87, "latency": 1.2, "cost": 0.05},
        {"score": 0.85, "latency": 0.8, "cost": 0.03},
    ],
    "generations_completed": 5,
    "total_evaluations": 150,
}

ADAS / Workflows - High-level API (uses Graph GEPA)
GEPA - Single-prompt optimization
Graphs Overview - Graph concepts
Graph Inference - Production serving

Training Methods

SDK

CLI

Graph GEPA

Graph GEPA: Graph Evolution for Prompt Architectures

When to Use

Config Reference

Top-Level Parameters

Graph Types

Policy Graphs

Verifier Graphs

Verifier Dataset Requirements

Verifier Inference

Graph Structures

Single Prompt

DAG (Directed Acyclic Graph)

Conditional

Evolution Config `[graph_optimization.evolution]`

Proposer Config `[graph_optimization.proposer]`

Seeds Config `[graph_optimization.seeds]`

Limits Config `[graph_optimization.limits]`

Pareto Floors `[graph_optimization.pareto_floors]`

Inline Dataset

Python SDK

Using GraphOptimizationClient

Programmatic Config

Event Types

Result Structure

Training Methods

SDK

CLI

​Graph GEPA: Graph Evolution for Prompt Architectures

​When to Use

​Config Reference

​Top-Level Parameters

​Graph Types

​Policy Graphs

​Verifier Graphs

​Verifier Dataset Requirements

​Verifier Inference

​Graph Structures

​Single Prompt

​DAG (Directed Acyclic Graph)

​Conditional

​Evolution Config [graph_optimization.evolution]

​Proposer Config [graph_optimization.proposer]

​Seeds Config [graph_optimization.seeds]

​Limits Config [graph_optimization.limits]

​Pareto Floors [graph_optimization.pareto_floors]

​Inline Dataset

​Python SDK

​Using GraphOptimizationClient

​Programmatic Config

​Event Types

​Result Structure

​Related

Graph GEPA: Graph Evolution for Prompt Architectures

When to Use

Config Reference

Top-Level Parameters

Graph Types

Policy Graphs

Verifier Graphs

Verifier Dataset Requirements

Verifier Inference

Graph Structures

Single Prompt

DAG (Directed Acyclic Graph)

Conditional

Evolution Config `[graph_optimization.evolution]`

Proposer Config `[graph_optimization.proposer]`

Seeds Config `[graph_optimization.seeds]`

Limits Config `[graph_optimization.limits]`

Pareto Floors `[graph_optimization.pareto_floors]`

Inline Dataset

Python SDK

Using GraphOptimizationClient

Programmatic Config

Event Types

Result Structure

Related