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

# Development Guide

<Info>
  **Source Code:** [`src/gaia/`](https://github.com/amd/gaia/tree/main/src/gaia)
</Info>

<Badge text="development" color="orange" />

**Table of Contents**

* [Introduction](#introduction)
* [Before You Start](#before-you-start)
* [Setup and Installation](#setup-and-installation)
* [Running GAIA](#running-gaia)
* [Troubleshooting](#troubleshooting)
* [Support](#support)

***

## Introduction

GAIA is an open-source framework that runs generative AI applications on AMD hardware. GAIA uses [ONNX Runtime GenAI](https://github.com/microsoft/onnxruntime-genai) via [Lemonade Server](https://lemonade-server.ai/) for running Large Language Models (LLMs).

GAIA utilizes both NPU and iGPU on Ryzen AI systems for optimal performance on 300 series processors or above.

***

## Before You Start

### System Requirements

| Requirement | Minimum                             | Recommended       |
| ----------- | ----------------------------------- | ----------------- |
| **OS**      | Windows 11 Pro 24H2 / Ubuntu 22.04+ | -                 |
| **RAM**     | 16GB                                | 64GB              |
| **CPU**     | Ryzen AI 300-series                 | Ryzen AI MAX+ 395 |
| **Storage** | 20GB free                           | -                 |

**Driver Requirements:**

| Component   | Minimum Version   |
| ----------- | ----------------- |
| Radeon iGPU | `32.0.22029.1019` |
| NPU         | `32.0.203.314`    |

### Software Requirements

* **Git** - For version control
* **Lemonade Server** - Download from [lemonade-server.ai](https://lemonade-server.ai/)

***

## Setup and Installation

GAIA uses [uv](https://docs.astral.sh/uv/), a fast Python package manager that handles virtual environments, Python installation, and dependencies automatically.

### Step 1: Install uv

**Windows (PowerShell):**

```powershell theme={null}
irm https://astral.sh/uv/install.ps1 | iex
```

**Linux:**

```bash theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### Step 2: Clone GAIA

```bash theme={null}
git clone https://github.com/amd/gaia.git
cd gaia
```

### Step 3: Create Virtual Environment

```bash theme={null}
uv venv .venv --python 3.12
```

> **Note:** GAIA supports Python **≥3.10** (classifiers cover 3.10, 3.11, 3.12
> in `setup.py`), but linting configs (`black`/`mypy` in `pyproject.toml`) are
> pinned to `py312`, so **3.12 is recommended for contributors.** `uv` will
> download 3.12 automatically if it's not installed.

### Step 4: Activate the Environment

**Windows (PowerShell):**

```powershell theme={null}
.\.venv\Scripts\Activate.ps1
```

**Windows (Command Prompt):**

```cmd theme={null}
.\.venv\Scripts\activate.bat
```

**Linux:**

```bash theme={null}
source .venv/bin/activate
```

You should see `(.venv)` in your terminal prompt when activated.

### Step 5: Install Dependencies

<Warning>
  **Linux/WSL users:** GAIA's base dependencies (`transformers`, `accelerate`) require PyTorch. Always use `--extra-index-url` to install CPU-only PyTorch and avoid large CUDA packages (\~2GB → \~200MB).
</Warning>

```bash theme={null}
# Linux/WSL - CPU-only PyTorch (required for all installs)
uv pip install -e ".[dev]" --extra-index-url https://download.pytorch.org/whl/cpu
```

**Windows:**

```bash theme={null}
# Windows - default PyTorch
uv pip install -e ".[dev]"
```

**With optional extras:**

```bash theme={null}
# Linux/WSL  (uv picks the CPU-PyTorch wheel automatically via
# tool.uv.sources in pyproject.toml — no --extra-index-url needed)
uv pip install -e ".[dev,talk,rag,ui]"

# Windows
uv pip install -e ".[dev,talk,rag,ui]"
```

<Note>
  The `--extra-index-url https://download.pytorch.org/whl/cpu` workaround is
  only needed with plain `pip`. `uv` reads `tool.uv.sources.pytorch-cpu` from
  `pyproject.toml` and routes CPU-only torch wheels through the right index
  automatically.
</Note>

**Available extras** (see `setup.py` for the full list):

| Extra     | Use case                                                                 |
| --------- | ------------------------------------------------------------------------ |
| `dev`     | Test + lint tooling (pytest, black, isort, mypy, pylint, …)              |
| `ui`      | Agent UI backend (FastAPI + uvicorn + SSE); **required for `gaia --ui`** |
| `api`     | OpenAI-compatible API server (`gaia api start`)                          |
| `rag`     | RAG document Q\&A (sentence-transformers, FAISS, pdfplumber, …)          |
| `talk`    | Voice ASR/TTS (whisper, sounddevice, kokoro-onnx)                        |
| `mcp`     | MCP client/server bridge (`gaia mcp start`)                              |
| `audio`   | Lower-level audio tooling shared by talk                                 |
| `blender` | BlenderAgent 3D automation bindings                                      |
| `image`   | Stable Diffusion image agent                                             |
| `eval`    | Evaluation framework (ground-truth generation, batch experiments)        |
| `youtube` | `gaia youtube --download-transcript`                                     |
| `lint`    | Standalone lint dependency bundle                                        |

### Step 6: Claude Code Plugins (Optional)

GAIA ships a `.claude/settings.json` that declares two recommended Claude Code plugins from the official Anthropic marketplace:

* **`frontend-design`** — higher-quality, less generic UI generation
* **`superpowers`** — structured dev methodology (brainstorm → plan → TDD → review)

Plugins are **not auto-installed silently**. The first time you open this repo in [Claude Code](https://claude.com/claude-code) (v2.1.0+), you'll see a prompt:

> *"This project declares plugins. Install them?"*

Accept it once and the plugins become available for the repo. You can verify with:

```bash theme={null}
claude --version           # must be >= 2.1.0
claude plugin list         # shell command — lists installed plugins + status
# or, inside a Claude Code session, type `/plugin` to open the interactive plugin menu
```

To opt out, copy the entry into your local `.claude/settings.local.json` with `false`:

```json theme={null}
{
  "enabledPlugins": {
    "superpowers@claude-plugins-official": false
  }
}
```

### Deactivating

When done working:

```bash theme={null}
deactivate
```

> **See also:** [Agent SDK Documentation](/docs/guides/chat)

***

## Running GAIA

### Verify Installation

```bash theme={null}
gaia -v    # Check version
gaia -h    # View CLI options
```

### Start Chatting

<CodeGroup>
  ```bash Single Query theme={null}
  gaia chat -q "What is artificial intelligence?"
  ```

  ```bash Interactive theme={null}
  gaia chat
  ```
</CodeGroup>

> **Note:** GAIA automatically starts Lemonade Server when needed. For manual start: `lemonade-server serve`

### Running Electron Applications

GAIA includes Electron-based GUI applications. To run the JAX (Jira Agent Experience) app:

**Windows:**

```powershell theme={null}
.\src\gaia\apps\jira\webui\run.ps1
```

**Linux:**

```bash theme={null}
./src/gaia/apps/jira/webui/run.sh
```

### Agent UI Development

Start the Agent UI (backend + frontend) with the convenience scripts:

**Linux / macOS:**

```bash theme={null}
./installer/scripts/start-agent-ui.sh                # Start both backend + frontend
./installer/scripts/start-agent-ui.sh --backend-only # Backend only (port 4200)
./installer/scripts/start-agent-ui.sh --frontend-only # Frontend dev server only (port 5174)
```

**Windows PowerShell:**

```powershell theme={null}
.\installer\scripts\start-agent-ui.ps1               # Start both backend + frontend
.\installer\scripts\start-agent-ui.ps1 -BackendOnly  # Backend only (port 4200)
.\installer\scripts\start-agent-ui.ps1 -FrontendOnly # Frontend dev server only (port 5174)
```

Or start manually:

```bash theme={null}
# Terminal 1: Backend
uv run python -m gaia.ui.server --debug

# Terminal 2: Frontend (Vite dev server with hot reload)
cd src/gaia/apps/webui && npm run dev
```

### Linting and Formatting

`util/lint.py` drives all repo lint tooling. Running it with no flags runs
**every** check in sequence; pass a specific flag to run one:

```bash theme={null}
python util/lint.py --all --fix   # Run everything; autoformat with black + isort
python util/lint.py --black       # Code formatting
python util/lint.py --isort       # Import sorting
python util/lint.py --pylint      # pylint
python util/lint.py --flake8      # flake8
python util/lint.py --mypy        # type checking
python util/lint.py --bandit      # security scan
python util/lint.py --imports     # custom import-cycle check
python util/lint.py --doc-versions # verify versions in docs match src/gaia/version.py
```

### Running Tests

```bash theme={null}
python -m pytest tests/unit/        # Unit tests only
python -m pytest tests/ -xvs        # All tests, verbose
python -m pytest tests/ --hybrid    # Cloud + local testing
```

Key fixtures live in `tests/conftest.py` (`api_client`, `api_server`,
`require_lemonade`, `lemonade_available`). The `require_lemonade` fixture
auto-skips integration tests when no Lemonade server is running.

### Real-World Testing with Claude Code

Unit and integration tests prove code paths; they don't prove a feature works
end-to-end on real hardware. GAIA ships a **`gaia-testing` skill** (under
`.claude/skills/`) for [Claude Code](https://claude.com/claude-code): it drives
the real interface — the Agent UI in a browser, the CLI, or the Agent UI MCP
server (`gaia mcp serve`) — and brings back screenshots, logs, traces, and
per-operation timing as evidence, all collected to your local machine. In a
session, ask it to *"test / validate / QA this feature with screenshots"*; it
scales from a unit-only run up to a full real-world run gated by a single
approval prompt.

#### Declaring test machines

The real-world tier runs on a machine you nominate. The skill discovers
candidates from your **loaded Claude config only** — it never scans your
filesystem. Declare machines under a `## Dev Machines` (or `## Test Machines`)
heading in either:

* your **user-level** `~/.claude/CLAUDE.md` (shared across all your projects) —
  which may summarise them inline and point to a detail file it loads, such as
  `~/.claude/memory/dev-machines.md`; or
* the **project** `./CLAUDE.md` or `.claude/settings.json`.

Record each machine's name, access method (local, SSH host, or container),
hardware class (CPU / discrete GPU / Ryzen AI NPU), and any setup or test
commands. With nothing declared, the skill targets your **local machine**.

```markdown theme={null}
## Dev Machines
- my-gpu-box — SSH host, Ubuntu 24.04, discrete Radeon GPU; good for dGPU inference tests.
- my-npu-laptop — local, Ryzen AI NPU; good for NPU device-path tests.
```

> **Keep credentials out of committed files.** Put sudo passwords, tokens, and
> keys only in your **user-level** config (or a memory file it points to) —
> never in the repo's `CLAUDE.md` or `.claude/settings.json`. The skill reads
> them write-only and never echoes them into logs, screenshots, or reports.

***

## Troubleshooting

### "uv" command not found (Windows)

After installing uv, the command may not be recognized because PATH hasn't updated.

**Solution 1:** Restart PowerShell (simplest)

**Solution 2:** Update PATH in current session:

```powershell theme={null}
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
```

**Solution 3:** Use full path:

```powershell theme={null}
$env:USERPROFILE\.local\bin\uv.exe --version
```

### Virtual Environment Activation Fails (Windows)

If you see a script execution error:

```powershell theme={null}
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### Model Loading Issues

1. Check available system memory
2. Verify model compatibility with your hardware
3. Ensure all dependencies are correctly installed

### Environment Variable Issues

1. Verify the virtual environment is activated (look for `(.venv)` prefix)
2. Try restarting your terminal
3. Re-run the activation command for your platform

***

## Support

Report issues to `gaia@amd.com` or create an [issue on GitHub](https://github.com/amd/gaia/issues).

***

<small style="color: #666;">
  **License**

  Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.

  SPDX-License-Identifier: MIT
</small>