> ## Documentation Index
> Fetch the complete documentation index at: https://amd-gaia.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Document Q&A

> Chat with documents using text, voice, and RAG-powered retrieval

<Info>
  **First time here?** Complete the [Setup](/docs/setup) guide first to install GAIA and its dependencies.
</Info>

<Note>
  **Prefer a desktop app?** See [GAIA Chat Desktop](/docs/guides/agent-ui) for the privacy-first GUI with drag-and-drop document Q\&A.
</Note>

<Note>
  **Looking for the API?** See the [Agent SDK Reference](/docs/sdk/sdks/chat) for classes, methods, and code examples.
</Note>

## Quick Start

<Steps>
  <Step title="Install dependencies">
    Activate your virtual environment and install GAIA with RAG support:

    ```bash theme={null}
    uv pip install -e ".[rag]"
    ```
  </Step>

  <Step title="Create a simple chat">
    ```python title="simple_chat.py" theme={null}
    from gaia.chat.sdk import SimpleChat

    chat = SimpleChat()
    response = chat.ask("What is Python?")
    print(response)

    # Follow-up with conversation memory
    response = chat.ask("Give me an example")
    print(response)
    ```
  </Step>

  <Step title="Use the full SDK">
    ```python title="full_chat.py" theme={null}
    from gaia.chat.sdk import AgentSDK, AgentConfig

    config = AgentConfig(
        show_stats=True,
        max_history_length=6
    )
    chat = AgentSDK(config)

    response = chat.send("Hello! My name is Alex.")
    print(response.text)

    response = chat.send("What's my name?")
    print(response.text)  # Will remember "Alex"
    ```
  </Step>
</Steps>

## CLI Usage

### Interactive Mode

Start a conversational chat session:

<CodeGroup>
  ```bash Basic theme={null}
  # Start interactive chat
  gaia chat
  ```

  ```bash With Statistics theme={null}
  # Show performance metrics
  gaia chat --stats
  ```
</CodeGroup>

<AccordionGroup>
  <Accordion title="Session Commands">
    * `/resume [id]` - Resume a previous conversation (or list sessions if no id)
    * `/save` - Save current conversation
    * `/sessions` - List all saved sessions
    * `/reset` - Clear conversation and start fresh
    * `/help` or `/?` - Show help message
    * `/quit` - Exit the chat session
  </Accordion>
</AccordionGroup>

### Single Query Mode

```bash theme={null}
# One-shot query
gaia chat --query "What is artificial intelligence?"

# With statistics
gaia chat --query "Hello" --show-stats
```

## Document Q\&A (RAG)

<Note>
  RAG (Retrieval-Augmented Generation) enables chatting with documents — including PDF, Word (.docx), PowerPoint (.pptx), and Excel (.xlsx) — using semantic search and context retrieval.
</Note>

### CLI with RAG

<Tabs>
  <Tab title="Single Document">
    ```bash theme={null}
    # Chat with a PDF, Word, PowerPoint, or Excel document
    gaia chat --index manual.pdf
    gaia chat --index handbook.docx
    gaia chat --index slides.pptx
    gaia chat --index budget.xlsx
    ```
  </Tab>

  <Tab title="Multiple Documents">
    ```bash theme={null}
    # Chat with multiple documents (PDF, DOCX, PPTX, XLSX supported)
    gaia chat --index doc1.pdf report.docx slides.pptx
    ```
  </Tab>

  <Tab title="One-shot Query">
    ```bash theme={null}
    # One-shot query with document
    gaia chat --index report.pdf --query "Summarize the key findings"
    ```
  </Tab>

  <Tab title="Watch Folder">
    ```bash theme={null}
    # Auto-index every supported document in a folder, and any new ones dropped in later
    gaia chat --watch ./docs
    ```
  </Tab>

  <Tab title="Voice Mode">
    <Note>
      **Prerequisites:** Voice mode requires the `talk` module:

      ```bash theme={null}
      uv pip install -e ".[talk]"
      ```
    </Note>

    ```bash theme={null}
    # Voice with documents
    gaia talk --index manual.pdf
    ```
  </Tab>
</Tabs>

<Note>
  **Document Indexing Requirements:** Processing PDFs and PPTX files with images requires a Vision Language Model (VLM). GAIA uses `Qwen3-VL-4B-Instruct-GGUF` by default for extracting text from images in documents.

  To download all models needed for chat (including VLM):

  ```bash theme={null}
  gaia download --agent chat
  ```

  To see what models each agent requires: `gaia download --list`

  See the [CLI Reference](/docs/reference/cli#download-command) for more download options.
</Note>

### Interactive RAG Commands

When using `gaia chat` with documents (via `--index` flag or `/index` command), additional commands become available:

<AccordionGroup>
  <Accordion title="Session Management">
    Sessions preserve both your conversation history and indexed documents:

    * `/resume [id]` - Resume session with conversation and documents restored
    * `/save` - Save session including indexed documents
    * `/sessions` - List all saved sessions
    * `/reset` - Clear conversation and start a new session (indexed documents are preserved)
  </Accordion>

  <Accordion title="Document Management">
    * `/index <path>` - Index a document or directory (enables RAG if needed)
    * `/watch <dir>` - Watch directory for changes and auto-index new files
    * `/list` - List all currently indexed documents
    * `/status` - Show RAG system status (indexed files, chunks, memory usage)
  </Accordion>

  <Accordion title="Debug & Observability">
    * `/chunks <file>` - View indexed chunks for a specific file
    * `/chunk <id>` - View specific chunk by ID
    * `/test <query>` - Test query retrieval with relevance scores
    * `/dump <file|#>` - Export document and chunks to markdown
    * `/clear-cache` - Clear RAG cache and force re-indexing
    * `/search-debug` - Enable detailed search debugging output
  </Accordion>
</AccordionGroup>

### RAG Debug Mode

Enable debug mode to see detailed retrieval information:

<CodeGroup>
  ```bash CLI Debug theme={null}
  # CLI with debug
  gaia chat --index document.pdf --debug
  ```

  ```python Python Debug theme={null}
  # Python SDK with debug — ChatAgent takes a single ChatAgentConfig
  from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig

  config = ChatAgentConfig(
      rag_documents=['document.pdf'],
      debug=True,
      silent_mode=False,
  )
  agent = ChatAgent(config)

  result = agent.process_query("What is the vision statement?")
  print(result)
  ```
</CodeGroup>

<Accordion title="Debug Information Includes">
  * Search keys generated by the LLM
  * Chunks found for each search
  * Relevance scores
  * Deduplication statistics
  * Score distributions
</Accordion>

### Chunking Strategies

<CardGroup cols={2}>
  <Card title="Structural Chunking" icon="bolt">
    **Default - Fast processing**

    ```python theme={null}
    config = ChatAgentConfig(
        rag_documents=['document.pdf'],
        chunk_size=500,
        chunk_overlap=50,
    )
    agent = ChatAgent(config)
    ```
  </Card>

  <Card title="LLM-Based Semantic" icon="brain">
    **More accurate context**

    ```python theme={null}
    config = ChatAgentConfig(
        rag_documents=['document.pdf'],
        use_llm_chunking=True,
        chunk_size=500,
    )
    agent = ChatAgent(config)
    ```
  </Card>
</CardGroup>

### Troubleshooting

<AccordionGroup>
  <Accordion title="Missing Dependencies">
    ```bash theme={null}
    uv pip install -e ".[rag]"
    ```
  </Accordion>

  <Accordion title="Voice Mode: No Module Named 'pip'">
    If `gaia talk` fails with "No module named 'pip'", install dependencies manually:

    ```bash theme={null}
    # Install talk dependencies
    uv pip install -e ".[talk]"

    # If the error persists, install pip in your environment
    python -m ensurepip --upgrade
    ```
  </Accordion>

  <Accordion title="PDF Issues">
    * Ensure PDF has extractable text (not scanned images)
    * Check file is not password-protected
    * Verify file is not corrupted
  </Accordion>

  <Accordion title="Performance Tuning">
    ```python theme={null}
    # Faster processing
    chat.enable_rag(documents=["doc.pdf"], chunk_size=300, max_chunks=2)

    # Better quality
    chat.enable_rag(documents=["doc.pdf"], chunk_size=600, max_chunks=5, chunk_overlap=100)

    # Memory efficient
    chat.enable_rag(documents=["doc.pdf"], chunk_size=400, max_chunks=2)
    ```
  </Accordion>
</AccordionGroup>

## Dynamic Tool Loading

<Note>
  **Off by default, `doc` profile only.** This is the first stage of a phased
  rollout ([Dynamic Tool Loader plan](/docs/plans/tool-loader)); enable it explicitly to
  try it.
</Note>

The `doc` profile can load tools **semantically per turn** instead of showing the
LLM every registered tool on every turn. A small always-on CORE set is combined
with tools whose descriptions best match the conversation, which shrinks the
first-turn prompt and speeds up the first reply.

It activates only on the `doc` profile (the registered `doc` agent, the SDK with
`ChatAgentConfig(prompt_profile="doc")`, or `gaia eval agent --agent-type doc`).
Turn it on with the config field, an environment variable, or the Agent UI
**Settings → Dynamic Tools (Beta)** toggle. The env var wins over both — when it
is set, the UI toggle reflects the effective value and disables itself — which is
handy for the eval harness:

```python theme={null}
from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig

agent = ChatAgent(ChatAgentConfig(prompt_profile="doc", dynamic_tools=True))
```

```bash theme={null}
# Env override (applies wherever a doc-profile ChatAgent runs)
GAIA_DYNAMIC_TOOLS=1 gaia eval agent --category tool_selection --agent-type doc

# Optional tuning: match threshold (cosine, inclusive) and loaded-set cap
GAIA_DYNAMIC_TOOLS_TAU=0.20 GAIA_DYNAMIC_TOOLS_MAX=14 GAIA_DYNAMIC_TOOLS=1 ...
```

It needs memory enabled (it reuses the memory embedder). If memory is off, the
toggle is off, or the embedder is unreachable, the agent automatically falls back
to showing **all** tools — so a turn never loses access to a tool it needs. See
the [Dynamic Tool Loader plan](/docs/plans/tool-loader) for the full design.

## Next Steps

<CardGroup cols={2}>
  <Card title="GAIA Chat Desktop" icon="desktop" href="/docs/guides/agent-ui">
    Privacy-first desktop app with drag-and-drop document Q\&A
  </Card>

  <Card title="Agent SDK Reference" icon="code" href="/docs/sdk/sdks/chat">
    Classes, methods, and code examples
  </Card>

  <Card title="Voice Interaction" icon="microphone" href="/docs/guides/talk">
    Add speech recognition and text-to-speech
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/docs/reference/cli">
    Explore all command-line options
  </Card>

  <Card title="Agent UI SDK Reference" icon="server" href="/docs/sdk/sdks/agent-ui">
    Python backend API for the desktop chat application
  </Card>

  <Card title="API Server" icon="server" href="/docs/reference/api">
    Integrate via OpenAI-compatible API
  </Card>
</CardGroup>

***

<small style="color: #666;">
  **License**

  Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.

  SPDX-License-Identifier: MIT
</small>