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

# Review a Kapso build: the Solution and the record

> What a build hands back: the Solution with its branch, commit, score and evaluator version, explain() and diff(), and the record on disk that Solution.open reads from any process.

A build returns a `Solution`, and writes the same thing to
`<output>/.kapso/solution.json` every time it returns: finished, paused for
you, or out of budget. From any process, later or elsewhere:

```python theme={null}
from kapso import Solution

solution = Solution.open("campaign")
print(solution.explain())
print(solution.diff())
```

Before the build has returned there is no solution yet; `open()` says so
and names `kapso watch`.

## What the Solution holds

| Field | What it is |
| - | - |
| `brief` | The brief the build ran, as a `Brief` |
| `campaign` | The campaign directory, checked out at the delivered branch |
| `branch`, `commit` | The delivered candidate; both `None` when no candidate succeeded |
| `base_commit` | The seed commit, `diff()`'s base |
| `score` | The delivered candidate's measurement under the registered evaluator |
| `goal_achieved` | The judge's verdict that the objective was met |
| `stopped_reason`, `stop_detail` | `goal_achieved`, `max_iterations`, `budget_exhausted` (with the detail: `time_budget`, `cost_budget`, `attempt_would_not_fit`, `finishing_cut`) or `waiting_for_user` |
| `experiments`, `experiments_total` | Experiments this run, and across every resume |
| `cost_usd` | Model spend |
| `requests` | What you must answer, when `stopped_reason` is `waiting_for_user` |
| `feedback` | The last judgment, in full |
| `evaluator` | The evaluator version the score was measured under; `None` unless the evaluation maintainer is configured (see [Evaluation](https://docs.leeroo.com/docs/build/evaluation.md#versioned-the-registry)) |
| `harness` | The [harness](https://docs.leeroo.com/docs/harnesses.md) the build ran with: `name`, `version`, `hash`, `source`; `None` without one |
| `verification` | The harness's verdict on the delivered candidate: `verdict`, `summary`, `findings`; `None` when no verification ran |
| `rejected_candidates` | Candidates rejected for touching the evaluator, or voided by the harness's verification |
| `callback_metrics`, `callback_primary_metric` | Your own evaluator's numbers, when you passed an `iteration_evaluator` |
| `experience` | What the build was served: one entry per loaded source with its `reference`, `kind`, `resolved` location, pinned `head`, `provenance` and `scope`; empty when nothing was loaded |
| `session_failures` | The sessions' runs that ended `error`, `timeout` or `refused`: each run's `label`, `module`, `host`, `exit` and `error`; empty when every run ended well |

`explain()` renders these as a block; `diff()` is `git diff` from the seed
to the delivered commit, empty when nothing succeeded.

```text theme={null}
Solution for:    Raise the churn model's out-of-sample ROC AUC above 0.85
Campaign:        /home/me/churn/campaign
Candidate:       generic_exp_3 @ 4f1c0e2a…
Score:           0.8614
Goal achieved:   True
Stopped:         goal_achieved
Experiments:     3 this run, 3 in all
Cost:            $1.934

Feedback:
The AUC of 0.861 on the held-out rows clears the 0.85 target …
```

A build on a harness adds two rows before the feedback: `Harness:` with
the name, version and hash, and `Verified:` with the verdict and its
summary. A build whose sessions failed adds `Sessions failed:` after the
experiments line, each kind with its count and the error's first line
(`implementation on codex ×2 (Quota exceeded …)`).

## Three ways a build ends

* **The objective was met.** `goal_achieved` is true, `stopped_reason` is
  `goal_achieved`. Deploy it, or learn from it.
* **The budget ran out.** `stopped_reason` is `max_iterations` or
  `budget_exhausted`; `branch` is the best candidate so far and `score` its
  measurement. Resume with a bigger budget, or change the target. See
  [Resume and budgets](https://docs.leeroo.com/docs/build/resume-and-budgets.md).
* **The campaign is waiting on you.** `stopped_reason` is
  `waiting_for_user` and `requests` says what for. Answer through the
  [inbox](https://docs.leeroo.com/docs/build/inbox.md); the campaign continues the session that asked.

When `branch` is `None`, no candidate produced a valid measurement; the
experiment branches are still in the directory, and `kapso trace campaign`
shows what each one did.

## The search, branch by branch

```bash theme={null}
git -C campaign branch         # generic_exp_0, generic_exp_1, …, main
git -C campaign log --oneline generic_exp_2
kapso trace campaign           # each attempt: its sessions and runs, its score, its verdict, the cards it read
```

Every experiment stays checked in; the delivered one is checked out.
[Read the record](https://docs.leeroo.com/docs/build/trace.md) walks the trace section by section.

## What next

```python theme={null}
software = kapso.deploy(solution)      # running software; see Deploy
lesson = kapso.learn(solution)         # bank what the campaign taught; see Learn
```

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

## Related

> [card] [Resume and budgets](https://docs.leeroo.com/docs/build/resume-and-budgets.md)
>
> Give a stopped build more

> [card] [Deploy](https://docs.leeroo.com/docs/deploy/targets.md)
>
> From a Solution to running software

> [card] [Learn](https://docs.leeroo.com/docs/learn/what-learn-produces.md)
>
> What a finished campaign teaches

> [card] [Python API](https://docs.leeroo.com/docs/reference/kapso-api.md#solution)
>
> Every field, typed

Related pages: [Resume and budgets](https://docs.leeroo.com/docs/build/resume-and-budgets.md) · [Deploy](https://docs.leeroo.com/docs/deployment/overview.md) · [Learn](https://docs.leeroo.com/docs/learn/what-learn-produces.md) · [Python API](https://docs.leeroo.com/docs/reference/kapso-api.md#solution)

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.