> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leeroo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# KAPSO

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

## What is Kapso?

Kapso combines **iterative experimentation** with a **knowledge base** of best practices, domain knowledge, and implementation patterns to discover and validate ML/AI code improvements.

It automates the cycle of **designing**, **running**, **evaluating**, and **refining** solutions,  eventually adapting the optimized solution for **deployment** on your chosen infrastructure.

<Frame>
  <img src="https://api.leeroo.com/storage/v1/object/public/opensource/framework.png" alt="Kapso Framework Architecture" />
</Frame>

## Leeroopedia MCP Integration

Connect Kapso to [**Leeroopedia**](https://leeroopedia.com) — a curated knowledge base of 1000+ ML/AI frameworks. Kapso agents use it during ideation and implementation to search docs, build plans, diagnose failures, and look up hyperparameter defaults.

```bash theme={null}
pip install leeroopedia-mcp
```

Sign up at [leeroopedia.com](https://leeroopedia.com) for an API key (\$20 free credit on sign-up). See the [Leeroopedia MCP docs](https://github.com/Leeroo-AI/leeroopedia-mcp) for setup details.

## Core Workflow

```python theme={null}
from kapso.kapso import Kapso, Source, DeployStrategy

# Initialize Kapso with legal domain knowledge
kapso = Kapso(kg_index="data/indexes/legal_contracts.index")

# Research: Gather domain-specific alignment techniques
research_findings = kapso.research(
    "RLHF and DPO fine-tuning for legal contract analysis",
    depth="deep",
)

# Learn: Ingest knowledge from repositories
kapso.learn(
    sources=[
        Source.Repo("https://github.com/huggingface/trl"),
        *research_findings.repos(top_k=5),
    ],
    wiki_dir="data/wikis",
)

# Evolve: Build a solution through experimentation
# The agent writes evaluate.py to compute F1 score and signal when target is reached
solution = kapso.evolve(
    goal="Fine-tune Llama-3.1-8B on the CUAD dataset (https://huggingface.co/datasets/theatticusproject/cuad) for legal clause risk classification, target F1 > 0.85 on high-risk clause detection",
    output_path="./models/legal_risk_v1",
    context=[research_findings.ideas(top_k=10)],
)

# Deploy: Turn solution into running deployed_program
deployed_program = kapso.deploy(solution, strategy=DeployStrategy.MODAL)

# Cleanup
deployed_program.stop()
```

## The Four Pillars

<CardGroup cols={2}>
  <Card title="Evolve" icon="dna">
    **`.evolve()`** : Run iterative evaluation grounded experiments to build the optimum solution for a goal. Uses tree search, coding agents, and KG context to generate ideas and refine solutions.
  </Card>

  <Card title="Learn" icon="brain">
    **`.learn()`** : Ingest knowledge from repositories, past solutions, or written knowledge. Extracts patterns and best practices into the Knowledge Graph.
  </Card>

  <Card title="Research" icon="magnifying-glass">
    **`.research()`** : Run deep web research to gather ideas, implementation references and releveant repositories. Returns structured findings you can pass to learning or use as context for evolving solutions.
  </Card>

  <Card title="Deploy" icon="rocket">
    **`.deploy()`** :  Turn a solution into running app. Supports local execution, Docker containers, or cloud platforms like Modal.
  </Card>
</CardGroup>

## Core Components

| Component              | Description                                                                 |
| ---------------------- | --------------------------------------------------------------------------- |
| **Kapso**              | Main API class — orchestrates research, learn, evolve, and deploy           |
| **OrchestratorAgent**  | Runs the experimentation loop with budget tracking                          |
| **Search Strategy**    | Explores solutions via tree search (generic, benchmark\_tree\_search)       |
| **Coding Agents**      | Pluggable code generators: Aider, Gemini, Claude Code, OpenHands            |
| **Feedback Generator** | Validates evaluation results and decides when to stop                       |
| **Knowledge Pipeline** | Two-stage learning: Ingestors extract WikiPages → Merger integrates into KG |
| **Knowledge Search**   | Hybrid retrieval using Weaviate (semantic) + Neo4j (graph structure)        |
| **Repo Memory**        | Evidence-backed understanding of repository structure                       |
| **Deployment**         | Turn solutions into running software: Local, Docker, Modal, BentoML         |

## Supported Benchmarks

<CardGroup cols={2}>
  <Card title="MLE-Bench" icon="chart-line" href="/docs/benchmarks/mle-bench">
    Solve Kaggle ML competitions with automated experimentation. Supports tabular, image, text, and audio problems.
  </Card>

  <Card title="ALE-Bench" icon="code" href="/docs/benchmarks/ale-bench">
    Tackle AtCoder algorithmic optimization problems. Generates C++ solutions using optimization algorithms.
  </Card>
</CardGroup>

## Quick Links

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" href="/docs/quickstart">
    Get running in 5 minutes
  </Card>

  <Card title="Architecture" icon="sitemap" href="/docs/evolve/architecture">
    System design overview
  </Card>

  <Card title="Configuration" icon="gear" href="/docs/guides/configuration">
    YAML config reference
  </Card>
</CardGroup>

## Why Kapso?

* **Knowledge-Grounded**: Solutions are informed by domain knowledge, not just LLM priors
* **Iterative Refinement**: Tree search explores multiple approaches, learns from failures
* **Pluggable Components**: Swap coding agents, evaluators, and search strategies
* **Full Lifecycle**: From research to deployment in a single framework