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 ⭐

Early Access: Sign up for the hosted version of Kapso.

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

From PyPI (recommended)

pip install leeroo-kapso

Coding-agent CLI (required) — every Kapso inference call (judging, research, knowledge search, commit messages) runs as a coding-agent CLI session; there is no direct-API fallback. Install and authenticate the default agent, Codex CLI, before running anything:

npm install -g @openai/codex
codex login

An OPENAI_API_KEY in .env is still needed for embeddings (memory and knowledge-search indexing).

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

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