Agent UI Server

Documentation Index

Fetch the complete documentation index at: https://amd-gaia.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• SQLite for zero-configuration persistence (WAL mode for concurrent reads)
• FastAPI for automatic OpenAPI docs and Pydantic validation
• SSE (Server-Sent Events) for streaming chat responses
• Hybrid document model — global library with per-session attachment
• Shared database between CLI and desktop app

​

Module Structure

src/gaia/ui/
  __init__.py          # Package init
  server.py            # FastAPI app factory and global router wiring
  database.py          # ChatDatabase class (SQLite)
  models.py            # Pydantic request/response models
  sse_handler.py       # SSE output handler for streaming agent events
  tunnel.py            # Tunnel manager for mobile access via ngrok
  dispatch.py          # Background task dispatcher (agent jobs, session GC, etc.)
  document_monitor.py  # Watches the library for new/changed files
  dependencies.py      # FastAPI dependency-injection helpers (shared registry/db)
  build.py             # Embedded-frontend build bootstrap for prebuilt dist/
  utils.py             # Cross-router helpers
  _chat_helpers.py     # Agent factory / session mapping used by the chat router
  routers/             # One module per API surface (see below)

​

Routers (src/gaia/ui/routers/)

​

Server (server.py)

​

App Factory

def create_app(db_path: str = None) -> FastAPI:

• CORS middleware (allows all origins for local use)
• Database initialization and shared AgentRegistry
• Router registration (include_router for each module above)
• Static file serving (for web frontend, when dist/ build exists)
• Dispatch-queue + document-monitor startup tasks

​

Endpoint Registration

​

Streaming Implementation

1. A background thread calls AgentSDK.send_stream() synchronously
2. Chunks are placed into a queue.Queue
3. The async generator polls the queue and yields SSE events
4. On completion, the full response is saved to the database

# SSE event format
data: {"type": "chunk", "content": "partial text"}
data: {"type": "done", "message_id": 42, "content": "full response"}
data: {"type": "error", "content": "error description"}

​

Helper Functions

​

Database (database.py)

​

Schema

documents          -- Global document library
sessions           -- Chat conversations
session_documents  -- Many-to-many attachment relationship
messages           -- Conversation messages with optional RAG metadata

​

Configuration

• Foreign keys: Enabled (PRAGMA foreign_keys = ON)
• Journal mode: WAL (PRAGMA journal_mode = WAL)
• Thread safety: check_same_thread=False (FastAPI runs across threads)
• Row factory: sqlite3.Row for dict-like access

​

Transaction Management

@contextmanager
def _transaction(self):
    """Execute operations atomically."""
    try:
        yield
        self._conn.commit()
    except Exception:
        self._conn.rollback()
        raise

​

Document Deduplication

​

Document Upload Paths

​

Cascade Deletes

• Deleting a session cascades to its messages and session_documents entries
• Deleting a document cascades to session_documents entries

​

Models (models.py)

​

Dependencies

​

Required

​

Optional

​

Error Handling

​

Security Considerations

• CORS: Uses an allowlist of localhost origins plus ngrok regex. The standalone server (python -m gaia.ui.server) binds to localhost by default. Note: gaia chat --ui binds to 0.0.0.0 for Electron/browser access
• No authentication: Designed for single-user local use. Do not expose to untrusted networks
• File path validation: The upload-path endpoint sanitizes all user-provided paths:
  • Null byte rejection (prevents path injection)
  • Path resolution to absolute canonical paths (eliminates .. traversal)
  • File extension allowlist (only document/code file types accepted)
  • See _sanitize_document_path() in server.py
• Static file serving: URL paths are validated to stay within the dist/ directory via _sanitize_static_path(), preventing directory traversal
• SQL injection: Prevented by parameterized queries throughout
• No telemetry: No data is sent externally