Chat SDK - GAIA SDK

📖 You are viewing: User Guide - Learn how to build chat applicationsSee also: SDK Reference · API Specification

Source Code: src/gaia/chat/sdk.py · src/gaia/rag/sdk.py

The GAIA Chat SDK provides a programmable interface for building text-based conversational AI applications with conversation memory and optional document Q&A (RAG).

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

Quick Start

Install dependencies

Activate your virtual environment and install GAIA with RAG support:

uv pip install -e ".[rag]"

Create a simple chat

Start chatting with just a few lines of code:

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

Access advanced features with the complete ChatSDK:

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"

Core Classes

ChatConfig

Configure your chat session with these options:

@dataclass
class ChatConfig:
    model: str = "Qwen3-Coder-30B-A3B-Instruct-GGUF"  # Default validated model
    max_tokens: int = 512
    system_prompt: Optional[str] = None
    max_history_length: int = 4
    show_stats: bool = False
    use_local_llm: bool = True
    assistant_name: str = "gaia"

ChatResponse

Responses include text, history, and optional statistics:

@dataclass
class ChatResponse:
    text: str
    history: Optional[List[str]] = None
    stats: Optional[Dict[str, Any]] = None

SimpleChat

Lightweight wrapper for basic chat without complex configuration. Perfect for getting started quickly.

CLI Usage

Interactive Mode

Start a conversational chat session:

# Start interactive chat
gaia chat

Session Management

/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

Other Commands

/help or /? - Show help message
/quit - Exit the chat session

Document Q&A: To work with documents, see the Document Q&A (RAG) section below for RAG-specific commands.

Single Query Mode

Execute one-shot queries:

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

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

Python SDK Examples

Streaming Chat

Stream responses in real-time:

streaming.py

from gaia.chat.sdk import ChatSDK

chat = ChatSDK()

print("AI: ", end="", flush=True)
for chunk in chat.send_stream("Tell me a story"):
    if not chunk.is_complete:
        print(chunk.text, end="", flush=True)
print()

Custom Assistant Name

Personalize your assistant:

custom_assistant.py

from gaia.chat.sdk import ChatConfig, ChatSDK

config = ChatConfig(
    assistant_name="Gaia",
    system_prompt="You are Gaia, a helpful AI assistant."
)
chat = ChatSDK(config)

response = chat.send("What's your name?")
print(f"Gaia: {response.text}")

Session Management

Manage multiple conversation contexts:

sessions.py

from gaia.chat.sdk import ChatSession

sessions = ChatSession()

# Create different contexts with custom names
work_chat = sessions.create_session(
    "work",
    system_prompt="You are a professional assistant.",
    assistant_name="WorkBot"
)

personal_chat = sessions.create_session(
    "personal",
    system_prompt="You are a friendly companion.",
    assistant_name="Buddy"
)

# Separate conversation histories
work_response = work_chat.send("Draft a team email")
personal_response = personal_chat.send("What's for dinner?")

Conversation History

Access and manage conversation history:

history.py

from gaia.chat.sdk import ChatSDK

chat = ChatSDK()

chat.send("Hello")
chat.send("How are you?")

# Get formatted history
for entry in chat.get_formatted_history():
    print(f"{entry['role']}: {entry['message']}")

# Clear history
chat.clear_history()

# Check metrics
print(f"Conversation pairs: {chat.conversation_pairs}")

Document Q&A (RAG)

RAG (Retrieval-Augmented Generation) enables chatting with PDF documents using semantic search and context retrieval.

Python SDK with RAG

Enable RAG and index documents

rag_chat.py

from gaia.chat.sdk import ChatSDK

chat = ChatSDK()

# Enable RAG and index documents
chat.enable_rag(documents=["manual.pdf", "guide.pdf"])

Chat with document context

# Chat with document context
response = chat.send("What does the manual say about installation?")
print(response.text)

# Add more documents
chat.add_document("troubleshooting.pdf")

Disable RAG when done

# Disable RAG when done
chat.disable_rag()

CLI with RAG

Single Document
Multiple Documents
One-shot Query
Voice Mode

# Chat with single document
gaia chat --index manual.pdf

# Chat with multiple documents
gaia chat --index doc1.pdf doc2.pdf doc3.pdf

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

Prerequisites: Voice mode requires the talk module:

uv pip install -e ".[talk]"

# Voice with documents
gaia talk --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:

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 Configuration

Advanced RAG setup options:

advanced_rag.py

from gaia.chat.sdk import ChatSDK

chat = ChatSDK()

# Advanced RAG setup
chat.enable_rag(
    documents=["doc1.pdf", "doc2.pdf"],
    chunk_size=600,      # Larger chunks for more context
    max_chunks=4,        # More chunks per query
    chunk_overlap=100    # Overlap for context preservation
)

# Check indexed documents
if chat.rag:
    status = chat.rag.get_status()
    print(f"Indexed {status['indexed_files']} files")
    print(f"Total chunks: {status['total_chunks']}")

RAG Debug Mode

Enable debug mode to see detailed retrieval information:

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

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

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
)

RAG Troubleshooting

Missing Dependencies

uv pip install -e ".[rag]"

Voice Mode: No Module Named 'pip'

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

PDF Issues

Ensure PDF has extractable text (not scanned images)
Check file is not password-protected
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=600, max_chunks=5, chunk_overlap=100)

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

API Reference

ChatSDK Core Methods

Messaging

send(message: str) -> ChatResponse
send_stream(message: str)

History

get_history() -> List[str]
clear_history()
get_formatted_history() -> List[Dict]

RAG (Document Q&A)

enable_rag(documents=None, **kwargs)
disable_rag()
add_document(path: str) -> bool

Configuration

update_config(**kwargs)
get_stats() -> Dict
display_stats(stats=None)
start_interactive_session()

SimpleChat Methods

ask(question: str) -> str - Ask question, get response
ask_stream(question: str) - Ask question, stream response
clear_memory() - Clear conversation memory
get_conversation() -> List[Dict] - Get conversation history

ChatSession Methods

create_session(id, config=None, **kwargs) -> ChatSDK - Create new session
get_session(id) -> ChatSDK - Get existing session
delete_session(id) -> bool - Delete session
list_sessions() -> List[str] - List all sessions
clear_all_sessions() - Delete all sessions

Utility Functions

quick_chat(message, system_prompt=None, model=None, assistant_name=None) -> str
quick_chat_with_memory(messages, system_prompt=None, model=None, assistant_name=None) -> List[str]

Best Practices

Choose the Right Interface

SimpleChat for basic needs, ChatSDK for full features, ChatSession for multi-context apps

Memory Management

Configure max_history_length based on memory constraints

Performance

Enable show_stats=True during development

Error Handling

Wrap chat operations in try-catch blocks

Resource Cleanup

Clear sessions when done to free memory

Assistant Naming

Use meaningful names for distinct use cases

Next Steps

Voice Interaction

Add speech recognition and text-to-speech

CLI Reference

Explore all command-line options

Development Guide

Learn to build custom agents

API Server

Integrate via OpenAI-compatible API

Getting Started

User Guides

Playbooks

SDK Reference

​Quick Start

​Core Classes

​ChatConfig

​ChatResponse

​SimpleChat

SimpleChat

​CLI Usage

​Interactive Mode

​Single Query Mode

​Python SDK Examples

​Streaming Chat

​Custom Assistant Name

​Session Management

​Conversation History

​Document Q&A (RAG)

​Python SDK with RAG

​CLI with RAG

​Interactive RAG Commands

​RAG Configuration

​RAG Debug Mode

​Chunking Strategies

Structural Chunking

LLM-Based Semantic

​RAG Troubleshooting

​API Reference

​ChatSDK Core Methods

Messaging

History

RAG (Document Q&A)

Configuration

​SimpleChat Methods

​ChatSession Methods

​Utility Functions

​Best Practices

Choose the Right Interface

Memory Management

Performance

Error Handling

Resource Cleanup

Assistant Naming

​Next Steps

Voice Interaction

CLI Reference

Development Guide

API Server

Quick Start

Core Classes

ChatConfig

ChatResponse

SimpleChat

CLI Usage

Interactive Mode

Single Query Mode

Python SDK Examples

Streaming Chat

Custom Assistant Name

Session Management

Conversation History

Document Q&A (RAG)

Python SDK with RAG

CLI with RAG

Interactive RAG Commands

RAG Configuration

RAG Debug Mode

Chunking Strategies

RAG Troubleshooting

API Reference

ChatSDK Core Methods

SimpleChat Methods

ChatSession Methods

Utility Functions

Best Practices

Next Steps