v0.17.5

GAIA v0.17.5 Release Notes

GAIA v0.17.5 swaps the default model to Gemma 4 E4B, adds Chat Lite for machines that cannot host the 35B default, ships the Agent UI inside the PyPI wheel, and lands semantic code search and an optional governance layer. The C++ SDK gains VLM image support, mobile-tunnel diagnostics get a usability pass, and seven targeted bug fixes round out the patch.

Why upgrade:

• Gemma 4 E4B is the new default across LLM and VLM roles — single model in place of the previous LLM/VLM split, ~4.5B effective parameters, 128K context, ~5 GB footprint vs 19.7 GB previously.
• Chat Lite makes the Agent UI usable on 8–16 GB machines — a Qwen3-4B sibling of ChatAgent plus Settings controls for active model, context size, and per-agent memory warnings.
• pip install amd-gaia[ui] now serves the real React UI — the wheel contains the built dist/, byte-identical to the npm package.
• Semantic code search lands in CodeAgent — gaia-code index plus the code_index tool mixin for FAISS-backed search across your repo.

---

What's New

Gemma 4 E4B as the New Default Model

Gemma 4 E4B (Gemma-4-E4B-it-GGUF) replaces Qwen 3.5 35B and the separate Qwen 3-VL-4B as the single default across the LLM and VLM roles, the installer profiles, the CLI, the Agent UI, and the eval suite (PR #865). Gemma 4 is natively multimodal at ~4.5B effective parameters with a 128K context window and an Apache 2.0 licence, so one model now covers what previously required loading two. The post-swap eval baseline beats the pre-swap Qwen baseline 14/15 vs 13/15 across the bundled scenarios.

The minimum Lemonade version is now 10.2.0, and Lemonade's default port moves from 8000 to 13305 to match Lemonade's own default. A startup validator (_validate_profile_model_registry()) raises at import time if any AGENT_PROFILES entry references a model key that is not in MODELS.

---

Native OpenAI tool_calls Path

GAIA now passes tools=[...] to Lemonade for tool-capable models and consumes the response as native OpenAI tool_calls (PR #865). LemonadeProvider.chat() encodes tool calls as a sentinel JSON string ({"__tool_calls__": ...}) so existing callers keep their type signatures, and _parse_llm_response detects the sentinel to return the unified {"tool": ..., "tool_args": ...} dict downstream agents already use. The embedded-JSON format block (_PLANNING_FORMAT / _CONVERSATIONAL_FORMAT) is now excluded from the composed system prompt for tool-capable models — its presence actively prevented native tool_calls in prior testing. The legacy embedded-JSON path remains as a fallback for non-tool-calling models.

---

Chat Lite + Settings Controls

chat-lite is a new built-in agent that reuses ChatAgent but presets model_id to Qwen3-4B-Instruct-2507-GGUF, providing a working out-of-the-box option for hardware that cannot host the 35B Chat default (PR #802). It appears alongside Chat in the agent picker.

To make per-agent model swapping practical, three new Settings controls land in the Agent UI:

• Active Model — text field bound to the existing custom_model setting, with "Use agent default" as the placeholder. Empty falls through to the agent's registered models[0].
• Context Size — preset chips (4K / 8K / 16K / 32K) plus a numeric input; Apply reloads the active model via /api/system/load-model.
• Memory Warnings — AgentInfo.min_memory_gb is a new optional field on registrations and manifests; Settings renders a warning before the user picks an agent whose requirement exceeds available memory.

The pre-flight model loader in _chat_helpers.py now requires the specific expected model with ctx ≥ 32K rather than accepting any active LLM at any context size. This fixes the silent-truncation bug where Lemonade auto-loaded a requested model at its 4096 default context, truncating ChatAgent's >7K-token system prompt and producing an empty stream.

---

Semantic Code Search via CodeAgent

CodeIndexToolsMixin adds FAISS-backed semantic search of a codebase to CodeAgent (PR #721). Four @tool methods (index_codebase, search_code_index, get_index_status, clear_code_index) compose into the agent via MRO, the same pattern as RAGToolsMixin and FileIOToolsMixin. The mixin is registered in KNOWN_TOOLS so other agents can opt in with tools=["code_index"].

The gaia-code index subcommand replaces the removed top-level gaia index verb; all index operations (search, status, clear, chat) now live under the existing gaia-code standalone binary. Indexing the GAIA repo itself produces 973 files → 24,349 semantic chunks using nomic-embed-text-v2-moe-GGUF via Lemonade Server. The [code-index] extras group has been folded into [rag], so the install command is pip install -e '.[rag]'.

---

Agent UI Bundled in the PyPI Wheel

pip install amd-gaia[ui] && gaia chat --ui now serves a real React UI instead of the JSON / friendly-fallback page (PR #908). setup.py adds gaia.apps.webui to packages with package_data globs, and MANIFEST.in adds the authoritative recursive-include for the built dist/. Local builds produce a 1.41 MB wheel containing the nine webui assets (index.html, hashed JS/CSS, woff2 fonts, favicon).

The publish pipeline now builds the bundle once in build-npm and reuses the artifact in build-pypi, so the wheel and the npm package ship a byte-identical bundle (no vite-hash drift between runners). A new util/verify_wheel_dist.py enforces a deny-list at CI time: sourcemaps, dotfiles, node_modules, and leaked VITE_* env values, plus wheel-size caps. setup.py raises SystemExit with a remediation hint if a wheel build cannot find dist/index.html, except on the sdist, egg_info, develop, and editable_wheel paths used by pip install -e ..

---

Optional Governance Layer

A new gaia.governance package adds an opt-in action-level governance layer for GAIA agents, with extension points for future workflow-level features (PR #921). The framework is modular: developers mix in GovernedAgentMixin, tag tools with risk levels, and configure a policy engine, reviewer, and audit log. GaiaGovernanceAdapter composes policy evaluation, checkpointing, receipt issuance, and policy-version binding into a single entry point, returning ALLOW / BLOCK / REVIEW decisions per tool call.

The package ships with a comprehensive README.md and an examples/governed_weather_agent.py end-to-end demo. Because the layer is opt-in via mixin composition, existing agents are unaffected unless they explicitly enable it.

---

Agent Eval Toolchain

The Agent Eval suite is now a complete toolchain (PR #779): runner.py accepts custom --scenario-dir / --corpus-dir paths, tag filtering via --tag, JUnit XML output (--output-format junit), and custom personas. The CLI sheds the legacy gaia groundtruth, gaia report, gaia visualize, gaia create-template, gaia batch-experiment, and gaia synthetic-data commands (~1,900 lines). 27 test classes cover the full public API surface (scenario loading, runner, scorecard, corpus, CLI, audit), and three new guides land under docs/guides/eval.mdx (Getting Started, Scenario Authoring, CI/CD Integration). Roughly 15,879 lines of dead code in the previous evaluator, groundtruth generator, batch experiment runner, transcript/email generators, fix-code testbench, and Express.js webapp are removed.

---

VLM Image Support in the C++ SDK

The C++ SDK gains end-to-end vision support (PR #858). gaia::Image factories (fromBytes / fromFile) handle RFC 4648 base64 encoding, magic-byte MIME detection (PNG / JPEG / GIF / WebP / BMP), a 20 MiB size cap, and an O_NOFOLLOW + post-open fstat TOCTOU guard on POSIX. gaia::ContentPart adds text and image_url parts with toJson() producing the OpenAI vision wire format, and gaia::Message gains an additive std::optional<std::vector<ContentPart>> parts field that dispatches toJson() to array or string form — fully backward-compatible with existing aggregate-init sites.

Two new processQuery overloads (string + vector<Image> and vector<Message> caller-composed) flow through a private processQueryInternal that is the sole writer of conversationHistory_. Image parts are stripped from history at end-of-turn so base64 is never retained across calls. An RAII InFlightGuard via std::atomic<bool> and compare_exchange_strong makes concurrent processQuery calls on the same Agent throw std::runtime_error. The cpp/examples/vlm_agent.cpp demo plus 35 new unit tests (Image, ContentPart / Message, agent-level mock HTTP) cover the surface, alongside an integration test against live Lemonade.

---

Friendly ngrok Tunnel Diagnostics + Mobile Cookie Auth

Mobile Access used to surface raw ngrok stderr (ERR_NGROK_107, dial tcp ... no such host, or in the worst case nothing) when a tunnel failed to start. PR #872 parses every common ngrok failure into actionable guidance the modal renders verbatim. A preflight _check_ngrok_authtoken_configured honours $NGROK_AUTHTOKEN first, then v2 flat / v3 nested config layouts, and catches the unconfigured case before spawn. _parse_ngrok_error matches error codes plus English fragments and returns ready-to-paste install/config commands.

The same PR adds an HttpOnly-cookie auth path so opening the QR-code URL in a mobile browser Just Works: ?token=<uuid> in the URL is converted to a gaia_tunnel_token cookie on the SPA landing response, so React's same-origin fetch('/api/...') is authen...

v0.17.4

GAIA v0.17.4 Release Notes

GAIA v0.17.4 is a patch release covering two correctness fixes in the Agent UI custom-agent path, a null-safety fix in the C++ library for smaller LLMs, and a broken docs citation.

Why upgrade:

• Custom agents use their declared model — If a custom agent sets a model via kwargs.setdefault("model_id", ...), the Agent UI now respects that setting when the session is at the DB default, instead of falling back to the session model.
• Compatibility with smaller LLMs in the C++ library — The C++ JSON parser now tolerates null values in "tool" and "content" fields, which some smaller models emit in place of omitting the field.

---

What's New

Custom Agent model_id Respected in the Agent UI

_chat_helpers.py previously passed model_id=<session model> explicitly to registry.create_agent(), which defeated kwargs.setdefault("model_id", ...) in custom agents — setdefault only fires when the key is absent (PR #841). The Agent UI now builds create_kwargs conditionally, omitting model_id when the session is at the DB default so the agent's __init__ setdefault governs. Three-branch precedence is now explicit: custom_model setting > session-explicit model > agent's own setdefault.

A follow-up fix (PR #842) restored the pre-construction model_id as the agent-cache key. The initial PR #841 landing had switched _store_agent to use the post-construction _effective_model(agent, model_id) while _get_cached_agent still looked up with model_id, so keys never matched for custom-model agents and the agent was rebuilt on every turn. A two-turn cache-hit regression test and a static guard on _store_agent call sites were added alongside the fix.

Supporting refactor: extracted _build_create_kwargs() and _effective_model() helpers in src/gaia/ui/_chat_helpers.py to deduplicate the three-branch logic across streaming and non-streaming paths, and exported SESSION_DEFAULT_MODEL from database.py as the single source of truth.

---

C++ Library: Null-Safety in LLM Response Parsing

parseLlmResponse() in cpp/src/json_utils.cpp now guards .get<std::string>() calls on the "tool" and "answer" JSON fields with .is_string() / .is_null() checks (PR #780). This fixes a crash (json.exception.type_error.302: type must be string, but is null) when smaller LLMs (for example qwen3.5:9b) return null for those fields instead of omitting them. json.contains() returns true for null values, so the existing presence checks were insufficient.

---

Bug Fixes

• Email-triage agent plan: broken CMU citation link (PR #817) — Swapped the failing www.cs.cmu.edu/~tom/EMNLP2004_final.pdf URL in docs/plans/email-triage-agent.mdx for the canonical ACL Anthology record at W04-3240. The CMU URL was failing DNS resolution in CI, breaking the Verify external URLs check on every open docs PR. Restored the paper's full title ("Learning to Classify Email into 'Speech Acts'") for consistency with other citations in the same references list.

---

Full Changelog

5 commits since v0.17.3:

• 8fc43f3f — fix(cpp): add null-safety checks for JSON string fields in LLM response parsing (#780)
• 62722de2 — fix(ui): honor custom agent model_id when session is at DB default (#841)
• 4acfd400 — fix(ui): extract _build_create_kwargs/_effective_model, import SESSION_DEFAULT_MODEL
• 8f5c7621 — fix(ui): restore intent-key for agent cache store to fix miss regression (#842)
• a0fdb109 — docs(plans): fix broken CMU link to EMNLP 2004 Email Speech Acts paper (#817)

Full Changelog: v0.17.3...v0.17.4

---

Installation

Desktop installer (recommended for end users)

Download the installer for your platform from the assets below:

• Windows — gaia-agent-ui-*-x64-setup.exe (NSIS installer, autostart on by default)
• macOS — gaia-agent-ui-*-arm64.dmg (drag to Applications, Apple Silicon only)
• Linux — gaia-agent-ui-*-amd64.deb (Debian/Ubuntu) or gaia-agent-ui-*-x86_64.AppImage (any distro)

On first launch the app sets up its Python backend automatically (~5–10 minutes for the minimal profile, depends on your internet speed).

See the installation guide for setup details and troubleshooting.

Developer install (Python CLI)

Install GAIA using pip:

pip install amd-gaia

Or using uv:

uv pip install amd-gaia

Or via npm:

npm install -g @amd-gaia/agent-ui

v0.17.3

GAIA v0.17.3 Release Notes

GAIA v0.17.3 is an extensibility and resilience release. You can now package your own agents into a custom GAIA installer and seed them on first launch, point GAIA at alternative OpenAI-compatible inference servers from the C++ library (Ollama, for example), and start from three new reference agents (weather, RAG Q&A, HTML mockup) that execute against real Lemonade hardware in CI. It also hardens the RAG cache against an insecure-deserialization class of bug (CWE-502) — all users should upgrade.

Why upgrade:

• Ship your own GAIA — Export and import agents between machines, follow a new guide to produce a custom installer that seeds your agents on first launch, and on Windows install everything in one step because the installer now includes the Lemonade Server MSI.
• Work with alternative inference backends — The C++ library now preserves OpenAI-compatible /v1 base URLs instead of rewriting them to /api/v1, so servers that expose the standard /v1 path (Ollama, for example) work out of the box.
• Start from a working example — Three new reference agents (weather via MCP, RAG document Q&A, HTML landing-page generator) with integration tests that actually execute against Lemonade on a Strix CI runner.
• Safer RAG cache — Replaces pickle deserialization with JSON + HMAC-SHA256 (CWE-502). Unsigned or tampered caches are rejected and transparently rebuilt on the next query.
• Better document handling — Encrypted or corrupted PDFs now produce distinct, actionable errors (EncryptedPDFError, CorruptedPDFError) instead of generic failures, and the RAG index is hardened for concurrent queries.

---

What's New

Custom Installers and Agent Portability

You can now package a custom GAIA installer that ships with your own agents pre-loaded, and move agents between machines with export/import (PR #795). On Windows, the official installer now includes the Lemonade Server MSI and runs it during install, so a fresh machine has the complete local-LLM stack after a single download (PR #781).

What you can do:

• Export an agent from ~/.gaia/agents/ to a portable bundle with gaia agents export and import it on another machine with gaia agents import
• Follow the new custom-installer playbook at docs/playbooks/custom-installer/index.mdx to distribute GAIA with your agents pre-loaded — useful for workshops, team deployments, and internal tooling
• On Windows, the installer now includes Lemonade Server — no separate download for a complete first-run experience

Under the hood:

• gaia agents export / gaia agents import CLI commands round-trip agents between machines as portable bundles
• First-launch agent seeder (src/gaia/apps/webui/services/agent-seeder.cjs) copies <resourcesPath>/agents/<id>/ into ~/.gaia/agents/<id>/ the first time the app starts
• Windows NSIS installer embeds lemonade-server-minimal.msi into $PLUGINSDIR and runs it via msiexec /i ... /qn /norestart during install (auto-cleaned on exit)

---

Broader Backend Compatibility in the C++ Library

The C++ library now preserves OpenAI-compatible /v1 base URLs (PR #773) instead of rewriting them to /api/v1. That means inference servers that expose the standard OpenAI /v1 path — for example, Ollama at http://localhost:11434/v1 — work out of the box without needing a special adapter.

---

Reference Agents and Real-Hardware Integration Tests

Three new example agents and a Strix-runner CI workflow land together (PR #340).

What you can do:

• Copy examples/weather_agent.py, examples/rag_doc_agent.py, or examples/product_mockup_agent.py as a starting point for your own agents
• Run the new integration tests locally against Lemonade to validate agents end-to-end, not just structurally

Under the hood:

• tests/integration/test_example_agents.py executes agents and validates responses with a 5-minute-per-test timeout
• .github/workflows/test_examples.yml runs on the self-hosted Strix runner (stx label) with Lemonade serving Qwen3-4B-Instruct-2507-GGUF
• Docs homepage refreshed with a technical value prop ("Agent SDK for AMD Ryzen AI") and MCP / CUA added to the capabilities list

---

Smarter PDF Handling in RAG

Encrypted and corrupted PDFs now surface as distinct, actionable errors (EncryptedPDFError, CorruptedPDFError, EmptyPDFError) instead of generic failures or silent 0-chunk indexes (PR #784, closes #451). Encrypted PDFs are detected before extraction; corrupted PDFs are caught during extraction with a clear message. Combined with the indexing-failure surfacing in PR #723, you get a visible indexing-failed status the moment a document fails — and the RAG index itself is now thread-safe under concurrent queries (PR #746).

---

Security

RAG Cache Deserialization Replaced with JSON + HMAC

Fixes an insecure-deserialization issue in the RAG cache (CWE-502, PR #768). Previously, cached document indexes were serialized with Python pickle; if an attacker could write to ~/.gaia/ — via a shared drive, a sync conflict, or a malicious extension — loading that cache could execute arbitrary code.

v0.17.3 replaces pickle with signed JSON: caches are now serialized as JSON and authenticated with HMAC-SHA256 using a per-install key stored at ~/.gaia/cache/hmac.key. Unsigned or tampered caches are rejected and transparently rebuilt on the next query. Old .pkl caches from previous GAIA versions are ignored and re-indexed the next time you query a document.

You should upgrade if you share ~/.gaia/ across machines (Dropbox, iCloud, network home directories), run GAIA in a multi-user environment, or have ever imported RAG caches from another source.

---

Bug Fixes

• Ask Agent attaches files before sending to chat (PR #725) — Dropped files are indexed into RAG and attached to the active session before the prompt is consumed, so the model sees the document on the first turn instead of the second.
• Document indexing failures are surfaced (PR #723) — A document that produces 0 chunks now raises RuntimeError in the SDK and surfaces as indexing_status: failed in the UI, instead of looking like a silent success. Covers RAG SDK, background indexing, and re-index paths.
• Encrypted or corrupted PDFs produce actionable errors (PR #784, closes #451) — RAG now raises distinct EncryptedPDFError and CorruptedPDFError exceptions instead of generic failures, so you see exactly what went wrong.
• RAG index thread safety hardened (PR #746) — Adds RLock protection around index mutation paths and rebuilds chunk/index state atomically before publishing it, so concurrent queries read consistent snapshots and failed rebuilds no longer leak partial state.
• MCP JSON-RPC handler guards against non-dict bodies (PR #803) — A malformed JSON-RPC payload (array, string, null) now returns HTTP 400 Invalid Request: expected JSON object instead of an HTTP 500 from a TypeError.
• File-search count aligned with accessible results (PR #754) — The returned count now matches the number of files the tool actually surfaces, instead of a pre-filter total that over-reported results the caller could not access.
• Tracked block cursor replaces misplaced decorative cursor (PR #727) — Fixes the mis-positioned blinking cursor in the chat input box, which now tracks the actual caret position via a mirror-div technique.
• Ad-hoc sign the macOS app bundle instead of skipping code signing (PR #765) — The .app bundle inside the DMG now carries an ad-hoc signature, so Gatekeeper presents a single "Open Anyway" bypass in System Settings instead of the unrecoverable "is damaged" error. Full Apple Developer ID signing is still being finalized.

---

Release & CI

• Publish workflow: single approval gate, no legacy Electron apps (PR #758) — Removed the legacy jira and example standalone Electron apps from the publish pipeline; a single publish environment gate governs PyPI, npm, and installer publishing.
• Claude CI modernization (PR #797, PR #799, PR #783) — Migrated all four claude-code-action call sites to v1.0.99 (pinned by SHA, fixes an issue-handler hang), bumped --max-turns from 20 to 50 on both pr-review and pr-comment for deeper analysis, upgraded to Opus 4.7, standardized 23 subagent definitions with explicit when-to-use sections and tool allowlists, and added agent-builder tooling (manifest schema, lint.py --agents, BuilderAgent mixins).

---

Docs

• Roadmap overhaul (PR #710) — Milestone-aligned plans with voice-first as P0 and 9 new plan documents for upcoming initiatives.
• Plan: email triage agent (PR #796) — Specification for an upcoming email triage agent.
• Docs/source drift resolved (PR #794) — Fixed broken SDK examples across 15 docs, rewrote 5 spec files against the current source (including two that documented entire APIs that don't exist in code), added 20+ missing CLI flags to the CLI reference, and removed 2 already-shipped plan documents (installer, mcp-client).
• FAQ: data-privacy answer clarified for external LLM providers (PR #798) — Sharper guidance on what leaves your machine when you point GAIA at Claude or OpenAI.

---

Full Changelog

21 commits since v0.17.2:

• 6d3f3f71 — fix: replace misplaced decorative cursor with tracked terminal block cursor (#727)
• 874cf2a3 — fix: Ask Agent indexes and attaches files before sending to chat (#725)
• 4fa121e2 — fix: surface document indexing failures instead of silent 0-chunk success (#723)
• 34b1d06e — fix(ci): ad-hoc sign macOS DMG instead of skipping code signing (#765)
• 7188b83c — Roadmap overhaul: milestone-aligned plans with voice-first P0 and 9 new plan documents (#710)
• 1beddac5 — cpp: support Ollama-compatible /v1 endpoints (#773)
• cf9ac995 — fix: harden rag index thread safety (#746)
• 1c55c31b — fix(ci): remove ...

v0.17.2

GAIA v0.17.2 Release Notes

GAIA v0.17.2 makes GAIA a real desktop app. Download a one-click installer for Windows, macOS, or Linux — no Python, no pip, no terminal. Build your own agents by chatting with GAIA. And see exactly which MCP server ran which tool, with latency and filtering, right in the Agent Activity panel.

Why upgrade:

• Install in one click, no terminal required — One-click .exe / .dmg / .deb / .AppImage installers with automatic backend setup on first launch, background auto-updates, and native uninstall. The primary path for non-developer users.
• Build your own agents by chatting with GAIA — The new Builder Agent walks you through creating a custom agent and generates an agent.py for you. Drop Python or YAML agents into ~/.gaia/agents/ and switch between them per conversation.
• See what your MCP tools are actually doing — The Agent Activity panel now shows a "via {server}" badge on every MCP tool call, per-tool latency, and a filter bar to search or filter by status.
• Trust your RAG cache — Cached document indexes are now verified before loading, so a corrupted or tampered cache triggers a clean re-index instead of crashing the RAG system.
• Drag-and-drop uploads work in any browser — Document drops now work in Chrome, Safari, Firefox, and the packaged Electron app — no more "Not found" errors.

---

What's New

One-Click Desktop Installers

GAIA now ships as a native desktop app for every platform (PR #731). Download the installer and double-click — no Python, no pip, no terminal required.

What you can do:

• Download gaia-agent-ui-*.exe (Windows), .dmg (macOS), .deb or .AppImage (Linux) from GitHub Releases
• On first launch, the app downloads uv, creates a Python venv, installs the GAIA backend, and starts Lemonade Server automatically
• When a new version is available, you'll see a "Restart to update" prompt — same flow as Slack or VS Code
• Uninstall via Add/Remove Programs, drag-to-Trash, or apt remove; user data in ~/.gaia/ is preserved unless you explicitly purge it with gaia uninstall

Under the hood:

• Electron shell with first-launch bootstrap: uv + venv + gaia init --yes + Lemonade Server
• Code-signing scaffolding is in place for SignPath (Windows) and Apple Developer ID (macOS) — activates when signing secrets are configured, with zero code changes
• gaia uninstall CLI offers tiered cleanup: --venv, --purge, --purge-lemonade, --purge-models, --purge-hf-cache, --dry-run
• 42 unit tests for gaia uninstall; cross-platform CI via the new build-installers.yml workflow

Note: Windows users may see a SmartScreen prompt and macOS users may see a Gatekeeper dialog on first launch while code-signing is being finalized. Click More info → Run anyway (Windows) or right-click → Open (macOS).

---

Customizable Agents + Builder Agent

GAIA now supports per-session agent selection, and you can create your own agents by chatting with the Builder Agent (PR #720).

What you can do:

• Pick your agent from the selector in the chat footer or WelcomeScreen — switching mid-conversation starts a new session; switching on an empty session updates in place
• Click the "+" button to open the Builder Agent, which asks what you want your agent to do and generates agent.py (with optional MCP scaffolding) — it appears in the selector immediately, no server restart needed
• Drop a Python module (~/.gaia/agents/*/agent.py) or YAML manifest (~/.gaia/agents/*/agent.yaml) in place and it's discovered on the next server restart
• YAML manifests support MCP servers, model preferences, and conversation starters
• The message header shows the agent name — "GAIA My Agent | Thinking" during streaming and "GAIA My Agent | 3m ago" after completion

Under the hood:

• AgentRegistry discovers agents at boot from built-in Python agents, custom Python modules, and YAML manifests
• DispatchQueue boot orchestration runs _check_lemonade and _import_modules in parallel; _load_model runs after Lemonade is ready; all tasks report progress to the frontend
• Sessions store agent_type; the correct agent is instantiated on cache miss
• New guide: docs/guides/custom-agent.mdx
• Closes #612, #713

---

MCP Tool Execution Visibility

The Agent Activity panel now shows exactly which MCP server handled each tool call, how long it took, and lets you filter through long tool traces (PR #717).

What you can do:

• See a purple "via {server}" badge on every MCP tool call, identifying the server that handled it
• See per-tool latency (in ms) in the collapsed tool header
• Use the filter bar — appears when 2+ tool steps exist — to search by tool name or filter by status (All / Success / Error)
• MCP tool cards start collapsed by default to reduce noise; native tools still auto-expand

Under the hood:

• mcp_server added to tool_start SSE events; latency_ms measured at the SSE handler layer via time.monotonic()
• Server name resolved via _TOOL_REGISTRY lookup — no fragile prefix parsing
• No new SSE event types, no DB migration, no new API endpoints
• 11 new unit tests
• Closes #712

---

Security

RAG Cache Integrity Verification

Fixes a cache-deserialization issue where a corrupted or tampered RAG cache file on disk could cause the RAG system to crash or load untrusted data (PR #722, closes #447).

GAIA now verifies an integrity header before loading cached document indexes. If the check fails — corrupted file, wrong format, or oversized data — the cache is deleted automatically and documents are re-indexed on the next query. Old-format caches from previous GAIA versions are migrated transparently on first load.

---

Bug Fixes

• Drag-and-drop document upload works in any browser (PR #729, closes #728) — A new POST /api/documents/upload endpoint accepts file content as multipart form data and works in Chrome, Safari, Firefox, and the packaged Electron 40 app. The previous implementation relied on file.path, an Electron-only property removed in Electron 32. Files are deduplicated by content hash and capped at 20 MB.
• Linux installer: chrome-sandbox SUID bit and non-interactive setup (PR #743) — chrome-sandbox now has its SUID bit set during apt install (fixes immediate crash on Ubuntu 24.04 after package install). gaia init now accepts --yes to auto-answer prompts when invoked by the desktop installer's non-interactive bootstrap (fixes silent model-skip that caused the app to crash on first message).

---

Release & CI

• Unified publish workflow (PR #715) — Consolidated publish_installer.yml, publish-npm-ui.yml, and PyPI publishing into a single publish.yml workflow with one approval gate; PyPI and npm publish in parallel after approval.
• Claude review on fork PRs (PR #685) — Fixed fatal: a branch named 'main' already exists when reviewing fork PRs whose head branch is main.
• npm OIDC publishing (PR #683) — Upgraded npm to 11.5.1+ to enable OIDC trusted publishing (npm 10.9.4 returned ENEEDAUTH).
• webui package.json version sync (PR #682) — Removed -rc.1 suffix from package.json to match the v0.17.1 tag.

---

Full Changelog

10 commits since v0.17.1:

• 83f5148b — feat: MCP tool execution visualization in activity history (#717)
• df7a0ae4 — fix(linux): chrome-sandbox SUID and gaia init non-interactive mode (#743)
• f5b0d396 — feat: desktop installer for GAIA Agent UI (#530) (#731)
• d2ffb967 — fix: drag-and-drop document upload in browser mode (#728) (#729)
• 69155281 — fix: add integrity verification to RAG cache pickle loading (#447) (#722)
• 4d24071a — feat: agent registry with per-session agent selection (#720)
• e4c7a5ef — feat: unified publish workflow with single approval gate (#715)
• 3f52582d — fix: Claude workflow fails on fork PRs when head branch is 'main' (#685)
• 4fe04417 — fix: upgrade npm to 11.5.1+ for OIDC trusted publishing (#683)
• b19d8126 — fix: bump webui package.json version to 0.17.1 (#682)

Full Changelog: v0.17.1...v0.17.2

---

Installation

Desktop installer (recommended for end users)

Download the installer for your platform from the assets below:

• Windows — gaia-agent-ui-*-x64-setup.exe (NSIS installer, autostart on by default)
• macOS — gaia-agent-ui-*-arm64.dmg (drag to Applications, Apple Silicon only)
• Linux — gaia-agent-ui-*-amd64.deb (Debian/Ubuntu) or gaia-agent-ui-*-x86_64.AppImage (any distro)

On first launch the app sets up its Python backend automatically (~5–10 minutes for the minimal profile, depends on your internet speed).

See the installation guide for setup details and troubleshooting.

Developer install (Python CLI)

Install GAIA using pip:

pip install amd-gaia

Or using uv:

uv pip install amd-gaia

Or via npm:

npm install -g @amd-gaia/agent-ui

v0.17.1

GAIA v0.17.1 Release Notes

GAIA v0.17.1 hardens the framework with better version safety, richer eval insights, and a smoother Agent UI setup experience. The C++ agent framework also gains SSE streaming, runtime reconfiguration, and CI benchmarks.

Why upgrade:

• Catch Lemonade mismatches early — GAIA now warns you at startup if your running Lemonade Server version differs from the expected version, so you fix compatibility issues before they bite
• See where eval time goes — Per-turn performance data rolls up into scenario-level summaries in the eval scorecard, making it easy to spot slow steps
• Agent UI works out of the box — gaia init now builds the frontend automatically, so you no longer need a manual npm run build step

---

What's New

Lemonade Version Mismatch Warning

GAIA now detects when your running Lemonade Server version differs from the expected version and displays a clear warning with upgrade instructions (PR #637). No more silent incompatibilities.

Eval Performance Tracking

The eval scorecard now aggregates per-turn performance data — token counts, latency, throughput — into scenario-level summaries, so you can identify bottlenecks across multi-step evaluations (PR #637).

MCP Inference Stats

MCP responses now capture inference statistics from SSE events, giving you visibility into model performance during tool-augmented conversations (PR #637).

Agent UI Frontend Auto-Build

gaia init now builds the Agent UI frontend automatically via a new _ensure_webui_built() helper extracted into gaia/ui/build.py (PR #657). The Agent UI documentation prerequisites have also been corrected. Includes 7 new unit tests.

---

C++ Agent Framework

The C++ agent framework continues to mature with three updates:

• SSE streaming — SseParser for chunked SSE delivery, LemonadeClient streaming via httplib, and console streaming helpers. Enable with GAIA_STREAMING=1. Includes 18 new SSE parser tests (PR #518)
• Runtime reconfiguration — AgentConfig serialization, environment variable overrides (GAIA_BASE_URL, GAIA_MODEL_ID, etc.), dynamic setters (setModel(), setConfig(), setMaxSteps()), and thread-safe tool enable/disable via ToolRegistry (PR #531)
• Performance benchmarks — New benchmark_cpp.yml CI workflow tracks binary size, startup time, loop latency, and memory. PR runs compare against cached baselines with configurable thresholds (PR #519)

---

Bug Fixes

• MCP test isolation — Added isolate_home autouse fixture to prevent unit tests from reading or writing to the real ~/.gaia/mcp_servers.json (PR #658)
• npm publish — Switched to OIDC trusted publishing and removed registry-url to enable it (PRs #638, #639)
• Merge queue notifications — Resolved phantom failures in the merge-queue-notify workflow (PR #640)

---

Full Changelog

9 commits since v0.17.0:

• 780a711 - feat: Lemonade version mismatch warning, eval perf tracking, MCP stats (#637)
• 7ed2db3 - feat(cpp): SSE streaming response support for C++ agent framework (#518)
• 9c4101d - feat(cpp): performance benchmarks and binary size tracking (#519)
• 878a976 - feat(cpp): runtime configuration and dynamic reconfiguration (#531)
• e0e5695 - fix: isolate MCP unit tests from real ~/.gaia/mcp_servers.json (#658)
• bb010a0 - fix: build Agent UI frontend in gaia init and fix doc prerequisites (#657)
• 334b011 - fix: remove registry-url to enable OIDC trusted publishing (#639)
• 776dc34 - fix: resolve merge-queue-notify phantom failures (#640)
• 83a4db1 - fix: switch npm publish to OIDC trusted publishing (#638)

Full Changelog: v0.17.0...v0.17.1

v0.17.0

GAIA v0.17.0 Release Notes

Run AI agents locally on your PC — analyze documents, execute tools, and accomplish tasks without sending data to the cloud. GAIA v0.17.0 introduces the Agent UI, a privacy-first web application that puts a local AI agent on your AMD hardware.

npm install -g @amd-gaia/agent-ui
gaia-ui

Why upgrade:

• Keep sensitive documents on your machine — Ask questions about medical records, contracts, financial data, or any of 53+ file types and get answers with page citations. Nothing leaves your PC — the agent runs 100% locally on your AMD hardware
• An AI agent you can trust — Tool guardrails require your approval before the agent executes commands or writes files, so you stay in control of what happens on your machine
• Works on modest hardware — A 78% smaller system prompt means GAIA now runs reliably on smaller models like Qwen3.5 without timeouts, so you don't need top-tier hardware to get started
• Access from anywhere — Built-in ngrok tunnel lets you use your local GAIA instance from your phone or tablet while your data stays on your PC

Get started with the Agent UI guide — install, launch, and run your first task in under 60 seconds.

---

What's New

GAIA Agent UI

A privacy-first web application for running AI agents locally on your AMD hardware (PR #428). Analyze documents, generate code, search files, execute tools, and accomplish tasks — without sending anything to the cloud.

What you can do:

• Analyze your documents — Drag-and-drop PDFs, Word docs, or any of 53+ file formats and get answers with page-level citations, powered by local RAG
• Execute tools safely — The agent can run shell commands, write files, and use MCP tools — but only after you approve each action
• Search and browse files — The agent can find files, explore directories, and locate content across your projects
• Access from your phone — Built-in ngrok tunnel lets you use your local GAIA instance from any device
• Watch the agent think — Real-time streaming with <think> block rendering shows the agent's reasoning process inline
• Pick up where you left off — Create, switch, and persist sessions with full history
• Monitor performance — Hover tooltips show token counts, latency, and throughput metrics per response

Under the hood:

• FastAPI backend + React/TypeScript frontend + Electron shell with SSE streaming
• Redesigned Settings modal with system dashboard, model load/download actions, and live MCP server connection status with tool counts
• Terminal-inspired design: typewriter welcome animation, pixelated AMD cursor with red glow, glassmorphism, smooth crossfade transitions (PR #568)
• prefers-reduced-motion support — all animations respect OS accessibility settings
• Path traversal prevention, SQL parameterization, and input validation throughout
• 13+ bug fixes across backend, frontend, and integration layers

npm install -g @amd-gaia/agent-ui
gaia-ui

See the Agent UI guide for full setup, prerequisites, and onboarding.

---

Tool Execution Guardrails

AI agents are powerful but can be unpredictable. This release adds a safety layer so you approve every sensitive action before it happens (PR #565):

• Confirmation popup — Allow, Deny, or Always Allow before run_shell_command and other write/execute tools
• 60-second timeout — Auto-denies if you don't respond within a minute
• Expanded coverage — Extended to cover all write/execute tools, not just shell commands (PR #604)

---

Device Support Detection

Not sure if your hardware is supported? GAIA now tells you upfront and offers workarounds (PR #593):

• Supported devices — AMD Ryzen AI Max processors and AMD Radeon GPUs with ≥24 GB VRAM
• Clear banner messaging — Shows your processor name and links to a GitHub feature-request
• --base-url flag — Point to a remote Lemonade Server to use GAIA on any machine
• GAIA_SKIP_DEVICE_CHECK=1 — Environment variable override for advanced users

---

System Prompt Optimization

If you previously experienced timeouts or slow first responses on smaller models, this release fixes that (PR #617):

• 17,600 → 3,853 tokens (78% reduction) — Two-tier RAG gating only injects document context when relevant, meaning 4–5× faster prompt processing
• Qwen3.5 timeouts eliminated — Smaller prompt fits within context window of constrained models
• Timeout increased to 600s — Prevents premature timeouts on complex queries

---

Security

• Document upload vulnerability fixed — Closed a TOCTOU race condition that could allow file substitution during upload. Now uses atomic O_NOFOLLOW + fstat validation and serializes concurrent uploads via per-file asyncio.Lock (PR #564)

---

Bug Fixes

• LRU eviction silent failure — Fixed unbounded memory growth: added pre-flight rejection at capacity, logging on all failure paths, and fixed cache-load bug where cached files weren't tracked. New CLI flags: --max-indexed-files and --max-total-chunks (PR #567)
• Lemonade v10 device keys — Updated device key references: npu → amd_npu, gpu → amd_igpu/amd_dgpu. Fixed NPU detection in Hardware Advisor (PR #548)
• Agent UI rendering — Fixed post-tool thinking visibility, FileListView layout, and text spacing (PR #566)
• Agent UI guardrails & Windows paths — Tightened JSON safety regex, added platform context to system prompt for native Windows paths, cleared messages before session switch (PR #604)
• RAG indexing guards — gaia init now installs RAG dependencies for all profiles. Fixed crashes that occurred when optional dependencies weren't installed (PR #605)
• Reverted accidental changes — Restored per-file upload locking, tool confirmation flow, CSS design system, and formatting utilities accidentally reverted during a stale merge (PR #608)
• v0.16.1 release notes — Added missing PRs to previous release notes (PR #589)

---

Upgrade

npm install -g @amd-gaia/agent-ui@latest

---

Full Changelog

13 commits since v0.16.1:

• 2d08088 - fix: reduce system prompt 78% to fix Qwen3.5 timeouts + MCP runtime status (#609) (#617)
• b7a97e6 - Restore changes reverted by accidental PR #566 merge (#564, #565, #568) (#608)
• af652d9 - fix: RAG indexing guards, gaia init pip extras, and docs update (#605)
• 95b304f - Fix Agent UI guardrails, rendering, LRU eviction, and Windows paths (#604)
• 5dd71a2 - feat: guard Agent UI against unsupported devices (#593)
• cc90935 - Fix Agent UI Round 5: hide post-tool thinking, FileListView, text spacing (#566)
• 8a6452f - Fix LRU eviction silent failure allowing unbounded memory growth (#449) (#567)
• 3df90ff - Add tool execution guardrails with confirmation popup (#438) (#565)
• 8c2d24a - security: fix TOCTOU race condition in document upload endpoint (#448) (#564)
• bae3a62 - docs(releases): add missing PRs to v0.16.1 release notes (#589)
• 25c6d25 - Agent UI: terminal animations, pixelated cursor, and docs fixes (#568)
• b2ace80 - Add GAIA Agent UI: privacy-first local agent with document Q&A (#428)
• 4015bb2 - Fix Lemonade v10 system-info device key compatibility (#548)

Full Changelog: v0.16.1...v0.17.0

v0.16.1

What's Changed

• Fixed broken links to amd-gaia.ai in README.md by @evanjrowley in #497
• Update Lemonade Server to v10.0.0 by @kovtcharov in #498
• Fix GAIA CLI Linux test hanging in merge queue by @kovtcharov in #445
• C++ framework: tool security — policies, confirmation, allowlisting, arg validation by @itomek in #496
• ci: add doc link checker, scope workflow triggers, fix broken links by @kovtcharov in #499
• Fix gaia init version checks and MSI reliability by @kovtcharov in #478
• Fix MCP config stacking and tool display naming by @itomek in #477
• feat(cpp): Process Analyst Agent with LemonadeClient and background monitoring by @itomek in #426
• Release v0.16.1 by @kovtcharov in #516

New Contributors

• @evanjrowley made their first contribution in #497

Full Changelog: v0.16.0...v0.16.1

v0.16.0

GAIA v0.16.0 Release Notes

Major release introducing the C++17 Agent Framework — a native port of the GAIA agent system that lets you build AI PC agents in pure C++ with no Python runtime required. Also includes security hardening across the Python codebase and a comprehensive documentation site reorganization.

TL;DR:

• New: C++17 Agent Framework — Full native agent framework with MCP support, tool registry, and state machine — no Python needed
• New: Health Agent & WiFi Agent — Two production-ready C++ example agents for Windows system diagnostics
• New: CleanConsole — Polished terminal UI for C++ agents with ANSI colors and word-wrap
• New: C++ CI/CD Pipeline — Cross-platform build + STX hardware integration tests
• Security: 37 alerts resolved — 15 Dependabot + 22 code scanning alerts fixed across Python and JavaScript
• Docs: Site reorganization — C++ Framework gets dedicated top-level section, SDK accuracy fixes, sidebar icons, 17+ broken links repaired

---

What's New

C++17 Agent Framework

A complete native port of the GAIA base agent framework under cpp/. Build AI agents in pure C++17 with the same agent loop semantics as the Python src/gaia/agents/base/ — no Python runtime required.

Key capabilities:

• Agent state machine — PLANNING -> EXECUTING_PLAN -> DIRECT_EXECUTION -> ERROR_RECOVERY -> COMPLETION
• ToolRegistry with tool name resolution (unprefixed MCP name suffix match, case-insensitive fallback)
• MCP client with cross-platform stdio transport (Win32 CreateProcess + POSIX fork/exec), JSON-RPC 2.0, mcp_<server>_<tool> naming convention
• JSON parsing with 4-strategy fallback: direct parse, code-block extraction, bracket-matching, regex field extraction
• Parameter substitution — $PREV.field / $STEP_N.field across plan steps
• OpenAI-compatible HTTP client via cpp-httplib

#include <gaia/agent.h>

int main() {
    gaia::AgentConfig config;
    config.baseUrl = "http://localhost:8000/api/v1";
    config.modelId = "Qwen3-4B-Instruct-2507-GGUF";

    gaia::Agent agent(config);
    agent.processQuery("Check system health");
    return 0;
}

Build requirements: CMake 3.14+, C++17 compiler. All dependencies fetched automatically via FetchContent (nlohmann/json 3.11.3, cpp-httplib 0.15.3, googletest 1.14.0).

cd cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

See the C++ Framework documentation for the full setup guide and API reference.

Health Agent (C++)

A Windows system health agent that uses the MCP Windows server for PowerShell-based diagnostics. Two modes of operation:

Mode	Description
Quick summary (option 1)	Console-only output — 4 key metrics, no Notepad
Full diagnostics (option 15)	Comprehensive report with 12+ tool calls, written to file and opened in Notepad

Uses direct file-write + Start-Process notepad approach for reliable report delivery. Runs with 32K context to support comprehensive multi-tool diagnostics.

WiFi Agent (C++)

A network diagnostic agent that performs WiFi troubleshooting through MCP tool calls. Includes shell injection prevention and safe argument validation.

CleanConsole (C++)

New CleanConsole class providing a polished terminal UI for C++ agents with ANSI color output and automatic word-wrapping — a native equivalent of Python's AgentConsole.

C++ CI/CD Pipeline

Full cross-platform CI via .github/workflows/build_cpp.yml:

• Cloud CI: Ubuntu + Windows builds with mock unit tests, install verification, shared library builds
• STX hardware integration tests: LLM, MCP, WiFi, and Health agent tests on real AMD hardware
• Uses Qwen3-4B-Instruct-2507-GGUF model for integration testing
• Sequential test execution (-j 1) to prevent LLM server contention

---

Security

Dependabot & Code Scanning Fixes

Resolved 37 security alerts across the codebase (PR #352):

Dependabot (15 alerts):

Package	Severity	Fix
tar	High	Force >=7.5.8 — fixes path traversal and symlink vulnerabilities
qs	Low	Update to 6.14.2 — fixes arrayLimit bypass DoS
lodash	Medium	Update to 4.17.23 — fixes prototype pollution

Code Scanning (22 alerts):

Category	Count	Fix
Stack trace exposure	6	Replace str(e) in HTTP responses with generic messages
Path injection	8	Add path traversal validation and .. checks
Clear-text logging	4	Remove patient IDs from log messages
Missing workflow permissions	2	Add permissions: contents: read to CI jobs
URL redirect	1	Use explicit HTTP 303 redirect status
Missing rate limiting	1	Add express-rate-limit to login endpoint

---

Documentation

Site Reorganization

Major documentation restructuring for better navigation and accuracy (PR #427):

• C++ Framework promoted — Dedicated top-level "C++ Framework" section in the Documentation tab with setup, quickstart, overview, integration guides, user guides, and API reference
• SDK Reference reorganized — Split hybrid Chat guide into User Guide and SDK Reference; merged MCP Client guide into SDK Reference
• Welcome page improved — Get Started section before Capabilities; Python/C++ tabs with distinct feature cards
• Sidebar icons — 48 documentation pages now have Font Awesome sidebar icons
• SDK accuracy — Fixed 13 code examples to match actual source code (quick_chat() return type, create_client() factory pattern, process_query() method name, execution_state attribute, max_steps default, @tool decorator behavior)
• Broken links — 17+ broken internal links repaired; redirects added for all moved pages
• Copyright updated — 2024-2026 across all pages

C++ Documentation

Complete documentation suite for the C++ framework:

• docs/cpp/setup.mdx — Build requirements and installation
• docs/cpp/quickstart.mdx — Build your first C++ agent
• docs/cpp/overview.mdx — Architecture and components
• docs/cpp/integration.mdx — Integrating gaia_core into your project
• docs/cpp/custom-agent.mdx — Building custom agents
• docs/cpp/health-agent.mdx — Windows system health monitoring
• docs/cpp/wifi-agent.mdx — Network diagnostic agent
• docs/cpp/api-reference.mdx — Complete API reference

---

Bug Fixes

• C++ agent loop detection — Compare both tool name AND arguments to prevent false positives on consecutive mcp_windows_Shell calls with different args
• C++ tool result truncation — Reduce from 20K to 4K chars to prevent context overflow with small models
• C++ CI integration tests — Run with -j 1 to prevent tests from competing for the single LLM server; increase timeout from 20 to 30 minutes
• PowerShell API — Fix Get-WmiObject to Get-CimInstance in health agent

---

Upgrade

# Install/upgrade GAIA (Python)
pip install --upgrade amd-gaia

# Build C++ framework
cd cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

---

Full Changelog

4 commits since v0.15.4.1:

• 99394d3 - Add C++17 agent framework port (#351)
• fdaa0cb - Fix Dependabot and code scanning security alerts (#352)
• 1ed7c00 - C++ framework: docs, CI integration tests, health agent improvements (#425)
• 5fac5a9 - Reorganize documentation site and fix SDK accuracy issues (#427)

Full Changelog: v0.15.4.1...v0.16.0

v0.15.4.1

What's Changed

• Release v0.15.4.1 (#350) (73349b9)
• Fix gaia sd terminal preview and image viewer (#346) (8d12a4a)
• Fix gaia talk: mic sensitivity, LEMONADE_BASE_URL, stuck listening (#347) (#348) (1198af5)
• Refine MCP Client architecture diagram (#342) (05b6fda)
• Fix gaia init for remote Lemonade Server (#345) (12acbab)
• Fix gaia talk 'No module named pip' error (#344) (a094149)
• Fix MCP time server example to use mcp-server-time (#339) (d26b7a0)
• Add VLM profile and structured extraction API (#336) (b882930)

Installation

Install GAIA using pip:

pip install amd-gaia

Or using uv:

uv pip install amd-gaia

v0.15.4

What's Changed

• Add release notes for v0.15.4 and bump version (#337) (8e98962)
• MCP Client Support: Connect GAIA agents to any MCP server (#277) (290fb13)
• Update VLM model to Qwen3-VL-4B-Instruct-GGUF (#226) (3295114)
• Fix PowerShell $PID variable conflict in start-lemonade.ps1 (#331) (b209074)
• Add one-command installer scripts for Windows and Linux (#305) (514ba5e)
• Add Vision SDK to Q2 2026 Roadmap (#326) (0af6fa2)
• Fix VLM and Chat Documentation Discrepancies (#328) (66116fa)
• Add option for stx-test machine (#308) (4a8de23)
• Update eval framework to use SummarizerAgent (#269) (2cca205)

Installation

Install GAIA using pip:

pip install amd-gaia

Or using uv:

uv pip install amd-gaia