DAG Execution

How KyroJudge builds and executes a directed acyclic graph (DAG) from your pipeline steps.

KyroJudge executes evaluation steps as a Directed Acyclic Graph (DAG). Steps without dependencies run in parallel immediately; steps with depends_on wait for their dependencies to complete before starting.

How it works

Build phase — DAGBuilder reads all steps and their depends_on lists, constructs a dependency graph, and topologically sorts it.
Execution phase — DAGExecutor uses a priority queue (p-queue) to run ready steps in parallel, respecting maxConcurrency.
Step execution — StepExecutor calls the AI provider with the rendered prompt, parses the response, and marks the step complete.

Example: 3-step parallel pipeline

steps:
  - name: relevance    # Runs immediately
    prompt: ...
    output_format: json
 
  - name: safety       # Runs immediately (parallel with relevance)
    prompt: ...
    output_format: json
 
  - name: quality      # Waits for both relevance AND safety
    depends_on:
      - relevance
      - safety
    prompt: ...
    output_format: json

Execution diagram

Concurrency

By default, KyroJudge runs all independent steps in parallel. If you need to limit provider API calls:

const judge = new Judge('./pipeline.yaml', provider, {
  maxConcurrency: 3,
});

Cycle detection

If your config has circular dependencies, DAGBuilder throws a KyroConfigError at construction time — before any API calls are made:

KyroConfigError: Circular dependency detected: step_a → step_b → step_a

Failure propagation

When a step fails (returns ERROR):

Its result is marked ERROR with the root cause
Dependent steps are skipped unless an on_failure fallback is configured
Other independent branches continue executing

# step_b depends on step_a
# If step_a fails, step_b is skipped
# step_c is independent and still runs
steps:
  - name: step_a
    ...
  - name: step_b
    depends_on: [step_a]
    ...
  - name: step_c  # runs regardless of step_a/b outcome
    ...

Complex pipeline example

steps:
  - name: input_validation
    prompt: Validate the input format...
    output_format: json
 
  - name: relevance
    depends_on: [input_validation]
    prompt: Check relevance...
    output_format: json
 
  - name: safety
    depends_on: [input_validation]
    prompt: Check safety...
    output_format: json
 
  - name: factuality
    depends_on: [input_validation]
    prompt: Check factual accuracy...
    output_format: json
 
  - name: final_score
    depends_on: [relevance, safety, factuality]
    prompt: Aggregate all sub-scores into a final evaluation...
    output_format: json