Skip to main content

​
Evolve System

The Evolve System is Kapso’s core engine for building software solutions. It orchestrates an iterative experimentation loop that explores multiple approaches, learns from failures, and converges on high-quality solutions.

​
How It Works

The system works by:
  1. Receiving a goal : What you want to build (include success criteria in the goal)
  2. Initializing repo : From initial_repo, workflow search, or empty
  3. Gathering context : From Knowledge Graph and Repo Memory
  4. Generating solutions : Via pluggable coding agents
  5. Running evaluation : Agent builds and runs evaluation in kapso_evaluation/
  6. Generating feedback : Feedback generator validates results and decides stop/continue

​
Key Components

Orchestrator

Central coordinator that manages the experimentation loop, budget tracking, and component lifecycle

Search Strategies

Algorithms for exploring the solution space: tree search or linear search

Coding Agents

Pluggable code generators: Aider, Gemini, Claude Code, OpenHands

Feedback Generator

Validates evaluation results and decides when to stop

Repo Memory

Tracks code understanding with file-level evidence

​
Basic Usage

from kapso.kapso import Kapso, DeployStrategy

kapso = Kapso()

# Build a solution - agent builds evaluation dynamically
# Include success criteria in the goal
solution = kapso.evolve(
    goal="Build a random forest classifier for Iris with accuracy > 0.9",
    max_iterations=10,
)

# With user-provided evaluation and data
solution = kapso.evolve(
    goal="Optimize model inference speed to < 10ms",
    eval_dir="./my_evaluation/",   # Copied to kapso_evaluation/
    data_dir="./my_data/",         # Copied to kapso_datasets/
    initial_repo="https://github.com/org/starter",  # Or local path
)

# Deploy and run
deployed_program = kapso.deploy(solution, strategy=DeployStrategy.LOCAL)
result = deployed_program.run({"data_path": "./test.csv"})

​
Repository Initialization

When evolve() is called, the system initializes the workspace:
initial_repo ValueBehavior
Local pathUse existing repository as starting point
GitHub URLClone repository and use as starting point
None (default)Search for relevant workflow via Knowledge Graph. If found, clone workflow’s repo. Otherwise, create empty repo.

​
Configuration Modes

Kapso provides preset configurations for different use cases:
ModeSearch StrategyBest For
GENERICTree search (default)General problem solving
MINIMALLinear searchQuick experiments, simple problems
TREE_SEARCHTree search with debuggingComplex problems requiring exploration
SCOREDTree search with scoringProblems with clear metrics
# Use a specific mode
solution = kapso.evolve(
    goal="...",
    mode="MINIMAL",  # Fast, linear search
)

​
The Experimentation Loop

Each iteration of the evolve loop:
  1. Select — Choose which solution candidates to explore
  2. Expand — Generate new variations using the coding agent
  3. Implement — Agent implements solution code
  4. Evaluate — Agent builds and runs evaluation in kapso_evaluation/
  5. Feedback — Feedback generator validates results and provides guidance
  6. Check — If feedback says stop (goal achieved), return solution

​
Git Branch Model

Each experiment runs on its own Git branch: 
main
├── kapso/exp-001  (first experiment)
├── kapso/exp-002  (second experiment)
│   └── kapso/exp-002-debug-1  (debug iteration)
├── kapso/exp-003  (third experiment)
└── ...
This provides:
  • Isolation — Experiments don’t interfere with each other
  • History — Full Git history of all attempts
  • Recovery — Easy to checkout and examine any experiment

​
Workspace Structure

After setup, the workspace looks like: 
workspace/
├── kapso_evaluation/     # Agent builds evaluation here
│   └── evaluate.py       # Evaluation script
├── kapso_datasets/       # Data files (from data_dir)
├── .kapso/
│   └── repo_memory.json  # Codebase understanding
└── (solution code)       # From initial_repo or agent-built

​
Memory Systems

The Evolve System uses two memory systems:

​
Repo Memory

Tracks understanding of the codebase:
  • Architecture — High-level structure and patterns
  • Key Claims — Important facts about the code
  • File Evidence — Which files support each claim

​
Experiment History

Learns from past experiments via MCP tools:
  • Top Experiments — Best scoring experiments
  • Recent Experiments — Most recent experiments
  • Similar Experiments — Semantic search for related experiments

​
Budget Tracking

The Orchestrator tracks costs across all components: 
# Get cumulative cost
cost = orchestrator.get_cumulative_cost()
print(f"Total cost: ${cost:.2f}")
Budget limits can be set via max_iterations or time/cost budgets in configuration.

​
Next Steps

Architecture

Deep dive into system architecture

Execution Flow

Detailed walkthrough of the execution process

Search Strategies

How tree search and linear search explore solutions

Experiment Lifecycle

Lifecycle of a single experiment