Agent SDK

The direct OpenAI and LiteLLM provider adapters have been removed. Any use_chatgpt field shown below is a migration-error shim: setting it to True raises before inference. Use the Lemonade gateway path.

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

Import: from gaia.chat.sdk import AgentSDK, AgentConfig, SimpleChat, AgentSession, quick_chat

See also: User Guide · API Specification

Core Classes

AgentConfig

Configure your chat session:

@dataclass
class AgentConfig:
    model: str = "Gemma-4-E4B-it-GGUF"  # Default validated model (DEFAULT_MODEL_NAME)
    max_tokens: int = 512
    temperature: Optional[float] = None
    top_p: Optional[float] = None  # None = the provider's default
    system_prompt: Optional[str] = None
    max_history_length: int = 4
    show_stats: bool = False
    logging_level: str = "INFO"
    use_claude: bool = False       # Use Claude API
    use_chatgpt: bool = False      # Removed; True raises migration guidance
    use_local_llm: bool = True     # Use local LLM
    claude_model: str = "claude-sonnet-4-20250514"
    base_url: Optional[str] = None # Lemonade server URL
    assistant_name: str = "gaia"

The SDK applies the system prompt once per request. set_system_prompt() and update_config(system_prompt=...) take effect on the next request; structured message calls can override it for one request without changing the stored prompt. Custom prompts use the native system-message channel for every provider.

AgentResponse

Responses include text, history, and optional statistics:

@dataclass
class AgentResponse:
    text: str
    history: Optional[List[str]] = None
    stats: Optional[Dict[str, Any]] = None
    is_complete: bool = True  # False for streaming chunks
    usage: Optional[Dict[str, Any]] = None  # per-call token usage, when the provider reports it
    finish_reason: Optional[str] = None  # "length" = output-token limit cut it off
    reasoning: Optional[str] = None  # the model's reasoning, kept apart from `text`

A reasoning model (Gemma-4, Qwen3) can spend the whole max_tokens budget thinking. The reply then has empty text, finish_reason == "length", and the partial thought in reasoning. send() and send_messages() also log a warning naming the budget; the streaming methods report it on the final chunk. Raise max_tokens when that happens.

SimpleChat

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

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)

Quick Chat (One-Off)

from gaia.chat.sdk import quick_chat

# Single query — returns str directly
response = quick_chat("What is machine learning?")
print(response)

# With options
response = quick_chat(
    "Explain quantum computing",
    model="Qwen3.5-35B-A3B-GGUF",
    system_prompt="You are a physics teacher."
)
print(response)

Chat with Memory

from gaia.chat.sdk import AgentSDK, AgentConfig

config = AgentConfig(
    model="Qwen3-0.6B-GGUF",
    max_tokens=512,
    max_history_length=4,
    system_prompt="You are a helpful coding assistant.",
    assistant_name="CodeBot"
)

chat = AgentSDK(config)

# Multi-turn conversation
response1 = chat.send("What is Python?")
print(response1.text)

response2 = chat.send("Show me an example")
print(response2.text)  # LLM remembers context

# Check history
history = chat.get_history()
print(f"Conversation turns: {len(history)}")

chat.clear_history()

Streaming

from gaia.chat.sdk import AgentSDK

chat = AgentSDK()

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

from gaia.chat.sdk import AgentConfig, AgentSDK

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

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

Session Management

Manage multiple conversation contexts:

from gaia.chat.sdk import AgentSession

sessions = AgentSession()

# 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

Failed requests and streams cancelled before the final chunk preserve the previous history. Once the final chunk arrives, the completed turn remains in history even if the caller stops reading immediately.

from gaia.chat.sdk import AgentSDK

chat = AgentSDK()

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

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

chat.clear_history()
print(f"Conversation pairs: {chat.conversation_pairs}")

Chat with RAG

from gaia.chat.sdk import AgentSDK

chat = AgentSDK()

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

# 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
chat.disable_rag()

With RAG enabled, send() and send_stream() raise RAGContextError instead of answering without your documents. It fires when retrieval fails, or when the model’s window leaves under 500 tokens for document context after the system prompt, history, question and reply reserve. The message says what to shrink or what broke, and history is left as it was.

from gaia.chat.sdk import AgentSDK, RAGContextError

chat = AgentSDK()
chat.enable_rag(documents=["guide.pdf"])

try:
    response = chat.send("Summarize the guide")
except RAGContextError as e:
    print(f"Not sent: {e}")

Advanced RAG Configuration

from gaia.chat.sdk import AgentSDK

chat = AgentSDK()

chat.enable_rag(
    documents=["doc1.pdf", "doc2.pdf"],
    chunk_size=500,      # Largest chunks (500 is the maximum)
    max_chunks=4,        # More chunks per query
    chunk_overlap=100    # Overlap for context preservation
)

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

Custom Messages

from gaia.chat.sdk import AgentSDK

chat = AgentSDK()

messages = [
    {"role": "system", "content": "You are a math tutor."},
    {"role": "user", "content": "Explain calculus"},
    {"role": "assistant", "content": "Calculus is..."},
    {"role": "user", "content": "Give me an example"}
]

response = chat.send_messages(
    messages=messages,
    system_prompt="Be concise and clear"
)
print(response.text)

API Reference

AgentSDK Methods

Messaging

send(message: str) -> AgentResponse
send_stream(message: str)
send_messages(messages, system_prompt) -> AgentResponse

History

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

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

AgentSession Methods

create_session(session_id, config=None, **kwargs) -> AgentSDK — Create new session
get_session(session_id) -> AgentSDK — Get existing session
delete_session(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, AgentSDK for full features, AgentSession for multi-context apps

Memory Management

Configure max_history_length based on memory constraints

Performance

Enable show_stats=True during development

Resource Cleanup

Clear sessions when done to free memory

User Guide — CLI usage, RAG commands, troubleshooting
GAIA Chat Desktop — Desktop app with GUI and document Q&A
Agent UI SDK — Python backend for the desktop application (FastAPI, SQLite, REST API)
LLM Client — Language model integration
API Specification — Technical specification

Getting Started

C++ Framework

Python Framework

Core Classes

AgentConfig

AgentResponse

SimpleChat

Quick Chat (One-Off)

Chat with Memory

Streaming

Custom Assistant

Session Management

Conversation History

Chat with RAG

Advanced RAG Configuration

Custom Messages

API Reference

AgentSDK Methods

Messaging

History

RAG (Document Q&A)

Configuration

SimpleChat Methods

AgentSession Methods

Utility Functions

Best Practices

Choose the Right Interface

Memory Management

Performance

Resource Cleanup

​Core Classes

​AgentConfig

​AgentResponse

​SimpleChat

​Quick Chat (One-Off)

​Chat with Memory

​Streaming

​Custom Assistant

​Session Management

​Conversation History

​Chat with RAG

​Advanced RAG Configuration

​Custom Messages

​API Reference

​AgentSDK Methods

Messaging

History

RAG (Document Q&A)

Configuration

​SimpleChat Methods

​AgentSession Methods

​Utility Functions

​Best Practices

Choose the Right Interface

Memory Management

Performance

Resource Cleanup

​Related

Core Classes

AgentConfig

AgentResponse

SimpleChat

Quick Chat (One-Off)

Chat with Memory

Streaming

Custom Assistant

Session Management

Conversation History

Chat with RAG

Advanced RAG Configuration

Custom Messages

API Reference

AgentSDK Methods

SimpleChat Methods

AgentSession Methods

Utility Functions

Best Practices

Related