refactor(agents): migrate chat to hub (#1102) (#1456)

## Why this matters

ChatAgent — the flagship conversational agent powering `gaia chat` (and
`gaia chat --ui`) under its `chat`, `doc`, and `file` profiles — was the
last family of registry *builtins* still hardcoded inside the core
framework wheel. It now ships as the standalone **`gaia-agent-chat`**
wheel under `hub/agents/python/chat/`, with `chat`/`doc`/`file`
registered as three `gaia.agent` entry points that the registry
discovers automatically. The core wheel no longer hardcodes them, so the
chat family versions independently like every other migrated agent.
`gaia chat` resolves the agent through the registry and **fails loudly
with an install hint** if the wheel is absent (mirroring how #1446 made
`gaia browse`/`gaia analyze` resolve). All three profiles, their
full+lite model tiers (via `registry.build_model_tiers`), and their
per-profile prompt/tool wiring are preserved exactly.

Continues the #1102 Agent Hub restructure after connectors-demo (#1442)
and analyst/browser (#1446). The shared `FileToolsMixin` (directory
monitoring) stays framework-side — promoted to
`gaia.agents.tools.file_monitor_tools` — since tool mixins are framework
code (#1396).

## Test plan

- [x] `python util/lint.py --all` — black/isort clean (the only pylint
hit, `os.geteuid` in `lemonade_installer.py`, is a pre-existing
Windows-only false positive; mypy is warning-only)
- [x] `pytest tests/unit/agents/test_registry.py
tests/unit/test_agents_split.py tests/unit/cli/test_cli_smoke.py` —
registry + split green; the 4 `cli_smoke` `gaia-code`/`gaia-emr`
console-script hits are pre-existing shared-env pollution (verified
passing on the base checkout), unrelated to chat
- [x] `pip install -e hub/agents/python/chat && pytest
hub/agents/python/chat/tests/` — 7 passed (registration shapes for
chat/doc/file, lazy re-exports, discovery, `installed:` namespacing)
- [x] `pytest` across the chat-touched framework suites (chat agent,
integration, system-prompt budget, browser tools, multi-device,
required-connectors, registry factory, chat-UI helpers) — 182 passed
with the wheel installed; all skip cleanly via `importorskip` in a
framework-only env
- [x] Registry discovery lists `chat`/`doc`/`file` as `source=installed`
with `installed:chat` namespace; `builder`/`email` remain the only
resident builtins
- [ ] CI: the `Chat Agent Tests` workflow installs the wheel and runs
both the package smoke tests and the framework
session/RAG/path-validation suites

---------

Co-authored-by: Ovtcharov <kovtchar@amd.com>
Co-authored-by: Kalin Ovtcharov <kalin@extropolis.ai>

Author: 3 people

.github/workflows/test_chat_agent.yml

@@ -1,8 +1,9 @@
 # Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 
-# This workflow tests the GAIA Chat Agent functionality
-# Tests include: Session persistence, chat history, RAG, and path validation
+# This workflow tests the GAIA Chat Agent, which ships as the standalone
+# gaia-agent-chat wheel (#1102). Tests include the wheel's own smoke tests
+# plus the framework-side session, RAG, and path-validation suites.
 
 name: Chat Agent Tests
 
@@ -11,8 +12,9 @@ on:
   push:
     branches: [ main ]
     paths:
-      - 'src/gaia/agents/chat/**'
+      - 'hub/agents/python/chat/**'
       - 'src/gaia/agents/base/**'
+      - 'src/gaia/agents/tools/**'
       - 'src/gaia/rag/**'
       - 'src/gaia/chat/**'
       - 'tests/test_chat_agent.py'
@@ -23,8 +25,9 @@ on:
     branches: [ main ]
     types: [opened, synchronize, reopened, ready_for_review]
     paths:
-      - 'src/gaia/agents/chat/**'
+      - 'hub/agents/python/chat/**'
       - 'src/gaia/agents/base/**'
+      - 'src/gaia/agents/tools/**'
       - 'src/gaia/rag/**'
       - 'src/gaia/chat/**'
       - 'tests/test_chat_agent.py'
@@ -67,6 +70,19 @@ jobs:
           uv pip install --system -e .[dev,rag]
           # Install pytest-mock for mocking tests
           uv pip install --system pytest-mock
+          # ChatAgent ships as the standalone gaia-agent-chat wheel (#1102)
+          uv pip install --system -e hub/agents/python/chat
+
+      - name: Run Chat Agent Package Tests
+        env:
+          GAIA_MEMORY_DISABLED: "1"
+        run: |
+          echo "================================================================"
+          echo "                  CHAT AGENT PACKAGE TESTS"
+          echo "================================================================"
+          echo "Testing registration shapes, lazy re-exports, and discovery..."
+          echo ""
+          python -m pytest hub/agents/python/chat/tests/ -v --tb=short
 
       - name: Run Chat Agent Unit Tests
         env:

.github/workflows/test_security.yml

@@ -58,7 +58,11 @@ jobs:
         run: curl -LsSf https://astral.sh/uv/install.sh | sh
 
       - name: Install dependencies
-        run: uv pip install --system -e .[dev,rag]
+        run: |
+          uv pip install --system -e .[dev,rag]
+          # verify_*.py instantiate ChatAgent, which ships as the standalone
+          # gaia-agent-chat wheel (#1102).
+          uv pip install --system -e hub/agents/python/chat
 
       - name: Run Path Validator Security Tests
         env:
@@ -155,7 +159,12 @@ jobs:
         shell: pwsh
 
       - name: Install dependencies
-        run: uv pip install --system -e .[dev,rag]
+        run: |
+          uv pip install --system -e .[dev,rag]
+          # verify_*.py instantiate ChatAgent, which ships as the standalone
+          # gaia-agent-chat wheel (#1102).
+          uv pip install --system -e hub/agents/python/chat
+        shell: pwsh
 
       - name: Run Path Validator Security Tests
         shell: pwsh

.vscode/launch.json

@@ -53,7 +53,7 @@
             "name": "Chat Agent Debug - Model Selection",
             "type": "debugpy",
             "request": "launch",
-            "module": "gaia.agents.chat.app",
+            "module": "gaia_agent_chat.app",
             "args": ["--query", "hi"],
             "cwd": "${workspaceFolder}",
             "env": {

docs/guides/chat.mdx

@@ -208,7 +208,7 @@ gaia chat --index document.pdf --debug
 
 ```python Python Debug
 # Python SDK with debug — ChatAgent takes a single ChatAgentConfig
-from gaia.agents.chat.agent import ChatAgent, ChatAgentConfig
+from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig
 
 config = ChatAgentConfig(
     rag_documents=['document.pdf'],
@@ -322,7 +322,7 @@ is set, the UI toggle reflects the effective value and disables itself — which
 handy for the eval harness:
 
 ```python
-from gaia.agents.chat.agent import ChatAgent, ChatAgentConfig
+from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig
 
 agent = ChatAgent(ChatAgentConfig(prompt_profile="doc", dynamic_tools=True))
 ```

docs/plans/agent-ui-eval-benchmark.md

@@ -1059,7 +1059,7 @@ Single-scenario run: ~$0.10-0.15.
       "root_cause": "Smart Discovery workflow uses query keywords as file search patterns. Needs to extract likely document names, not just topic keywords.",
       "recommended_fix": {
         "target": "system_prompt",
-        "file": "src/gaia/agents/chat/agent.py",
+        "file": "hub/agents/python/chat/gaia_agent_chat/agent.py",
         "description": "In Smart Discovery section, instruct agent to search for common document names related to the topic, not just the exact query terms."
       }
     }

docs/plans/email-triage-agent.mdx

@@ -567,7 +567,7 @@ v0.20.0 for GaiaAgent broadly. The email-agent path explicitly opts out:
   flips red loudly if an email-content payload is ever seen heading to a cloud
   backend. This is the alarm, not the defense — the defense is the tag check.
 - An integration test asserts this invariant on every PR touching `gaia/llm/`
-  or `gaia/agents/chat/`.
+  or `hub/agents/python/chat/`.
 
 Nothing in this spec relies on the user "just trusting" the local-only claim.
 

docs/plans/security-model.mdx

@@ -783,8 +783,8 @@ The following security measures are already implemented in the codebase:
 
 | Measure | Location | Description |
 |---------|----------|-------------|
-| Shell command whitelist | `src/gaia/agents/chat/tools/shell_tools.py` | `ALLOWED_COMMANDS` set restricts CLI tool to read-only commands |
-| Git command whitelist | `src/gaia/agents/chat/tools/shell_tools.py` | Only read-only git subcommands (`status`, `log`, `diff`, etc.) |
+| Shell command whitelist | `src/gaia/agents/tools/shell_tools.py` | `ALLOWED_COMMANDS` set restricts CLI tool to read-only commands |
+| Git command whitelist | `src/gaia/agents/tools/shell_tools.py` | Only read-only git subcommands (`status`, `log`, `diff`, etc.) |
 | Localhost-only MCP bridge | `src/gaia/mcp/mcp.json` | `GAIA_MCP_HOST` defaults to `localhost` |
 | Subprocess timeout | `src/gaia/mcp/external_services.py` | `timeout=30` on MCP subprocess calls |
 | Tool registry validation | `src/gaia/agents/base/agent.py` | Rejects unregistered tool names |

docs/plans/tool-loader.mdx

@@ -3,7 +3,7 @@ title: "Dynamic Tool Loader"
 ---
 
 <Info>
-  **Source Code:** [`src/gaia/agents/base/tool_loader.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/tool_loader.py) · bundles [`src/gaia/agents/chat/tool_bundles.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/chat/tool_bundles.py)
+  **Source Code:** [`src/gaia/agents/base/tool_loader.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/base/tool_loader.py) · bundles [`hub/agents/python/chat/gaia_agent_chat/tool_bundles.py`](https://github.com/amd/gaia/blob/main/hub/agents/python/chat/gaia_agent_chat/tool_bundles.py)
 </Info>
 
 <Note>
@@ -272,7 +272,7 @@ when set — the toggle then reflects the effective value and disables — so τ
 the cap stay env-only tuning.
 
 **CORE (10, always-on, cap- & eviction-exempt)** — defined in
-[`tool_bundles.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/chat/tool_bundles.py):
+[`tool_bundles.py`](https://github.com/amd/gaia/blob/main/hub/agents/python/chat/gaia_agent_chat/tool_bundles.py):
 `remember`, `recall`, `update_memory`, `forget`, `search_past_conversations`,
 `read_file`, `query_documents`, `query_specific_file`, `set_loop_state`,
 `request_user_input`.
@@ -351,7 +351,7 @@ baseline — meaning **CORE-only is the ~60%-reduction best case** and a full
 #### How Part 2 shipped (implementation reference)
 
 **`load_tools` is always-on via CORE.** `load_tools` is added to
-[`DOC_CORE_TOOLS`](https://github.com/amd/gaia/blob/main/src/gaia/agents/chat/tool_bundles.py)
+[`DOC_CORE_TOOLS`](https://github.com/amd/gaia/blob/main/hub/agents/python/chat/gaia_agent_chat/tool_bundles.py)
 (CORE = 11), so once registered it renders in **both** the text prompt and the
 native `tools=` schema every active turn and is cap-/eviction-exempt. It is
 registered **only when the loader is active** (`self.tool_loader is not None`),
@@ -481,7 +481,7 @@ needs a seeded procedure matching a scenario goal.
 These were open in the design sketch; Part 1 (#1449) decided them as follows:
 
 1. **Bundle definitions and CORE membership** — *decided.* CORE = 10 names and 12
-   bundles, in [`tool_bundles.py`](https://github.com/amd/gaia/blob/main/src/gaia/agents/chat/tool_bundles.py)
+   bundles, in [`tool_bundles.py`](https://github.com/amd/gaia/blob/main/hub/agents/python/chat/gaia_agent_chat/tool_bundles.py)
    (see [How Part 1 shipped](#part-1-selection-dual-path-filtering-landed-1449)),
    pinned to cover the 37-tool `doc` registry exactly.
 2. **Similarity threshold τ / cap** — *decided.* τ = `0.20` inclusive, cap = `14`

docs/playbooks/chat-agent/part-1-getting-started.mdx

@@ -141,7 +141,7 @@ Get a working agent running to understand the basic flow.
 
     ```python title="my_chat_agent.py"
     import json
-    from gaia.agents.chat.agent import ChatAgent, ChatAgentConfig
+    from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig
 
     # Create agent with a document
     config = ChatAgentConfig(
@@ -383,7 +383,7 @@ flowchart TD
 <CodeGroup>
 ```python Example: Multiple Mixins
 from gaia.agents.base.agent import Agent
-from gaia.agents.chat.tools import RAGToolsMixin, FileToolsMixin
+from gaia.agents.tools import RAGToolsMixin, FileToolsMixin
 
 class MyAgent(Agent, RAGToolsMixin, FileToolsMixin):
     def _register_tools(self):

docs/playbooks/chat-agent/part-2-advanced-features.mdx

@@ -30,7 +30,7 @@ Use GAIA's built-in mixins instead of implementing tools from scratch.
 ```python step4_with_mixins.py
 from gaia.agents.base.agent import Agent
 from gaia.agents.base.console import AgentConsole
-from gaia.agents.chat.tools import RAGToolsMixin, FileToolsMixin
+from gaia.agents.tools import RAGToolsMixin, FileToolsMixin
 from gaia.agents.tools import FileSearchToolsMixin
 from gaia.rag.sdk import RAGSDK, RAGConfig
 
@@ -101,7 +101,7 @@ agent.process_query("Find research papers in my Documents folder, index them, an
     - `list_indexed_documents()` - List currently indexed files
     - `rag_status()` - Get index statistics
 
-    **Import:** `from gaia.agents.chat.tools import RAGToolsMixin`
+    **Import:** `from gaia.agents.tools import RAGToolsMixin`
   </Tab>
 
   <Tab title="FileSearchToolsMixin">
@@ -117,7 +117,7 @@ agent.process_query("Find research papers in my Documents folder, index them, an
     **Directory monitoring:**
     - `add_watch_directory(directory)` - Monitor and auto-index changes
 
-    **Import:** `from gaia.agents.chat.tools import FileToolsMixin`
+    **Import:** `from gaia.agents.tools import FileToolsMixin`
   </Tab>
 
   <Tab title="Registration">
@@ -142,7 +142,7 @@ Add file system monitoring to automatically reindex documents when they change.
 
 <CodeGroup>
 ```python step5_with_monitoring.py
-from gaia.agents.chat.agent import ChatAgent, ChatAgentConfig
+from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig
 
 # The full ChatAgent includes file monitoring!
 config = ChatAgentConfig(
@@ -210,7 +210,7 @@ Implement session persistence to avoid re-indexing on every restart.
 
 <CodeGroup>
 ```python step6_create_session.py
-from gaia.agents.chat.agent import ChatAgent, ChatAgentConfig
+from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig
 
 config = ChatAgentConfig(
     rag_documents=["./manual.pdf"]
@@ -227,7 +227,7 @@ if agent.save_current_session():
 ```
 
 ```python step6_load_session.py
-from gaia.agents.chat.agent import ChatAgent
+from gaia_agent_chat.agent import ChatAgent
 
 agent = ChatAgent()
 
@@ -288,7 +288,7 @@ The `ChatAgent` class combines all components. Here's how to configure and use i
 <Tabs>
   <Tab title="Full Configuration">
     ```python title="complete_agent.py"
-    from gaia.agents.chat.agent import ChatAgent, ChatAgentConfig
+    from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig
     from pathlib import Path
 
     # Complete configuration
@@ -437,7 +437,7 @@ Extend the agent by adding domain-specific tools.
 <Tabs>
   <Tab title="Custom Tools">
     ```python title="custom_tools.py"
-    from gaia.agents.chat.agent import ChatAgent, ChatAgentConfig
+    from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig
     from gaia.agents.base.tools import tool
 
     class CustomDocAgent(ChatAgent):
@@ -568,7 +568,7 @@ Override system prompts to create domain-specific behavior.
 <Tabs>
   <Tab title="Research Agent">
     ```python title="research_agent.py"
-    from gaia.agents.chat.agent import ChatAgent
+    from gaia_agent_chat.agent import ChatAgent
 
     class ResearchAgent(ChatAgent):
         """Academic research specialist."""
@@ -591,7 +591,7 @@ Override system prompts to create domain-specific behavior.
 
   <Tab title="Support Agent">
     ```python title="support_agent.py"
-    from gaia.agents.chat.agent import ChatAgent
+    from gaia_agent_chat.agent import ChatAgent
 
     class CustomerSupportAgent(ChatAgent):
         """Customer support specialist."""
@@ -637,7 +637,7 @@ Override system prompts to create domain-specific behavior.
 <Tabs>
   <Tab title="Implementation">
     ```python title="research_assistant.py"
-    from gaia.agents.chat.agent import ChatAgent, ChatAgentConfig
+    from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig
     from pathlib import Path
 
     research_folder = Path.home() / "Research" / "AI-Papers"
@@ -684,7 +684,7 @@ Override system prompts to create domain-specific behavior.
 <Tabs>
   <Tab title="Setup">
     ```python title="knowledge_base.py"
-    from gaia.agents.chat.agent import ChatAgent, ChatAgentConfig
+    from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig
     import os
 
     docs_root = "/company/shared/documentation"
@@ -709,7 +709,7 @@ Override system prompts to create domain-specific behavior.
 
   <Tab title="Team Usage">
     ```python title="load_shared_session.py"
-    from gaia.agents.chat.agent import ChatAgent
+    from gaia_agent_chat.agent import ChatAgent
 
     # Team member loads shared session
     agent = ChatAgent()
@@ -739,7 +739,7 @@ Override system prompts to create domain-specific behavior.
 <Tabs>
   <Tab title="Implementation">
     ```python title="personal_assistant.py"
-    from gaia.agents.chat.agent import ChatAgent, ChatAgentConfig
+    from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig
     from pathlib import Path
 
     config = ChatAgentConfig(