# Kapso: An Agent Framework That Treats ML Optimization as Repeated Experimentation

> Kapso is a Python framework that combines coding agents, tree search, and a knowledge graph to automate ML/AI program synthesis. It is built around four pillars: evolve, learn, research, and deploy. The core judgement: Kapso is powerful for autonomous experimentation, but its reliance on external agent CLIs and optional infrastructure makes setup and operation more involved than a typical library.

**Leeroo-AI/kapso** — A Knowledge-grounded framework for Autonomous ML/AI Program Synthesis and Optimization

- Repository: https://github.com/Leeroo-AI/kapso
- Website: https://leeroo.com/
- Stars: 131 · Forks: 18
- Language: Python
- License: MIT
- Published: 2026-08-26 · Updated: 2026-08-26 · Language: en
- Canonical page: https://hysenlabs.com/projects/leeroo-ai-kapso

## What Kapso Actually Does Differently

Most AutoML tools optimize hyperparameters or search over architectures. Kapso does something broader: it treats the entire ML pipeline as a program that can be synthesized and optimized through iterative experimentation. The README describes it as combining iterative experimentation with a knowledge base of best practices to discover code improvements. The mechanism is not a single algorithm but a loop. You give it a goal, an initial repository, and a time budget. It then runs experiments, uses coding agents to generate and refine code, and applies tree search to navigate the space of possible solutions. The key difference from a hyperparameter tuner is that Kapso can modify the code itself, not just the configuration. It can rewrite training loops, change model architectures, or add new preprocessing steps. This makes it applicable to problems where the bottleneck is algorithmic, not just parametric. The framework is designed for users who have a concrete ML task, a codebase, and a metric to improve, and who want an autonomous system to explore the solution space.

## The Four Pillars and Their Actual Mechanisms

Kapso's architecture is organized around four methods, each with a distinct role. The evolve pillar, invoked via .evolve(), runs the core experimentation cycle. It uses tree search, coding agents, and knowledge graph context to generate and refine solutions. The README gives an example: you call kapso.evolve(goal="Optimize the model in train.py; target accuracy > 0.80 on evaluate.py", initial_repo="./my_project", output_path="./campaign", time_budget_minutes=120). The campaign prints a status path that you can watch live with the kapso watch command. The learn pillar has two memories. learn() mines your own completed campaigns into evidence-priced knowledge cards, which are essentially distilled experiences. learn_knowledge() ingests external repositories and research into a knowledge graph. The research pillar, .research(), runs deep web searches and returns structured findings that can be fed into the knowledge base or used as context for evolution. The deploy pillar, .deploy(), turns a solution into running software, supporting local execution, Docker, or cloud platforms like Modal. Each pillar is a separate API, but they are designed to work together: research feeds knowledge, knowledge feeds evolution, and evolution produces deployable artifacts.

## Setup Is Not a Simple pip Install

The quickstart makes one thing clear: Kapso is not a standalone Python package. It runs its inference through coding-agent CLIs, and there is no direct-API fallback. That means you must install Node.js 18 or later, then install and log in to two CLI tools: @openai/codex for research, judging, and utilities, and @anthropic-ai/claude-code for ideation and implementation. You also need an OpenAI API key for embeddings, which you add to a .env file. The package itself is installed with pip install leeroo-kapso, and then you run kapso doctor to verify that all the CLIs are logged in and the key is present. The doctor command tells you the exact fix for anything missing. Optional knowledge-graph features require Docker and two services: Weaviate and Neo4j, started via bash scripts/start_infra.sh from a source checkout. The README is explicit that the knowledge graph is not needed to start a basic evolve campaign, which is a relief. But the hard dependency on external agent CLIs is a significant operational constraint. If you are behind a corporate proxy or cannot install global npm packages, Kapso will not work. This is a real trade-off: the framework outsources the heavy lifting of code generation to proprietary agents, which means you are tied to their availability and login requirements.

## The Knowledge Graph Is the Differentiator, but It Is Optional

Kapso's knowledge-grounded claim comes from its knowledge graph integration. You can import external knowledge from repositories and web research into a graph stored in Weaviate and Neo4j. The learn_knowledge() method takes a Source.Repo object and findings from research, then ingests them. Once the graph is populated, campaigns consult it automatically. This is what separates Kapso from a plain agent loop. The evolution process can draw on prior experience and external best practices, not just trial and error. The README gives an example of researching RLHF and DPO for legal contract analysis, ingesting the Hugging Face TRL repository, and then running an evolve campaign with that context. The system also has a separate memory called learn() that mines your own finished campaigns into evidence-priced knowledge cards. That is a form of meta-learning: the system gets better at solving similar problems over time. However, none of this is required for a basic evolve call. You can run Kapso with no knowledge graph at all, which means the "knowledge-grounded" part is an optional enhancement, not the core mechanism. That is worth noting: the marketing emphasizes knowledge, but the minimum viable product is just an agent-based experiment loop.

## Deployment Is a First-Class Concern, with Limits

Many AutoML frameworks stop at producing a model or a set of hyperparameters. Kapso explicitly includes a deploy pillar. The .deploy() method takes a solution and turns it into running software. It supports three strategies: local execution, Docker containers, and cloud platforms like Modal. The README shows a simple example: deployed = kapso.deploy(solution, strategy=DeployStrategy.LOCAL), then deployed.run({"input": "data"}) and deployed.stop(). This is a practical feature for teams that want to move from experimentation to production without rewriting the output. However, the deployment support is not deeply documented in the README. There is no mention of how it handles scaling, monitoring, or rollback. The cloud support is limited to Modal, which is a specific serverless platform. If your infrastructure is on AWS, GCP, or Azure, you may need to adapt the deployment output yourself. The framework gives you a starting point, not a full production pipeline. That is a reasonable boundary, but it means the deploy pillar is more of a bridge than a complete solution.

## Benchmarks and Claims: What the README Says

The README makes strong claims about Kapso's performance. It states that Kapso achieved the Grand Master Trophy at IOAI 2026, surpassed the best human contestant in the AI Model Track. It also claims to beat the best foundation model on RelBench, a Stanford benchmark for predictive ML over enterprise data, and to rank #1 on MLE-Bench among open-source systems. These are significant claims, but the README does not provide methodology details. It links to benchmark-specific README files and a technical report on arXiv, but the cleaned README we have does not include those details. There is no information on the compute budget, the number of runs, or the variance of results. As a technology editor, I cannot verify these claims from the provided material. I can only report that the project makes them. That is a limitation for anyone evaluating Kapso. You should read the linked benchmark files and the technical report before trusting the headline numbers. The leaderboard positions are also time-sensitive: they reflect a specific point in time, and other systems may have surpassed them since. The claims are impressive, but they are not a substitute for your own evaluation on your own tasks.

## A Real Alternative: OpenHands and the Trade-off in Approach

Kapso is not the only framework that uses agents to write and optimize code. A direct alternative is OpenHands, an open-source AI developer agent that can also modify codebases and run experiments. The key difference is in the architecture. OpenHands is a general-purpose coding agent that you can point at a repository and ask to implement a feature or fix a bug. It does not have a built-in knowledge graph or a dedicated evolve loop. Kapso is specialized for ML optimization: it has the tree search, the campaign abstraction, and the knowledge ingestion. If your goal is to improve a specific ML metric, Kapso's structure may save you time. If your goal is broader software engineering, OpenHands is more flexible. There is also a practical difference in dependencies: OpenHands can run with a single agent backend, while Kapso requires two specific CLIs and an OpenAI key. That makes Kapso heavier to set up. The choice depends on whether you want a narrow, optimized tool or a general-purpose agent. Kapso's focus is its strength, but it is also its limitation.

## Maintenance, License, and Upgrade Considerations

Kapso is licensed under MIT, which is permissive and allows commercial use, modification, and redistribution with attribution. That is a low legal barrier for adoption. The repository is actively maintained, with recent releases v0.3.4, v0.3.3, and v0.3.2 all pushed on the same date, 2026-08-27. That suggests a rapid release cycle, which can be good for getting fixes but also means the API may change frequently. The README mentions a legacy aider adapter that is an extra for Python <3.13, indicating that the project is evolving its agent backends. The default claude/codex agents require no extras, which is the intended path. Maintenance cost is a real concern: you are not just maintaining a Python dependency. You need to keep Node.js, the two CLI tools, and their logins up to date. If the underlying agent CLIs change their authentication or API, Kapso may break. The kapso doctor command is designed to catch such issues, but it is still an operational burden. The knowledge graph infrastructure, if you use it, adds Docker containers that need monitoring and updates. Before adopting Kapso, budget time for these external dependencies, not just for the Python package itself.

## Conclusion

Kapso is for engineering teams that want to automate the full cycle of ML experimentation: generating code, testing it, learning from results, and deploying the final solution. It is not for users who expect a plug-and-play optimizer without external dependencies. You need Node.js, logged-in CLI agents for OpenAI Codex and Anthropic Claude Code, and an OpenAI API key just to run the simplest campaign. If you are considering Kapso, first verify that your environment can support these prerequisites and that you are comfortable with the cost of running multiple agent invocations. If you need a lighter-weight approach or want to avoid external agent dependencies, look at alternatives like OpenHands or AutoML libraries. For teams that can manage the infrastructure, Kapso's integration of a knowledge graph and its documented performance on benchmarks like MLE-Bench and RelBench make it a serious candidate. The final judgement: adopt Kapso only if you are prepared to manage its operational complexity and can validate its results against your own baseline, not just the published leaderboard claims.

## FAQ

### What is kapso?

A Python framework from Leeroo for running long-running agents that optimise ML and data systems. You state an objective, it runs a campaign of candidate solutions measured against that objective, and it stores what worked as evidence-priced knowledge cards for the next campaign.

### How do I install kapso?

Install Node.js 18 or newer, then the OpenAI Codex and Claude Code CLIs globally and log both in, add an OPENAI_API_KEY to .env for embeddings, and run pip install leeroo-kapso on Python 3.10 or newer. Inference has no direct-API fallback, so the CLIs are mandatory.

### What is the difference between kapso learn() and learn_knowledge()?

Two separate memory stores. learn() mines your own finished campaigns into evidence-priced knowledge cards, which is experience the system earned, while learn_knowledge() ingests repositories and research into the Knowledge Graph, which is imported knowledge.

### Why did pip install kapso install the wrong thing?

The package name on PyPI is leeroo-kapso. A separate package named kapso is an unrelated WhatsApp tool that installs a kapso command of its own and shadows this one, so the documented fix is to run pip uninstall kapso first.

### What does kapso doctor check?

It reports what your configuration actually needs and names the fix for anything missing, and requirements follow the config, so an all-Codex setup is never asked for Claude. You can scope it to one verb, for example kapso doctor evolve, to see just that verb's requirements.

### What licence is kapso under?

MIT, and the project is classified as Development Status 4 - Beta at version 0.5.0. The classifiers cover Python 3.10, 3.11 and 3.12.

## Sources

- [Official documentation](https://leeroo.com/)
- [Official README](https://github.com/Leeroo-AI/kapso#readme)
- [Project repository](https://github.com/Leeroo-AI/kapso)
- [Release notes](https://github.com/Leeroo-AI/kapso/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/leeroo-ai-kapso