> ## 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.

# Your first Kapso build

> Run the churn example: a brief, a protected evaluator, a first build on a fresh install, and the Solution it hands back with its score, branch and diff.

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

```bash theme={null}
kapso doctor build
```

Every required row must read `[OK ]`; the coding-agent logins are the part
people miss. See [Install](https://docs.leeroo.com/docs/installation.md).

## Get the example

```bash theme={null}
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

```text examples/churn-first-build/kapso-brief.md theme={null}
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](https://docs.leeroo.com/docs/build/brief.md).

## Build

> [tab] CLI
>
> ```bash theme={null}
> 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.

> [tab] Python
>
> ```python examples/churn-first-build/run.py theme={null}
> """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:

```python theme={null}
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](https://docs.leeroo.com/docs/build/inbox.md).

## Deploy it, learn from it

```python theme={null}
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)
```

```bash theme={null}
kapso deploy campaign --target local
```

## Related

> [card] [The brief](https://docs.leeroo.com/docs/build/brief.md)
>
> What each line is for, and the three cases

> [card] [Run and watch](https://docs.leeroo.com/docs/build/run-and-watch.md)
>
> Every flag, the status file, the summary block

> [card] [Review the result](https://docs.leeroo.com/docs/build/review.md)
>
> The Solution and the record

> [card] [Examples](https://github.com/Leeroo-AI/kapso/tree/main/examples)
>
> Seven tasks, each a brief and twelve lines

Related pages: [The brief](https://docs.leeroo.com/docs/build/brief.md) · [Run and watch](https://docs.leeroo.com/docs/build/run-and-watch.md) · [Review the result](https://docs.leeroo.com/docs/build/review.md) · [Install](https://docs.leeroo.com/docs/installation.md)

Kapso is an open-source framework by [Leeroo](https://leeroo.com) that builds software toward measurable goals through experiment campaigns. Source code: [github.com/Leeroo-AI/kapso](https://github.com/Leeroo-AI/kapso) · Install: `pip install leeroo-kapso` · Every page as plain text: [llms.txt](https://docs.leeroo.com/llms.txt).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.