Kapso

A Knowledge-grounded framework for Autonomous AI/ML Program Synthesis and Optimization

Learn more · Join Discord · Website

If you like this project, please support us by giving it a star ⭐

News

• 🏆 IOAI² Grand Master Trophy at IOAI 2026: competing fully autonomously in the AI Model Track of the International Olympiad in AI, Kapso surpassed the best human contestant and ranked top 3 among all AI system participants, a field spanning major AI labs and startups.

• Beats the best foundation model on RelBench: on Stanford's benchmark for predictive ML over enterprise data, Kapso passes KumoRFM-v2 in outcome prediction and forecasting, and the best reported results in recommendations. Published results live on the official RelBench leaderboard.

  

• 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).

  

• #1 on ALE-Bench: KAPSO achieved top ranking on long-horizon algorithmic discovery problems (ALE Benchmark).

  

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

🚀 Quickstart

Installation

1. Prerequisites. Kapso runs its inference through coding-agent CLIs (there is no direct-API fallback), so you need Node.js and both agent CLIs logged in before anything works:

# Node.js 18+ (https://nodejs.org), then:
npm install -g @openai/codex            # research, judging, utilities
codex login

npm install -g @anthropic-ai/claude-code  # ideation + implementation (default mode)
claude auth login

Add an OpenAI key for embeddings (memory and knowledge-search indexing):

echo 'OPENAI_API_KEY=sk-...' >> .env

2. Install the package (Python 3.10+):

pip install leeroo-kapso

3. Verify the setup:

kapso doctor

doctor checks the CLIs, their logins, and the key, and tells you the exact fix for anything missing. The optional items it reports (docker, Weaviate, Neo4j) matter only for the knowledge-graph features below.

Knowledge-graph backends (optional) — learn_knowledge() and kg_index store into local Weaviate + Neo4j. From a source checkout:

bash scripts/start_infra.sh   # starts both via docker

From source (for development)

git clone https://github.com/leeroo-ai/kapso.git
cd kapso

conda create -n kapso python=3.12 && conda activate kapso
pip install -e .

The legacy aider adapter is an extra (pip install "leeroo-kapso[aider]", Python <3.13); the default claude/codex agents need no extras.

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

The core loop needs nothing beyond the prerequisites above:

from kapso import Kapso

kapso = Kapso()   # no knowledge graph needed to start

# Evolve: build a solution through experimentation. The campaign prints
# `status: <path>` at launch — watch it live from another terminal with
#     kapso watch ./campaign
solution = kapso.evolve(
    goal="Optimize the model in train.py; target accuracy > 0.80 on evaluate.py",
    initial_repo="./my_project",         # or omit to start from scratch
    output_path="./campaign",
    time_budget_minutes=120,
)
print(solution.explain())

# Learn from the campaign you just ran: mine the trajectory, grade the
# lessons, and bank evidence-priced knowledge cards.
lesson = kapso.learn(solution)
print(lesson.explain())

# Evolve again — with `learning.serving.enabled: true` in your config,
# the next campaign is served the cards it just earned.
solution2 = kapso.evolve(goal="...", output_path="./campaign2")

With the knowledge-graph backends running, you can also import outside knowledge and serve it to campaigns:

from kapso import Kapso, Source

kapso = Kapso()

# Research the web, then ingest findings + a repository into the KG
findings = kapso.research(
    "RLHF and DPO fine-tuning for legal contract analysis",
    mode=["idea", "implementation"],
)
kapso.learn_knowledge(
    Source.Repo("https://github.com/huggingface/trl"),
    findings.ideas,
    findings.implementations,
    wiki_dir="data/wikis",
)

# Campaigns on this Kapso now consult the knowledge graph automatically
solution = kapso.evolve(goal="Fine-tune Llama-3.1-8B for clause risk classification")

And to turn a solution into running software:

from kapso import DeployStrategy

deployed = kapso.deploy(solution, strategy=DeployStrategy.LOCAL)
result = deployed.run({"input": "data"})
deployed.stop()

For detailed integration steps, see the Quickstart and Installation guides.

Examples

Supported Benchmarks

📚 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}, 
}