Kapso
A Knowledge-grounded framework for Autonomous ML/AI Program Synthesis and Optimization
Install / Use
/learn @Leeroo-AI/KapsoREADME
<p align="center"> <img src="https://api.leeroo.com/storage/v1/object/public/opensource/framework.png" alt="Kapso Framework Architecture" width="700"> </p>Early Access: Sign up for the hosted version of Kapso.
News
-
Leeroopedia MCP Integration: Kapso now connects to Leeroopedia MCP — your ML & Data Knowledge Wiki. Learnt by AI, built by AI, for AI. A centralized playbook of best practices and expert-level knowledge for Machine Learning and Data domains. Kapso agents use it during ideation and implementation to search knowledge, build plans, diagnose failures, and more.
-
Moltbook Agents 🦞: Build AI agents that optimize other agents and debate on Moltbook! Get started →
-
Technical Report: Our technical report is now available! Read the paper
-
#1 on MLE-Bench: KAPSO achieved top ranking among open-source systems on Kaggle ML competitions (MLE Benchmark).
<img src="https://api.leeroo.com/storage/v1/object/public/opensource/mle_benchmark.png" alt="MLE-Bench Results" width="600"> -
#1 on ALE-Bench: KAPSO achieved top ranking on long-horizon algorithmic discovery problems (ALE Benchmark).
<img src="https://api.leeroo.com/storage/v1/object/public/opensource/ale_benchmark.png" alt="ALE-Bench Results" width="600">
What is KAPSO?
KAPSO combines iterative experimentation with a knowledge base of best practices and tricks to discover ML/AI code improvements.
It automates the cycle of designing, testing, and refining algorithms, eventually adapting the optimized solution for deployment on your chosen infrastructure.
The Four Pillars
| Pillar | Method | Description |
|--------|--------|-------------|
| Evolve | .evolve() | Run iterative experiments to build software for a goal. Uses tree search, coding agents, and KG context to generate and refine solutions. |
| Learn | .learn() | Ingest knowledge from repositories, past solutions, or research results. Extracts patterns and best practices into the Knowledge Graph. |
| Research | .research() | Run deep web research to gather ideas and implementation references. Returns structured findings you can feed into the knowledge base or use as context for evolving solutions. |
| Deploy | .deploy() | Turn a solution into running software. Supports local execution, Docker containers, or cloud platforms like Modal. |
🚀 Quickstart
Installation
From PyPI (recommended)
pip install leeroo-kapso
From source (for development or to access wiki knowledge data)
git clone https://github.com/leeroo-ai/kapso.git
cd kapso
# Pull Git LFS files (wiki knowledge data)
git lfs install
git lfs pull
# Create conda environment (recommended)
conda create -n kapso python=3.12
conda activate kapso
# Install in development mode
pip install -e .
Leeroopedia MCP (optional) — connect Kapso to Leeroopedia, a curated ML/AI knowledge base. Sign up at leeroopedia.com for an API key, then:
pip install leeroopedia-mcp
echo 'LEEROOPEDIA_API_KEY=kpsk_your_key_here' >> .env
Basic Usage
from kapso import Kapso, Source, DeployStrategy
# Initialize Kapso
# If you have a Knowledge Graph, pass kg_index; otherwise just use Kapso()
kapso = Kapso(kg_index="data/indexes/legal_contracts.index")
# Research: Gather domain-specific techniques from the web
# mode: "idea" | "implementation" | "study" (can pass multiple as list)
# depth: "light" | "deep" (default: "deep")
findings = kapso.research(
"RLHF and DPO fine-tuning for legal contract analysis",
mode=["idea", "implementation"],
depth="deep",
)
# Learn: Ingest knowledge from repositories and research into the KG
kapso.learn(
Source.Repo("https://github.com/huggingface/trl"),
*findings.ideas, # List[Source.Idea]
*findings.implementations, # List[Source.Implementation]
wiki_dir="data/wikis",
)
# Evolve: Build a solution through experimentation
# Use research results as context via to_string()
solution = kapso.evolve(
goal="Fine-tune Llama-3.1-8B for legal clause risk classification, target F1 > 0.85",
data_dir="./data/cuad_dataset",
output_path="./models/legal_risk_v1",
context=[findings.to_string()],
)
# Deploy: Turn solution into running deployed_program
deployed_program = kapso.deploy(solution, strategy=DeployStrategy.MODAL)
deployed_program.stop()
For detailed integration steps, see the Quickstart and Installation guides.
Examples
| Example | Description | |---------|-------------| | CUDA Optimization | Optimize CUDA kernels for GPU performance | | PyTorch Optimization | Optimize PyTorch operations for speedup | | ML Model Development | Improve ML model accuracy on tabular data | | Prompt Engineering | Optimize prompts for better LLM performance | | Agentic Scaffold | Optimize agentic AI workflows |
Supported Benchmarks
| Benchmark | Description | |-----------|-------------| | MLE-Bench | Kaggle ML competitions — tabular, image, text, audio problems | | ALE-Bench | AtCoder algorithmic optimization — C++ solution generation |
📚 Documentation & Support
- Full Documentation: docs.leeroo.com
- Community: Discord
- Website: leeroo.com
Contributing
We welcome contributions! Please see our Contributing Guide for details on how to get started.
Citation
If you use Kapso in your research, please cite:
@misc{nadaf2026kapsoknowledgegroundedframeworkautonomous,
title={KAPSO: A Knowledge-grounded framework for Autonomous Program Synthesis and Optimization},
author={Alireza Nadafian and Alireza Mohammadshahi and Majid Yazdani},
year={2026},
eprint={2601.21526},
archivePrefix={arXiv},
primaryClass={cs.AI},
url={https://arxiv.org/abs/2601.21526},
}
