Evolution Visualization Dashboard

Relevant source files

The following files were used as context for generating this wiki page:

• apps/web/src/app/(protected)/(traces)/evolution/[run_id]/page.tsx
• apps/web/src/features/evolution/lib/results/workflow-evolution-tracer.ts
• apps/web/src/lib/evolution-utils.ts
• apps/web/src/app/components/evolution/WorkflowEvolutionVisualization.tsx
• apps/web/src/app/components/evolution/EvolutionGraph.tsx
• apps/web/src/app/(protected)/(traces)/evolution/page.tsx
• apps/web/src/app/components/evolution/FailedRunVisualization.tsx
• packages/core/src/improvement/gp/README.md
• packages/core/src/utils/persistence/README.md
• features/evolution/lib/results/README.md

The Evolution Visualization Dashboard provides a comprehensive interface for observing and analyzing the performance of self-improving agentic workflows. It tracks how workflows evolve over time, either through iterative improvement ("Cultural Evolution") or population-based genetic programming ("GP"). The dashboard displays key metrics such as accuracy, cost, success rates, and the genealogical history of workflow versions, offering crucial insights into the optimization process.

This system is central to the project's goal of achieving autonomous workflow optimization by making the evolutionary journey transparent and understandable to developers.

Sources: README.md, packages/core/README.md, packages/core/src/improvement/gp/README.md

System Architecture and Data Flow

The dashboard is composed of several frontend components that consume data processed by a dedicated backend tracer. The data originates from the application's database, which stores records of every workflow execution and its evolutionary context.

The following diagram illustrates the data flow from a user request to the final rendered visualization.

This diagram shows the end-to-end process for visualizing an evolution run.

Sources: apps/web/src/app/(protected)/(traces)/evolution/[run_id]/page.tsx, apps/web/src/app/components/evolution/EvolutionGraph.tsx:29-40, apps/web/src/features/evolution/lib/results/workflow-evolution-tracer.ts, apps/web/src/lib/evolution-utils.ts

Database Schema

The visualization relies on a structured database schema that captures the entire history of an evolution run. The key tables and their relationships are shown below.

This ER diagram outlines the database tables that store data about evolution runs, generations, and workflow invocations.

Sources: packages/core/src/utils/persistence/README.md, features/evolution/lib/results/README.md

Core Data Structures

The data fetched from the backend is organized into a set of well-defined interfaces before being passed to the frontend components.

*Sources: apps/web/src/lib/evolution-utils.ts

EvolutionNode

Represents a single workflow invocation within an evolution run.

Field	Type	Description
invocationId	string	Unique ID for the workflow execution.
versionId	string	ID of the WorkflowVersion that was executed.
runId	string	The ID of the overarching evolution run.
generationNumber	number	The generation number this node belongs to.
accuracy	number	The measured accuracy of the invocation.
fitnessScore	number	The calculated fitness score.
status	string	Execution status (completed, failed, etc.).
operation	string	The genetic operation that created this version (e.g., crossover, mutation).
parentId	string	The parent version ID for mutations.
parent1Id	string	The first parent version ID for crossovers.
parent2Id	string	The second parent version ID for crossovers.
startTime	string	The start time of the invocation.
usdCost	number	The cost of the invocation in USD.
dsl	Record<string, unknown>	The JSON-based workflow definition.

*Sources: apps/web/src/lib/evolution-utils.ts:6-36

EvolutionGraph

A comprehensive object containing all data for a single evolution run, ready for visualization.

This class diagram shows the structure of the EvolutionGraph object and its main components.

*Sources: apps/web/src/lib/evolution-utils.ts:38-76

Backend Data Processing

workflow-evolution-tracer.ts

This server-side module is responsible for querying the database and constructing the EvolutionGraph object. Its primary export is the traceWorkflowEvolution function.

The process is as follows:

1. Fetch Target: Retrieves the target WorkflowInvocation using the provided invocationId.
2. Fetch Run Context: Gets the associated EvolutionRun, Generation, WorkflowVersion records.
3. Fetch All Run Data: Queries all WorkflowInvocation, WorkflowVersion, and Generation records associated with the run_id. This ensures the entire evolutionary history is captured.
4. Build Nodes: Maps each WorkflowInvocation to an EvolutionNode, enriching it with version and generation metadata.
5. Create Progression Timeline: Filters completed nodes with accuracy scores to create the accuracyProgression timeline.
6. Calculate Statistics: Computes aggregate stats like total cost, max accuracy, and invocation counts.
7. Assemble Graph: Combines all processed data into a single EvolutionGraph object and returns it.

*Sources: apps/web/src/features/evolution/lib/results/workflow-evolution-tracer.ts:8-169

evolution-utils.ts

This client-side utility library contains the createEvolutionVisualizationData function, which transforms the raw EvolutionGraph from the backend into a format optimized for UI components.

It creates an object with the following properties:

• summary: High-level statistics for display in summary cards (e.g., peak accuracy, total cost).
• timeline: Data points formatted for the accuracy progression chart.
• invocationsByGeneration: Invocations grouped by their generation number, used for box plots or other generational visualizations.
• nodes: A simplified list of nodes for graph visualizations like the GPEvolutionGraph.
• milestones: Key points in the evolution, such as the first run, the target run, and significant jumps in accuracy.

*Sources: apps/web/src/lib/evolution-utils.ts:79-147

Frontend Components & Pages

Pages

Evolution Runs List (/evolution)

This page serves as the entry point for exploring evolution runs. It displays a filterable and sortable table of all past and currently running evolutions.

• State Management: Uses a useEvolutionRunsStore (Zustand store) to manage state for filters, sorting, search terms, and the list of runs.
• Features:
  • Search by goal text.
  • Filter by status (completed, running, failed), type (iterative, gp), and date range.
  • Option to hide runs with zero invocations.
  • Sort by various columns like start_time, total_invocations, and avg_accuracy_delta.
  • Links to the detailed visualization page for each run.
• Stale Run Detection: A run is marked as "stale" if it has been in the running state for more than 5 hours.

*Sources: apps/web/src/app/(protected)/(traces)/evolution/page.tsx

Individual Run View (/evolution/[run_id])

This page provides a detailed view of a single evolution run. It is the primary consumer of the visualization components.

• Primary View: It uses the EvolutionGraph component to render the main visualization.
• Generational Breakdown: It displays a list of generations, each expandable to show the workflow structures and individual invocations within it.
• Structure Grouping: It groups workflow versions by their DSL hash, allowing users to see how many different workflow structures were explored during the run. Each structure is shown with a StructureMiniMap.
• DSL Viewer: Users can click to view the full JSON DSL of any workflow version in a modal.

*Sources: apps/web/src/app/(protected)/(traces)/evolution/[run_id]/page.tsx

Visualization Components

EvolutionGraph

This component acts as a high-level wrapper. It fetches the evolution data for a given runId from the /api/evolution/[run_id]/trace endpoint. Based on the response, it decides which visualization to render:

• If data is successfully fetched, it renders WorkflowEvolutionVisualization.
• If the API returns an error indicating no successful invocations, it fetches basic run info and renders FailedRunVisualization.
• It also handles loading and error states.

*Sources: apps/web/src/app/components/evolution/EvolutionGraph.tsx

WorkflowEvolutionVisualization

This is the main component for displaying a successful evolution run. It is responsible for laying out all the charts and statistical information.

• Summary Stats: Displays key metrics like Target Accuracy, Peak Accuracy, and Total Invocations in prominent cards.
• Charts:
  • IterativeEvolutionChart: A line chart showing accuracy progression over time or iterations.
  • GPEvolutionGraph: A graph visualization showing the genealogical relationships between workflow nodes (versions).
• Data Normalization: It contains logic to handle edge cases, such as normalizing runs where all invocations are in a single generation, or synthesizing generation data for failed runs to still show some form of progression.

*Sources: apps/web/src/app/components/evolution/WorkflowEvolutionVisualization.tsx

FailedRunVisualization

When an evolution run fails to produce any successful invocations, this component is rendered. It provides a summary of the failure, including:

• Failure Rate
• Total Attempts
• Run Status and Goal
• A brief analysis of why visualization is limited (e.g., "Zero Successful Completions").
• Recommendations for debugging, such as checking system logs or reviewing workflow configuration.

*Sources: apps/web/src/app/components/evolution/FailedRunVisualization.tsx