Development Guide

Source Code: src/gaia/

Table of Contents

Introduction
Before You Start
Setup and Installation
Running GAIA
Troubleshooting
Support

Introduction

GAIA is an open-source framework that runs generative AI applications on AMD hardware. GAIA uses ONNX Runtime GenAI via Lemonade Server 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

Setup and Installation

GAIA uses uv, a fast Python package manager that handles virtual environments, Python installation, and dependencies automatically.

Step 1: Install uv

Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Step 2: Clone GAIA

git clone https://github.com/amd/gaia.git
cd gaia

Step 3: Create Virtual Environment

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):

.\.venv\Scripts\Activate.ps1

Windows (Command Prompt):

.\.venv\Scripts\activate.bat

Linux:

source .venv/bin/activate

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

Step 5: Install Dependencies

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

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

Windows:

# Windows - default PyTorch
uv pip install -e ".[dev]"

With optional extras:

# 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]"

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.

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 (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:

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:

{
  "enabledPlugins": {
    "superpowers@claude-plugins-official": false
  }
}

Deactivating

When done working:

deactivate

See also: Agent SDK Documentation

Running GAIA

Verify Installation

gaia -v    # Check version
gaia -h    # View CLI options

Start Chatting

gaia chat -q "What is artificial intelligence?"

gaia chat

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:

.\src\gaia\apps\jira\webui\run.ps1

Linux:

./src/gaia/apps/jira/webui/run.sh

Agent UI Development

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

./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:

.\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:

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

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

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

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

$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"

Solution 3: Use full path:

$env:USERPROFILE\.local\bin\uv.exe --version

Virtual Environment Activation Fails (Windows)

If you see a script execution error:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Model Loading Issues

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

Environment Variable Issues

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

Support

Report issues to [email protected] or create an issue on GitHub.

Command Line

API & Development

Help

Development Guide

Introduction

Before You Start

System Requirements

Software Requirements

Setup and Installation

Step 1: Install uv

Step 2: Clone GAIA

Step 3: Create Virtual Environment

Step 4: Activate the Environment

Step 5: Install Dependencies

Step 6: Claude Code Plugins (Optional)

Deactivating

Running GAIA

Verify Installation

Start Chatting

Running Electron Applications

Agent UI Development

Linting and Formatting

Running Tests

Real-World Testing with Claude Code

Declaring test machines

Troubleshooting

”uv” command not found (Windows)

Virtual Environment Activation Fails (Windows)

Model Loading Issues

Environment Variable Issues

Support

​Introduction

​Before You Start

​System Requirements

​Software Requirements

​Setup and Installation

​Step 1: Install uv

​Step 2: Clone GAIA

​Step 3: Create Virtual Environment

​Step 4: Activate the Environment

​Step 5: Install Dependencies

​Step 6: Claude Code Plugins (Optional)

​Deactivating

​Running GAIA

​Verify Installation

​Start Chatting

​Running Electron Applications

​Agent UI Development

​Linting and Formatting

​Running Tests

​Real-World Testing with Claude Code

​Declaring test machines

​Troubleshooting

​”uv” command not found (Windows)

​Virtual Environment Activation Fails (Windows)

​Model Loading Issues

​Environment Variable Issues

​Support

Introduction

Before You Start

System Requirements

Software Requirements

Setup and Installation

Step 1: Install uv

Step 2: Clone GAIA

Step 3: Create Virtual Environment

Step 4: Activate the Environment

Step 5: Install Dependencies

Step 6: Claude Code Plugins (Optional)

Deactivating

Running GAIA

Verify Installation

Start Chatting

Running Electron Applications

Agent UI Development

Linting and Formatting

Running Tests

Real-World Testing with Claude Code

Declaring test machines

Troubleshooting

”uv” command not found (Windows)

Virtual Environment Activation Fails (Windows)

Model Loading Issues

Environment Variable Issues

Support