===============
LIBRARY RULES
===============
From library maintainers:
- GAIA has two frameworks: Python (src/gaia/) and C++ (cpp/). Most documentation covers the Python SDK.
- Python agents inherit from the base Agent class in src/gaia/agents/base/agent.py
- Tools are registered using the @tool decorator from gaia.agents.base.tools
- LLM inference runs locally via Lemonade Server on AMD NPU/GPU hardware
- Default models: Qwen3-0.6B-GGUF (general), Qwen3.5-35B-A3B-GGUF (agents/code), Qwen3-VL-4B-Instruct-GGUF (vision)
- Agent UI is the primary user interface — launch with 'gaia --ui' for privacy-first desktop chat with document Q&A
- All new features require tests in tests/ and documentation in docs/ (.mdx format for Mintlify)
- Use 'uv pip install -e .[dev]' for development setup
- The code index (gaia.code_index) provides semantic search over repositories using local FAISS + Lemonade embeddings

### CLI and UI State Consistency Example 1

Source: https://github.com/amd/gaia/blob/main/docs/plans/setup-wizard.mdx

Demonstrates how the system maintains consistent state when a user starts setup via CLI and then opens the Electron app.

```bash
1. User runs `gaia init --profile chat` in terminal
2. Downloads complete, Lemonade running, models loaded
3. User opens Electron app
4. App reads ~/.gaia/initialized -> skips wizard, goes to chat
```

--------------------------------

### CLI and UI State Consistency Example 2

Source: https://github.com/amd/gaia/blob/main/docs/plans/setup-wizard.mdx

Illustrates state consistency when a user starts setup via the Electron app and then uses the CLI to resume.

```bash
1. User opens Electron app first, starts wizard
2. Closes app mid-download at 40%
3. Runs `gaia init` in terminal
4. CLI reads setup-state.json, resumes download from 40%
```

--------------------------------

### Install and Start Lemonade Server

Source: https://github.com/amd/gaia/blob/main/docs/plans/docker-containers.mdx

Commands to install the `lemonade-server` package using pip and then start the server. The server is configured to listen on all interfaces (`0.0.0.0`).

```bash
# Install Lemonade Server
pip install lemonade-server

# Start server
lemonade-server serve --host 0.0.0.0
```

--------------------------------

### GAIA CLI Onboarding Commands

Source: https://github.com/amd/gaia/blob/main/docs/plans/setup-wizard.mdx

Examples of how to initiate or bypass the GAIA setup wizard using the command-line interface.

```bash
$ gaia chat
  [First run detected]
  Welcome to GAIA! Run `gaia init` to set up, or pass --skip-setup to proceed manually.
```

```bash
$ gaia init
  [Launches CLI onboarding wizard]
```

```bash
$ gaia init --profile chat --yes
  [Silent mode -- no prompts, uses defaults for the chat profile]
```

--------------------------------

### Setup State File Example

Source: https://github.com/amd/gaia/blob/main/docs/plans/setup-wizard.mdx

This JSON structure represents the state of the GAIA setup process, including system scan results, selected profiles, and model download status.

```json
{
  "version": 1,
  "started_at": "2026-04-01T12:00:00Z",
  "completed_at": null,
  "current_step": "model_selection",
  "system_scan": {
    "os": "windows",
    "os_version": "11 Pro 10.0.26200",
    "arch": "x86_64",
    "ram_gb": 32,
    "disk_free_gb": 120,
    "amd_gpu": "Radeon 780M",
    "amd_npu": "Ryzen AI",
    "npu_detected": true,
    "node_version": "20.11.0",
    "python_version": "3.11.8",
    "lemonade_installed": true,
    "lemonade_version": "10.0.0",
    "lemonade_running": false
  },
  "selected_profile": "chat",
  "models_downloaded": ["Qwen3-0.6B-GGUF"],
  "models_pending": ["Qwen3.5-35B-A3B-GGUF", "nomic-embed-text-v1.5-GGUF"],
  "skipped_steps": [],
  "error_log": []
}
```

--------------------------------

### Initialize GAIA (Recommended)

Source: https://github.com/amd/gaia/blob/main/docs/reference/cli.mdx

Use this command for a quick and recommended start to GAIA. It installs Lemonade Server and downloads required models.

```bash
gaia init
```

--------------------------------

### Start MCP Documentation Server

Source: https://github.com/amd/gaia/blob/main/docs/plans/mcp-docs.mdx

Use this command to start the MCP server. Ensure you have the GAIA CLI installed.

```bash
gaia mcp docs start
```

--------------------------------

### CLI Usage Examples

Source: https://github.com/amd/gaia/blob/main/docs/playbooks/chat-agent/part-3-deployment.mdx

Demonstrates how to invoke the 'doc-qa' CLI tool for both single questions and interactive sessions after installation.

```bash
# One-shot query
doc-qa "What does the manual say about installation?"

# Interactive mode
doc-qa --interactive

# From anywhere after install
cd ~/
projects
doc-qa "Search my indexed docs for API examples"

```

--------------------------------

### Generate Detailed Installation Logs

Source: https://github.com/amd/gaia/blob/main/docs/reference/troubleshooting.mdx

Run the GAIA Windows setup with the /LOG flag to generate a detailed installation log file for troubleshooting.

```powershell
gaia-windows-setup.exe /LOG=install_log.txt
```

--------------------------------

### Install Node.js via NVM

Source: https://github.com/amd/gaia/blob/main/docs/sdk/sdks/mcp.mdx

Instructions to install Node.js using NVM if 'npx' is not found. Refer to the setup guide for detailed instructions.

```bash
# If not, install Node.js via NVM
# See Setup guide for instructions
```

--------------------------------

### Node.js MCP Server Example

Source: https://github.com/amd/gaia/blob/main/docs/guides/mcp/client.mdx

Example command to start an npm-based MCP server using Node.js. This is required for certain types of MCP servers.

```bash
npx -y @modelcontextprotocol/server-memory
```

--------------------------------

### Start Lemonade Server

Source: https://github.com/amd/gaia/blob/main/docs/integrations/mcp.mdx

Ensure the LLM backend is running before proceeding with GAIA setup.

```bash
lemonade-server serve --ctx-size 8192
```

--------------------------------

### Run Hardware Advisor Agent (Developer Install)

Source: https://github.com/amd/gaia/blob/main/docs/playbooks/hardware-advisor/index.mdx

Run the hardware advisor agent example directly from the cloned GAIA repository. This is used when you have installed GAIA in editable mode.

```bash
uv run examples/hardware_advisor_agent.py
```

--------------------------------

### Run the Generated Todo Tracking App

Source: https://github.com/amd/gaia/blob/main/docs/playbooks/code-agent/part-1-introduction.mdx

Navigate to the generated app directory, install dependencies, set up the database, and start the development server. The app will be accessible at http://localhost:3000.

```bash
cd todo-tracking-app
npm install
npx prisma generate
npx prisma db push
npm run dev
```

--------------------------------

### Initialize GAIA with SD Profile

Source: https://github.com/amd/gaia/blob/main/docs/guides/sd.mdx

Install the necessary Lemonade Server and download the required models (SDXL-Turbo and Gemma-4-E4B-it-GGUF) for the Stable Diffusion agent. This is a one-time setup step.

```bash
gaia init --profile sd
```

--------------------------------

### Quick Start with Governance

Source: https://github.com/amd/gaia/blob/main/docs/sdk/sdks/governance.mdx

Demonstrates basic setup for an agent with governance enabled. When a governed tool like `wipe_disk` is called, governance intercepts it, issues a receipt, and denies the action.

```python
from gaia import Agent, tool
from gaia.governance import GaiaGovernanceAdapter, GovernedAgentMixin, govern


@tool
@govern(risk="blocked", reason="destructive")
def wipe_disk() -> dict:
    return {"status": "ok"}


class MyAgent(GovernedAgentMixin, Agent):
    ...


agent = MyAgent(governance_adapter=GaiaGovernanceAdapter.default())
```

--------------------------------

### Install Agent from PyPI

Source: https://github.com/amd/gaia/blob/main/docs/guides/hub-publishing.mdx

Install your published agent using pip, simulating how a user would install it.

```bash
pip install gaia-agent-my-agent
```

--------------------------------

### Refactoring CLI Install Logic for Desktop Installer

Source: https://github.com/amd/gaia/blob/main/docs/plans/desktop-installer.mdx

Illustrates the proposed refactoring of the installation logic. The goal is to consolidate the install logic into a single shared module (`services/backend-installer.cjs`) that can be called by both the npm CLI (`bin/gaia-ui.cjs`) and the Electron main process (`main.cjs`). This ensures a single source of truth for installation.

```text
Before:
  bin/gaia-ui.mjs ─┐
                   │  (separate, divergent install logic — only npm path works)
  main.cjs ────────┤  ← broken: no install logic at all
                   │
                   └─→ ~/.gaia/venv/

After:
  bin/gaia-ui.cjs ─┐
                   ├─→ services/backend-installer.cjs ─→ ~/.gaia/venv/
  main.cjs ────────┘   (single source of truth, both call it)
```

--------------------------------

### Install GAIA AI

Source: https://github.com/amd/gaia/blob/main/docs/presentations/agent-eval-benchmark.html

Install the GAIA AI package using pip. This is the first step to getting started with the evaluation benchmark.

```bash
# Install GAIA
$ pip install gaia-ai
```

--------------------------------

### Full Agent Configuration Example

Source: https://github.com/amd/gaia/blob/main/docs/sdk/core/agent-system.mdx

Demonstrates all available configuration parameters for initializing an agent, including LLM selection, local and cloud settings, and behavior tuning.

```python
agent = MyAgent(
    # === LLM Selection ===
    use_claude=False,              # Use Anthropic Claude API
    use_chatgpt=False,             # Use OpenAI ChatGPT API
    # If both are False, uses local Lemonade Server

    # === Local LLM Settings ===
    base_url="http://localhost:13305/api/v1",  # Lemonade server URL
    model_id="Qwen3.5-35B-A3B-GGUF",  # Model to use

    # === Cloud LLM Settings ===
    claude_model="claude-sonnet-4-20250514",  # Claude model version
    # API keys are read from environment: ANTHROPIC_API_KEY, OPENAI_API_KEY

    # === Agent Behavior ===
    max_steps=20,                  # Max reasoning loop iterations
    streaming=True,                # Stream responses token-by-token
    silent_mode=False,             # Suppress console output

    # === Debugging ===
    debug_prompts=False,           # Print raw prompts to console
    show_prompts=False,            # Show prompts in output
)
```

--------------------------------

### Build Frontend (First Time Only)

Source: https://github.com/amd/gaia/blob/main/docs/guides/emr.mdx

For source installations, build the frontend by navigating to the frontend directory, installing dependencies, and running the build command. Ensure you return to the repository root afterward.

```bash
cd hub/agents/python/emr/gaia_agent_emr/dashboard/frontend
```

```bash
npm install
```

```bash
npm run build
```

```bash
cd ../../../../../..
```

--------------------------------

### Install and Run n8n Locally (npx)

Source: https://github.com/amd/gaia/blob/main/docs/integrations/n8n.mdx

Use npx to run n8n without a global installation. This is a quick way to get started.

```bash
npx n8n
```

--------------------------------

### Run the Application

Source: https://github.com/amd/gaia/blob/main/docs/playbooks/code-agent/part-3-validation-building.mdx

Navigate to the application directory and start the development server.

```bash
cd movie-tracking-app
npm run dev
```

--------------------------------

### Install GAIA Framework via Pip

Source: https://github.com/amd/gaia/blob/main/README.md

Install the amd-gaia Python package using pip. This is the quickest way to get started with the GAIA framework for Python development.

```bash
pip install amd-gaia
```

--------------------------------

### Developer Quick Start: Start Servers and Open UI

Source: https://github.com/amd/gaia/blob/main/docs/deployment/ui.mdx

Steps to launch the Lemonade Server and the Agent UI backend for local development. Access the UI at the specified URL.

```bash
# 1. Start Lemonade Server
lemonade-server serve

# 2. Start Agent UI backend
python -m gaia.ui.server

# 3. Open http://127.0.0.1:4200 in your browser
```

--------------------------------

### Start the LLM server manually

Source: https://github.com/amd/gaia/blob/main/docs/guides/agent-ui.mdx

Start the Lemonade LLM server manually after initializing GAIA with a profile. This command is part of the manual backend setup for the Python CLI installation path.

```bash
lemonade-server serve       # Start the LLM server
```

--------------------------------

### Initialize GAIA with Minimal Setup

Source: https://github.com/amd/gaia/blob/main/docs/reference/cli.mdx

This command provides a fast setup by initializing GAIA with only the minimal required profile.

```bash
gaia init --minimal
```

--------------------------------

### Example Lemonade Install Error

Source: https://github.com/amd/gaia/blob/main/docs/reference/troubleshooting.mdx

This is an example of a 404 Not Found error that may occur during dependency installation on Linux if the apt package cache is not updated.

```text
E: Failed to fetch http://archive.ubuntu.com/ubuntu/pool/... 404 Not Found
E: Unable to fetch some archives, maybe run apt-get update or try with --fix-missing?
```

--------------------------------

### Run day-zero onboarding

Source: https://github.com/amd/gaia/blob/main/docs/reference/cli.mdx

Initiates the agent's initial memory setup. This can be configured to include conversational onboarding, system discovery scans, or a reset of discovered items.

```bash
gaia memory bootstrap [OPTIONS]
```

```bash
gaia memory bootstrap
```

```bash
gaia memory bootstrap --chat-only
```

```bash
gaia memory bootstrap --discover
```

```bash
gaia memory bootstrap --reset
```

--------------------------------

### Install and Run n8n Locally (Global)

Source: https://github.com/amd/gaia/blob/main/docs/integrations/n8n.mdx

Install n8n globally using npm for persistent access. After installation, start the n8n service.

```bash
npm install -g n8n
n8n start
```

--------------------------------

### Get Installed Software

Source: https://github.com/amd/gaia/blob/main/docs/cpp/health-agent.mdx

Queries the registry to list installed software, typically the top 20 by size or install date. Use this to manage disk space.

```powershell
Registry query
```

--------------------------------

### Start Agent UI Backend

Source: https://github.com/amd/gaia/blob/main/docs/guides/mcp/agent-ui.mdx

Use the startup script for Linux/macOS or Windows PowerShell. Alternatively, run manually with `uv run`. Verify the backend is running by checking its health endpoint.

```bash
# Option 1: Using the startup script (recommended)
# Linux/macOS
./installer/scripts/start-agent-ui.sh

# Windows PowerShell
.\installer\scripts\start-agent-ui.ps1
```

```bash
# Option 2: Manual
uv run python -m gaia.ui.server --debug
```

```bash
curl http://localhost:4200/api/health
```

--------------------------------

### Verify Claude Code CLI Installation

Source: https://github.com/amd/gaia/blob/main/docs/guides/eval.mdx

Check if the Claude Code CLI is installed by running the version command. Refer to the Claude Code installation guide if it's not found.

```bash
claude --version
```

--------------------------------

### Get Windows Update History

Source: https://github.com/amd/gaia/blob/main/docs/cpp/health-agent.mdx

Lists recently installed Windows hotfixes with their installation dates. Useful for tracking system updates.

```powershell
Get-HotFix
```

--------------------------------

### Run Complete SD Agent Example

Source: https://github.com/amd/gaia/blob/main/docs/playbooks/sd-agent/index.mdx

Use this command to run the complete example script provided in the GAIA repository.

```bash
python examples/sd_agent_example.py
```

--------------------------------

### Install and Run whatsapp-web.js Prototype

Source: https://github.com/amd/gaia/blob/main/docs/spikes/whatsapp-webjs.md

Steps to set up and execute the whatsapp-web.js prototype. Ensure Node.js (16+) is installed. This script will print a QR code to the terminal for authentication.

```bash
cd experiments/whatsapp-webjs
npm install
node index.js
```

--------------------------------

### Install Chat Agent for Development

Source: https://github.com/amd/gaia/blob/main/docs/playbooks/chat-agent/part-1-getting-started.mdx

Install the Chat Agent in editable mode from a cloned repository. Use this for development or to access project examples.

```bash
git clone https://github.com/amd/gaia.git
cd gaia
uv venv .venv
source .venv/bin/activate  # On Windows: .\.venv\Scripts\Activate.ps1
uv pip install -e ".[rag]"
```

--------------------------------

### Start the Server

Source: https://github.com/amd/gaia/blob/main/docs/sdk/sdks/agent-ui.mdx

Demonstrates how to create and run the FastAPI server for the Agent UI, with options for default, custom, or in-memory database paths.

```APIDOC
## Start the Server

### Description
Create and run the FastAPI server for the Agent UI. Supports default, custom, or in-memory database paths.

### Usage

**Create App Instances:**
```python
from gaia.ui.server import create_app

# Create with default database (~/.gaia/chat/gaia_chat.db)
app = create_app()

# Create with custom database path
app = create_app(db_path="/path/to/my/chat.db")

# Create with in-memory database (for testing)
app = create_app(db_path=":memory:")
```

**Run with uvicorn:**
```python
import uvicorn
from gaia.ui.server import create_app

app = create_app()
uvicorn.run(app, host="localhost", port=4200)
```

**Run from command line:**
```bash
python -m gaia.ui.server --port 4200
```
```

--------------------------------

### Linux Runtime Usage Example

Source: https://github.com/amd/gaia/blob/main/docs/plans/docker-containers.mdx

Example commands for creating and connecting to the Linux GAIA Docker container, and running GAIA commands.

```bash
# Create container
docker run -dit \
  --name gaia \
  -p 13305:13305 \
  -e LEMONADE_BASE_URL=<lemonade-url> \
  amd/gaia:linux

# Connect and use GAIA
docker exec -it gaia zsh
gaia llm "Hello from Docker!"
gaia chat
```

--------------------------------

### Start Vite Dev Server

Source: https://github.com/amd/gaia/blob/main/docs/playbooks/emr-agent/part-2-dashboard.mdx

Navigate to the frontend directory, install dependencies, and start the Vite development server for hot reloading. This is used for frontend development.

```bash
cd hub/agents/python/emr/gaia_agent_emr/dashboard/frontend
npm install
npm run dev
```

--------------------------------

### Windows Runtime Usage Example

Source: https://github.com/amd/gaia/blob/main/docs/plans/docker-containers.mdx

Example commands for creating and connecting to the Windows GAIA Docker container, and running GAIA commands.

```powershell
# Create container
docker run -dit `
  --name gaia `
  -p 13305:13305 `
  -e LEMONADE_BASE_URL=<lemonade-url> `
  amd/gaia:windows

# Connect and use GAIA
docker exec -it gaia powershell
gaia llm "Hello from Windows Docker!"
gaia chat
```

--------------------------------

### Copy Example Agent Python Scripts

Source: https://github.com/amd/gaia/blob/main/docs/releases/v0.17.3.mdx

Use these commands to copy the provided example agent Python scripts to your working directory. These can serve as starting points for developing your own agents.

```bash
cp examples/weather_agent.py
cp examples/rag_doc_agent.py
cp examples/product_mockup_agent.py
```

--------------------------------

### MCP Tool: search_docs Example Usage

Source: https://github.com/amd/gaia/blob/main/docs/plans/mcp-docs.mdx

Demonstrates an example input and output for the 'search_docs' tool. This shows how to query for information and the expected format of the search results.

```json
Input: {"query": "how to add tools to an agent", "limit": 3}

Output: [
  {"title": "Tool Decorator", "path": "/sdk/core/tools", "snippet": "Use @tool decorator..."},
  {"title": "Agent System", "path": "/sdk/core/agent-system", "snippet": "_register_tools() method..."},
  {"title": "Quickstart", "path": "/quickstart", "snippet": "Define tools inside your agent..."}
]
```

--------------------------------

### Login and Dual-Publish Agent

Source: https://github.com/amd/gaia/blob/main/docs/reference/cli.mdx

This example first prompts the user to enter tokens for both the Hub and PyPI, then publishes the agent. Ensure the agent is located in hub/agents/python/summarize/.

```bash
gaia agent login --hub --pypi          # prompts for each token
```

```bash
gaia agent publish hub/agents/python/summarize/
```

--------------------------------

### Start GAIA Agent UI from Python CLI

Source: https://github.com/amd/gaia/blob/main/docs/guides/agent-ui.mdx

Launch the GAIA Agent UI when GAIA is already installed via pip or uv. This command starts the UI on the default address http://127.0.0.1:4200.

```bash
gaia --ui
```

--------------------------------

### Build AgentUI Frontend and Start AgentUI

Source: https://github.com/amd/gaia/blob/main/docs/local-test/README.md

Build the AgentUI frontend to reflect the current branch and then start the AgentUI application.

```bash
# 3. Build the AgentUI frontend so the Settings page reflects this branch.
cd src/gaia/apps/webui && npm install && npm run build && cd -

# 4. Start the AgentUI.
gaia chat --ui
```

--------------------------------

### Complete GAIA Tool Example

Source: https://github.com/amd/gaia/blob/main/docs/sdk/core/tools.mdx

An example of a Python tool function that collects system statistics and returns them in the GAIA standard response format. The 'instruction' field guides the LLM on how to present the data to the user.

```python
@tool
def get_system_stats() -> dict:
    """Get current system statistics.

    Args:
        None

    Use this tool when the user asks about system health,
    performance, or resource usage.
    """
    stats = collect_system_stats()

    return {
        "status": "success",
        "message": "Retrieved system statistics",
        "data": {
            "cpu_percent": stats.cpu,
            "memory_gb_used": stats.memory_used,
            "memory_gb_total": stats.memory_total,
            "disk_free_gb": stats.disk_free
        },
        "instruction": (
            "Summarize these statistics in a human-readable format. "
            "Your answer must be a plain text string, not a JSON object."
        )
    }
```

--------------------------------

### Make AppImage executable and run

Source: https://github.com/amd/gaia/blob/main/docs/deployment/ui.mdx

Make the downloaded AppImage file executable and then run it. This is for portable installs or distros without apt.

```bash
chmod +x gaia-agent-ui-*.AppImage
./gaia-agent-ui-*.AppImage
```

--------------------------------

### Power Automate Outlook Setup Wizard

Source: https://github.com/amd/gaia/blob/main/docs/plans/power-automate-outlook.md

This is a visual representation of the inline setup wizard presented in the Agent UI for connecting Outlook via Power Automate. It guides users through importing flow templates and pasting trigger URLs.

```text
┌─────────────────────────────────────────────────────┐
│  ⚡ Outlook via Power Automate                      │
│                                                     │
│  Access your Outlook inbox and calendar through     │
│  Power Automate. No Azure AD app registration       │
│  required.                                          │
│                                                     │
│  ┌─── Step 1: Import Flow Templates ─────────────┐  │
│  │                                                │  │
│  │  Download these 4 flow templates and import    │  │
│  │  them at flow.microsoft.com:                   │  │
│  │                                                │  │
│  │  📥 gaia-inbox.zip      (list emails)          │  │
│  │  📥 gaia-read-email.zip (read single email)    │  │
│  │  📥 gaia-send-draft.zip (send email)           │  │
│  │  📥 gaia-calendar.zip   (calendar events)      │  │
│  │                                                │  │
│  │  [Open Power Automate ↗]  [Download All ↓]    │  │
│  └────────────────────────────────────────────────┘  │
│                                                     │
│  ┌─── Step 2: Paste Trigger URLs ────────────────┐  │
│  │                                                │  │
│  │  Inbox Flow URL *                              │  │
│  │  ┌──────────────────────────────────────────┐  │  │
│  │  │ https://prod-XX.logic.azure.com/...      │  │  │
│  │  └──────────────────────────────────────────┘  │  │
│  │                                                │  │
│  │  Read Email Flow URL                           │  │
│  │  ┌──────────────────────────────────────────┐  │  │
│  │  │ (optional)                               │  │  │
│  │  └──────────────────────────────────────────┘  │  │
│  │                                                │  │
│  │  Send Draft Flow URL                           │  │
│  │  ┌──────────────────────────────────────────┐  │  │
│  │  │ (optional)                               │  │  │
│  │  └──────────────────────────────────────────┘  │  │
│  │                                                │  │
│  │  Calendar Flow URL                             │  │
│  │  ┌──────────────────────────────────────────┐  │  │
│  │  │ (optional)                               │  │  │
│  │  └──────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────┘  │
│                                                     │
│  [Test Connection]                     [Save]       │
│                                                     │
│  ┌─── Per-Agent Grants ──────────────────────────┐  │
│  │  Email Triage Agent          [●] email.read   │  │
│  │                              [ ] email.send   │  │
│  │                              [●] calendar.read│  │
│  └────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
```

--------------------------------

### Initialize GAIA with Speed Display

Source: https://github.com/amd/gaia/blob/main/docs/releases/v0.15.2.mdx

Use this command for a quick setup that displays download speeds. It downloads all required models directly.

```bash
gaia init
```

--------------------------------

### SSE Event: Processing Started Payload

Source: https://github.com/amd/gaia/blob/main/docs/playbooks/emr-agent/part-2-dashboard.mdx

Example payload for the 'processing_started' SSE event, indicating a file has been detected and processing has begun.

```json
{
  "type": "processing_started",
  "data": {"filename": "patient_form.jpg"},
  "timestamp": "2025-01-15T10:30:00Z"
}
```

--------------------------------

### Complete GAIA Code Example: Prompt to Working App

Source: https://github.com/amd/gaia/blob/main/docs/playbooks/code-agent/part-3-validation-building.mdx

Demonstrates the full cycle of using GAIA Code, from initial prompt to a running Next.js application. Includes generation, running the app, and basic usage verification.

```bash
# 1. Generate
gaia-code "Build me a workout tracking app in nextjs where I can track workout, duration, date, and goal"

# 2. Run
cd workout-tracking-app
npm run dev

# 3. Use
# Opens at http://localhost:3000
# ✓ Create workouts
# ✓ View workout list
# ✓ Edit workouts
# ✓ Delete workouts
```

--------------------------------

### Run All Blender Examples

Source: https://github.com/amd/gaia/blob/main/docs/reference/features.mdx

Execute all predefined examples for the Blender agent. This command is for testing and demonstration purposes.

```bash
gaia blender
```

--------------------------------

### Search Assigned Issues

Source: https://github.com/amd/gaia/blob/main/docs/guides/jira.mdx

Use these commands to find issues assigned to you. No specific setup is required beyond having the gaia CLI installed.

```bash
gaia jira "show my issues"
```

```bash
gaia jira "what am I working on"
```

--------------------------------

### Initialize GAIA with Remote Lemonade Server

Source: https://github.com/amd/gaia/blob/main/docs/reference/cli.mdx

This command initializes GAIA to use a remote Lemonade Server, skipping local installation and starting.

```bash
gaia init --remote
```

--------------------------------

### Running an MCP Client Agent Example

Source: https://github.com/amd/gaia/blob/main/docs/guides/mcp/client.mdx

Command to launch an example GAIA agent that acts as an MCP client. This connects to MCP servers and allows for interactive tool usage.

```bash
uv run examples/mcp_config_based_agent.py
```

--------------------------------

### Scenario YAML Format Example

Source: https://github.com/amd/gaia/blob/main/docs/presentations/agent-eval-benchmark.html

Defines a multi-turn conversation scenario for evaluating context retention, including setup documents and ground truth.

```yaml
id: cross_turn_file_recall
category: context_retention
persona: data_analyst

setup:
  index_documents:
    - path: eval/corpus/docs/report.html

turns:
  - turn: 1
    objective: Index document
    user_message: "Read report.html"
    success_criteria: "Agent reads file"

  - turn: 2
    objective: Ask about content
    user_message: "What was the Q3 revenue?"
    ground_truth:
      facts: ["$4.2M"]
      source_files: ["report.html"]
```

--------------------------------

### SimpleChat

Source: https://github.com/amd/gaia/blob/main/docs/sdk/sdks/chat.mdx

A lightweight wrapper for basic chat without complex configuration. It's perfect for getting started quickly with simple ask-response interactions.

```APIDOC
## SimpleChat

Lightweight wrapper for basic chat without complex configuration. Perfect for getting started quickly.

```python
from gaia.chat.sdk import SimpleChat

chat = SimpleChat()
response = chat.ask("What is Python?")
print(response)

# Follow-up with conversation memory
response = chat.ask("Give me an example")
print(response)
```
```

--------------------------------

### Quick Start: Web Search and Summarization

Source: https://github.com/amd/gaia/blob/main/docs/guides/browse.mdx

Initiates a web search and summarizes relevant links using the browse command.

```bash
gaia browse -q "Find recent AMD Ryzen AI SDK docs and summarize the relevant links"
```

--------------------------------

### Nginx Reverse Proxy Configuration for GAIA

Source: https://github.com/amd/gaia/blob/main/docs/integrations/n8n.mdx

Example Nginx configuration for a production setup, including SSL, API key authentication, and proxy settings.

```nginx
server {
    listen 443 ssl;
    server_name gaia-mcp.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8765;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;

        # API Key validation
        if ($http_x_api_key != "your-secret-key") {
            return 403;
        }
    }
}
```

--------------------------------

### Basic SD Command Usage Examples

Source: https://github.com/amd/gaia/blob/main/docs/guides/sd.mdx

Demonstrates various ways to use the 'gaia sd' command, including generating only an image, generating an image with a story, creating multiple images, and analyzing an existing image file.

```bash
# Just an image (no story)\ngaia sd "robot kitten"
```

```bash
# Image with story (automatic)\ngaia sd "create a cute robot kitten and tell me a short story about it"
```

```bash
# Multiple images\ngaia sd "create 3 robot kittens"
```

```bash
# Analyze existing image\ngaia sd "tell me about .gaia/cache/sd/images/robot.png"
```

--------------------------------

### Enable Memory via API

Source: https://github.com/amd/gaia/blob/main/docs/guides/memory.mdx

Use this command to enable memory for headless or scripted setups. Verify the setting by making a GET request to the same endpoint.

```bash
curl -X PUT http://localhost:4200/api/memory/settings \
  -H "Content-Type: application/json" \
  -H "X-Gaia-UI: 1" \
  -d '{"memory_enabled": true}'
```

```bash
curl http://localhost:4200/api/memory/settings
# → {"memory_enabled": true, ...}
```

--------------------------------

### Start n8n Locally

Source: https://github.com/amd/gaia/blob/main/docs/integrations/n8n.mdx

Install and run n8n on your local machine to enable it to access your local MCP bridge. This is the recommended option for browser-based n8n instances.

```bash
npm install -g n8n
n8n start
# Opens at http://localhost:5678
# Now it can access your local MCP bridge
```

--------------------------------

### Start Agent UI Backend

Source: https://github.com/amd/gaia/blob/main/docs/guides/mcp/agent-ui.mdx

Start the Agent UI backend server using the provided command. Ensure this is running before attempting to use the MCP server.

```bash
uv run python -m gaia.ui.server
```