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

# Quickstart

> Run your first Forge tuning session in 15 minutes.

## Prerequisites

* An NVIDIA or AMD GPU (or use `--dry-run` on CPU)
* Python 3.10+
* An Anthropic API key (or any supported LLM provider)

## Install

```bash theme={null}
pip install aevyra-forge
export ANTHROPIC_API_KEY=sk-ant-...
```

## Prepare a workload

Forge optimizes against **your** real traffic. The workload is a JSONL
file — one request per line:

```jsonl theme={null}
{"prompt": "Explain attention in transformers.", "expected_output_tokens": 256}
{"prompt": "Write a Python function to merge two sorted lists.", "expected_output_tokens": 128}
```

A 50-example starter is bundled:

```bash theme={null}
# Use the bundled sample
ls examples/sample_workload.jsonl
```

For production use, export a sample of your real traffic from Langfuse,
your API gateway logs, or any JSONL source.

## Run

```bash theme={null}
aevyra-forge tune \
  --model meta-llama/Llama-3.2-1B-Instruct \
  --device cuda \
  --workload examples/sample_workload.jsonl \
  --max-experiments 10
```

Forge will:

1. Auto-detect your GPU via `nvidia-smi` / `rocm-smi`
2. Boot vLLM with the baseline config
3. Benchmark your workload at up to 8 concurrent requests
4. Ask the agent LLM to propose a mutation
5. Boot → bench → keep or revert, repeat

Results are saved to `.forge/runs/<run-id>/`.

## Resume an interrupted run

If a run is interrupted (Ctrl-C, timeout, OOM), resume with no
arguments — Forge reads everything from the saved config:

```bash theme={null}
aevyra-forge tune resume
```

## View results

```bash theme={null}
aevyra-forge report .forge/
```

Prints a summary table with throughput, P99 latency, accuracy, and
whether each experiment was kept.

## Device options

| Flag            | Hardware   | Requirement             |
| --------------- | ---------- | ----------------------- |
| `--device cuda` | NVIDIA GPU | `nvidia-smi` on PATH    |
| `--device rocm` | AMD GPU    | `rocm-smi` on PATH      |
| `--device cpu`  | No GPU     | `--dry-run` recommended |

## LLM providers

The `--llm` flag selects the agent model. Format: `provider/model`.

```bash theme={null}
# Anthropic (default)
--llm anthropic/claude-sonnet-4-6

# OpenRouter
--llm openrouter/meta-llama/llama-3.1-70b-instruct

# OpenAI
--llm openai/gpt-4o
```

Set the corresponding API key environment variable before running.

## Next steps

* [Tutorial: Colab quickstart](/forge/tutorial-colab-quickstart) — run on
  a free T4
* [Concepts: Recipe](/forge/concepts/recipe) — what's in `recipe.yaml`
* [Concepts: Playbook](/forge/concepts/playbook) — how the agent decides
  what to try
* [CLI reference](/forge/cli) — all commands and flags