🦞 Gradient AI — Knowledge Bases & RAG

⚠️ This is an unofficial community skill, not maintained by DigitalOcean. Use at your own risk.

"A lobster never forgets. Neither should your agent." — the KB lobster

Build a Retrieval-Augmented Generation pipeline using DigitalOcean's Gradient Knowledge Bases. Store your documents in DO Spaces, index them into a managed Knowledge Base (backed by OpenSearch), and query them with semantic or hybrid search.

Architecture

Your Agent                   DigitalOcean
┌─────────────┐     upload    ┌──────────────┐
│  Documents  │ ──────────▶  │  DO Spaces   │
└─────────────┘              │  (S3-compat) │
                              └──────┬───────┘
                                     │ auto-index
                              ┌──────▼───────┐
                              │ Knowledge    │
                              │ Base (KBaaS) │
                              │ ┌──────────┐ │
                              │ │OpenSearch│ │
                              │ └──────────┘ │
                              └──────┬───────┘
                                     │ retrieve
┌─────────────┐     answer    ┌──────▼───────┐
│  Your Agent │ ◀──────────  │  RAG Results │
│  + LLM      │              │  + Citations │
└─────────────┘              └──────────────┘

📖 Knowledge Base docs

API Endpoints

This skill connects to three official DigitalOcean service endpoints:

All endpoints are owned and operated by DigitalOcean. The *.do-ai.run hostnames are the Gradient AI Platform's service domains.

Authentication

This skill uses two different credentials — think of it as a two-claw approach:

Credential scoping: Use minimally-scoped tokens. Create a dedicated Model Access Key for GRADIENT_API_KEY. For DO_API_TOKEN, use a scoped API token with only Knowledge Base and Spaces permissions. Avoid using your account-root token.

Optional but recommended:

export GRADIENT_KB_UUID="your-kb-uuid"     # Default KB for queries
export DO_SPACES_BUCKET="your-bucket"      # Default bucket for uploads
export DO_SPACES_ENDPOINT="https://nyc3.digitaloceanspaces.com"

Tools

📦 Store Documents in Spaces

Upload files to DO Spaces for Knowledge Base indexing. This is the storage layer — documents land here before being indexed.

# Upload a file
python3 gradient_spaces.py --upload /path/to/report.md --bucket my-kb-data

# Upload with a key prefix (folder structure)
python3 gradient_spaces.py --upload report.md --bucket my-kb-data --prefix "research/2026-02-15/"

# List files in a bucket
python3 gradient_spaces.py --list --bucket my-kb-data

# List files with a prefix filter
python3 gradient_spaces.py --list --bucket my-kb-data --prefix "research/"

# Delete a file
python3 gradient_spaces.py --delete "research/old_report.md" --bucket my-kb-data

📖 DO Spaces docs

🏗️ Create and Manage Knowledge Bases

Full CRUD for Knowledge Bases. Create them programmatically instead of clicking through the console like a land-dweller.

# List all Knowledge Bases
python3 gradient_kb_manage.py --list

# Create a new KB
python3 gradient_kb_manage.py --create --name "My Research KB" --region nyc3

# Show details for a specific KB
python3 gradient_kb_manage.py --show --kb-uuid "your-kb-uuid"

# Delete a KB (⚠️ permanent!)
python3 gradient_kb_manage.py --delete --kb-uuid "your-kb-uuid"

📖 Create KBs via API

📁 Manage Data Sources

Connect your Spaces bucket (or web URLs) to a Knowledge Base. This is what tells the KB "index these documents."

# Add a DO Spaces data source
python3 gradient_kb_manage.py --add-source \
  --kb-uuid "your-kb-uuid" \
  --bucket my-kb-data \
  --prefix "research/"

# List data sources for a KB
python3 gradient_kb_manage.py --list-sources --kb-uuid "your-kb-uuid"

# Trigger re-indexing (auto-detects the data source)
python3 gradient_kb_manage.py --reindex --kb-uuid "your-kb-uuid"

# Trigger re-indexing for a specific source
python3 gradient_kb_manage.py --reindex --kb-uuid "your-kb-uuid" --source-uuid "ds-uuid"

🦞 Pro tip: Auto-indexing. If your KB has auto-indexing enabled, you can skip manual re-index triggers. The KB will detect changes in your Spaces bucket automatically. Configure it in the DigitalOcean Console → Knowledge Base → Settings.

🔍 Query the Knowledge Base

Search your indexed documents with semantic or hybrid queries. This is where the magic happens — your documents become answers.

# Basic query
python3 gradient_kb_query.py --query "What happened with the Q4 earnings?"

# Control number of results
python3 gradient_kb_query.py --query "Revenue trends" --num-results 20

# Tune hybrid search balance (see below)
python3 gradient_kb_query.py --query "$CAKE price movement" --alpha 0.5

# JSON output (for piping to other tools)
python3 gradient_kb_query.py --query "SEC filings summary" --json

Direct API call:

curl -s https://kbaas.do-ai.run/v1/{kb-uuid}/retrieve \
  -H "Authorization: Bearer $DO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What happened with Q4 earnings?",
    "num_results": 10,
    "alpha": 0.5
  }'

📖 KB retrieval API

🎛️ The alpha Parameter — Hybrid Search Tuning

This is the secret sauce. The alpha parameter controls the balance between lexical (keyword) and semantic (meaning) search:

🦞 Rule of claw: Start at 0.5. Go lower when searching for specific things ($CAKE, 10-K, 2026-02-15). Go higher when exploring ideas ("What's the market sentiment?").

🧠 RAG-Enhanced Queries

The full pipeline: query the KB → build a context prompt → call an LLM to synthesize. One command, complete answers with citations.

python3 gradient_kb_query.py \
  --query "Summarize all research on $CAKE" \
  --rag \
  --model "openai-gpt-oss-120b"

This automatically:

1. 🔍 Queries the Knowledge Base for relevant documents
2. 📝 Builds a prompt with the retrieved context
3. 🤖 Calls the LLM to synthesize an answer

Note: RAG queries call the Gradient Inference API under the hood, so you'll need GRADIENT_API_KEY set. If you have the gradient-inference skill loaded too, you're all set.

Advanced Configuration

Embedding Models & Chunking

When creating a Knowledge Base, you can choose how documents are split into searchable chunks:

Configure these in the DigitalOcean Console when creating the KB, or via the API's embedding_model and chunking parameters.

📖 KB configuration options

CLI Reference

All scripts accept --json for machine-readable output.

gradient_spaces.py      --upload FILE | --list | --delete KEY
                        [--bucket NAME] [--prefix PATH] [--key KEY] [--json]

gradient_kb_manage.py   --list | --create | --show | --delete
                        | --list-sources | --add-source | --reindex
                        [--kb-uuid UUID] [--source-uuid UUID]
                        [--name NAME] [--region REGION] [--bucket NAME]
                        [--prefix PATH] [--json]

gradient_kb_query.py    --query TEXT [--kb-uuid UUID] [--num-results N]
                        [--alpha F] [--rag] [--model ID] [--json]

Environment Variables

External Endpoints

Security & Privacy

• Your DO_API_TOKEN is sent as a Bearer token to api.digitalocean.com and kbaas.do-ai.run
• Spaces credentials are used for S3-compatible uploads to {region}.digitaloceanspaces.com
• Documents you upload become private in your Spaces bucket by default
• KB queries are scoped to your account — no cross-tenant access
• No credentials or data are sent to any third-party endpoints

Trust Statement

By using this skill, documents and queries are sent to DigitalOcean's Knowledge Base and Spaces APIs. Only install if you trust DigitalOcean with the documents you index.

Important Notes

• Documents uploaded to Spaces are private by default
• Re-indexing is best-effort — if the API call fails, auto-indexing kicks in on its own schedule
• The retrieval API returns document chunks, not full documents
• Deleting a KB is permanent — the indexed data is gone. The source files in Spaces are not affected.