Example Projects¶

This guide includes six complete example projects that demonstrate how to build applications on Cohesity Gaia. Each project is self-contained with its own README, dependencies, and instructions — start with the one that matches your experience level, or work through them progressively.

Projects at a Glance¶

Project	Description	Complexity	Stack
01 — Hello Gaia	Minimal CLI tool that queries Gaia from the terminal	Beginner	Python
02 — Chat App	Full-stack chat application with streaming responses	Intermediate	FastAPI + React
03 — Document Search	Document search & analysis with exhaustive search and refinement	Advanced	FastAPI + React
04 — Gaia MCP Server	MCP server over Streamable HTTP for Cursor/Claude/MCP clients	Advanced	FastAPI + FastMCP
05 — Marketplace Chat	Full-stack chat app packaged for Cohesity App Marketplace deployment	Intermediate	FastAPI + React + AppSpec
06 — Marketplace MCP Server	MCP server on the Marketplace, exposing Gaia to Cursor/Claude Desktop/Copilot	Advanced	FastMCP + AppSpec

01 — Hello Gaia¶

A minimal starting point. This CLI tool connects to the Gaia API, lists available datasets, and lets you ask a question — all in a single Python script. Perfect for verifying your API key works and understanding the basic request/response cycle.

What You'll Learn¶

Installing and configuring the gaia_sdk package
Authenticating with environment variables
Listing datasets and sending a RAG query
Handling basic errors

Quick Run¶

Bash

cd examples/01-hello-gaia

# Install dependencies
pip install -r requirements.txt

# Set your API key
export GAIA_API_KEY="your-api-key-here"

# Run it
python hello_gaia.py

Sample output

Text Only

Connecting to Gaia...
Found 3 datasets:
  1. engineering-docs
  2. support-tickets
  3. financial-reports

Select a dataset (1-3): 1

Ask a question (or 'quit'): What were the main incidents last week?

Answer: Based on the engineering documentation, there were two main
incidents last week: a database failover on Tuesday affecting the
billing service, and a network partition on Thursday in the us-west-2
region...

Sources:
  - incident-report-2024-03-12.pdf (p. 3-7)
  - postmortem-network-partition.md (p. 1-4)

Key File¶

File	Purpose
`hello_gaia.py`	Complete CLI application (~80 lines)
`requirements.txt`	Python dependencies
`.env.example`	Environment variable template

Browse project files
Open code browser

02 — Chat App¶

A full-stack conversational interface. This project builds a web-based chat application where users can select a dataset, ask questions, and see streaming responses in real time. It demonstrates the core patterns you'll use in most Gaia applications.

What You'll Learn¶

FastAPI backend with GaiaClient integration
SSE streaming from backend to frontend
React chat UI with message history
Conversation management with conversation_id
Session-based authentication
Error handling across the full stack

Architecture¶

Text Only

┌──────────────────┐     ┌──────────────────┐     ┌──────────────┐
│   React Frontend │────▶│  FastAPI Backend  │────▶│   Gaia API   │
│   (Chat UI)      │ SSE │  (Proxy + Auth)   │     │              │
└──────────────────┘     └──────────────────┘     └──────────────┘

Quick Run¶

With DockerWithout Docker

Bash

cd examples/02-chat-app

# Set your API key
cp backend/.env.example backend/.env
# Edit backend/.env with your GAIA_API_KEY

# Start everything
docker compose up --build

Open http://localhost in your browser.

Bash

cd examples/02-chat-app

# Backend
cd backend
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your GAIA_API_KEY
uvicorn app.main:app --reload &

# Frontend
cd ../frontend
npm install
npm run dev

Open http://localhost:5173 in your browser.

Key Files¶

File	Purpose
`backend/app/main.py`	FastAPI application with CORS and lifespan
`backend/app/routes/ask.py`	Query and streaming endpoints
`backend/app/routes/datasets.py`	Dataset listing endpoint
`frontend/src/pages/ChatPage.tsx`	Main chat interface
`frontend/src/components/MessageBubble.tsx`	Chat message rendering
`frontend/src/hooks/useStreaming.ts`	SSE streaming hook
`docker-compose.yml`	Full-stack container orchestration

Browse project files
Open code browser

03 — Document Search¶

An advanced search and analysis tool. This project implements a document search interface with exhaustive search, pagination, document refinement, and feedback — showcasing Gaia's full feature set for e-discovery and compliance workflows.

What You'll Learn¶

Exhaustive search with pagination tokens
Refine queries with specific documents
Feedback loop (thumbs up/down)
Dataset discovery and document hierarchy
Document upload and indexing
Advanced error handling and retry logic
Production-grade project structure

Architecture¶

Text Only

┌──────────────────┐     ┌──────────────────────────────┐     ┌──────────────┐
│   React Frontend │────▶│      FastAPI Backend          │────▶│   Gaia API   │
│                  │     │                                │     │              │
│  - Search page   │     │  - /api/search/exhaustive     │     │  /ask/exhaust│
│  - Results list  │     │  - /api/refine                │     │  /ask/refine │
│  - Doc viewer    │     │  - /api/feedback              │     │  /query-fb   │
│  - Upload panel  │     │  - /api/upload                │     │  /upload-*   │
└──────────────────┘     └──────────────────────────────┘     └──────────────┘

Quick Run¶

With DockerWithout Docker

Bash

cd examples/03-document-search

# Set your API key
cp backend/.env.example backend/.env
# Edit backend/.env with your GAIA_API_KEY

# Start everything
docker compose up --build

Open http://localhost in your browser.

Bash

cd examples/03-document-search

# Backend
cd backend
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your GAIA_API_KEY
uvicorn app.main:app --reload &

# Frontend
cd ../frontend
npm install
npm run dev

Open http://localhost:5173 in your browser.

Key Files¶

File	Purpose
`backend/app/routes/search.py`	Exhaustive search with pagination
`backend/app/routes/refine.py`	Answer refinement with document selection
`backend/app/routes/feedback.py`	Feedback submission
`backend/app/routes/upload.py`	Document upload and session management
`frontend/src/pages/SearchPage.tsx`	Search interface with filters
`frontend/src/pages/DocumentViewer.tsx`	Document detail view with refinement
`frontend/src/components/SearchResults.tsx`	Paginated result list
`frontend/src/components/FileUpload.tsx`	Drag-and-drop upload component

Browse project files
Open code browser

04 — Gaia MCP Server (Local)¶

An MCP-native server implementation. This project shows how to package Gaia capabilities as MCP tools so AI assistants can call enterprise search and RAG operations through Model Context Protocol.

What You'll Learn¶

Running an MCP server over Streamable HTTP
Exposing Gaia operations as MCP tools (ask, list_datasets, exhaustive_search)
Server-side secret handling for GAIA_API_KEY
Testing with MCP Inspector and connecting from Cursor
Containerizing the MCP server for cloud deployment

Architecture¶

Text Only

┌──────────────┐   MCP (Streamable HTTP)   ┌────────────────────────┐   HTTPS   ┌──────────────┐
│ MCP Client   │──────────────────────────▶│ Gaia MCP Server        │──────────▶│ Gaia API     │
│ (Cursor etc) │        /mcp endpoint      │ (FastAPI + FastMCP)    │           │ (Helios)     │
└──────────────┘                           └────────────────────────┘           └──────────────┘

Quick Run¶

Bash

cd examples/04-gaia-mcp-server

python -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt
cp .env.example .env
# Edit .env and set GAIA_API_KEY

uvicorn server:app --host 0.0.0.0 --port 8002 --reload

MCP endpoint: http://localhost:8002/mcp

Key Files¶

File	Purpose
`server.py`	FastMCP tools + FastAPI mount at `/mcp`
`.env.example`	Gaia configuration template
`requirements.txt`	Python dependencies (`mcp`, `fastapi`, `httpx`)
`Dockerfile`	Containerized MCP server

Browse project files Open code browser

05 — Marketplace Chat App¶

A Cohesity Marketplace-ready chat application. This project packages the same full-stack chat experience as Example 02 into a single Docker image designed for deployment on the Cohesity App Marketplace. No login page — the Marketplace's token gate handles user authentication. The Gaia API key is configured by the cluster admin and never exposed to users.

What You'll Learn¶

The single-container pattern — React compiled into the Python Docker image
Marketplace AppSpec — appspec.yaml with cohesityTag: ui and cohesityEnv
Admin-configured API key — injected via appspec.yaml env block, read from environment
App SDK environment variables — HOST_IP, APP_AUTHENTICATION_TOKEN, and others
Serving React StaticFiles from FastAPI (no Nginx needed)

Architecture¶

Text Only

Cohesity Marketplace
┌──────────────────────────────────────────────────┐
│  Token Gate → NodePort → Pod                     │
│               ┌──────────────────────────────┐   │
│               │  gaia-chat:latest            │   │
│               │  FastAPI (port 8080)         │   │
│               │   ├── /api/*   (Gaia proxy)  │──▶│─▶ Gaia API
│               │   └── /*       (React)       │   │
│               └──────────────────────────────┘   │
└──────────────────────────────────────────────────┘

Quick Run (Local Docker)¶

Bash

cd examples/05-marketplace-chat

docker build -t gaia-chat:latest .
docker run -p 8080:8080 -e GAIA_API_KEY="your-key" gaia-chat:latest

Open http://localhost:8080.

Key Files¶

File	Purpose
`main.py`	FastAPI app — mounts React from `./static` when built
`settings.py`	Pydantic Settings — Gaia config + Marketplace env vars
`api/routes.py`	`/datasets`, `/ask/stream`, `/conversations`, `/status`
`frontend/`	React + TypeScript app — no login page
`appspec.yaml`	Cohesity Marketplace deployment manifest
`app.json`	App metadata (`unrestricted_app_ui_access: false`)
`Dockerfile`	Multi-stage: Node 20 → Python 3.11-slim

Browse project files Marketplace deployment guide

06 — Marketplace MCP Server¶

A persistent MCP server deployed to the Cohesity Marketplace. Once deployed, this server exposes your Gaia knowledge bases as MCP tools that Cursor, Claude Desktop, Microsoft Copilot, and other AI assistants can call directly — without any external hosting, cloud accounts, or VPN configuration beyond what your team already uses.

What You'll Learn¶

unrestricted_app_ui_access: true — MCP clients connect programmatically; token gate is bypassed
cohesityEnv: MCP_NODE_PORT — Injecting the dynamically assigned NodePort for URL discovery
FastMCP with synchronous httpx — Tool functions cannot be async; use httpx.Client instead of GaiaClient
HTML landing page — Displays the correct MCP URL and ready-to-paste Cursor/Claude Desktop config
Single-stage Dockerfile — No frontend; smallest possible image

Architecture¶

Text Only

MCP Client (Cursor / Claude Desktop / MS Copilot)
        │  HTTP POST /mcp
        ▼
Cohesity Cluster (HOST_IP:MCP_NODE_PORT)
┌─────────────────────────────────────────────┐
│  gaia-mcp:latest                            │
│  FastMCP Server                             │──▶ Gaia API
│   ├── /mcp  (MCP Streamable HTTP)           │
│   └── /     (Landing page with MCP URL)     │
└─────────────────────────────────────────────┘

Quick Run (Local Docker)¶

Bash

cd examples/06-marketplace-mcp

docker build -t gaia-mcp:latest .
docker run -p 8002:8002 -e GAIA_API_KEY="your-key" gaia-mcp:latest

MCP endpoint: http://localhost:8002/mcp Landing page: http://localhost:8002/

MCP Tools¶

Tool	Description
`list_datasets`	List available Gaia knowledge bases
`ask`	RAG query with source citations
`exhaustive_search`	Find all matching documents in a dataset
`list_conversations`	Retrieve conversation history

Key Files¶

File	Purpose
`server.py`	FastMCP tools + HTML landing page
`appspec.yaml`	AppSpec with `cohesityEnv: MCP_NODE_PORT`
`app.json`	`unrestricted_app_ui_access: true`
`Dockerfile`	Single-stage Python image

Browse project files MCP on Marketplace guide

Which Example Should I Start With?¶

Text Only

Do you have your API key working?
├── No  → Start with 01-hello-gaia to verify connectivity
└── Yes
    ├── Need a chat interface (local)?        → 02-chat-app
    ├── Need document search?                 → 03-document-search
    ├── Need MCP tools for AI agents (local)? → 04-gaia-mcp-server
    ├── Deploying to Cohesity Marketplace?
    │   ├── Chat / web app?                   → 05-marketplace-chat
    │   └── MCP server for AI tools?          → 06-marketplace-mcp-server
    └── Want to learn everything?             → Work through all six in order

Running All Examples¶

Each example is independent — they don't share dependencies or state. You can run them side by side on different ports, or work through them sequentially.

Use Cursor for exploration

Open any example project in Cursor and use the AI chat (Cmd+L) to ask questions about the code: "How does the streaming hook work?" or "What happens when the pagination token is null?". The Cursor rules will provide Gaia-aware context for the answers.

Next Steps¶

What is Gaia? — Understand the platform before diving into code.
Getting Started — Set up authentication and make your first API call.
SDK Reference — Full reference for the GaiaClient methods used in these examples.
Marketplace Deployment — Deploy Examples 05 and 06 to the Cohesity App Marketplace.