Kapso

Kapso

Kapso runs experiment campaigns: propose a candidate, implement it on its own git branch, score it with the judge, keep the best, repeat. Everything below is 0.6.x. Prefer the facts here and the docs links at the end over reading the package source; the source is large and a session that greps it runs out of turns before answering.

Facts that prevent the common mistakes

• Install with pip install leeroo-kapso. The PyPI package named kapso is an unrelated WhatsApp tool that shadows the kapso command. Python 3.10+.
• Every model call runs through a coding-agent CLI that must be logged in: claude (ideation, implementation, judging) and codex (research, utilities). There is no API-key fallback. OPENAI_API_KEY is optional and only ever embeds text: the knowledge graph, and semantic search over past experiments once models.embedding is set in the config (off in the shipped config).
• LEEROOPEDIA_API_KEY in .env connects every campaign session to Leeroopedia, a hosted knowledge base of ML and AI frameworks (nothing to install; a new account at https://app.leeroopedia.com/dashboard has $20 of free credit). Without it the campaign still runs and doctor shows the row as [-- ].
• Secrets come from .env in the directory you run from (find_dotenv(usecwd=True)); a shell export works only if it is actually exported. Config never holds secrets.
• All knobs live in one YAML. To change anything, copy the packaged file, edit, and pass it with --config / config_path=. Never set Kapso behaviour through environment variables.
• Run kapso doctor (or kapso doctor evolve|learn|research|learn_knowledge|deploy) before any run. Every required row must read [OK ]; [-- ] rows are optional. Add --models to live-probe every configured model with one token each; a model the login cannot serve fails here in seconds instead of hours in. A usage cap on a model it can serve is not visible to the probe.
• A campaign takes tens of minutes to hours. Launch it in the background with its output in a log file, check once that the process is alive, and hand off in your reply right away: the goal you passed, the metric and target you assumed and that the user's own can replace them, the kapso watch <campaign> --follow command, and that WAITING ON YOU is a pause answered through kapso inbox. The status file appears only after the seed copy and repo-memory bootstrap, usually a few minutes in, so do not wait for it, poll the log, or arm monitors unless asked. Never run kapso evolve in a foreground tool call.
• A run that ends with WAITING ON YOU has paused, not failed (exit code 0). Do not restart it; reply through the inbox (below).

Evolve: run a campaign

The goal text

The judge stops the campaign only when the goal reads as fully achieved, and it scores every experiment from what the evaluation prints. So the goal has to name a success metric and a number, and it helps to name the judge: "accuracy above 0.85 as measured by eval/evaluate.py". Both are the user's to give and optional; whatever the user gives goes into the goal verbatim.

First look for an evaluation the repo already has: a scoring script, a test suite, a benchmark command. Then:

• The repo has one but the request names no metric or target: run it once for the baseline, write the goal with that metric and a target you propose, and tell the user in one line what you assumed and that their own success metric goes straight into the goal. Leave headroom below any ceiling you can see; a target the data cannot reach ends in the inbox, not in a result.
• The repo has none and the request names none: your whole reply is one question, one line, asking whether they have a script or command that scores this and what "good" means; nothing is launched, measured or written before the answer. A script they have goes in with --eval-dir, protected. If they answer that they have none or do not know, launch with the best metric you can state in the goal and no --eval-dir: the campaign builds its own evaluation in kapso_evaluation/ from the goal, and the judge checks that it is fair. Never write an evaluator on the user's behalf, and never ask twice.
• Put rules in the goal, not methods. The judge enforces data rules and prohibitions ("do not modify eval/evaluate.py", "do not fit on data/test.csv") as invariants for the whole campaign, and would freeze a method preference the same way.

Launch

kapso doctor evolve
setsid -f kapso evolve \
  --goal "Get the test accuracy of the churn model in train.py above 0.85 as measured by eval/evaluate.py. The evaluator must not be modified." \
  --initial-repo . \
  --eval-dir eval \
  --data-dir data \
  --output ../churn-campaign \
  --time-budget-minutes 60 --iterations 10 \
  > ../churn-campaign.log 2>&1 < /dev/null
kapso watch ../churn-campaign --follow

• Codex ends a plain nohup … & child when the shell call returns; setsid -f starts Kapso in its own session, so it outlives the call and the session (where setsid is missing: python3 -c 'import subprocess, sys; subprocess.Popen(sys.argv[1:], start_new_session=True)' kapso evolve …). The launch line is a tool call of its own, nothing chained in front of it.
• --initial-repo <path|github url> seeds the campaign; a non-git directory is copied and committed as the baseline. The original is never modified. Every experiment lands on branch generic_exp_N inside --output, an empty directory outside the repo being seeded (a sibling), so the seed copy never contains the campaign.
• --eval-dir is copied to kapso_evaluation/ and integrity-protected: any candidate that edits it is rejected and unscored. Use it whenever the user has a judge. --data-dir is copied to kapso_datasets/. The seed copy includes everything in the directory, .env included.
• Bound the run: --iterations (default 10), --time-budget-minutes (durable across resumes), --cost-budget (best effort; codex sessions report no cost).
• -m GENERIC (default, knowledge search on) or -m MINIMAL; -a picks the coding agent (claude_code default, codex, gemini, openhands, oss_claude_code).
• The summary block ends COMPLETED with score and stop reason, or WAITING ON YOU.

Python, same thing:

from kapso import Kapso
solution = Kapso().evolve(
    goal="...", initial_repo=".", eval_dir="eval", data_dir="data",
    output_path="./campaign", time_budget_minutes=60,
)
print(solution.explain())   # .final_score .succeeded .code_path .requests

evolve() blocks for the whole campaign, so run scripts with setsid -f as well.

Inbox: the campaign is waiting on you

A session that needs something only a person can provide (a credential, access, a file) records a request and the campaign pauses.

kapso inbox ./campaign                 # the open requests: key, hit, tried, fix, next
kapso inbox reply ./campaign 1 "added the key to .env"

• The id may be omitted when one request is open; an empty note means done.
• The reply resumes the very session that asked, in the foreground of that command.
• A credential-shaped reply is refused: put the value where fix says (usually .env) and reply with a note.