Skip to main content
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

1

Install dependencies

Activate your virtual environment and install GAIA with RAG support:
uv pip install -e ".[rag]"
2

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

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
  • /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 PDF documents using semantic search and context retrieval.

​
CLI with RAG

# Chat with single document
gaia chat --index manual.pdf
PDF Indexing Requirements: Processing PDFs with images requires a Vision Language Model (VLM). GAIA uses Qwen3-VL-4B-Instruct-GGUF by default for extracting text from images in PDFs.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:
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)
  • /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)
  • /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
  • 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

uv pip install -e ".[rag]"
If gaia talk fails with “No module named ‘pip’”, install dependencies manually:
# Install talk dependencies
uv pip install -e ".[talk]"

# If the error persists, install pip in your environment
python -m ensurepip --upgrade
  • Ensure PDF has extractable text (not scanned images)
  • Check file is not password-protected
  • Verify file is not corrupted
# 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)

​
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