v0.15.0

GAIA v0.15.0 Release Notes

Overview

This release transforms GAIA into a full AI Agent Framework (SDK v1.0.0), introduces the Medical Intake Agent with Dashboard, adds the Database Module for SQLite-backed agents, and includes comprehensive documentation improvements with new playbooks.

Installation

# Install uv (ultra-fast Python package manager)
# Windows: irm https://astral.sh/uv/install.ps1 | iex
# macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

git clone https://github.com/amd/gaia.git
cd gaia
uv venv .venv --python 3.12
source .venv/bin/activate  # Windows: .\.venv\Scripts\Activate.ps1
uv pip install -e .
gaia -v

Or install from PyPI:

uv pip install amd-gaia

What's New

🚀 SDK v1.0.0 - AI Agent Framework

GAIA is now positioned as a pure framework/SDK for building AI PC agents:

• 900+ line API reference with 20+ components
• 60+ MDX documentation files organized into tabs
• 55+ interface validation tests
• Mintlify-powered documentation site at amd-gaia.ai

from gaia import Agent, tool

class MyAgent(Agent):
    def _get_system_prompt(self) -> str:
        return "You are a helpful assistant."

    def _register_tools(self):
        @tool
        def greet(name: str) -> str:
            """Greet someone by name."""
            return f"Hello, {name}!"

🏥 Medical Intake Agent with Dashboard

Complete patient intake form processing system:

• Automatic file watching for intake forms (.png, .jpg, .pdf)
• VLM-powered data extraction (Qwen2.5-VL on NPU)
• SQLite database with 17 patient fields
• Real-time React dashboard with SSE updates
• Natural language patient queries

gaia-emr watch          # Auto-process forms
gaia-emr dashboard      # Launch web dashboard
gaia-emr query "Find patient John Smith"

🗄️ Database Module

New gaia.database module with two usage patterns:

DatabaseAgent (prototyping):

from gaia import DatabaseAgent

class MyAgent(DatabaseAgent):
    def __init__(self, **kwargs):
        super().__init__(db_path="data/app.db", **kwargs)

DatabaseMixin (production):

from gaia import Agent, DatabaseMixin, tool

class MyAgent(Agent, DatabaseMixin):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.init_db("data/app.db")

🧪 Testing Utilities Module

New gaia.testing module for testing agents without real LLM/VLM services:

• MockLLMProvider, MockVLMClient, MockToolExecutor
• temp_directory, temp_file, create_test_agent fixtures
• assert_llm_called, assert_tool_called assertions
• 51 unit tests with full coverage

from gaia.testing import MockLLMProvider, assert_llm_called

def test_my_agent():
    mock_llm = MockLLMProvider(responses=["I found the data"])
    agent = MyAgent(skip_lemonade=True)
    agent.chat = mock_llm
    result = agent.process_query("Find data")
    assert_llm_called(mock_llm)

💻 Hardware Advisor Agent

New example agent with LemonadeClient APIs for dynamic model recommendations:

python examples/hardware_advisor_agent.py

📚 GAIA Code Playbook

Complete 3-part playbook for the Code Agent:

• Part 1: Introduction and fundamentals
• Part 2: Application creation and development
• Part 3: Validation and building workflows

Improvements

Agent UX Enhancements

• Rich Panel Final Answers: Agent responses now appear with green-bordered panels and "✅ Final Answer" title
• Better Completion Messages: Removed confusing step counters, now shows clean "Processing complete!" message
• Enhanced Error Display: Shows execution trace with Query → Plan Step → Tool → Error, plus code context with line pointers

Code Agent

• Limited router to TypeScript only (other languages report helpful error)
• Fixed default path issue where create-next-app would fail on non-empty directories
• Added dynamic timer scaffolding and artifact-aware planning

Lemonade Server Integration

• Centralized initialization in LemonadeManager singleton
• Changed context size check from error to warning (agents continue running)
• Fixed VLM image processing breaking embeddings endpoint

Documentation

• New setup.mdx with step-by-step installation guide
• New glossary.mdx with 50+ GAIA terms
• Streamlined learning path: Quickstart → Hardware Advisor → Playbooks/Guides
• Applied <CodeGroup> component across multiple docs for compact command examples
• Standardized license headers across 90+ files
• Added source code links throughout documentation

PyPI Package

• Renamed from gaia to amd-gaia (import name remains gaia)
• Enhanced PyTorch CPU-only build support

Bug Fixes

• #1092: Agent receives empty response after tool execution - fixed duplicate message insertion
• #1088: Confusing agent completion messages showing incomplete steps
• #1087: Context size error now shows as warning instead of blocking
• #134: Blender MCP 'Namespace' object has no attribute 'stats'
• #1075: VLM image processing breaks embeddings endpoint
• #1083: Agent tool calling fixed with JSON format instructions in base class
• #1095: Windows npx command can't find TypeScript compiler
• #1137: Code agent default path fails on non-empty directories
• #1079: Authentication flow for documentation sub-pages
• #940: Empty LLM response when last message has role==tool

Infrastructure

CI/CD

• All workflows now skip tests on draft PRs (unless ready_for_ci label added)
• New test_unit.yml workflow for fast unit/integration tests
• Updated GitHub Actions: actions/checkout v5, actions/setup-python v6

Documentation Site

• Access code protection via Express.js proxy server
• Railway deployment with cookie-based authentication
• Open redirect and XSS vulnerability fixes

Breaking Changes

None. All changes are additive.

Full Changelog

40 commits from 8 contributors

Key PRs:

• #1063 - Transform GAIA into AI Agent Framework (SDK v1.0.0)
• #1101 - Medical Intake Agent with Dashboard
• #1093 - Add Database Module with DatabaseMixin and DatabaseAgent
• #1098 - Add Testing Utilities Module
• #1131 - GAIA Code Playbook
• #1113 - Hardware Advisor agent
• #1112 - Fix agent empty response after tool execution
• #1085 - Rename PyPI package to amd-gaia
• #1067 - Centralize Lemonade Server Initialization

Full Changelog: v0.14.2...v0.15.0

v0.14.1

GAIA v0.14.1 Release Notes

Overview

This release enhances the Code Agent with checklist-based orchestration for web development, upgrades to Lemonade Server v9.1.0, and fixes chat history persistence.

Installation

# Install uv (ultra-fast Python package manager)
# Windows: irm https://astral.sh/uv/install.ps1 | iex
# macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

git clone https://github.com/amd/gaia.git
cd gaia
uv venv .venv --python 3.12
source .venv/bin/activate  # Windows: .\.venv\Scripts\Activate.ps1
uv pip install -e .
gaia -v

Note: As GAIA is upgraded, the above flow is the recommended one. A new installer is coming in a future.

What's New

🛠️ Code Agent Enhancements

New orchestration framework for building web applications:

• Checklist-driven workflows that break complex tasks into structured steps
• Automatic project type detection (Next.js, Python) with appropriate tooling
• Conversation history summarization for faster debugging cycles
• Validation tools for build, lint, and type-checking

gaia code "Create a task management app with user authentication"

🍋 Lemonade Server v9.1.0

• Upgraded to Lemonade Server v9.1.0
• Health check verifies Lemonade installation with clear error messages if missing
• Context size validation ensures sufficient tokens before agent execution

💬 Chat Improvements

• History persistence fix: Conversation history now properly saves with /save and restores with /resume
• Better no-document behavior: Chat agent uses general knowledge instead of failing when no documents are indexed

Improvements

• Linting: Cross-platform linting script (util/lint.py) for Windows/macOS/Linux
• CI/CD: New chat agent test workflow

What's Changed

• GAIA Code Enhancements by @itomek
• Implement cross-platform linting script by @kovtcharov
• Add health check for Lemonade server installation by @kovtcharov
• Add context size validation for Lemonade server by @kovtcharov
• Fix Chat History Persistence by @kovtcharov
• Enhance chat agent behavior when no documents indexed by @kovtcharov
• Faster Web Dev Agent Iterations by @eddierichter-amd
• Update Lemonade version to 9.1.0 by @kovtcharov

Full Changelog: v0.14.0...v0.14.1

v0.14.0

GAIA v0.14.0 Release Notes

Overview

This release introduces the Knowledge Assistant for document Q&A with agentic RAG, transitions to a streamlined cross-platform developer workflow using uv, and includes Lemonade Server v9.0.8 with auto-start capabilities.

Installation

# Install uv (ultra-fast Python package manager)
# Windows: irm https://astral.sh/uv/install.ps1 | iex
# macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

git clone https://github.com/amd/gaia.git
cd gaia
uv venv .venv --python 3.12
source .venv/bin/activate  # Windows: .\.venv\Scripts\Activate.ps1
uv pip install -e .
gaia -v

Why uv? 10-100x faster installs, automatic Python management, cross-platform support (Windows/macOS/Linux), and editable installs.

Note: As GAIA is upgraded, the above flow is the recommended one. A new installer is coming in a future.

What's New

📚 Knowledge Assistant - Document Q&A

Chat with your documents using agentic RAG:

• Index PDFs, markdown, text, CSV, JSON, and 30+ code file types
• Semantic search with hybrid keyword boosting
• VLM image extraction from PDFs
• Auto-discovery: agent searches, indexes, and answers automatically

gaia chat --index manual.pdf
gaia rag quick report.pdf "What are the key findings?"
gaia talk --index document.pdf

🍎 Cross-Platform Support

• Native macOS and Linux support
• Removed Conda dependency, migrated to Python venv
• macOS testing in CI/CD

🍋 Lemonade Server v9.0.8 Auto-Start

• GAIA automatically starts Lemonade Server if not running
• Version compatibility checks
• --base-url support for custom endpoints

⬇️ Model Pull with Streaming Progress

gaia model pull Qwen2.5-3B-Instruct-GGUF

Download models with real-time progress updates and resume support.

🛠️ Code Agent Improvements

• Enhanced debugging capabilities
• Structured tool role messages
• Bug fixes and deprecated tool cleanup

🔗 Unified --base-url CLI Support

Use custom Lemonade Server URLs across all commands:

gaia chat --base-url http://custom-server:8000

Improvements

• Evaluation: Transcript validation, extended timeouts, resume/retry for groundtruth
• Security: Path traversal prevention with PathValidator
• Infrastructure: Constants refactoring, localhost reference updates
• Developer Experience: API documentation, Lemonade MSI installer, Node.js v20 VSCode prereq
• CI/CD: Workflow updates

Full Changelog: v0.13.0...v0.14.0

v0.13.0

GAIA v0.13.0 Release Notes

Overview

This major release introduces GAIA Code, a proof-of-concept AI coding agent with VSCode integration, and a Docker Agent for containerized workflows. Most significantly, this release establishes a new architecture that allows GAIA agents to be easily built, and to be exposed via API, MCP, and CLI, opening up extensive possibilities for agent composition and integration. The release also includes improvements to the evaluation framework and enhanced documentation for building custom agents.

What's New

🚀 GAIA Code Agent with VSCode Integration (#774, #864)

Introduced a proof-of-concept AI-powered coding agent with Visual Studio Code integration:

• In-Editor Development: Trigger GAIA Code Agent from VSCode via extension coupled with GitHub Copilot
• Automated Code Generation: Generate Python code from natural language descriptions
• Test-Driven Development: Automatic test generation and execution
• Iterative Refinement: Multi-iteration approach to code quality
• File Context Awareness: Automatic workspace file monitoring and context

Note: GAIA Code is currently a proof-of-concept focused on Python development workflows.

Files Changed: src/gaia/agents/code/, VSCode extension files

🐳 Docker Agent (#811, #833)

New proof-of-concept Docker agent for containerized application development:

• Container Management: Create, start, stop, and manage Docker containers
• Image Building: Automated Dockerfile generation and image builds
• Docker Compose Support: Multi-container orchestration capabilities
• Isolated Environments: Containerized development environments for projects

Note: The Docker Agent is currently a proof-of-concept demonstrating containerized workflow automation.

🏗️ Agent Architecture: Multi-Protocol Exposure (#846)

Major architectural enhancement enabling GAIA agents to be exposed through multiple interfaces:

• API Exposure: RESTful API endpoints for agent interactions
• MCP (Model Context Protocol): Native MCP server support for agent communication
• CLI Interface: Command-line access to agent capabilities
• Unified Pattern: Class inheritance-based design pattern for building new agents

This architecture opens up powerful possibilities:

• Integrate agents into existing tools and workflows
• Build custom agents using established patterns
• Mix and match communication protocols based on needs

Improvements

🔧 Evaluation Framework Improvements

Fix: Remove Silent Fallback in Transcript Matching (#843)

Improved error handling in evaluation transcript matching:

• Fail-Fast Approach: Clear failures instead of silent fallbacks
• Better Debugging: Improved error messages for mismatches
• Data Integrity: Ensures evaluation data consistency

Restore Python Execution Tools (#839)

Re-added essential Python execution capabilities:

• Restored run_test tool for test execution
• Restored execute_python_file tool for script running
• Better integration with code agent workflows

Getting Started with Custom Agents

With the new agent architecture, building custom agents is straightforward. Agents can inherit from base classes and automatically gain API, MCP, and CLI exposure. See the updated documentation for examples and best practices.

v0.12.1

GAIA v0.12.1 Release Notes

Overview

This patch release focuses on bug fixes and improvements to the evaluation framework, particularly addressing issues with the visualization and reporting tools. All changes improve the reliability and usability of the gaia eval, gaia visualize, and gaia report commands.

What's Changed

Bug Fixes

🔧 Fix Evaluation Visualizer Model Count and Path Issues (#823)

Fixed multiple critical issues in the gaia visualize and gaia report commands:

• Incorrect Model Count in Consolidated Report: Fixed model count calculation in the webapp to show the correct number of models (was showing only 4 instead of 8)

  • Now calculates unique models directly from metadata.evaluation_files instead of filtered/grouped data

• Windows Path Separator Bug: Fixed cross-platform compatibility issue in isMainEvaluationEntry() function

  • Now handles both Unix (/) and Windows (\) path separators correctly

• Incorrect Default Directory Paths: Updated default paths to match actual evaluation output locations

  • Changed from workspace/evaluation to workspace/output/evaluations
  • Changed from workspace/experiments to workspace/output/experiments

• Outdated Report Filename: Updated default report filename from LLM_RAG_Evaluation_Report.md to LLM_Evaluation_Report.md

  • Better reflects support for multiple evaluation types (RAG, summarization, etc.)

Files Changed: src/gaia/cli.py, src/gaia/eval/eval.py, src/gaia/eval/webapp/public/app.js

Improvements

📊 Standardize Evaluation Workflow Default Directories (#820)

Implemented consistent default parameters across all evaluation commands with a unified directory structure:

./output/
├── test_data/          # gaia generate
├── groundtruth/        # gaia groundtruth
├── experiments/        # gaia batch-experiment
└── evaluations/        # gaia eval

Key Changes:

• Added centralized directory constants in cli.py
• Added GAIA_WORKSPACE environment variable support for flexible workspace management
• Updated all command defaults to use the new structure
• Updated documentation in docs/eval.md and docs/cli.md

Benefits:

• Consistency: All evaluation artifacts organized in one location
• Maintainability: Centralized constants eliminate duplication
• Flexibility: Workspace environment variable for managing multiple projects
• Cleanup: Single directory to clean or ignore

Files Changed: Multiple files including CLI, evaluation modules, webapp components, and documentation

🏷️ Improve Reporting for Cloud Model Identifiers (#834)

Enhanced model counting logic in the Evaluation Visualizer to support additional cloud model identifiers:

• Added support for 'gpt-4' and 'gemini' model identifiers
• Improved accuracy of model classification in reports

Files Changed: src/gaia/eval/webapp/public/app.js

Contributors

• Kalin Ovtcharov (@kalin-ovtcharov)

Upgrade Notes

If you have existing evaluation workflows, note the following directory changes:

• ./evaluation → ./output/evaluations
• ./experiments → ./output/experiments

You can set the GAIA_WORKSPACE environment variable to use a custom workspace location if needed.

---

Full Changelog: v0.12.0...v0.12.1

v0.12.0

Release v0.12.0 - Docker Agent Integration

Features & Enhancements

Docker Agent Integration (#810, #811)

• Added Docker agent for natural language containerization with AI-powered Dockerfile generation
• Implemented modular MCP architecture with per-agent server support using FastMCP
• Created gaia mcp docker command for standalone Docker agent MCP server
• Added Docker application framework for testing and demonstrations
• Enhanced agent system with MCPAgent base class for Model Context Protocol support

Model Improvements

• Updated default model to Qwen3-Coder-30B-A3B-Instruct-GGUF for improved code generation performance
• Optimized Dockerfile generation with multi-step planning and validation

Architecture Improvements

• Implemented AgentMCPServer for wrapping MCP agents and exposing them via HTTP + JSON-RPC
• Refactored MCP transport layer for better modularity and agent isolation
• Enhanced agent execution with detailed status reporting and result handling

Documentation

• Comprehensive Docker agent documentation with setup and usage examples (docker.md)
• Updated MCP documentation with Docker agent integration guide (mcp.md)
• Added CLI examples for Docker agent workflows

Demo

gaia-docker.mp4

v0.11.2

Release Notes - v0.11.2

Features & Enhancements

Eval Framework Improvements (#784)

• Added chat template support for better model compatibility
• Implemented thinking token extraction for advanced analysis
• Enhanced batch experiment runner with multi-model configuration support
• Expanded evaluation documentation and webapp UI improvements
• Added new multi_model_summarization.json configuration

Updates

Lemonade Backend (#818)

• Updated to Lemonade v8.1.12

Documentation

Developer Documentation (#803)

• Clarified repository structure and development workflow
• Updated release process documentation

Changes Summary

• 20 files changed, 948 insertions(+), 603 deletions(-)
• Focus areas: evaluation framework enhancements, model compatibility, and documentation clarity

v0.11.1

Architecture Improvements

• Code quality improvements — Improved static analysis and cleaned up the codebase
• Static analysis cleanup — Resolved warnings and reduced false positives

Testing & CI/CD

• Lint workflow — Expanded CI to run comprehensive linting, type checks, security scans, and import smoke tests
• Local dev tooling — Added a helper script (util/lint.ps1) to run and optionally fix checks locally

Bug Fixes

• Filesystem — Prevent unintended directory creation when no new directory is required

Documentation

• Model installation — Clarified how to install/manage additional models via Lemonade model manager; cross-linked in CLI guide and FAQ

Full Changelog: v0.11.0...v0.11.1

v0.11.0

App Development Framework

Electron-based framework for building AI-powered desktop applications.

• Example app template — Ready-to-use MCP integration demo
• NPM integration — Streamlined development workflows
• CI/CD automation — GitHub workflows for building and packaging

JAX Desktop Application

Electron-based Jira Dashboard with integrated AI assistant.

• Desktop App — Projects, issues, search, and creation
• System status — Real-time GAIA and MCP Bridge monitoring
• AI chat assistant — Context-aware help for Jira workflows

n8n Workflow Integration

Complete integration guide with pre-built workflow templates.

• Pre-built templates — Common automation scenarios
• HTTP integration — Simple REST API calls to MCP server
• Example workflows — Email summarization, Jira automation, content
  generation

Architecture Improvements

• Enhanced agent system — Improved state management and tool registry
• Blender agent refactoring — Package renamed to lowercase
  agents/blender/ for consistency
• Streaming support — Real-time response streaming throughout agent
  interactions

Testing & CI/CD

• Jira agent tests — Complete test suite with interactive mode
• MCP integration tests — Dedicated test workflows for Windows and Linux
• Enhanced CI/CD — App building workflows and automated testing

Documentation

New comprehensive guides for MCP integration, n8n workflows, Jira agent
usage, and app development.

jira-app-demo-01.mp4

v0.10.1

GAIA v0.10.1 Release Notes

🌟 TL;DR - Key Highlights

• 📄 Document Q&A Evaluation - Process PDF documents and evaluate AI models on question-answering tasks
• 🛠️ Installation Fixes - Resolved critical installer issues with shortcuts and CLI launching
• 🔧 Build Infrastructure - Added GitHub workflows for future app distribution
• 🔄 Updated Dependencies - Latest RAUX (v0.2.4) and Lemonade (v8.1.5) for improved stability

🚀 New Features

Document Q&A Evaluation Support

Enhanced the evaluation framework with comprehensive PDF processing capabilities for question-answering experiments.

• PDF text extraction using the pypdf library for local document processing
• Dedicated Q&A configuration (basic_qa.json) for document-based evaluation experiments
• Enhanced groundtruth consolidation for Q&A pairs and RAG use cases
• Document content caching for improved performance during batch experiments

💡 Quick Start:

# Generate Q&A groundtruth from PDFs
gaia groundtruth -d ./data/pdf --use-case qa --num-samples 3 -o ./groundtruth

# Run Q&A experiments
gaia batch-experiment -c ./src/gaia/eval/configs/basic_qa.json -i ./groundtruth/consolidated_qa_groundtruth.json -o ./experiments

# Evaluate and visualize results
gaia eval -d ./experiments -o ./evaluation
gaia visualize --experiments-dir ./experiments --evaluations-dir ./evaluation

GitHub Workflows for App Distribution

Added foundational infrastructure for building and packaging GAIA mini-apps:

• PR validation workflows for app builds
• Release build automation
• Automated packaging workflows

🐛 Bug Fixes

• Fix gaia visualize webapp not found error
• Installer improvements - Fixed NSIS installer flow for proper shortcut creation after RAUX installation
• CLI launching - Resolved issues with launch_gaia.bat --cli execution
• Package distribution - Added missing package extras ([talk,dev,eval,youtube,audio]) to installer
• CI/CD enhancements - Improved release script to exclude test workflows from distribution

🔄 Updates

• RAUX Integration updated to version 0.2.4 (v0.6.5+raux.0.2.4) fixing installation failures that showed blank screens instead of error messages in the terminal display
• Lemonade Backend updated to version 8.1.5 for improved performance and stability
• Package structure - Updated setup.py with complete module structure (chat, talk, apps, eval, mcp, agents)
• Added Discord label

📖 Documentation

The Document Q&A evaluation workflow is documented in detail at
https://github.com/aigdat/gaia/blob/main/docs/eval.md#workflow-3-document-qa.