Your first Kapso build

From a fresh install to a Solution, in about three quarters of an hour on the shipped config (the ideation step alone runs ten to fifteen minutes before the first candidate is implemented; a faster profile for small briefs is on the redesign’s list). The task is a churn model with an evaluator present: the shipped logistic regression scores 0.797 ROC AUC on held-out rows, the brief asks for 0.85, and a gradient boosting model with no feature work reaches 0.832, so there is room (numbers from the example’s own baseline.py, 2026-10-24, on its generated data).

Before you start

kapso doctor build

Every required row must read [OK ]; the coding-agent logins are the part people miss. See Install.

Get the example

git clone --depth 1 https://github.com/Leeroo-AI/kapso /tmp/kapso-src
cp -r /tmp/kapso-src/examples/churn-first-build . && cd churn-first-build
pip install numpy pandas scikit-learn   # the generator, the model and the evaluator
python generate.py          # 10,000 training rows, 3,000 held out, seeded

Read the brief

examples/churn-first-build/kapso-brief.md

Objective    Raise the churn model's out-of-sample ROC AUC above 0.85
             without changing the prediction contract: predict.py keeps
             writing id,churn_probability for every holdout id.
Measured by  kapso_evaluation/evaluate.py, ROC AUC on the held-out rows
Baseline     0.797 (the shipped logistic regression, bootstrap SE 0.010)
Target       0.85
Rules
  - the evaluator is never modified
  - no fitting on the holdout rows: their labels sit under the protected `kapso_evaluation/private/`, the evaluator's alone
Budget       minutes=45 experiments=3

The objective, how it is measured, where it starts, where it should end, what must never happen, how much to spend. The judge reads all of it. See The brief.

Build

CLI
Python

kapso build --brief kapso-brief.md --evaluation evaluation --data data --repo repo --output campaign --detach
kapso watch campaign --follow

The first line returns at once with the pid, the log and the watch line; the second follows the campaign until it ends.

examples/churn-first-build/run.py

"""Your first build: the churn model, scored by the evaluator Kapso protects.

Run from this directory, after `python generate.py`; the campaign lands in campaign/."""
from kapso import Kapso, Brief

solution = Kapso().build(
    Brief.read("kapso-brief.md"),
    evaluation="evaluation", data="data", repo="repo", output="campaign",
)
print(solution.explain())

python run.py is the CLI line’s twin and blocks until the build returns; run one or the other, since both build into campaign/.

--evaluation evaluation is copied into the campaign as kapso_evaluation/, which is the name the brief uses, and protected: a candidate that edits it is rejected. --repo is copied, never modified; every experiment lands on a branch inside campaign/.

What you get back

The run ends with a summary block, COMPLETED with the candidate, the score and the stop reason (in campaign.log for a detached run). The same solution, from any process, once the build has returned:

from kapso import Solution

solution = Solution.open("campaign")
solution.score            # the delivered candidate's ROC AUC
solution.branch           # generic_exp_2
solution.goal_achieved    # the judge's verdict on the objective
solution.stopped_reason   # goal_achieved, max_iterations, …
print(solution.diff())    # the delivered code against the seed

If the block says WAITING ON YOU instead, a session needs something only you can provide; kapso inbox campaign shows the request and kapso inbox reply resumes the campaign. See The inbox.

Deploy it, learn from it

from kapso import Kapso, Solution

kapso = Kapso()
solution = Solution.open("campaign")
software = kapso.deploy(solution, target="local")
software.run({"tenure_months": 3, "monthly_spend": 92.0, "support_tickets": 4})
lesson = kapso.learn(solution)

kapso deploy campaign --target local

The brief

What each line is for, and the three cases

Run and watch

Every flag, the status file, the summary block

Review the result

The Solution and the record

Examples

Seven tasks, each a brief and twelve lines

Related pages: The brief · Run and watch · Review the result · Install 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.

Start

Build

Harnesses

Experience

Deploy

Learn

How it works

Benchmarks

Before you start

Get the example

Read the brief

Build

What you get back

Deploy it, learn from it

The brief

Run and watch

Review the result

Examples

​Before you start

​Get the example

​Read the brief

​Build

​What you get back

​Deploy it, learn from it

​Related

The brief

Run and watch

Review the result

Examples

Before you start

Get the example

Read the brief

Build

What you get back

Deploy it, learn from it

Related