Document Q&A

First time here? Complete the Setup guide first to install GAIA and its dependencies.

Prefer a desktop app? See GAIA Chat Desktop for the privacy-first GUI with drag-and-drop document Q&A.

Looking for the API? See the Agent SDK Reference for classes, methods, and code examples.

Quick Start

Install dependencies

Activate your virtual environment and install GAIA with RAG support:

uv pip install -e ".[rag]"

Create a simple chat

simple_chat.py

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)

Use the full SDK

full_chat.py

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"

CLI Usage

Interactive Mode

Start a conversational chat session:

# Start interactive chat
gaia chat

# Show performance metrics
gaia chat --stats

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

Single Query Mode

# One-shot query
gaia chat --query "What is artificial intelligence?"

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

Document Q&A (RAG)

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

CLI with RAG

Single Document
Multiple Documents
One-shot Query
Watch Folder
Voice Mode

# 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

# Chat with multiple documents (PDF, DOCX, PPTX, XLSX supported)
gaia chat --index doc1.pdf report.docx slides.pptx

# One-shot query with document
gaia chat --index report.pdf --query "Summarize the key findings"

# Auto-index every supported document in a folder, and any new ones dropped in later
gaia chat --watch ./docs

Prerequisites: Voice mode requires the talk module:

uv pip install -e ".[talk]"

# Voice with documents
gaia talk --index manual.pdf

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):

gaia download --agent chat

To see what models each agent requires: gaia download --listSee the CLI Reference for more download options.

Interactive RAG Commands

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

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)

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)

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

RAG Debug Mode

Enable debug mode to see detailed retrieval information:

# CLI with debug
gaia chat --index document.pdf --debug

# 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)

Debug Information Includes

Search keys generated by the LLM
Chunks found for each search
Relevance scores
Deduplication statistics
Score distributions

Chunking Strategies

Structural Chunking

Default - Fast processing

config = ChatAgentConfig(
    rag_documents=['document.pdf'],
    chunk_size=500,
    chunk_overlap=50,
)
agent = ChatAgent(config)

LLM-Based Semantic

More accurate context

config = ChatAgentConfig(
    rag_documents=['document.pdf'],
    use_llm_chunking=True,
    chunk_size=500,
)
agent = ChatAgent(config)

Troubleshooting

Missing Dependencies

uv pip install -e ".[rag]"

PDF Issues

Ensure PDF has extractable text (not scanned images)
Check the PDF does not need a password to open — remove it with qpdf --decrypt --password=YOUR_PASSWORD in.pdf out.pdf (PDFs with only permission restrictions index fine)
Verify file is not corrupted

Performance Tuning

# Faster processing
chat.enable_rag(documents=["doc.pdf"], chunk_size=300, max_chunks=2)

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

# Memory efficient
chat.enable_rag(documents=["doc.pdf"], chunk_size=400, max_chunks=2)

Dynamic Tool Loading

Off by default, doc profile only. This is the first stage of a phased rollout (Dynamic Tool Loader plan); enable it explicitly to try it.

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 SDK with ChatAgentConfig(prompt_profile="doc"), or gaia eval agent --agent-type doc, an explicit override since the eval otherwise scores the flagship gaia agent. The doc id is no longer offered in the agent picker, but it still resolves, so the eval command is unchanged. 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:

from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig

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

# 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 for the full design.

Next Steps

GAIA Chat Desktop

Privacy-first desktop app with drag-and-drop document Q&A

Agent SDK Reference

Classes, methods, and code examples

Voice Interaction

Add speech recognition and text-to-speech

CLI Reference

Explore all command-line options

Agent UI SDK Reference

Python backend API for the desktop chat application

API Server

Integrate via OpenAI-compatible API

Getting Started

C++ Framework

Python Framework

Quick Start

CLI Usage

Interactive Mode

Single Query Mode

Document Q&A (RAG)

CLI with RAG

Interactive RAG Commands

RAG Debug Mode

Chunking Strategies

Structural Chunking

LLM-Based Semantic

Troubleshooting

Dynamic Tool Loading

Next Steps

GAIA Chat Desktop

Agent SDK Reference

Voice Interaction

CLI Reference

Agent UI SDK Reference

API Server

​Quick Start

​CLI Usage

​Interactive Mode

​Single Query Mode

​Document Q&A (RAG)

​CLI with RAG

​Interactive RAG Commands

​RAG Debug Mode

​Chunking Strategies

Structural Chunking

LLM-Based Semantic

​Troubleshooting

​Dynamic Tool Loading

​Next Steps

GAIA Chat Desktop

Agent SDK Reference

Voice Interaction

CLI Reference

Agent UI SDK Reference

API Server

Quick Start

CLI Usage

Interactive Mode

Single Query Mode

Document Q&A (RAG)

CLI with RAG

Interactive RAG Commands

RAG Debug Mode

Chunking Strategies

Troubleshooting

Dynamic Tool Loading

Next Steps