> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leeroo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> How Kapso builds solutions through iterative experimentation
# 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
```mermaid theme={null}
flowchart TB
subgraph Evolve["Evolve System"]
G[Goal] --> O[Orchestrator]
O --> SS[Search Strategy]
SS --> CA[Coding Agent]
CA --> AE[Agent Evaluation]
AE --> FG[Feedback Generator]
FG -->|Continue| SS
FG -->|Stop| S[Solution]
end
KG[Knowledge Graph] --> O
RM[Repo Memory] --> CA
```
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
Central coordinator that manages the experimentation loop, budget tracking, and component lifecycle
Algorithms for exploring the solution space: tree search or linear search
Pluggable code generators: Aider, Gemini, Claude Code, OpenHands
Validates evaluation results and decides when to stop
Tracks code understanding with file-level evidence
## Basic Usage
```python theme={null}
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` Value | Behavior |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Local path | Use existing repository as starting point |
| GitHub URL | Clone 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:
| Mode | Search Strategy | Best For |
| ------------- | -------------------------- | -------------------------------------- |
| `GENERIC` | Tree search (default) | General problem solving |
| `MINIMAL` | Linear search | Quick experiments, simple problems |
| `TREE_SEARCH` | Tree search with debugging | Complex problems requiring exploration |
| `SCORED` | Tree search with scoring | Problems with clear metrics |
```python theme={null}
# 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:
```python theme={null}
# 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
Deep dive into system architecture
Detailed walkthrough of the execution process
How tree search and linear search explore solutions
Lifecycle of a single experiment