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

# Installation

> Complete installation guide for Kapso and benchmarks

## Core Installation

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

  <Step title="Or install from source (for development or wiki 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 .
    ```

    <Note>
      This repository uses Git LFS for large files in `data/wikis_batch_top100/`.
      If you didn't install Git LFS before cloning, run these commands to fetch the files.
    </Note>
  </Step>

  <Step title="Configure API keys">
    Create `.env` in project root:

    ```bash theme={null}
    # Required for most operations
    OPENAI_API_KEY=your-openai-api-key

    # For Gemini coding agent
    GOOGLE_API_KEY=your-google-api-key

    # For Claude Code coding agent
    ANTHROPIC_API_KEY=your-anthropic-api-key

    # For Leeroopedia MCP (curated ML/AI knowledge — sign up at leeroopedia.com)
    LEEROOPEDIA_API_KEY=your-leeroopedia-api-key
    ```
  </Step>
</Steps>

## Coding Agent Setup

Kapso supports multiple coding agents. Install the ones you plan to use:

<Tabs>
  <Tab title="Aider (Default)">
    Aider is installed automatically with `pip install -e .`

    No additional setup required. Uses git-centric diff-based editing.

    ```bash theme={null}
    # Verify installation
    aider --version
    ```
  </Tab>

  <Tab title="Claude Code">
    Claude Code requires Node.js and the Anthropic CLI:

    ```bash theme={null}
    # Install Claude Code CLI
    npm install -g @anthropic-ai/claude-code

    # Verify installation
    claude --version
    ```

    Set `ANTHROPIC_API_KEY` in your `.env` file.
  </Tab>

  <Tab title="Gemini">
    Gemini uses the Google AI SDK, installed with core dependencies.

    Set `GOOGLE_API_KEY` in your `.env` file.
  </Tab>

  <Tab title="OpenHands">
    <Warning>
      OpenHands has conflicting dependencies with `aider-chat`. Use a **separate conda environment**.
    </Warning>

    ```bash theme={null}
    # Create separate environment
    conda create -n openhands_env python=3.12
    conda activate openhands_env

    # Install OpenHands
    pip install openhands-ai litellm
    ```

    Do NOT install OpenHands in the same environment as Kapso.
  </Tab>
</Tabs>

## Leeroopedia MCP (Optional)

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, verify code, diagnose failures, and look up hyperparameter defaults.

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

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

```bash theme={null}
LEEROOPEDIA_API_KEY=kpsk_your_key_here
```

See the [Leeroopedia MCP docs](https://github.com/Leeroo-AI/leeroopedia-mcp) for Claude Code and Cursor setup.

## Benchmark Installation

<Tabs>
  <Tab title="MLE-Bench">
    MLE-Bench provides Kaggle competition problems.

    **Prerequisites:**

    * Git LFS (`sudo apt-get install git-lfs` or `brew install git-lfs`)

    **Installation:**

    ```bash theme={null}
    # Clone and install MLE-Bench
    git clone https://github.com/openai/mle-bench.git
    cd mle-bench
    git lfs install
    git lfs fetch --all
    git lfs pull
    pip install -e .
    cd ..

    # Install MLE-specific dependencies
    pip install -r benchmarks/mle/requirements.txt
    ```

    **Verify:**

    ```bash theme={null}
    PYTHONPATH=. python -m benchmarks.mle.runner --list
    ```
  </Tab>

  <Tab title="ALE-Bench">
    ALE-Bench provides AtCoder algorithmic optimization problems.

    **Prerequisites:**

    * Docker
    * libcairo2-dev (`sudo apt-get install -y libcairo2-dev`)

    **Installation:**

    ```bash theme={null}
    # Clone and install ALE-Bench
    git clone https://github.com/SakanaAI/ALE-Bench.git
    cd ALE-Bench
    pip install .
    pip install ".[eval]"

    # Build Docker container for evaluation
    bash ./scripts/docker_build_202301.sh $(id -u) $(id -g)
    cd ..
    ```

    **Verify:**

    ```bash theme={null}
    PYTHONPATH=. python -m benchmarks.ale.runner --list
    ```
  </Tab>
</Tabs>

## Infrastructure Setup

Kapso uses Docker containers for its knowledge graph infrastructure:

* **Weaviate**: Vector database for semantic search
* **Neo4j**: Graph database for relationships
* **MediaWiki** (optional): Web UI for browsing wiki pages

### Quick Start (Recommended)

```bash theme={null}
# Start all infrastructure
./scripts/start_infra.sh

# Stop infrastructure (data preserved)
./scripts/stop_infra.sh

# Stop and wipe all data
./scripts/stop_infra.sh --volumes
```

### Default Service URLs

| Service       | URL                                            | Credentials              |
| ------------- | ---------------------------------------------- | ------------------------ |
| MediaWiki     | [http://localhost:8090](http://localhost:8090) | `admin` / `adminpass123` |
| Neo4j Browser | [http://localhost:7474](http://localhost:7474) | `neo4j` / `password`     |
| Weaviate      | [http://localhost:8080](http://localhost:8080) | Anonymous (no auth)      |

### Manual Setup

If you prefer to start services individually:

<Accordion title="Docker Compose (All Services)">
  ```bash theme={null}
  docker compose -f services/infrastructure/docker-compose.yml up -d
  ```

  This starts:

  * **Weaviate** (port 8080) - Vector database for embeddings
  * **Neo4j** (ports 7474, 7687) - Graph database for relationships
  * **MediaWiki** (port 8090) - Web UI for browsing wiki pages
  * **MariaDB** - Backend database for MediaWiki
</Accordion>

<Accordion title="Individual Containers">
  **Weaviate (vector DB):**

  ```bash theme={null}
  docker run -d --name weaviate \
      -p 8080:8080 -p 50051:50051 \
      -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \
      -e PERSISTENCE_DATA_PATH='/var/lib/weaviate' \
      semitechnologies/weaviate:1.27.0
  ```

  **Neo4j (graph DB):**

  ```bash theme={null}
  docker run -d --name neo4j \
      --restart unless-stopped \
      -p 7474:7474 -p 7687:7687 \
      -e NEO4J_AUTH=neo4j/password \
      neo4j:5.18.0
  ```
</Accordion>

### Configure Environment

Add infrastructure settings to your `.env`:

```bash theme={null}
# Neo4j connection
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

# Weaviate connection
WEAVIATE_URL=http://localhost:8080

# MediaWiki (optional)
MW_BASE=http://localhost:8090
MW_USER=admin
MW_PASS=adminpass123
```

## Knowledge Graph Indexing

After infrastructure is running, index your wiki pages:

### Using Kapso API (Recommended)

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

# Initialize Kapso
kapso = Kapso(config_path="src/config.yaml")

# Index wiki pages (one-time operation)
kapso.index_kg(
    wiki_dir="data/wikis",
    save_to="data/indexes/my_knowledge.index",
)

# Load existing index on subsequent runs
kapso = Kapso(
    config_path="src/config.yaml",
    kg_index="data/indexes/my_knowledge.index",
)
```

### Index File Format

The `.index` file is a JSON reference to the indexed data:

```json theme={null}
{
  "version": "1.0",
  "created_at": "2025-01-15T10:30:00Z",
  "data_source": "data/wikis_llm_finetuning",
  "search_backend": "kg_graph_search",
  "backend_refs": {
    "weaviate_collection": "KapsoWiki",
    "embedding_model": "text-embedding-3-large"
  },
  "page_count": 99
}
```

### KG Search Backends

| Backend             | Data Format                 | Storage          | Use Case                           |
| ------------------- | --------------------------- | ---------------- | ---------------------------------- |
| `kg_graph_search`   | Wiki pages (.md/.mediawiki) | Weaviate + Neo4j | Semantic search with LLM reranking |
| `kg_llm_navigation` | JSON (nodes/edges)          | Neo4j only       | LLM-guided graph navigation        |

## Environment Variables Reference

| Variable              | Required | Default                 | Description                                              |
| --------------------- | -------- | ----------------------- | -------------------------------------------------------- |
| `OPENAI_API_KEY`      | Yes      | -                       | OpenAI API key (also for embeddings)                     |
| `GOOGLE_API_KEY`      | No       | -                       | Google API key for Gemini                                |
| `ANTHROPIC_API_KEY`   | No       | -                       | Anthropic API key for Claude                             |
| `LEEROOPEDIA_API_KEY` | No       | -                       | Leeroopedia API key ([sign up](https://leeroopedia.com)) |
| `NEO4J_URI`           | No       | `bolt://localhost:7687` | Neo4j connection URI                                     |
| `NEO4J_USER`          | No       | `neo4j`                 | Neo4j username                                           |
| `NEO4J_PASSWORD`      | No       | `password`              | Neo4j password                                           |
| `WEAVIATE_URL`        | No       | `http://localhost:8080` | Weaviate server URL                                      |
| `MW_BASE`             | No       | `http://localhost:8090` | MediaWiki base URL                                       |
| `MW_USER`             | No       | `admin`                 | MediaWiki username                                       |
| `MW_PASS`             | No       | `adminpass123`          | MediaWiki password                                       |
| `CUDA_DEVICE`         | No       | `0`                     | GPU device for ML training                               |

## Verify Installation

```bash theme={null}
# Check core installation
python -c "from kapso.kapso import Kapso; print('Kapso OK')"

# Check orchestrator
python -c "from kapso.execution.orchestrator import OrchestratorAgent; print('Orchestrator OK')"

# Check knowledge search
python -c "from kapso.knowledge_base.search import KnowledgeSearchFactory; print('Knowledge Search OK')"

# Check MLE-Bench (if installed)
python -c "import mlebench; print('MLE-Bench OK')"

# Check ALE-Bench (if installed)
python -c "import ale_bench; print('ALE-Bench OK')"

# Check Neo4j driver
python -c "from neo4j import GraphDatabase; print('Neo4j driver OK')"

# Check Weaviate client
python -c "import weaviate; print('Weaviate client OK')"
```

## Troubleshooting

<Accordion title="Services won't start">
  ```bash theme={null}
  # Check Docker logs
  docker compose -f services/infrastructure/docker-compose.yml logs

  # Check individual service
  docker logs weaviate
  docker logs neo4j
  ```
</Accordion>

<Accordion title="MediaWiki issues">
  ```bash theme={null}
  # View MediaWiki logs
  docker compose -f services/infrastructure/docker-compose.yml logs wiki

  # Full reset (deletes all data)
  ./scripts/stop_infra.sh --volumes
  ./scripts/start_infra.sh
  ```
</Accordion>

<Accordion title="Port conflicts">
  If default ports are in use, modify `services/infrastructure/docker-compose.yml` or use different port mappings.
</Accordion>