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

.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(

docs/playbooks/chat-agent/part-3-deployment.mdx

@@ -249,11 +249,11 @@ def _generate_search_keys(self, query: str) -> List[str]:
         },
         # 👇 Your new agent
         "doc-qa": {
-            "class_name": "gaia.agents.chat.agent.ChatAgent",
+            "class_name": "gaia_agent_chat.agent.ChatAgent",
             "init_params": {
                 "silent_mode": True,
                 # Only kwargs recognised by ChatAgentConfig will be applied;
-                # see ChatAgentConfig in src/gaia/agents/chat/agent.py.
+                # see ChatAgentConfig in hub/agents/python/chat/gaia_agent_chat/agent.py.
                 "rag_documents": ["./company_docs"],
             },
             "description": "Document Q&A agent backed by RAG",
@@ -320,7 +320,7 @@ def _generate_search_keys(self, query: str) -> List[str]:
     ```python title="cli.py"
     #!/usr/bin/env python3
     import sys
-    from gaia.agents.chat.agent import ChatAgent, ChatAgentConfig
+    from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig
 
     def main():
         if len(sys.argv) < 2:
@@ -674,15 +674,15 @@ def _generate_search_keys(self, query: str) -> List[str]:
 ## Source Code Reference
 
 <CardGroup cols={2}>
-  <Card title="ChatAgent" icon="code" href="https://github.com/amd/gaia/blob/main/src/gaia/agents/chat/agent.py">
+  <Card title="ChatAgent" icon="code" href="https://github.com/amd/gaia/blob/main/hub/agents/python/chat/gaia_agent_chat/agent.py">
     Main agent implementation with session management and file monitoring
   </Card>
 
-  <Card title="RAGToolsMixin" icon="database" href="https://github.com/amd/gaia/blob/main/src/gaia/agents/chat/tools/rag_tools.py">
+  <Card title="RAGToolsMixin" icon="database" href="https://github.com/amd/gaia/blob/main/src/gaia/agents/tools/rag_tools.py">
     Document indexing and query tools
   </Card>
 
-  <Card title="FileToolsMixin" icon="folder" href="https://github.com/amd/gaia/blob/main/src/gaia/agents/chat/tools/file_tools.py">
+  <Card title="FileToolsMixin" icon="folder" href="https://github.com/amd/gaia/blob/main/src/gaia/agents/tools/file_monitor_tools.py">
     Directory monitoring implementation
   </Card>
 

docs/reference/agent-core-loop-architecture.md

@@ -1,7 +1,7 @@
 # Agent Core Loop — Architecture Review & Improvement Roadmap
 
 **Date:** 2026-03-22
-**Scope:** `src/gaia/agents/base/agent.py` + `src/gaia/agents/chat/agent.py`
+**Scope:** `src/gaia/agents/base/agent.py` + `hub/agents/python/chat/gaia_agent_chat/agent.py`
 **Context:** Analysis driven by failures surfaced in the Agent UI eval benchmark (34-scenario suite).
 
 ---

docs/sdk/advanced-patterns.mdx

@@ -12,7 +12,7 @@ icon: "diagram-project"
 ```python
 from gaia.agents.base.agent import Agent
 from gaia.agents.base.api_agent import ApiAgent
-from gaia.agents.chat.tools.file_tools import FileToolsMixin
+from gaia.agents.tools.file_monitor_tools import FileToolsMixin
 from gaia.agents.tools.file_tools import FileSearchToolsMixin
 from gaia.agents.tools.rag_tools import RAGToolsMixin
 from gaia.agents.tools.shell_tools import ShellToolsMixin

docs/sdk/agents/specialized.mdx

@@ -3,11 +3,11 @@ title: "Specialized"
 ---
 
 <Info>
-  **Source Code:** [`src/gaia/agents/chat/`](https://github.com/amd/gaia/blob/main/src/gaia/agents/chat/), [`src/gaia/agents/docker/`](https://github.com/amd/gaia/blob/main/src/gaia/agents/docker/), [`src/gaia/agents/jira/`](https://github.com/amd/gaia/blob/main/src/gaia/agents/jira/), [`src/gaia/agents/blender/`](https://github.com/amd/gaia/blob/main/src/gaia/agents/blender/)
+  **Source Code:** [`hub/agents/python/chat/gaia_agent_chat/`](https://github.com/amd/gaia/blob/main/hub/agents/python/chat/gaia_agent_chat/), [`src/gaia/agents/docker/`](https://github.com/amd/gaia/blob/main/src/gaia/agents/docker/), [`src/gaia/agents/jira/`](https://github.com/amd/gaia/blob/main/src/gaia/agents/jira/), [`src/gaia/agents/blender/`](https://github.com/amd/gaia/blob/main/src/gaia/agents/blender/)
 </Info>
 
 <Note>
-**Import:** `from gaia.agents.chat.agent import ChatAgent`
+**Import:** `from gaia_agent_chat.agent import ChatAgent`
 </Note>
 ---
 
@@ -19,7 +19,7 @@ title: "Specialized"
 **Purpose:** General-purpose conversational agent with file operations, RAG, and shell command capabilities.
 
 ```python
-from gaia.agents.chat.agent import ChatAgent, ChatAgentConfig
+from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig
 
 # Configure the chat agent (use ChatAgentConfig; ChatAgent takes a single
 # `config` argument rather than loose kwargs)