Run your first Kapso campaign in under ten minutes

Give Kapso a goal it can measure and it runs a campaign: designing candidate solutions, implementing each one, scoring it, and refining the best. You get back the winning code, its score, and a git branch per experiment.

Before you start

Kapso runs its inference through coding-agent CLIs, so confirm the machine is ready first:

kapso doctor evolve

Every required row must read [OK ]. If any does not, follow Installation — the CLIs and their logins are the part people miss.

Run a campaign

State a goal with a number in it. A goal Kapso cannot score is a goal it cannot optimize.

CLI
Python

kapso evolve \
    --goal "Build a random forest classifier for the Iris dataset with accuracy > 0.9" \
    --iterations 10 \
    --output ./iris_solution

from kapso import Kapso

kapso = Kapso()

solution = kapso.evolve(
    goal="Build a random forest classifier for the Iris dataset with accuracy > 0.9",
    max_iterations=10,
    output_path="./iris_solution",
)

print(solution.explain())

The campaign stops when the goal is met or the iteration budget runs out.

Bound the run by wall clock or spend instead of iterations with --time-budget-minutes and --cost-budget. Both are also evolve() keyword arguments.

What you get back

evolve() returns a SolutionResult:

solution.goal              # the goal you gave it
solution.code_path         # directory holding the winning code
solution.final_score       # score of the delivered solution
solution.succeeded         # whether the goal was met
solution.experiment_logs   # one summary per experiment
solution.final_feedback    # the last feedback, including the stop decision
solution.metadata          # cost, iteration count, final evaluation
solution.explain()         # all of the above as readable text

Every experiment is committed to its own branch, so you can read the whole search, not just the winner:

cd ./iris_solution
git branch -a

  generic_exp_0
  generic_exp_1
* generic_exp_2
  main

If the run ends with WAITING ON YOU instead of COMPLETED, a session needs something only you can provide, such as an API key. kapso inbox shows the request and kapso inbox reply resumes the campaign; see the inbox.

Deploy the result

from kapso import Kapso, DeployStrategy

deployed = kapso.deploy(solution, strategy=DeployStrategy.LOCAL)
result = deployed.run({"data_path": "./test.csv"})
deployed.stop()

DeployStrategy accepts AUTO (the default, which picks for you), LOCAL, DOCKER, MODAL, BENTOML and LANGGRAPH. See Deployment.

Give the campaign more to work with

A campaign starts stronger when it starts with context. All three are optional; the first is a single line.

Connect Leeroopedia

A key for Leeroopedia, the hosted knowledge base of ML and AI frameworks, and every session can look up how a framework actually behaves, have its plan reviewed, pull documented hyperparameter ranges and diagnose a failed run. Nothing to install; new accounts come with $20 of free credit.

LEEROOPEDIA_API_KEY=kpsk_...   # in .env

The final summary and kapso watch --tree show what the campaign consulted and the credits used. See Connect Leeroopedia.

Research the problem first

findings = kapso.research(
    "QLoRA fine-tuning memory optimizations",
    mode=["idea", "implementation"],
    depth="deep",
)

solution = kapso.evolve(
    goal="Fine-tune Llama-3.1-8B with QLoRA, target eval loss < 0.5",
    context=[findings.to_string()],
    output_path="./qlora_v1",
)

mode takes "idea", "implementation", "study", or a list of them. depth is "light" or "deep".

Ground it in a knowledge graph

Index a corpus once, then point campaigns at the index:

kapso = Kapso()
kapso.index_kg(
    wiki_dir="data/wikis",
    save_to="data/indexes/finetuning.index",
)

kapso = Kapso(kg_index="data/indexes/finetuning.index")

Indexing needs Weaviate and Neo4j running. See Optional: knowledge-graph backends.

How Evolve works

The experiment loop, end to end

CLI reference

Every command, flag and default

Execution flow

What happens inside one experiment

Knowledge and learning

How campaigns compound over time

Related pages: How Evolve works · CLI reference · Execution flow · Knowledge and learning Kapso is an open-source framework by Leeroo that builds software toward measurable goals through experiment campaigns. Source code: github.com/Leeroo-AI/kapso · Install: pip install leeroo-kapso · Every page as plain text: llms.txt.

Getting started

Evolve system

Knowledge graph

Trajectory learning

Research

Deployment

Benchmarks

Run your first Kapso campaign in under ten minutes

Before you start

Run a campaign

What you get back

Deploy the result

Give the campaign more to work with

Connect Leeroopedia

Research the problem first

Ground it in a knowledge graph

How Evolve works

CLI reference

Execution flow

Knowledge and learning

​Before you start

​Run a campaign

​What you get back

​Deploy the result

​Give the campaign more to work with

​Connect Leeroopedia

​Research the problem first

​Ground it in a knowledge graph

​Related

How Evolve works

CLI reference

Execution flow

Knowledge and learning

Before you start

Run a campaign

What you get back

Deploy the result

Give the campaign more to work with

Connect Leeroopedia

Research the problem first

Ground it in a knowledge graph

Related