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

# Quick Start

> Get started with SkyDiscover in under 5 minutes

Get your first AI-driven discovery running in minutes with this step-by-step guide.

## Prerequisites

* **Python 3.10 or higher** (3.10-3.13 supported)
* **[uv](https://docs.astral.sh/uv/)** package manager (recommended) or pip
* **LLM API key** (OpenAI, Gemini, Claude, or local model)

## Quick Setup

<Steps>
  <Step title="Install SkyDiscover">
    Install the base package with uv:

    ```bash theme={null}
    git clone https://github.com/skydiscover-ai/skydiscover.git
    cd skydiscover
    uv sync
    ```

    Or install specific extras:

    ```bash theme={null}
    # For math benchmarks
    uv sync --extra math

    # For multiple extras
    uv sync --extra math --extra adrs
    ```
  </Step>

  <Step title="Set up API key">
    Export your LLM API key:

    <CodeGroup>
      ```bash OpenAI theme={null}
      export OPENAI_API_KEY="sk-your-key-here"
      ```

      ```bash Google Gemini theme={null}
      export GEMINI_API_KEY="your-gemini-key-here"
      ```

      ```bash Anthropic Claude theme={null}
      export ANTHROPIC_API_KEY="sk-ant-your-key-here"
      ```
    </CodeGroup>
  </Step>

  <Step title="Run your first discovery">
    Try the circle packing example (requires `--extra math`):

    ```bash theme={null}
    uv run skydiscover-run \
      benchmarks/math/circle_packing/initial_program.py \
      benchmarks/math/circle_packing/evaluator.py \
      --config benchmarks/math/circle_packing/config.yaml \
      --search adaevolve \
      --iterations 100
    ```

    <Accordion title="View expected output">
      ```
      Iteration 1/100: Best score = 2.103
      Iteration 5/100: Best score = 2.267
      Iteration 10/100: Best score = 2.412
      ...
      Iteration 100/100: Best score = 2.621

      Best solution saved to: outputs/circle_packing_adaevolve_20260305_123456/best_solution.py
      Final score: 2.621 (target: 2.635 from AlphaEvolve)
      ```
    </Accordion>
  </Step>
</Steps>

## Understanding the Example

### The Circle Packing Problem

The circle packing problem asks: What's the optimal arrangement of n circles of diameter 1 in a unit circle?

### Initial Program

The starting solution uses a constructor-based approach:

```python initial_program.py theme={null}
import numpy as np

# EVOLVE-BLOCK-START
def generate_circle_packing(n):
    """Generate n circle positions within a unit circle."""
    theta = np.linspace(0, 2*np.pi, n, endpoint=False)
    r = 0.3  # Initial radius for positioning
    positions = np.array([[r*np.cos(t), r*np.sin(t)] for t in theta])
    return positions
# EVOLVE-BLOCK-END

if __name__ == "__main__":
    positions = generate_circle_packing(26)
    np.save("positions.npy", positions)
```

The `EVOLVE-BLOCK` markers tell SkyDiscover which region to optimize. Everything outside remains unchanged.

### Evaluator Function

The evaluator scores how tightly circles can be packed:

```python evaluator.py theme={null}
import numpy as np

def evaluate(program_path):
    """Score a circle packing solution."""
    # Execute the program
    exec(open(program_path).read(), globals())
    
    # Load positions
    positions = np.load("positions.npy")
    n = len(positions)
    
    # Calculate minimum pairwise distance
    min_dist = float('inf')
    for i in range(n):
        for j in range(i+1, n):
            dist = np.linalg.norm(positions[i] - positions[j])
            min_dist = min(min_dist, dist)
    
    # Score = diameter of packed circles
    # Higher is better (tighter packing)
    score = min_dist
    
    return {
        "combined_score": score,
        "artifacts": {
            "min_distance": min_dist,
            "num_circles": n
        }
    }
```

### How Evolution Works

1. **Iteration 1**: SkyDiscover runs the initial program and evaluates it
2. **Iteration 2-100**: The LLM proposes improvements to the `generate_circle_packing` function
3. **Selection**: AdaEvolve uses adaptive strategies to select which programs to evolve
4. **Evaluation**: Each new program is scored by the evaluator
5. **Best tracking**: The highest-scoring solution is saved

## Try Your Own Problem

### Option 1: Start from Scratch

Let the LLM generate a solution from just an evaluator:

```bash theme={null}
uv run skydiscover-run evaluator.py \
  --search evox \
  --model gpt-5 \
  --iterations 50
```

### Option 2: Python API

Use SkyDiscover programmatically:

```python theme={null}
from skydiscover import run_discovery

result = run_discovery(
    evaluator="evaluator.py",
    initial_program="initial_program.py",
    search="adaevolve",
    model="gpt-5",
    iterations=100
)

print(f"Best score: {result.best_score}")
print(f"Best solution:\n{result.best_solution}")
```

### Option 3: Custom Evaluator

Create a custom optimization problem:

```python my_evaluator.py theme={null}
def evaluate(program_path):
    # Run your custom test suite
    score = run_tests(program_path)
    
    return {
        "combined_score": score,
        "artifacts": {
            "tests_passed": 42,
            "performance_ms": 123
        }
    }
```

Then run:

```bash theme={null}
uv run skydiscover-run my_evaluator.py \
  --search adaevolve \
  --iterations 100
```

## Choose a Search Algorithm

Different algorithms work better for different problems:

<CardGroup cols={2}>
  <Card title="AdaEvolve" icon="brain" href="/algorithms/adaevolve">
    **Best for:** Most problems

    Adaptive multi-island search with UCB selection and paradigm breakthroughs
  </Card>

  <Card title="EvoX" icon="sparkles" href="/algorithms/evox">
    **Best for:** Complex landscapes

    Self-evolving algorithm that adapts its own strategy
  </Card>

  <Card title="Beam Search" icon="magnifying-glass" href="/algorithms/beam-search">
    **Best for:** Discrete decisions

    Maintains multiple candidate solutions in parallel
  </Card>

  <Card title="Top-K" icon="arrow-up" href="/algorithms/topk">
    **Best for:** Quick experiments

    Simple greedy selection of top performers
  </Card>
</CardGroup>

## Common Workflows

<AccordionGroup>
  <Accordion title="Resume from checkpoint">
    If a run is interrupted, resume from the last checkpoint:

    ```bash theme={null}
    uv run skydiscover-run evaluator.py \
      --checkpoint outputs/my_run_20260305_123456/checkpoint_50 \
      --iterations 100
    ```
  </Accordion>

  <Accordion title="Use multiple models">
    Distribute load across multiple LLMs:

    ```bash theme={null}
    uv run skydiscover-run evaluator.py \
      --model "gpt-5,gemini/gemini-3-pro-preview" \
      --iterations 100
    ```

    Or configure in YAML:

    ```yaml theme={null}
    llm:
      models:
        - name: "gpt-5"
          weight: 0.7
        - name: "gemini/gemini-3-pro-preview"
          weight: 0.3
    ```
  </Accordion>

  <Accordion title="Enable live monitoring">
    Add to your config or command line:

    ```yaml config.yaml theme={null}
    monitor:
      enabled: true
      host: "0.0.0.0"
      port: 8080
    ```

    Then visit `http://localhost:8080` to see:

    * Real-time scatter plot of all programs
    * Code diffs and metrics
    * Progress charts
    * AI-generated summaries
  </Accordion>

  <Accordion title="Optimize multiple files (agentic mode)">
    Let the LLM read and modify multiple files:

    ```bash theme={null}
    uv run skydiscover-run initial_program.py evaluator.py \
      --agentic \
      --search adaevolve \
      --iterations 100
    ```

    The LLM can now read any file in your codebase and make coordinated changes across multiple files.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="book" href="/concepts/overview">
    Learn how SkyDiscover works under the hood
  </Card>

  <Card title="Writing Evaluators" icon="pencil" href="/guides/writing-evaluators">
    Best practices for creating effective scoring functions
  </Card>

  <Card title="Browse Examples" icon="folder-open" href="/examples/overview">
    Explore math, systems, and algorithm optimization examples
  </Card>

  <Card title="Configuration Guide" icon="sliders" href="/guides/configuration">
    Advanced configuration options and YAML reference
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="API key not found">
    Make sure you've exported your API key:

    ```bash theme={null}
    export OPENAI_API_KEY="sk-..."
    ```

    Or pass it via config:

    ```yaml theme={null}
    llm:
      models:
        - name: "gpt-5"
          api_key: "sk-..."
    ```
  </Accordion>

  <Accordion title="Module not found">
    Install the required extras for your benchmark:

    ```bash theme={null}
    uv sync --extra math  # For math benchmarks
    uv sync --extra adrs  # For systems benchmarks
    ```
  </Accordion>

  <Accordion title="Rate limit errors">
    Reduce iteration frequency or use multiple models:

    ```yaml theme={null}
    llm:
      models:
        - name: "gpt-5-mini"
          weight: 0.8
        - name: "gpt-5"
          weight: 0.2
    ```
  </Accordion>
</AccordionGroup>