​

Evolve System

​

How It Works

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

​

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

​

Configuration Modes

# Use a specific mode
solution = kapso.evolve(
    goal="...",
    mode="MINIMAL",  # Fast, linear search
)

​

The Experimentation 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

main
├── kapso/exp-001  (first experiment)
├── kapso/exp-002  (second experiment)
│   └── kapso/exp-002-debug-1  (debug iteration)
├── kapso/exp-003  (third experiment)
└── ...

• 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

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

​

Repo Memory

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

​

Experiment History

• Top Experiments — Best scoring experiments
• Recent Experiments — Most recent experiments
• Similar Experiments — Semantic search for related experiments

​

Budget Tracking

# Get cumulative cost
cost = orchestrator.get_cumulative_cost()
print(f"Total cost: ${cost:.2f}")

​

Next Steps