From 3f7d1bd845d039731912b1ea0442450b16e0085f Mon Sep 17 00:00:00 2001 From: Kalin Ovtcharov Date: Thu, 25 Jun 2026 14:05:30 -0700 Subject: [PATCH] docs(guides): reorganize nav, fill stub guides, trim bloated ones MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reorganize the flat User Guides nav into seven logical sub-groups ordered easiest→advanced (Setup & Hardware → Core Agents → Developer Tools → Connected Agents → Specialized Agents → Build & Extend → MCP Integration), so readers can find the right agent instead of scanning a 22-item list. Fill the thin stubs to the quality bar of chat/code: telegram-adapter goes from a 17-line placeholder to a full guide (install extra, BotFather token, start/stop/status, allow-list, background daemon, per-user sessions); browse and analyze gain prerequisites and next-steps cross-links. Every command and flag verified against src/gaia/cli.py and the agent source. Trim the three most bloated guides — jira 760→388, memory 781→523, emr 695→464 — by cutting duplicate examples, padded best-practices, and copy-pasted test harnesses while preserving all accurate, load-bearing content. Fixed several stale commands/paths found against source along the way. Add missing icon frontmatter (analyze, browse, email, npu, telegram) and missing description frontmatter (blender, docker, jira, routing, telegram); every guide now carries a consistent title/description/icon triple. Rebuild the guides landing page to mirror the new groups and include all agents. Internal link check passes (Broken: 0). --- docs/docs.json | 77 ++-- docs/guides/analyze.mdx | 71 +++- docs/guides/blender.mdx | 1 + docs/guides/browse.mdx | 66 +++- docs/guides/docker.mdx | 1 + docs/guides/email.mdx | 1 + docs/guides/emr.mdx | 287 ++------------- docs/guides/index.mdx | 111 +++++- docs/guides/jira.mdx | 612 ++++++------------------------- docs/guides/memory.mdx | 341 +++-------------- docs/guides/npu.mdx | 1 + docs/guides/routing.mdx | 1 + docs/guides/telegram-adapter.mdx | 137 ++++++- 13 files changed, 599 insertions(+), 1108 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 5397cf0a5..e18862c5e 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -74,27 +74,62 @@ "group": "User Guides", "pages": [ "guides/index", - "guides/hardware-advisor", - "guides/npu", - "guides/chat", - "guides/browse", - "guides/analyze", - "guides/talk", - "guides/code", - "guides/telegram-adapter", - "guides/code-index", - "guides/sd", - "guides/emr", - "guides/blender", - "guides/jira", - "guides/email", - "guides/docker", - "guides/routing", - "guides/custom-agent", - "guides/hub-publishing", - "guides/mcp/agent-ui", - "guides/mcp/client", - "guides/mcp/windows-system-health" + { + "group": "Setup & Hardware", + "pages": [ + "guides/hardware-advisor", + "guides/npu" + ] + }, + { + "group": "Core Agents", + "pages": [ + "guides/chat", + "guides/talk", + "guides/browse", + "guides/analyze" + ] + }, + { + "group": "Developer Tools", + "pages": [ + "guides/code", + "guides/code-index", + "guides/docker" + ] + }, + { + "group": "Connected Agents", + "pages": [ + "guides/email", + "guides/telegram-adapter", + "guides/jira" + ] + }, + { + "group": "Specialized Agents", + "pages": [ + "guides/sd", + "guides/blender", + "guides/emr", + "guides/routing" + ] + }, + { + "group": "Build & Extend", + "pages": [ + "guides/custom-agent", + "guides/hub-publishing" + ] + }, + { + "group": "MCP Integration", + "pages": [ + "guides/mcp/agent-ui", + "guides/mcp/client", + "guides/mcp/windows-system-health" + ] + } ] }, { diff --git a/docs/guides/analyze.mdx b/docs/guides/analyze.mdx index fc6517e7a..9c08d5968 100644 --- a/docs/guides/analyze.mdx +++ b/docs/guides/analyze.mdx @@ -1,13 +1,25 @@ --- title: "Analyst Agent" description: "Load structured rows into scratchpad tables and query them with a focused GAIA agent." +icon: "chart-column" --- -# Analyst Agent + + **First time here?** Complete the [Setup](/setup) guide first to install GAIA and its dependencies. + -The Analyst Agent is a focused structured-data agent for users who want scratchpad table tools without the full Chat Agent tool surface. It is useful for CSV-style rows, extracted records, and calculations that should be performed by SQL instead of mental arithmetic. +The Analyst Agent is a focused structured-data agent for users who want scratchpad table tools without the full Chat Agent tool surface. It's useful for CSV-style rows, extracted records, and calculations that should be performed by SQL instead of mental arithmetic. -## Quick start +**Who it's for:** anyone who has rows of data and wants the model to compute over them reliably — totals, group-bys, filters — by writing SQL against an in-memory scratchpad table rather than guessing at numbers. + +## Prerequisites + +- GAIA installed (see [Setup](/setup)). +- A local model available — run `gaia init` if you haven't set one up. By default the agent uses the local Lemonade backend. + +## Quick Start + +Run a single analysis task with `-q`: ```bash gaia analyze -q "Create a sales table, insert these rows, and calculate revenue by region" @@ -19,25 +31,62 @@ Use interactive mode when you want to build up tables and ask follow-up question gaia analyze ``` -## Tool surface +## Tool Surface `gaia analyze --list-tools` shows the exact tools available in your installed version. The focused Analyst Agent exposes: -- `create_table` for creating scratchpad tables. -- `insert_data` for loading structured rows. -- `query_data` for SQL calculations and filtering. -- `list_tables` for inspecting available tables. -- `drop_table` for removing scratchpad tables. +- `create_table` — create a scratchpad SQL table. +- `insert_data` — load structured rows. +- `query_data` — run SQL calculations and filtering. +- `list_tables` — inspect available tables. +- `drop_table` — remove a scratchpad table. -The Analyst Agent does not register browser tools. Use `gaia browse` for web research, or `gaia chat` when you need the broader mixed tool set. +The Analyst Agent does not register browser tools. Use [`gaia browse`](/guides/browse) for web research, or [`gaia chat`](/guides/chat) when you need the broader mixed tool set. -## Local model options +## Model and Backend Options By default, `gaia analyze` uses the local Lemonade backend configured for GAIA. You can override the model or backend with the common agent flags: ```bash +# Use a smaller local model for lighter tasks gaia analyze --model Qwen3-4B-Instruct-2507-GGUF -q "Summarize this table" + +# Run against the Claude API instead of local inference gaia analyze --use-claude -q "Normalize these rows and calculate totals" ``` +Other shared agent flags work here too — `--max-steps` to bound the run, `--trace` to save a JSON execution trace, and `--stats` for performance metrics. + In the Agent UI the analyst appears as a single `data` card with a model-size selector — pick **Lite (~4B)** for shorter analysis tasks on lighter hardware, or **Full** for the default model. (The old `data-lite` registry ID still resolves to `data` on the lite tier for existing sessions.) + +## Next Steps + + + + Search the web, fetch pages, and download files. + + + + The full chat agent with RAG, memory, and the broader tool set. + + + + Every `gaia` command and flag. + + + + Browse every GAIA agent. + + + +--- + + + +**License** + +Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved. + +SPDX-License-Identifier: MIT + + diff --git a/docs/guides/blender.mdx b/docs/guides/blender.mdx index 2d78e2a4a..aab167680 100644 --- a/docs/guides/blender.mdx +++ b/docs/guides/blender.mdx @@ -1,5 +1,6 @@ --- title: "Blender Agent" +description: "Create and modify 3D scenes in Blender through natural-language commands." icon: "cube" --- diff --git a/docs/guides/browse.mdx b/docs/guides/browse.mdx index 16a3875ce..531d0df5a 100644 --- a/docs/guides/browse.mdx +++ b/docs/guides/browse.mdx @@ -1,13 +1,26 @@ --- title: "Browser Agent" description: "Search the web, fetch pages, and download files with a focused GAIA agent." +icon: "globe" --- -# Browser Agent + + **First time here?** Complete the [Setup](/setup) guide first to install GAIA and its dependencies. + The Browser Agent is a focused web-research agent for users who want GAIA's browser tools without the full Chat Agent tool surface. It can search the web, fetch readable page text, and download files through the same path validation and web-client limits used by the broader agent stack. -## Quick start +**Who it's for:** anyone doing quick, repeatable web research from the CLI — gathering links on a topic, pulling the readable text out of a page, or grabbing a file — without loading RAG, scratchpad, or file-editing tools. + +## Prerequisites + +- GAIA installed (see [Setup](/setup)). +- A local model available — run `gaia init` if you haven't set one up. By default the agent uses the local Lemonade backend. +- Network access for web search and page fetches. + +## Quick Start + +Run a single research task with `-q`: ```bash gaia browse -q "Find recent AMD Ryzen AI SDK docs and summarize the relevant links" @@ -19,23 +32,60 @@ Use interactive mode when you want to refine a web-research task over multiple t gaia browse ``` -## Tool surface +## Tool Surface `gaia browse --list-tools` shows the exact tools available in your installed version. The focused Browser Agent exposes: -- `search_web` for web search. -- `fetch_page` for extracting readable page text. -- `download_file` for saving a user-requested URL locally. +- `search_web` — run a web search for a query. +- `fetch_page` — fetch a URL and return readable page text. +- `download_file` — download a user-requested URL to a local file. -The Browser Agent does not register scratchpad or file-system analysis tools. Use `gaia analyze` for structured data work, or `gaia chat` when you need the broader mixed tool set. +The Browser Agent does not register scratchpad or file-system analysis tools. Use [`gaia analyze`](/guides/analyze) for structured data work, or [`gaia chat`](/guides/chat) when you need the broader mixed tool set. -## Local model options +## Model and Backend Options By default, `gaia browse` uses the local Lemonade backend configured for GAIA. You can override the model or backend with the common agent flags: ```bash +# Use a smaller local model for lighter tasks gaia browse --model Qwen3-4B-Instruct-2507-GGUF -q "Fetch this page and list citations" + +# Run against the Claude API instead of local inference gaia browse --use-claude -q "Compare these two URLs" ``` +Other shared agent flags work here too — `--max-steps` to bound the run, `--trace` to save a JSON execution trace, `--stats` for performance metrics, and `--allowed-paths` to control where downloads may be written. + In the Agent UI the browser appears as a single `web` card with a model-size selector — pick **Lite (~4B)** for shorter browser tasks on lighter hardware, or **Full** for the default model. (The old `web-lite` registry ID still resolves to `web` on the lite tier for existing sessions.) + +## Next Steps + + + + Load structured rows into scratchpad tables and query them with SQL. + + + + The full chat agent with RAG, memory, and the broader tool set. + + + + Every `gaia` command and flag. + + + + Browse every GAIA agent. + + + +--- + + + +**License** + +Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved. + +SPDX-License-Identifier: MIT + + diff --git a/docs/guides/docker.mdx b/docs/guides/docker.mdx index d8d6f2bb6..07b11cda6 100644 --- a/docs/guides/docker.mdx +++ b/docs/guides/docker.mdx @@ -1,5 +1,6 @@ --- title: "Docker Agent" +description: "Containerize applications with natural-language commands — no Docker expertise required." icon: "docker" --- diff --git a/docs/guides/email.mdx b/docs/guides/email.mdx index 7d58175fe..bb82a389b 100644 --- a/docs/guides/email.mdx +++ b/docs/guides/email.mdx @@ -1,6 +1,7 @@ --- title: "Email Triage" description: "Read, organize, and reply to Gmail with all email content processed locally on your machine." +icon: "envelope" --- # Email Triage Agent diff --git a/docs/guides/emr.mdx b/docs/guides/emr.mdx index 738b0cfef..6688fda60 100644 --- a/docs/guides/emr.mdx +++ b/docs/guides/emr.mdx @@ -78,206 +78,48 @@ The EMR agent uses three models, downloaded automatically on first run via `gaia ## Prerequisites +Complete the [Setup](/setup) guide first to install Lemonade Server and `uv`. Then install GAIA with the EMR extras in a Python 3.12 virtual environment. + - Installs [amd-gaia](https://pypi.org/project/amd-gaia/) from PyPI. **Recommended** for most users on **Windows**. - - ### Step 1: Create Project Directory - - Open **PowerShell** and run: - ```powershell - mkdir my-emr-project - ``` - ```powershell - cd my-emr-project - ``` - - ### Step 2: Create Virtual Environment - ```powershell uv venv .venv --python 3.12 - ``` - - uv will automatically download Python 3.12 if not already installed. - - ### Step 3: Activate the Environment - - ```powershell .\.venv\Scripts\Activate.ps1 + uv pip install "amd-gaia[api,rag]" + gaia-emr --help ``` - If you see a script execution error, run this once: - ```powershell - Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser - ``` - Then retry the activation command. + If activation fails with a script execution error, run once: + `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`, then retry. - - You should see `(.venv)` in your terminal prompt when activated. - - ### Step 4: Install GAIA with EMR Dependencies - - ```powershell - uv pip install "amd-gaia[api,rag]" - ``` - - ### Step 5: Verify Installation - - ```powershell - gaia-emr --help - ``` - Installs [amd-gaia](https://pypi.org/project/amd-gaia/) from PyPI. **Recommended** for most users on **Linux**. - - ### Step 1: Create Project Directory - - Open a **terminal** and run: - ```bash - mkdir my-emr-project - ``` - ```bash - cd my-emr-project - ``` - - ### Step 2: Create Virtual Environment - ```bash uv venv .venv --python 3.12 - ``` - - uv will automatically download Python 3.12 if not already installed. - - ### Step 3: Activate the Environment - - ```bash source .venv/bin/activate - ``` - - You should see `(.venv)` in your terminal prompt when activated. - - ### Step 4: Install GAIA with EMR Dependencies - - ```bash uv pip install "amd-gaia[api,rag]" - ``` - - ### Step 5: Verify Installation - - ```bash gaia-emr --help ``` - - For contributors. Clones [amd/gaia](https://github.com/amd/gaia) from GitHub. + + For contributors. Clone the repo and install in editable mode (changes take effect without reinstalling): - - **Requires:** [Git for Windows](https://git-scm.com/download/win) must be installed. - - - ### Step 1: Clone the Repository - - Open **PowerShell** and run: - ```powershell - git clone https://github.com/amd/gaia.git - ``` - ```powershell - cd gaia - ``` - - ### Step 2: Create Virtual Environment - - ```powershell - uv venv .venv --python 3.12 - ``` - - ### Step 3: Activate the Environment - - ```powershell - .\.venv\Scripts\Activate.ps1 - ``` - - - If you see a script execution error, run this once: - ```powershell - Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser - ``` - Then retry the activation command. - - - You should see `(.venv)` in your prompt when activated. - - ### Step 4: Install in Editable Mode - - ```powershell - uv pip install -e ".[dev,api,rag]" - ``` - - ### Step 5: Verify Installation - - ```powershell - gaia-emr --help - ``` - - - Changes to GAIA source code will take effect immediately without reinstalling. - - - - - For contributors. Clones [amd/gaia](https://github.com/amd/gaia) from GitHub. - - - **Requires:** Git must be installed (`sudo apt install git`). - - - ### Step 1: Clone the Repository - - Open a **terminal** and run: ```bash git clone https://github.com/amd/gaia.git - ``` - ```bash cd gaia - ``` - - ### Step 2: Create Virtual Environment - - ```bash uv venv .venv --python 3.12 - ``` - - ### Step 3: Activate the Environment - - ```bash - source .venv/bin/activate - ``` - - You should see `(.venv)` in your prompt when activated. - - ### Step 4: Install in Editable Mode - - ```bash + source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1 uv pip install -e ".[dev,api,rag]" - ``` - - ### Step 5: Verify Installation - - ```bash gaia-emr --help ``` - - - Changes to GAIA source code will take effect immediately without reinstalling. - - The `api` extra provides FastAPI and uvicorn for the web dashboard. The `rag` extra provides PyMuPDF for PDF processing. + The `api` extra provides FastAPI and uvicorn for the web dashboard; the `rag` extra provides PyMuPDF for PDF processing. `uv` downloads Python 3.12 automatically if it isn't already installed. @@ -288,10 +130,6 @@ The EMR agent uses three models, downloaded automatically on first run via `gaia ## Quick Start - - **First time here?** Complete the [Setup](/setup) guide first to install Lemonade Server and uv. - - ### Step 1: Initialize (First Time Only) Download and load all required models before first use: @@ -546,59 +384,30 @@ The agent accepts scanned or photographed intake forms in these formats: ## Under the Hood -### Image Preprocessing Pipeline - -Before reaching the VLM, intake forms go through an optimization pipeline: - -1. **EXIF Orientation** - Auto-rotates images based on camera metadata (critical for phone photos) -2. **Resolution Scaling** - Resizes to max 1024px while preserving aspect ratio (balances quality vs. token count) -3. **JPEG Compression** - Reduces file size with quality=85 for faster transmission to the model -4. **Token Estimation** - Calculates expected image tokens to verify they fit within context window +- **Image preprocessing** — Before reaching the VLM, forms are auto-rotated from EXIF orientation (critical for phone photos), scaled to a max 1024px dimension, and JPEG-compressed (quality 85) to balance extraction quality against image token count. +- **Returning-patient detection** — A multi-signal lookup combines exact name + DOB match, fuzzy matching for misspellings ("Jon Smith" → "John Smith"), and `nomic-embed` vector similarity. When a returning patient is detected, changes from their previous record (new allergies, updated insurance) are highlighted. +- **Real-time dashboard** — The FastAPI backend streams processing events to the React frontend over Server-Sent Events (SSE), so the UI updates within ~100ms of file detection without polling or WebSockets. +- **Safe DB queries** — Natural language questions are answered via LLM tool calling: the model never writes SQL directly, it calls predefined, validated tools (e.g. `search_patients`) that construct queries safely. -### Returning Patient Detection - -The agent uses a multi-signal approach to identify returning patients: - -- **Exact Match** - Name + DOB combination lookup in SQLite -- **Fuzzy Match** - Levenshtein distance for misspellings ("Jon Smith" → "John Smith") -- **Embedding Similarity** - Vector search using nomic-embed for semantic matching - -When a returning patient is detected, the agent highlights any changes from their previous record (new allergies, updated insurance, etc.). +--- -### Real-Time Dashboard Architecture +## Troubleshooting -The dashboard uses **Server-Sent Events (SSE)** for real-time updates without polling: +### Context Size Too Small -- FastAPI backend streams processing events as they occur -- React frontend subscribes to `/api/events` endpoint -- Sub-100ms latency from file detection to UI update -- No WebSocket complexity—SSE is simpler and works through proxies +``` +Context size too small! Image requires 4203 tokens but model context is only 4096. +``` -### Tool Calling for Database Queries +Large form images can require 4,000–8,000+ tokens. Set Lemonade context size to **32768**: right-click the Lemonade tray icon → Settings → Context Size → 32768, then restart the model. -When you ask a natural language question, the LLM uses **function calling** (tool use) to interact with the database: +### Model Download Failed / Init Fails -```mermaid -%%{init: {'themeVariables': { 'fontSize': '18px' }}}%% -sequenceDiagram - participant User - participant LLM - participant Tool - participant DB - - User->>LLM: Query - LLM->>Tool: search_patients() - Tool->>DB: SQL query - DB-->>Tool: Results - Tool-->>LLM: Formatted - LLM-->>User: Response +``` +Download succeeded but failed to rename file: The process cannot access the file ``` -This pattern ensures the LLM never directly writes SQL—it calls predefined, validated tools that safely construct queries. - ---- - -## Troubleshooting +Run `gaia-emr init` again to resume. If it keeps failing, close any apps using the model files, delete the partial/corrupted model folder from Lemonade's cache (Windows: `%LOCALAPPDATA%\AMD\LemonadeModels\`, Linux: `~/.local/share/lemonade/models/`), restart Lemonade Server, then re-run `gaia-emr init`. ### PyMuPDF Required @@ -606,7 +415,7 @@ This pattern ensures the LLM never directly writes SQL—it calls predefined, va ERROR: PyMuPDF required for PDF processing ``` -**Solution**: `pip install "amd-gaia[rag]"` +Install the RAG extra: `pip install "amd-gaia[rag]"`. ### JSON Parse Failed @@ -614,7 +423,7 @@ ERROR: PyMuPDF required for PDF processing WARNING: Failed to parse extraction for: form.jpg ``` -**Solution**: Check image quality and form layout clarity. +The VLM output wasn't valid JSON — usually a low-quality or unclear form image. Check image clarity, or re-run `gaia-emr test ` to inspect the raw extraction. ### Database Locked @@ -622,47 +431,7 @@ WARNING: Failed to parse extraction for: form.jpg ERROR: database is locked ``` -**Solution**: Only one agent should access the database at a time. - -### Slow First Run - -First run downloads models (LLM, VLM, embeddings) which may take several minutes. Subsequent runs start immediately. - -### Model Download Failed - -``` -Failed to download file: [model files] -Download succeeded but failed to rename file: The process cannot access the file -``` - -**Solution**: Run `gaia-emr init` again to resume the download. If the error persists: -1. Close any applications that may be using the model files -2. Delete partial downloads in Lemonade's model cache directory -3. Run `gaia-emr init` again - -### Context Size Too Small - -``` -Context size too small! Image requires 4203 tokens but model context is only 4096. -``` - -**Solution**: Increase Lemonade context size: -1. Right-click Lemonade tray icon → Settings -2. Set Context Size to **32768** -3. Restart the model - -### Corrupted Model / Init Fails - -If `gaia-emr init` fails repeatedly or the agent won't start due to model errors: - -**Solution**: Delete the corrupted model from Lemonade's cache and restart: -1. Close Lemonade Server (right-click tray icon → Exit) -2. Navigate to the model cache directory: - - Windows: `%LOCALAPPDATA%\AMD\LemonadeModels\` - - Linux: `~/.local/share/lemonade/models/` -3. Delete the corrupted model folder (e.g., `Gemma-4-E4B-it-GGUF/`) -4. Restart Lemonade Server -5. Run `gaia-emr init` again to re-download +Only one agent process should access a given database file at a time. Stop other `gaia-emr` processes pointed at the same `--db` path. --- diff --git a/docs/guides/index.mdx b/docs/guides/index.mdx index 62fa0b0a8..252073d18 100644 --- a/docs/guides/index.mdx +++ b/docs/guides/index.mdx @@ -19,7 +19,7 @@ User guides show you how to **use** GAIA's pre-built agents and SDKs. Each guide --- -## Hardware & System +## Setup & Hardware Determine what LLMs your system can run based on RAM, GPU, and NPU capabilities. + + + Run GAIA agents on AMD Ryzen AI NPU for power-efficient local inference. + --- -## Conversational AI +## Core Agents Natural voice conversations using Whisper (ASR) and Kokoro (TTS). + + + Search the web, fetch pages, and download files with a focused agent. + + + + Load structured rows into scratchpad tables and query them with SQL. + --- -## Development Tools +## Developer Tools + + Semantic search over your codebase using local AMD-accelerated embeddings. + + Natural language interface for containerizing applications. + + +--- + +## Connected Agents + + + + Read, organize, and reply to Gmail with email content processed locally. + + + + Talk to GAIA from Telegram on any device, with per-user sessions. + - Automate patient intake form processing with VLM extraction and local database storage. + Multi-modal image generation with LLM prompt enhancement and VLM story creation. + + Automate patient intake form processing with VLM extraction and local database storage. + + + + Create your own AI agents and add them to the GAIA Agent UI. + + + + Build, version, and publish a GAIA agent to the Agent Hub. + + + +--- + ## MCP Integration Connect your agent to any MCP server - filesystem, GitHub, databases, and hundreds more. @@ -144,13 +228,20 @@ User guides show you how to **use** GAIA's pre-built agents and SDKs. Each guide | Check what models your hardware can run | [Hardware Advisor](/guides/hardware-advisor) | | Build a chatbot or document Q&A | [Document Q&A](/guides/chat) | | Add voice to your agent | [Voice Interaction](/guides/talk) | +| Research the web from the CLI | [Browser Agent](/guides/browse) | +| Run SQL over structured rows | [Analyst Agent](/guides/analyze) | | Generate Next.js applications | [Code Agent](/guides/code) | +| Search your codebase semantically | [Code Index](/guides/code-index) | | Containerize applications | [Docker Agent](/guides/docker) | +| Triage your Gmail inbox locally | [Email Triage](/guides/email) | +| Chat with GAIA from your phone | [Telegram Adapter](/guides/telegram-adapter) | | Work with Jira tickets | [Jira Agent](/guides/jira) | -| Process medical intake forms | [Medical Intake](/guides/emr) | +| Generate images from text | [Image Generation](/guides/sd) | | Create 3D scenes with AI | [Blender Agent](/guides/blender) | +| Process medical intake forms | [Medical Intake](/guides/emr) | | Route requests to specialized agents | [Routing Agent](/guides/routing) | -| Connect agents to external MCP tools | [MCP Client](/sdk/sdks/mcp) | +| Build and publish your own agent | [Custom Agents](/guides/custom-agent) | +| Connect agents to external MCP tools | [MCP Client](/guides/mcp/client) | | Monitor Windows system health | [Windows System Health](/guides/mcp/windows-system-health) | --- diff --git a/docs/guides/jira.mdx b/docs/guides/jira.mdx index 48e1354e8..4a6c69eef 100644 --- a/docs/guides/jira.mdx +++ b/docs/guides/jira.mdx @@ -1,67 +1,49 @@ --- title: "Jira Agent" +description: "Search, create, and update Jira issues with plain-English commands via the Atlassian REST API." icon: "ticket" --- - **Source Code:** [`src/gaia/agents/jira/agent.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/jira/agent.py) · [`src/gaia/apps/jira/app.py`](https://github.com/amd/gaia/blob/main/src/gaia/apps/jira/app.py) + **Source Code:** [`hub/agents/python/jira/gaia_agent_jira/agent.py`](https://github.com/amd/gaia/blob/main/hub/agents/python/jira/gaia_agent_jira/agent.py) · [`src/gaia/apps/jira/app.py`](https://github.com/amd/gaia/blob/main/src/gaia/apps/jira/app.py) ## Overview -The GAIA Jira Agent provides a natural language interface for interacting with Atlassian Jira. The agent communicates directly with the Atlassian REST API - no intermediary services or MCP bridge required. It automatically discovers your Jira instance configuration and allows you to search, create, and update issues using plain English commands. +The GAIA Jira Agent provides a natural language interface to Atlassian Jira. It talks directly to the Atlassian REST API — no intermediary services or MCP bridge required. On first use it auto-discovers your instance configuration (projects, issue types, statuses, priorities) so it adapts to *your* Jira setup, then lets you search, create, and update issues with plain English. > **First time here?** Complete the [Setup](/setup) guide first to install GAIA and its dependencies. - -> **Desktop WebUI**: GAIA includes a JIRA WebUI as an Electron desktop application. See the [WebUI Configuration](#webui-configuration) section below for setup instructions. +> +> **Desktop WebUI**: GAIA also ships a JIRA WebUI Electron app. See [WebUI Configuration](#webui-configuration) below. ## Quick Start ### Prerequisites -1. **GAIA Installation**: - Follow the [Setup](/setup) guide to install GAIA. The base installation includes all dependencies needed for the Jira agent. - -2. **Download Required Model**: - The Jira agent uses the `Qwen3.5-35B-A3B-GGUF` model for reliable JSON parsing and JQL generation. +1. **GAIA Installation** — Follow the [Setup](/setup) guide. The base install includes everything the Jira agent needs. - Use the Lemonade server's model manager to download it: - 1. Start Lemonade server: `lemonade-server serve` - 2. Open the model manager in your browser (typically http://localhost:13305) - 3. Search for and download: `Qwen3.5-35B-A3B-GGUF` +2. **Download the model** — The agent uses `Qwen3.5-35B-A3B-GGUF` for reliable JSON parsing and JQL generation. Download it via the Lemonade model manager: + 1. Start the server: `lemonade-server serve` + 2. Open the model manager (typically http://localhost:13305) + 3. Search for and download `Qwen3.5-35B-A3B-GGUF` - Note: The model is over 17GB and can take a while to download depending on your internet connection. Due to its size, it should be run on a Strix Halo device or similar high-performance hardware with sufficient memory. It provides the best results for complex Jira queries and will be automatically selected when you run Jira commands. + The model is over 17 GB, so download takes a while and is best run on a Strix Halo (or similar high-memory) device. It is selected automatically when you run Jira commands. -3. **Set Jira Credentials**: - - Required - Your Jira credentials: +3. **Set Jira credentials**: ```bash export ATLASSIAN_SITE_URL=https://your-domain.atlassian.net - ``` - - ```bash export ATLASSIAN_API_KEY=your-api-token - ``` - - ```bash export ATLASSIAN_USER_EMAIL=your-email@example.com ``` - Or create a `.env` file in the project root (see `.env.example` for template) + Or create a `.env` file in the project root (see `.env.example` for a template). See [Getting Your Jira API Token](#getting-your-jira-api-token) for token setup. ### Verify Installation -Check that GAIA is installed correctly: - ```bash gaia --version -``` - -Test Jira credentials (will auto-discover your instance): - -```bash -gaia jira "show all projects" +gaia jira "show all projects" # auto-discovers your instance ``` ### Basic Usage @@ -88,36 +70,17 @@ gaia jira "set MDP-6 priority to high" ``` -## Important Note + +The agent was developed and tested against a dummy Jira project. Real instances vary in custom fields, workflows, and permissions, so you may hit errors or unexpected results. Auto-discovery adapts to most setups, but highly customized environments may need manual adjustment. + -The Jira agent was developed and tested using a dummy Jira project. Different Jira projects may have varying configurations, custom fields, workflows, and permissions that could affect the agent's behavior. You may encounter errors or unexpected results depending on your specific Jira instance setup. The agent's auto-discovery feature helps adapt to different configurations, but some manual adjustments may be needed for complex or highly customized Jira environments. +## Architecture -## Architecture Overview +The CLI (`gaia jira`) wraps **JiraApp** (`src/gaia/apps/jira/app.py`), which drives the **JiraAgent** (`hub/agents/python/jira/gaia_agent_jira/agent.py`): -### Key Components - -1. **JiraAgent** (`src/gaia/agents/jira/agent.py`) - - - Core agent that processes natural language queries - - Automatically discovers Jira instance configuration (projects, issue types, statuses, priorities) - - Uses LLM to translate natural language to JQL and execute operations - - Registers three main tools: `jira_search`, `jira_create`, `jira_update` - -2. **JiraApp** (`src/gaia/apps/jira/app.py`) - - - Application wrapper for the JiraAgent - - Provides high-level methods for common operations - - Handles interactive mode - - Formats output for user display - -3. **GAIA Jira CLI** (`gaia jira` command) - - - Easy command-line interface for Jira operations - - Supports both direct queries and interactive mode - - Automatically manages agent lifecycle - - No coding required - just natural language commands - -### How It Works +- **JiraAgent** — processes natural language, auto-discovers your instance configuration, translates queries to JQL, and registers three tools: `jira_search`, `jira_create`, `jira_update`. +- **JiraApp** — high-level wrapper that handles interactive mode and formats output for display. +- **`gaia jira` CLI** — manages the agent lifecycle; supports direct queries and interactive mode. ```mermaid %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#E2A33E', 'primaryTextColor':'#1a1a1a', 'primaryBorderColor':'#A87B2D', 'lineColor':'#EFC480', 'fontFamily': 'system-ui, -apple-system, sans-serif'}}}%% @@ -142,117 +105,61 @@ graph LR linkStyle 0,1,2,3,4,5,6 stroke:#E2A33E,stroke-width:2px ``` -1. **Automatic Discovery**: On first use, the agent discovers your Jira instance configuration -2. **Dynamic Prompting**: Uses discovered config to teach the LLM about your specific Jira setup -3. **Natural Language Processing**: LLM converts queries to structured tool calls -4. **Tool Execution**: Executes appropriate Jira operations via REST API -5. **Result Formatting**: Returns user-friendly responses +1. **Automatic discovery** — on first use it queries your Jira instance for projects, issue types, statuses, and priorities. +2. **Dynamic prompting** — that discovered config teaches the LLM about your specific setup. +3. **Query translation** — the LLM converts natural language into structured tool calls (and JQL). +4. **Tool execution** — calls the Jira REST API. +5. **Result formatting** — returns a user-friendly response. ## Usage Examples -### Natural Language Commands +The agent understands a wide range of phrasings — the examples below are representative, not exhaustive. -#### Search Operations - -Find your assigned issues: +### Search ```bash +# Assigned to you gaia jira "show my issues" -``` - -```bash gaia jira "what am I working on" -``` - -Search by priority and type: -```bash +# By priority and type gaia jira "find high priority ideas" -``` - -```bash gaia jira "show medium priority ideas from this week" -``` -Search by project: - -```bash +# By project gaia jira "issues in project MDP" -``` - -```bash gaia jira "what's happening in MDP" -``` - -Time-based searches: -```bash +# Time-based gaia jira "issues created today" -``` - -```bash gaia jira "bugs fixed last week" -``` - -```bash gaia jira "what changed yesterday" -``` - -Sprint queries: -```bash +# Sprint queries gaia jira "current sprint ideas" -``` - -```bash gaia jira "unfinished ideas in active sprint" ``` -#### Creating Issues - -Simple idea creation: +### Create ```bash gaia jira "create idea: Explore VR travel features" -``` - -Create with details: - -```bash gaia jira "create an idea: Implement AI chatbot, high priority" -``` - -```bash gaia jira "new idea: Add user analytics dashboard" +gaia jira "create idea in MDP: Refactor user profile data" # specify project ``` -Specify project: - -```bash -gaia jira "create idea in MDP: Refactor user profile data" -``` - -#### Updating Issues - -Change priority: +### Update ```bash +# Change priority gaia jira "update MDP-5 set priority to High" -``` - -Change status: -```bash +# Change status gaia jira "move MDP-6 to Discovery" -``` - -```bash gaia jira "move MDP-5 to Parking lot" -``` -Update multiple fields: - -```bash +# Update multiple fields gaia jira "update JKL-012 priority High and assign to me" ``` @@ -262,8 +169,6 @@ gaia jira "update JKL-012 priority High and assign to me" gaia jira --interactive ``` -You'll see: - ``` 🚀 GAIA Jira App - Interactive Mode Type 'help' for commands, 'exit' to quit @@ -275,135 +180,47 @@ jira> show my open issues Status: Parking lot | Priority: Medium | Assignee: You • MDP-5 - Refactor user profile data Status: Parking lot | Priority: Medium | Assignee: You -... ``` ## Integration Methods -GAIA provides two methods for third-party applications to integrate with the Jira agent: - -### 1. Python API (Direct Integration) +### 1. Python API Use the JiraAgent directly in your Python applications: ```python -from gaia.agents.jira.agent import JiraAgent - -# Initialize the agent -agent = JiraAgent( - model_id="Qwen3.5-35B-A3B-GGUF", - silent_mode=True # Suppress console output for API usage -) +from gaia_agent_jira.agent import JiraAgent -# Discover Jira configuration (do this once) +# Initialize and discover Jira configuration (do this once) +agent = JiraAgent(silent_mode=True) # silent_mode suppresses console output config = agent.initialize() print(f"Connected to Jira with {len(config['projects'])} projects") # Execute natural language queries result = agent.process_query("show my high priority ideas in MDP") - -if result['status'] == 'success': - print(f"Result: {result['final_answer']}") +if result["status"] == "success": + print(f"Result: {result['result']}") print(f"Steps taken: {result['steps_taken']}") - # Access detailed conversation history if needed - for msg in result.get('conversation', []): - if msg['role'] == 'system' and 'issues' in msg.get('content', {}): - issues = msg['content']['issues'] - for issue in issues: - print(f" - {issue['key']}: {issue['summary']}") - -# Create a new issue -result = agent.process_query("create an idea: Implement AI chatbot with medium priority") - -# Update an existing issue -result = agent.process_query("update MDP-5 set priority to High") - -# Complex queries -result = agent.process_query( - "find all ideas in Parking lot status and show their priorities" -) +# Create and update issues +agent.process_query("create an idea: Implement AI chatbot with medium priority") +agent.process_query("update MDP-5 set priority to High") ``` -### 2. MCP Server (HTTP/JSON-RPC Integration) +`process_query` returns a dict with `status` (`"success"`, `"failed"`, or `"incomplete"`), `result`, `steps_taken`, `conversation`, and `error_history`. -For non-Python applications, use the MCP bridge to access the Jira agent via HTTP. +### 2. MCP Server (HTTP/JSON-RPC) -Start the MCP bridge (if needed for external integrations): +For non-Python applications, expose the agent over HTTP via the MCP bridge: ```bash gaia mcp start --port 8765 ``` -Then integrate from any language: - -**JavaScript/Node.js Example:** -```javascript -async function queryJira(query) { - const response = await fetch('http://localhost:8765/', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ - jsonrpc: '2.0', - id: '1', - method: 'tools/call', - params: { - name: 'gaia.jira', - arguments: { - query: query, - operation: 'query' - } - } - }) - }); - - const result = await response.json(); - if (result.result) { - const content = JSON.parse(result.result.content[0].text); - return content; - } - throw new Error(result.error || 'Unknown error'); -} - -// Usage examples -const issues = await queryJira('show my open ideas'); -const newIssue = await queryJira('create idea: Add VR support'); -const update = await queryJira('update MDP-6 to high priority'); -``` - -**Python with HTTP (alternative to direct API):** -```python -import requests - -def query_jira_via_mcp(query): - response = requests.post('http://localhost:8765/', json={ - 'jsonrpc': '2.0', - 'id': '1', - 'method': 'tools/call', - 'params': { - 'name': 'gaia.jira', - 'arguments': { - 'query': query, - 'operation': 'query' - } - } - }) - - result = response.json() - if 'result' in result: - import json - content = json.loads(result['result']['content'][0]['text']) - return content - raise Exception(result.get('error', 'Unknown error')) - -# Usage -issues = query_jira_via_mcp('show ideas in MDP project') -print(f"Success: {issues['success']}") -print(f"Result: {issues['result']}") -``` +Then call it from any language with a JSON-RPC `tools/call`. The response payload is JSON in `result.content[0].text`. -**cURL Example:** -```bash + +```bash cURL curl -X POST http://localhost:8765/ \ -H "Content-Type: application/json" \ -d '{ @@ -412,333 +229,144 @@ curl -X POST http://localhost:8765/ \ "method": "tools/call", "params": { "name": "gaia.jira", - "arguments": { - "query": "show my ideas in Parking lot status" - } + "arguments": { "query": "show my ideas in Parking lot status" } } }' ``` -For detailed MCP integration with workflow tools, see: -- **[MCP Documentation](/integrations/mcp)** - Complete MCP bridge reference -- **[n8n Integration Guide](/integrations/n8n)** - Workflow automation examples - -## Key Features - -### Automatic Configuration Discovery - -The agent automatically discovers your Jira instance configuration on first use. - -The agent learns about: -- Available projects and their keys -- Issue types (Bug, Task, Story, Epic, etc.) -- Valid statuses (To Do, In Progress, Done, etc.) -- Priority levels (Highest, High, Medium, Low, Lowest) -- Custom fields and values specific to your instance - -This means the agent adapts to YOUR Jira setup without any configuration files. - -### Intelligent Query Translation +```javascript JavaScript +async function queryJira(query) { + const response = await fetch("http://localhost:8765/", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "tools/call", + params: { name: "gaia.jira", arguments: { query } }, + }), + }); + const result = await response.json(); + if (result.result) { + return JSON.parse(result.result.content[0].text); + } + throw new Error(result.error || "Unknown error"); +} -The agent uses an LLM to understand context and intent: +const issues = await queryJira("show my open ideas"); +``` + -- **"my issues"** → Knows to use `assignee = currentUser()` -- **"critical"** → Maps to your instance's priority values -- **"this week"** → Calculates correct date ranges -- **"in progress"** → Uses your actual status names (even if custom) +For workflow integrations, see the [MCP Documentation](/integrations/mcp) and [n8n Integration Guide](/integrations/n8n). -### Robust Error Handling and Recovery +## Key Features -- **Error Recovery**: Automatically retries failed operations with exponential backoff -- **Intelligent Fallbacks**: When operations fail, the agent attempts alternative approaches -- **Credential Validation**: Validates credentials before operations to prevent unnecessary API calls -- **Helpful Error Messages**: Provides specific, actionable error messages for invalid queries -- **Smart Suggestions**: Suggests corrections for common mistakes (e.g., invalid issue types, wrong field names) -- **Network Resilience**: Handles network issues gracefully with automatic reconnection attempts -- **State Recovery**: Maintains conversation context even after errors, allowing users to continue without starting over +- **Automatic configuration discovery** — learns your projects, issue types, statuses, priorities, and custom fields on first use, with no config files. +- **Intelligent query translation** — maps intent to your instance: `"my issues"` → `assignee = currentUser()`, `"critical"` → your priority values, `"this week"` → correct date ranges, `"in progress"` → your real status names. +- **Robust error handling** — validates credentials before calling the API, retries failed operations, suggests corrections for invalid issue types or field names, and preserves conversation context across errors. ## Configuration ### Getting Your Jira API Token -1. Log into your Atlassian account -2. Go to [Account Settings > Security > API tokens](https://id.atlassian.com/manage-profile/security/api-tokens) -3. Click "Create API token" -4. Give it a name (e.g., "GAIA Integration") -5. Copy the token and save it securely +1. Log into your Atlassian account. +2. Go to [Account Settings > Security > API tokens](https://id.atlassian.com/manage-profile/security/api-tokens). +3. Click **Create API token**, name it (e.g. "GAIA Integration"), and copy it somewhere safe. ### Setting Environment Variables -#### Windows - -```cmd -set ATLASSIAN_SITE_URL=https://your-domain.atlassian.net -``` - -```cmd -set ATLASSIAN_API_KEY=your-api-token -``` - -```cmd -set ATLASSIAN_USER_EMAIL=your-email@example.com -``` - -#### Linux/Mac - + + ```bash export ATLASSIAN_SITE_URL=https://your-domain.atlassian.net -``` - -```bash export ATLASSIAN_API_KEY=your-api-token -``` - -```bash export ATLASSIAN_USER_EMAIL=your-email@example.com ``` - -#### Using .env file - -Create a .env file in your project root: - + + +```cmd +set ATLASSIAN_SITE_URL=https://your-domain.atlassian.net +set ATLASSIAN_API_KEY=your-api-token +set ATLASSIAN_USER_EMAIL=your-email@example.com +``` + + ```bash ATLASSIAN_SITE_URL=https://your-domain.atlassian.net ATLASSIAN_API_KEY=your-api-token ATLASSIAN_USER_EMAIL=your-email@example.com ``` - -## Advanced Usage + + ### Custom Model Selection -Use a different LLM model for specific use cases: - -```python -agent = JiraAgent( - model_id="gpt-4", - debug=True, - show_prompts=True -) -``` - -### Saving Query History - -Save query results to file for audit/analysis: +Override the default model when constructing the agent: ```python -result = agent.process_query( - "show all security-related issues", - output_to_file=True, - filename="security_audit.json" -) - -print(f"Results saved to: {result.get('output_file')}") +agent = JiraAgent(model_id="gpt-4", debug=True, show_prompts=True) ``` ## Troubleshooting -### Common Issues and Solutions - #### "Missing Jira credentials" -Check if environment variables are set: +Confirm the environment variables are set, then verify the token works directly: ```bash -echo $ATLASSIAN_SITE_URL -``` +echo $ATLASSIAN_SITE_URL $ATLASSIAN_API_KEY $ATLASSIAN_USER_EMAIL -```bash -echo $ATLASSIAN_API_KEY -``` - -```bash -echo $ATLASSIAN_USER_EMAIL -``` - -Verify API token is valid by testing with curl: - -```bash curl -u your-email@example.com:your-api-token \ https://your-domain.atlassian.net/rest/api/2/myself ``` #### "No issues found" when you know they exist -Enable debug mode to see the generated JQL: +Run with `--debug` to see the generated JQL, and confirm you can view the project: ```bash gaia jira --debug "your query" -``` - -Check if you have permission to view the project: - -```bash gaia jira "show all projects" ``` #### "Invalid issue type" errors -Discover what issue types are available: +Discover the issue types your instance actually uses: ```python agent = JiraAgent() config = agent.initialize() -print("Available issue types:", config['issue_types']) -``` - -Note: The dummy project uses "Idea" and "Epic" as issue types, not "Bug"/"Task"/"Story" - -#### MCP Bridge Connection Issues - -Check if MCP bridge is running: - -```bash -gaia mcp status -``` - -Restart the bridge if needed: - -```bash -gaia mcp stop +print("Available issue types:", config["issue_types"]) ``` -```bash -gaia mcp start -``` +Note: the dummy project uses "Idea" and "Epic" as issue types, not "Bug"/"Task"/"Story". -Test the bridge directly: +#### MCP bridge connection issues ```bash -curl -X POST http://localhost:8765/ \ - -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' +gaia mcp status # is it running? +gaia mcp stop && gaia mcp start # restart ``` ## Best Practices -### 1. Use Specific Queries +- **Be specific** — `"show my high priority ideas in project MDP"` beats `"show issues"`. +- **Let discovery run first** — call `agent.initialize()` (or any query) once so the agent knows your projects, statuses, and issue types before you create or update. +- **Use interactive mode** (`gaia jira --interactive`) for iterative exploration. -Good - specific and actionable: - -```bash -gaia jira "show my high priority ideas in project MDP" -``` - -Less effective - too vague: - -```bash -gaia jira "show issues" -``` - -### 2. Leverage Auto-Discovery - -Let the agent discover your setup first: - -```python -agent = JiraAgent() -config = agent.initialize() -``` - -Now the agent knows your specific configuration: - -```python -result = agent.process_query("create an Idea") -``` - -### 3. Use Interactive Mode for Exploration - -Best for iterative queries and exploration: - -```bash -gaia jira --interactive -``` - -### 4. Create Related Ideas - -Create multiple related ideas efficiently: - -```python -for idea in ["AI chatbot", "VR features", "Analytics dashboard"]: - agent.process_query(f"create idea: {idea}") -``` - -## Testing Your Integration - -### Quick Test Script - -```python -#!/usr/bin/env python -"""Test your Jira integration""" - -from gaia.agents.jira.agent import JiraAgent -import os - -if not os.getenv("ATLASSIAN_SITE_URL"): - print("❌ Missing ATLASSIAN_SITE_URL") - exit(1) - -print("✅ Credentials found") - -agent = JiraAgent(silent_mode=True) -config = agent.initialize() - -if config['projects']: - print(f"✅ Connected! Found {len(config['projects'])} projects") - print(f" Projects: {', '.join([p['key'] for p in config['projects'][:3]])}...") -else: - print("❌ No projects found - check permissions") - exit(1) - -result = agent.process_query("show 3 recent issues") -if result['status'] == 'success': - print("✅ Query successful!") - print(f" Result: {result['final_answer'][:100]}...") -else: - print(f"❌ Query failed: {result.get('error_history', [])}") -``` - -### Running Agent Tests - -Run the test suite: - -```bash -python scripts/jira_smoke.py -``` - -Run with specific options - choose tests interactively: - -```bash -python scripts/jira_smoke.py --interactive -``` - -Show debug output: - -```bash -python scripts/jira_smoke.py --debug -``` - -Display LLM prompts: - -```bash -python scripts/jira_smoke.py --show-prompts -``` +To exercise the integration end-to-end, run the smoke test: `python scripts/jira_smoke.py` (add `--interactive`, `--debug`, or `--show-prompts` as needed). ## Limitations -- **API Rate Limits**: Atlassian enforces rate limits on API calls -- **Field Permissions**: Can only access/modify fields you have permission for -- **Bulk Operations**: Currently processes items sequentially, not in parallel -- **Attachment Support**: Does not currently support file attachments -- **Workflow Transitions**: Limited support for complex workflow transitions +- **API rate limits** — Atlassian enforces rate limits on API calls. +- **Field permissions** — can only access or modify fields you have permission for. +- **Bulk operations** — items are processed sequentially, not in parallel. +- **Attachments** — file attachments are not supported. +- **Workflow transitions** — limited support for complex transitions. ## WebUI Configuration -The JIRA WebUI provides an in-app configuration screen where you can: -- Enter your JIRA server URL -- Set your username/email -- Configure your API token - -Configuration is stored locally and persists between sessions. +The JIRA WebUI provides an in-app configuration screen for your JIRA server URL, username/email, and API token. Configuration is stored locally and persists between sessions. ## See Also @@ -757,4 +385,4 @@ Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved. SPDX-License-Identifier: MIT - \ No newline at end of file + diff --git a/docs/guides/memory.mdx b/docs/guides/memory.mdx index d5ee272fd..5cda1e5ac 100644 --- a/docs/guides/memory.mdx +++ b/docs/guides/memory.mdx @@ -56,68 +56,24 @@ Until you enable memory, none of the behaviors on this page (cross-session recal ## Try It Right Now -Five minutes after you enable memory (above). Here's what a second brain feels like: +With memory enabled (above), here's what a second brain feels like. Teach it something in one session, then start a fresh one and watch it recall: - - - ```bash - gaia chat - ``` - - - - ``` - You: "Remember that I'm working on the GAIA memory system - and I prefer detailed code examples" - Agent: "Got it! I've noted that you're working on the GAIA memory - system and that you prefer detailed code examples." - ``` - - - - ``` - You: "What do you know about me?" - Agent: "You're working on the GAIA memory system, and you prefer - detailed code examples." - ``` - - - - ``` - You: "Remember: standup tomorrow at 10am, Sarah is presenting - the API migration results" - Agent: "Done -- I'll remind you about the standup tomorrow and - I've linked Sarah to this note." - ``` - - - - Close the chat and start fresh: - ```bash - gaia chat - ``` - - - - ``` - You: "What's coming up?" - Agent: "You have a standup at 10am -- Sarah is presenting - the API migration results." +``` +# Session 1 +gaia chat +You: "Remember that I'm working on the GAIA memory system, and that + standup is tomorrow at 10am -- Sarah is presenting the API migration." +Agent: "Got it -- I've noted your project and linked Sarah to the standup." - You: "What do you know about Sarah?" - Agent: "Sarah is presenting the API migration results at - tomorrow's standup." - ``` - The agent remembered across sessions -- no copy-paste, no notes app. - +# Session 2 (close the chat, start fresh) +gaia chat +You: "What's coming up?" +Agent: "You have a standup at 10am -- Sarah is presenting the API migration." +You: "What do you know about Sarah?" +Agent: "Sarah is presenting the API migration results at tomorrow's standup." +``` - - ```bash - gaia chat --ui - ``` - Click the **Brain** icon in the toolbar. You'll see every memory the agent has, filterable and editable. - - +The agent remembered across sessions -- no copy-paste, no notes app. Run `gaia chat --ui` and click the **Brain** icon to see every memory, filterable and editable. --- @@ -214,21 +170,13 @@ You: "What do you know about Sarah?" Agent: [recalls all entries linked to entity person:sarah_chen] ``` -Recall also supports **temporal filtering** with `time_from` and `time_to`. The agent converts natural language dates to concrete time ranges using the current date it always knows: +Recall also supports **temporal filtering** with `time_from` and `time_to`. The agent converts natural language dates ("last week", "in March") to concrete time ranges using the current date it always knows: ``` You: "What did we discuss about deployment last week?" Agent: "Last week you pushed the staging deploy and hit a kubectl permissions error. You resolved it by adding the service account role." - -You: "What errors have I seen this week?" -Agent: "Two errors this week: a missing pytest conftest.py on Monday, - and a Docker build failure yesterday due to a stale cache." - -You: "What meetings did I have in March?" -Agent: "Four standups in March: API migration (Sarah), two design - reviews, and the Q2 planning kickoff on the 28th." ``` ### update_memory @@ -257,97 +205,29 @@ Agent: [recalls the entry, deletes it] ### search_past_conversations -Searches across all past conversation sessions by keyword, time range, or both. +Searches across all past conversation sessions by keyword (`query`), time range (`days` or `time_from`/`time_to`), or both. ``` You: "What did we discuss about database migration?" Agent: "Found 3 conversations mentioning database migration: two sessions last month about the Postgres schema, and one this week where you decided to add a new index." - -You: "What did we talk about in the last 7 days?" -Agent: "This week's conversations covered: code review for the - auth module, debugging the CI pipeline, and planning - the Q2 dashboard." - -You: "What were we working on in March?" -Agent: [searches conversation turns from March 1-31 and summarizes] ``` --- ## Your Second Brain -Memory turns GAIA into a personal knowledge system that grows smarter with every conversation. Here are real things you can try right now. - -### Daily Journal - -Log your work at the end of the day. Recall it weeks later without digging through notes. - -``` -You: "Log today's work: finished the memory spec, reviewed analysis docs, - pushed the feature branch. Still blocked on the CI lint step." - -Agent: "Logged. I'll remember this when you ask about your work history." - -— Two weeks later — - -You: "What did I work on the first week of April?" -Agent: "On April 1st, you finished the memory spec, reviewed analysis docs, - and pushed the feature branch. You were blocked on CI lint." - -You: "When did I push the memory branch?" -Agent: "April 1st -- you pushed feature/agent-memory that day." -``` - -### Meeting Notes - -Capture standup notes, and the agent automatically extracts per-person facts and deadlines. - -``` -You: "In today's standup: Sarah said the API migration is done. - John is blocked waiting for design review. - Deadline for Q2 report moved to April 15." - -Agent: Stored 3 items: - - Note: standup summary (domain=meeting:standup) - - Reminder: Q2 report due April 15 (with due_at) - - Fact: John blocked on design review (linked to person:john) - -— Next week — - -You: "Is John still blocked?" -Agent: "Last I heard (April 1st standup), John was blocked - waiting for design review." - -You: "What's the Q2 report deadline?" -Agent: "April 15th -- the deadline was moved from the original date." -``` - -### Research & Reading Notes - -Save article summaries, then find them by concept -- not just keywords. - -``` -You: "Save this: the Hindsight paper shows that cross-encoder reranking - after RRF fusion gives 91.4% accuracy on LongMemEval. Key insight: - independent encoders miss fine-grained relevance signals." - -Agent: "Saved. I'll surface that when you ask about retrieval or search accuracy." +Memory turns GAIA into a personal knowledge system that grows smarter with every conversation. Common uses: -— Later — +- **Daily journal** -- log your work; recall it weeks later by date ("what did I work on the first week of April?"). +- **Meeting notes** -- paste standup notes; the agent extracts per-person facts and deadlines automatically. +- **Research notes** -- save article summaries and find them later by concept, not just keywords. +- **Personal reminders** -- set due dates (including recurring ones); the agent surfaces them proactively. +- **Contact profiles** -- knowledge about people accumulates across conversations, linked to entities. +- **Error learning** -- when a tool fails, the agent remembers the pattern and avoids it next time. -You: "What do I know about improving retrieval accuracy?" -Agent: "The Hindsight paper found that cross-encoder reranking after - RRF fusion reaches 91.4% on LongMemEval. The key insight is - that independent encoders miss fine-grained relevance signals." -``` - -The semantic search found the match even though you asked about "retrieval accuracy" and the memory says "cross-encoder reranking" -- because it searches by meaning. - -### Personal Reminders - -Set reminders with due dates. The agent surfaces them proactively -- even if you're talking about something else. +A representative example -- proactive, time-aware reminders: ``` You: "Remind me to submit the expense report by Friday" @@ -360,52 +240,7 @@ Agent: "Sure, here's the refactored version. By the way, your expense report is due tomorrow -- don't forget to submit it." ``` -Recurring reminders work too -- the agent advances the date automatically each time it fires: - -``` -You: "Remind me to do a weekly review every Friday at 5pm" -Agent: "Set. I'll remind you every Friday at 5pm and roll it - forward automatically after each reminder." -``` - -### Contact Profiles - -Build knowledge about people across conversations. The agent links everything to entities. - -``` -You: "Sarah Chen is the VP of Engineering, her email is sarah@company.com" -Agent: "Got it -- I've saved Sarah's info. Her email is stored privately." - -— Another conversation — - -You: "Sarah prefers morning meetings and likes detailed agendas" -Agent: "Added to Sarah's profile." - -— Later — - -You: "I need to set up a meeting with Sarah about the roadmap" -Agent: "Sarah prefers morning meetings with detailed agendas. - Her email is sarah@company.com. Want me to draft an agenda?" -``` - -### Error Learning - -When a tool fails, the agent remembers the error pattern and avoids it next time -- automatically. - -``` -Session 1: -Agent runs: import torch -Error: ModuleNotFoundError: No module named 'torch' -[agent silently stores this as an error pattern to avoid in future] - -Session 2: -You: "Can you test this PyTorch model?" -Agent: "I know from past experience that torch isn't installed - on this machine. Let me install it first with - pip install torch --index-url ..." -``` - -No manual intervention -- the agent learned from failure and adapted. +Recurring reminders advance their date automatically each time they fire (e.g. *"remind me to do a weekly review every Friday at 5pm"*). --- @@ -510,68 +345,23 @@ The agent always knows the current date and time. It can track commitments and d 4. If the due date passes, the item appears as **overdue** until resolved ``` -Day 1: -You: "I have a course starting next Tuesday" -Agent: "Noted -- I'll remind you as it gets closer." - -Day 5 (3 days before): -You: "What's the weather like?" -Agent: "It's sunny. By the way, your online course starts in 3 days." - -Day 8 (the day): -You: "Good morning" -Agent: "Good morning! Your course starts today. How's it going?" +Day 1: You: "I have a course starting next Tuesday" + Agent: "Noted -- I'll remind you as it gets closer." +Day 5: You: "What's the weather like?" + Agent: "It's sunny. By the way, your online course starts in 3 days." +Day 8: You: "Good morning" + Agent: "Good morning! Your course starts today. How's it going?" ``` -### Accountability - -The agent can hold you accountable to your own commitments: - -``` -You: "I committed to exercising 3 times this week" -Agent: "Holding you to it! I'll check in at the end of the week." - -Friday evening: -You: "Let's plan the weekend" -Agent: "Before we plan -- it's the end of the week. How did - the exercise commitment go? Did you hit 3 times?" -``` +The same mechanism powers **accountability** -- commit to something ("I'll exercise 3 times this week") and the agent checks in proactively when the deadline nears. --- ## Intelligent Extraction -After each conversation turn (with memory enabled), the agent automatically decides what's worth remembering -- without you saying "remember." This isn't pattern matching; the LLM sees your existing memory alongside the new conversation and makes intelligent decisions: - -- **ADD** -- new knowledge not already in memory -- **UPDATE** -- a fact has changed (old version preserved with lineage) -- **DELETE** -- information explicitly contradicted +After each conversation turn (with memory enabled), the agent automatically decides what's worth remembering -- without you saying "remember." This isn't pattern matching; the LLM sees your existing memory alongside the new conversation and decides whether to **ADD** new knowledge, **UPDATE** a changed fact (old version preserved with lineage), or **DELETE** something you've contradicted. -### How it works - -You say "we switched from React to Vue." The agent: - -1. Searches existing memory, finds `"Project uses React 19"` (stored last month) -2. Recognizes this is a correction, not a new fact -3. Creates a new entry: `"Project uses Vue 3 (switched from React)"` -4. Marks the old React entry as `superseded_by` the new one -- preserving history - -No duplicate. No contradiction. The old fact is still visible in the dashboard's superseded view if you ever want to see how things evolved. - -### What gets extracted - -The agent extracts information that would be **useful in future conversations** -- facts, preferences, project details, people, deadlines. It skips greetings, task confirmations, and ephemeral details. - -``` -You: "I've been using the new AMD Ryzen 9 9950X for the project, - and it's much faster for local LLM inference. The team - decided to standardize on Python 3.12 going forward." - -Agent silently extracts: - - fact: "User has AMD Ryzen 9 9950X" (new) - - fact: "Team standardized on Python 3.12" (update if version changed) - - No action on "much faster" (subjective, ephemeral) -``` +It extracts information useful in future conversations -- facts, preferences, project details, people, deadlines -- and skips greetings, confirmations, and ephemeral details. For example, "we standardized on Python 3.12 and I'm using a Ryzen 9 9950X" stores two facts but ignores subjective asides like "it's much faster." Intelligent extraction kicks in for messages of 20+ words. Short messages like "yes" or "thanks" are skipped. The LLM's explicit memory tools (`remember`, `update_memory`, `forget`) still handle anything the auto-extraction misses. @@ -621,61 +411,14 @@ The dashboard also provides maintenance tools for keeping your memory healthy: ## How Memory Improves Over Time -### Confidence scoring - -Every memory entry has a confidence score from 0.0 to 1.0: - -| Source | Confidence | How created | -|--------|-----------|-------------| -| LLM-extracted | **0.4** | Automatically captured from conversation | -| Discovery | **0.4** | Found during bootstrap system scan | -| Tool-stored | **0.5** | Agent explicitly called `remember()` | -| Error auto | **0.5** | Automatically stored from tool failure | -| Consolidation | **0.5** | Distilled from old conversation sessions | -| User-created | **0.8** | Manually added via the dashboard | - -Each time a memory is recalled, its confidence increases by +0.02. Frequently-used memories become more prominent in the system prompt. - -### Confidence decay - -Memories that are not accessed for 30+ days have their confidence multiplied by 0.9. This happens once per session start. Over time, stale knowledge naturally fades from the system prompt in favor of actively-used information. - -### Fact lineage - -When facts change, the old version is preserved with a `superseded_by` link. You can see the full history of how a fact evolved in the dashboard's superseded view. - -``` -March: "Project uses React 18" - -> superseded by: "Project uses React 19" (April) - -> superseded by: "Project uses Vue 3" (May) -``` - -Each version keeps its original timestamp, so you can answer "what framework were we using in March?" - -### Automatic error learning - -When a tool call fails, the agent automatically stores the error pattern as knowledge. Next time, the system prompt includes "Known errors to avoid" so the agent can handle or avoid the same failure. - -``` -Agent runs: import torch -Error: ModuleNotFoundError: No module named 'torch' - -Next session system prompt: -Known errors to avoid: - - execute_code: import torch fails -- torch not installed on this machine -``` - -### Session consolidation - -Conversations older than 14 days are automatically distilled into durable knowledge items. The LLM summarizes each old session and extracts facts worth preserving, then stores them as notes. The original conversations remain until the 90-day prune, but the extracted knowledge lives indefinitely. - -This means you never lose important context -- even from conversations months ago. - -### Background reconciliation - -On startup, the agent scans for contradictory facts across sessions and resolves them automatically. If it finds two items that say conflicting things (e.g., "uses PostgreSQL" and "migrated to DynamoDB"), it supersedes the older one and boosts the newer one's confidence. Reinforcing facts get a confidence boost too. +These mechanisms run automatically -- you don't need to manage them. -You don't need to do anything -- the agent keeps its own knowledge consistent. +- **Confidence scoring** -- every entry has a 0.0--1.0 confidence. Newly created entries start lower for auto-captured items (LLM-extracted and discovery at **0.4**; tool-stored, error, and consolidation at **0.5**) and higher for user-created dashboard entries (**0.8**). Each recall adds +0.02, so frequently-used memories rank higher in the system prompt. +- **Confidence decay** -- entries not accessed for 30+ days are multiplied by 0.9 once per session start, so stale knowledge fades in favor of what you actively use. +- **Fact lineage** -- when a fact changes, the old version is kept with a `superseded_by` link and its original timestamp, so you can answer "what framework were we using in March?" The dashboard's superseded view shows the full chain. +- **Automatic error learning** -- a failed tool call is stored as an error pattern; the next session's system prompt includes a "Known errors to avoid" list so the agent doesn't repeat it. +- **Session consolidation** -- conversations older than 14 days are distilled into durable notes (extracted facts live indefinitely; raw conversations are pruned at 90 days), so old context is never lost. +- **Background reconciliation** -- on startup the agent resolves contradictory facts across sessions, superseding the older item and boosting the newer (and reinforcing) one's confidence. ### Procedural memory (skills) diff --git a/docs/guides/npu.mdx b/docs/guides/npu.mdx index ec9966f82..dbf82ffc8 100644 --- a/docs/guides/npu.mdx +++ b/docs/guides/npu.mdx @@ -1,6 +1,7 @@ --- title: "NPU Acceleration" description: "Run GAIA agents on AMD Ryzen AI NPU for power-efficient local inference" +icon: "bolt" --- # NPU Acceleration diff --git a/docs/guides/routing.mdx b/docs/guides/routing.mdx index 1b0875fe5..1512b4f41 100644 --- a/docs/guides/routing.mdx +++ b/docs/guides/routing.mdx @@ -1,5 +1,6 @@ --- title: "Routing Agent" +description: "Analyze each request and route it to the right specialized GAIA agent." icon: "route" --- diff --git a/docs/guides/telegram-adapter.mdx b/docs/guides/telegram-adapter.mdx index 4d4b9bbe4..5f8e83c4c 100644 --- a/docs/guides/telegram-adapter.mdx +++ b/docs/guides/telegram-adapter.mdx @@ -1,15 +1,136 @@ --- -title: Telegram Adapter +title: "Telegram Adapter" +description: "Connect GAIA agents to Telegram — receive messages and stream responses back to users." +icon: "paper-plane" --- -# Telegram Adapter + + **First time here?** Complete the [Setup](/setup) guide first to install GAIA and its dependencies. + -This guide describes how to configure the GAIA Telegram adapter to receive messages from Telegram users and stream responses back. +The Telegram adapter lets you talk to GAIA from the Telegram app on any device. It runs a bot that receives messages, runs each one through a local GAIA chat session, and streams the response back to the chat — so your phone becomes a front-end for the same agent you run on your desktop. -Key points: +It's a **messaging adapter**, not a separate agent: every conversation is backed by the standard [Agent SDK](/sdk/sdks/chat), so RAG, memory, and tool use behave exactly as they do in `gaia chat`. Each Telegram user gets their own isolated session, and photos or files sent to the bot are saved locally for the agent to process. -- Install `python-telegram-bot` in your environment. -- Configure a bot token via the Telegram BotFather and pass it to `run_telegram(token=...)`. -- The adapter supports background daemon mode and per-user sessions. +## Prerequisites -See `src/gaia/messaging/telegram.py` for the implementation details and configuration options. + + + The adapter depends on `python-telegram-bot`, which ships in the `telegram` extra: + + ```bash + uv pip install -e ".[telegram]" + ``` + + + + In Telegram, open a chat with [@BotFather](https://t.me/BotFather), send `/newbot`, and follow the prompts. BotFather returns a **bot token** that looks like `123456789:ABCdef...`. Keep it secret — anyone with the token can control your bot. + + + + The adapter runs inference through your local Lemonade backend, the same as `gaia chat`. If you haven't set up a model yet, run `gaia init` first. + + + +## Quick Start + +Start the adapter in the foreground, passing the token from BotFather: + +```bash +gaia telegram start --token 123456789:ABCdef... +``` + +The bot begins polling Telegram immediately. Open your bot in the Telegram app, send it a message, and you'll get a streamed reply. Press `Ctrl+C` to stop. + + + The token is supplied **only** via `--token` — there is no environment variable for it. Wrap the command in a script or shell history that keeps the token out of shared logs. + + +## Core Usage + +### Run in the background + +Use `--background` to run the adapter as a daemon. It writes a PID file to `~/.gaia/telegram.pid`, logs to `~/.gaia/telegram.log`, and exposes a health endpoint on `127.0.0.1:8765`: + +```bash +gaia telegram start --token 123456789:ABCdef... --background +``` + +### Restrict who can use the bot + +By default the bot replies to **anyone** who messages it. Pass `--allowed-users` with a comma-separated list of numeric Telegram user IDs to lock it down: + +```bash +gaia telegram start \ + --token 123456789:ABCdef... \ + --allowed-users 11111111,22222222 \ + --background +``` + + + To find your own Telegram user ID, message [@userinfobot](https://t.me/userinfobot). Messages from anyone not on the allow-list are ignored. + + +### Check status and stop + +```bash +# Show whether the background adapter is running (queries the health endpoint) +gaia telegram status + +# Stop the background adapter gracefully +gaia telegram stop + +# Force-stop if a graceful shutdown doesn't complete +gaia telegram stop --force +``` + +`gaia telegram status` checks `127.0.0.1:8765` by default. If you changed the health binding, point it at the right host and port with `--health-host` and `--health-port`. + +### Command reference + +| Command | Key options | Purpose | +|---------|-------------|---------| +| `gaia telegram start` | `--token` (required), `--allowed-users`, `--background` | Start polling Telegram | +| `gaia telegram stop` | `--force` | Stop the background adapter | +| `gaia telegram status` | `--health-host`, `--health-port` | Report adapter health | + +## How It Works + +- **Per-user sessions** — the adapter keeps one Agent SDK session per Telegram user ID, so conversation history and memory stay separated between users. +- **Streaming replies** — responses stream back into the Telegram chat as the model generates them. +- **Attachments** — photos and files sent to the bot are saved to a temporary path so the agent can read or analyze them. +- **Local inference** — all model calls go through your local Lemonade backend; message content is processed on your machine. + +Implementation lives in [`src/gaia/messaging/telegram.py`](https://github.com/amd/gaia/blob/main/src/gaia/messaging/telegram.py). + +## Next Steps + + + + The chat agent that backs every Telegram session — RAG, memory, and tools. + + + + Give your Telegram bot a persistent memory across conversations. + + + + The desktop front-end for the same agents. + + + + Browse every GAIA agent and adapter. + + + +--- + + + +**License** + +Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved. + +SPDX-License-Identifier: MIT + +