Agent UI SDK

from gaia.ui.server import create_app

# Create with default database (~/.gaia/chat/gaia_chat.db)
app = create_app()

# Create with custom database path
app = create_app(db_path="/path/to/my/chat.db")

# Create with in-memory database (for testing)
app = create_app(db_path=":memory:")

import uvicorn
from gaia.ui.server import create_app

app = create_app()
uvicorn.run(app, host="localhost", port=4200)

python -m gaia.ui.server --port 4200

from gaia.ui.database import ChatDatabase

db = ChatDatabase()  # Uses default path ~/.gaia/chat/gaia_chat.db

# Create a session
session = db.create_session(title="My Chat", model="Qwen3.5-35B-A3B-GGUF")
print(f"Session ID: {session['id']}")

# Add messages
db.add_message(session["id"], "user", "Hello!")
db.add_message(session["id"], "assistant", "Hi there! How can I help?")

# Retrieve messages
messages = db.get_messages(session["id"])
for msg in messages:
    print(f"{msg['role']}: {msg['content']}")

# Clean up
db.close()

from gaia.ui.database import ChatDatabase, DEFAULT_DB_PATH

class ChatDatabase:
    def __init__(self, db_path: str = None):
        """Initialize database connection.

        Args:
            db_path: Path to SQLite database file.
                     Defaults to ~/.gaia/chat/gaia_chat.db.
                     Use ":memory:" for in-memory database (testing).
        """

db = ChatDatabase()

# Create session with attached documents
session = db.create_session(
    title="Project Review",
    model="Qwen3.5-35B-A3B-GGUF",
    system_prompt="You are a code review assistant.",
    document_ids=["doc-abc123"],
)

# Update title
db.update_session(session["id"], title="Sprint 42 Review")

# List recent sessions
for s in db.list_sessions(limit=10):
    print(f"{s['title']} ({s['message_count']} messages)")

# Add a user message
db.add_message(session_id, "user", "What does this function do?")

# Add an assistant message with RAG sources
db.add_message(
    session_id,
    "assistant",
    "This function initializes the database connection...",
    rag_sources=[
        {"document_id": "doc-123", "filename": "main.py", "chunk": "def init_db()...", "score": 0.92}
    ],
    tokens_prompt=150,
    tokens_completion=87,
)

# Retrieve conversation
messages = db.get_messages(session_id)
for msg in messages:
    print(f"[{msg['role']}] {msg['content'][:80]}...")

import hashlib

# Add a document
doc = db.add_document(
    filename="manual.pdf",
    filepath="/home/user/docs/manual.pdf",
    file_hash=hashlib.sha256(open("manual.pdf", "rb").read()).hexdigest(),
    file_size=1_234_567,
    chunk_count=45,
)

# Attach to a session
db.attach_document(session_id, doc["id"])

# Check which documents are in a session
docs = db.get_session_documents(session_id)
for d in docs:
    print(f"{d['filename']} ({d['chunk_count']} chunks)")

stats = db.get_stats()
print(f"Sessions: {stats['sessions']}")
print(f"Messages: {stats['messages']}")
print(f"Documents: {stats['documents']}")
print(f"Total chunks: {stats['total_chunks']}")
print(f"Total size: {stats['total_size_bytes']} bytes")

from gaia.ui.server import create_app

def create_app(db_path: str = None, webui_dist: str = None) -> FastAPI:
    """Create and configure the FastAPI application.

    Args:
        db_path: Path to SQLite database.
                 None for default (~/.gaia/chat/gaia_chat.db).
                 ":memory:" for testing.
        webui_dist: Path to a prebuilt Agent UI bundle to serve as static
                 files. None falls back to the bundle that ships with the
                 installed package (used by `gaia --ui-dist`).

    Returns:
        Configured FastAPI application with all routers (agents, chat,
        documents, files, mcp, sessions, system, tunnel) registered.
    """

app = create_app(db_path=":memory:")
db        = app.state.db               # ChatDatabase
registry  = app.state.agent_registry   # AgentRegistry (see /spec/plugin-registry)
dispatch  = app.state.dispatch_queue   # background job queue
monitor   = app.state.document_monitor # watches the library for new files

class SystemStatus(BaseModel):
    """System readiness status returned by GET /api/system/status."""
    lemonade_running: bool = False
    model_loaded: Optional[str] = None
    embedding_model_loaded: bool = False
    disk_space_gb: float = 0.0
    memory_available_gb: float = 0.0
    initialized: bool = False
    version: str = "0.1.0"

class CreateSessionRequest(BaseModel):
    """POST /api/sessions"""
    title: Optional[str] = None
    model: Optional[str] = None
    system_prompt: Optional[str] = None
    document_ids: List[str] = []

class UpdateSessionRequest(BaseModel):
    """PUT /api/sessions/{session_id}"""
    title: Optional[str] = None
    system_prompt: Optional[str] = None

class SessionResponse(BaseModel):
    """Returned by session endpoints."""
    id: str
    title: str
    created_at: str
    updated_at: str
    model: str
    # The model a turn runs: custom override, agent preference, device config
    effective_model: Optional[str] = None
    system_prompt: Optional[str] = None
    message_count: int = 0
    document_ids: List[str] = []
    # Where the next chat turn is answered. inference_remote is None when it
    # can't be determined; the UI then makes no local-or-cloud claim.
    inference_remote: Optional[bool] = None
    inference_provider: Optional[str] = None       # "lemonade", "fireworks", "amd", ...
    inference_provider_name: Optional[str] = None  # "Fireworks AI"
    inference_description: Optional[str] = None    # one sentence, as the TUI shows it

class SessionListResponse(BaseModel):
    sessions: List[SessionResponse]
    total: int

class ChatRequest(BaseModel):
    """POST /api/chat/send"""
    session_id: str
    message: str
    document_ids: Optional[List[str]] = None
    stream: bool = True   # SSE streaming by default

class ChatResponse(BaseModel):
    """Non-streaming response from POST /api/chat/send."""
    message_id: int
    content: str
    sources: List[SourceInfo] = []
    tokens: Optional[Dict[str, int]] = None

class SourceInfo(BaseModel):
    """RAG source citation."""
    document_id: str
    filename: str
    chunk: str
    score: float
    page: Optional[int] = None

class MessageResponse(BaseModel):
    """Individual message in a session."""
    id: int
    session_id: str
    role: str             # "user", "assistant", or "system"
    content: str
    created_at: str
    rag_sources: Optional[List[SourceInfo]] = None
    agent_steps: Optional[List[AgentStepResponse]] = None

class MessageListResponse(BaseModel):
    messages: List[MessageResponse]
    total: int

class DocumentResponse(BaseModel):
    """Document in the global library."""
    id: str
    filename: str
    filepath: str
    file_size: int
    chunk_count: int
    indexed_at: str
    last_accessed_at: Optional[str] = None
    sessions_using: int = 0
    indexing_status: str = "complete"  # pending | indexing | complete | failed | cancelled | missing

class DocumentListResponse(BaseModel):
    documents: List[DocumentResponse]
    total: int
    total_size_bytes: int
    total_chunks: int

class DocumentUploadRequest(BaseModel):
    """POST /api/documents/upload-path"""
    filepath: str

class AttachDocumentRequest(BaseModel):
    """POST /api/sessions/{session_id}/documents"""
    document_id: str

-- Global document library
CREATE TABLE documents (
    id TEXT PRIMARY KEY,
    filename TEXT NOT NULL,
    filepath TEXT NOT NULL,
    file_hash TEXT UNIQUE NOT NULL,
    file_size INTEGER DEFAULT 0,
    chunk_count INTEGER DEFAULT 0,
    indexed_at TEXT,
    last_accessed_at TEXT,
    indexing_status TEXT DEFAULT 'complete',  -- pending | indexing | complete | failed | cancelled
    file_mtime REAL                          -- file modification time (Unix epoch)
);

-- Sessions (conversations)
CREATE TABLE sessions (
    id TEXT PRIMARY KEY,
    title TEXT NOT NULL DEFAULT 'New Chat',
    created_at TEXT,
    updated_at TEXT,
    model TEXT NOT NULL DEFAULT 'Qwen3.5-35B-A3B-GGUF',
    system_prompt TEXT
);

-- Many-to-many: documents attached to sessions
CREATE TABLE session_documents (
    session_id TEXT REFERENCES sessions(id) ON DELETE CASCADE,
    document_id TEXT REFERENCES documents(id) ON DELETE CASCADE,
    attached_at TEXT,
    PRIMARY KEY (session_id, document_id)
);

-- Messages
CREATE TABLE messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id TEXT REFERENCES sessions(id) ON DELETE CASCADE,
    role TEXT CHECK(role IN ('user', 'assistant', 'system')) NOT NULL,
    content TEXT NOT NULL,
    created_at TEXT,
    rag_sources TEXT,          -- JSON array of source citations
    agent_steps TEXT,          -- JSON array of agent execution steps
    inference_stats TEXT,      -- JSON blob with timing/token stats
    tokens_prompt INTEGER,
    tokens_completion INTEGER
);

-- Key/value user settings (e.g. custom_model override)
CREATE TABLE settings (
    key TEXT PRIMARY KEY,
    value TEXT
);

import pytest
from fastapi.testclient import TestClient
from gaia.ui.server import create_app

@pytest.fixture
def client():
    """Create test client with in-memory database."""
    app = create_app(db_path=":memory:")
    return TestClient(app)

def test_create_session(client):
    resp = client.post("/api/sessions", json={"title": "Test Chat"})
    assert resp.status_code == 200
    data = resp.json()
    assert data["title"] == "Test Chat"
    assert data["message_count"] == 0

def test_send_message(client):
    # Create session first
    session = client.post("/api/sessions", json={}).json()
    session_id = session["id"]

    # Send a non-streaming message
    resp = client.post("/api/chat/send", json={
        "session_id": session_id,
        "message": "Hello",
        "stream": False,
    })
    assert resp.status_code == 200

def test_document_lifecycle(client):
    # This test requires a real file on disk
    pass

def test_health_check(client):
    resp = client.get("/api/health")
    assert resp.status_code == 200
    assert resp.json()["status"] == "ok"

from gaia.ui.database import ChatDatabase

def test_session_crud():
    db = ChatDatabase(":memory:")

    # Create
    session = db.create_session(title="Test")
    assert session["title"] == "Test"

    # Read
    fetched = db.get_session(session["id"])
    assert fetched is not None

    # Update
    updated = db.update_session(session["id"], title="Updated")
    assert updated["title"] == "Updated"

    # Delete
    assert db.delete_session(session["id"]) is True
    assert db.get_session(session["id"]) is None

    db.close()

def test_message_ordering():
    db = ChatDatabase(":memory:")
    session = db.create_session()

    db.add_message(session["id"], "user", "First")
    db.add_message(session["id"], "assistant", "Second")
    db.add_message(session["id"], "user", "Third")

    messages = db.get_messages(session["id"])
    assert len(messages) == 3
    assert messages[0]["content"] == "First"
    assert messages[2]["content"] == "Third"

    db.close()

from gaia_agent_chat.agent import ChatAgent, ChatAgentConfig

# The server creates a ChatAgent instance per request. ChatAgent derives its
# system prompt from `prompt_profile` ("chat" | "doc" | "file" | "data" |
# "web" | "full") — there is no `system_prompt` config field.
config = ChatAgentConfig(
    model_id=session.get("model", "Qwen3.5-35B-A3B-GGUF"),
    prompt_profile="doc",
    allowed_paths=["/path/to/files"],
)
agent = ChatAgent(config)

# Process a query (agent reasons, uses tools, returns response)
result = agent.process_query(message)

from gaia.rag.sdk import RAGSDK, RAGConfig

config = RAGConfig()
rag = RAGSDK(config)
result = rag.index_document(filepath)
chunk_count = result.get("num_chunks", 0)

npm install -g @amd-gaia/agent-ui

gaia-ui              # Start Python backend + open browser
gaia-ui --serve      # Serve frontend only (Node.js static server)
gaia-ui --port 8080  # Custom port
gaia-ui --version    # Show version

# Check version consistency (package.json matches version.py)
node installer/version/bump-ui-version.mjs --check

# Sync package.json to version.py
node installer/version/bump-ui-version.mjs

# Full release (sync, commit, tag, push)
node installer/version/release-ui.mjs