Skip to main content
First time here? Complete the Setup guide first to install GAIA and its dependencies.
Looking for the API? See the Chat 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 ChatSDK, ChatConfig

config = ChatConfig(
    show_stats=True,
    max_history_length=6
)
chat = ChatSDK(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
agent = ChatAgent(
    rag_documents=['document.pdf'],
    chunk_size=500,
    chunk_overlap=50
)

LLM-Based Semantic

More accurate context
agent = ChatAgent(
    rag_documents=['document.pdf'],
    use_llm_chunking=True,
    chunk_size=500
)

​
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

Chat SDK Reference

Classes, methods, and code examples

Voice Interaction

Add speech recognition and text-to-speech

CLI Reference

Explore all command-line options

API Server

Integrate via OpenAI-compatible API