> ## 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.

# Quickstart

> Get Kapso running in 5 minutes

## Prerequisites

* Python 3.12+
* Git with Git LFS
* API keys for OpenAI and/or Google (Gemini)

## Installation

<Steps>
  <Step title="Install from PyPI (recommended)">
    ```bash theme={null}
    pip install leeroo-kapso
    ```
  </Step>

  <Step title="Or install from source (for wiki knowledge data)">
    ```bash theme={null}
    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_conda python=3.12
    conda activate kapso_conda

    # Install in development mode
    pip install -e .
    ```
  </Step>

  <Step title="Set up API keys">
    Create a `.env` file in the project root:

    ```bash theme={null}
    OPENAI_API_KEY=your-openai-api-key
    GOOGLE_API_KEY=your-google-api-key       # For Gemini models
    ANTHROPIC_API_KEY=your-anthropic-api-key # For Claude Code
    ```
  </Step>

  <Step title="Connect Leeroopedia MCP (optional)">
    Give Kapso access to curated best practices from 1000+ ML/AI frameworks:

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

    Sign up at [app.leeroopedia.com](https://app.leeroopedia.com) for an API key (\$20 free credit), then add to your `.env`:

    ```bash theme={null}
    LEEROOPEDIA_API_KEY=kpsk_your_key_here
    ```
  </Step>
</Steps>

## Run Your First Experiment

### Option 1: Python API (Recommended)

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

# Initialize Kapso
kapso = Kapso()

# Build a solution — Kapso runs experiments automatically
# The developer agent builds evaluation dynamically and the feedback generator
# validates results and decides when to stop
solution = kapso.evolve(
    goal="Build a random forest classifier for the Iris dataset with accuracy > 0.9",
    max_iterations=10,
)

# Deploy and run
deployed_program = kapso.deploy(solution, strategy=DeployStrategy.LOCAL)
result = deployed_program.run({"data_path": "./test.csv"})

# Cleanup
deployed_program.stop()
```

### Option 2: CLI

```bash theme={null}
# Basic usage
kapso evolve --goal "Build a random forest classifier for the Iris dataset"

# With options
kapso evolve \
    --goal "Build a feature engineering pipeline for tabular data" \
    --iterations 10 \
    --coding-agent aider

# List available options
kapso --list-agents
```

## Expected Output

```
============================================================
EVOLVING: Build a random forest classifier for the Iris dataset
============================================================
  Max iterations: 10
  Coding agent: from config

Running experiments...
Experiment 1: Developer agent implementing solution...
Experiment 1: Running evaluation in kapso_evaluation/...
Experiment 1: Feedback generator validating results...
Experiment 1 completed with cumulative cost: $0.125
####################################################################################################
Experiment with score 0.92:
# Solution: Random forest with GridSearchCV hyperparameter tuning...
# Feedback: Good progress! Accuracy 0.92 meets the > 0.9 target. Goal achieved.
####################################################################################################

============================================================
Evolution Complete
============================================================
Solution at: ./workspace
Experiments run: 1
Total cost: $0.125
Goal achieved: Yes
```

The system creates git branches for each experiment and outputs the best solution path.

## With Knowledge Graph (Optional)

For domain-specific context, index a knowledge graph first:

<Steps>
  <Step title="Start infrastructure">
    ```bash theme={null}
    # Start Weaviate + Neo4j (required for KG)
    ./scripts/start_infra.sh
    ```
  </Step>

  <Step title="Index wiki pages (one-time setup)">
    ```python theme={null}
    from kapso.kapso import Kapso

    kapso = Kapso()
    kapso.index_kg(
        wiki_dir="data/wikis_llm_finetuning",
        save_to="data/indexes/llm_finetuning.index",
    )
    ```
  </Step>

  <Step title="Use the indexed KG">
    ```python theme={null}
    from kapso.kapso import Kapso

    # Load from existing index
    kapso = Kapso(kg_index="data/indexes/llm_finetuning.index")

    solution = kapso.evolve(
    goal="Fine-tune Llama-3.1-8B with QLoRA, target loss < 0.5",
    output_path="./models/qlora_v1",
    )
    ```
  </Step>
</Steps>

## Web Research (Optional)

Kapso can do deep web research before evolving:

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

kapso = Kapso()

# Research returns ResearchFindings with ideas and implementations
# mode: "idea" | "implementation" | "both" (default: "both")
# depth: "light" | "deep" (default: "deep")

findings = kapso.research(
    "unsloth FastLanguageModel example",
    mode="both",
    depth="deep",
)

# Use research as context for evolving
solution = kapso.evolve(
    goal="Fine-tune a model with Unsloth + LoRA",
    context=[findings.to_string()],
    output_path="./models/unsloth_v1",
)
```

## Understanding the Output

After `evolve()` completes, you get a `SolutionResult`:

```python theme={null}
solution.goal             # Original goal
solution.code_path        # Path to generated code
solution.experiment_logs  # List of experiment summaries
solution.final_feedback   # FeedbackResult with stop decision and score
solution.metadata         # Cost, iterations, final evaluation

# Check if goal was achieved
if solution.succeeded:
    print(f"Goal achieved with score: {solution.final_score}")
```

The code is in a git repository with branches for each experiment:

```bash theme={null}
cd ./models/iris_v1
git branch -a
# * experiment_2  (best solution)
#   experiment_1
#   experiment_0
#   main
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Full Installation" icon="download" href="/docs/installation">
    Set up MLE-Bench, ALE-Bench, and infrastructure
  </Card>

  <Card title="Architecture" icon="sitemap" href="/docs/concepts/architecture">
    Understand the system design
  </Card>

  <Card title="Configuration" icon="gear" href="/docs/guides/configuration">
    Customize modes and parameters
  </Card>

  <Card title="Execution Flow" icon="diagram-project" href="/docs/concepts/execution-flow">
    How experiments are run
  </Card>
</CardGroup>