Skip to content

SKILL.md

Latest commit

 

History

History
150 lines (119 loc) · 5.13 KB

SKILL.md

File metadata and controls

150 lines (119 loc) · 5.13 KB
name zeppelin
description Use the Zeppelin vector search engine to store and search text using semantic embeddings. Supports creating namespaces, embedding text, upserting vectors, and querying by similarity or BM25 full-text search.

Zeppelin Vector Search

An S3-native vector search engine. Two services:

  • Zeppelin API: http://44.242.236.80:8080 — vector storage and search
  • Embed API: http://44.242.236.80:8090 — text → vector encoding (all-MiniLM-L6-v2, 384-dim)

Quick Start: Store and Search Text

1. Create a namespace (384 dimensions to match the embed model)

curl -X POST http://44.242.236.80:8080/v1/namespaces \
  -H "Content-Type: application/json" \
  -d '{"dimensions": 384}'
# Response includes "name": "<uuid>" — SAVE THIS! It cannot be recovered if lost.

2. Embed your text

curl -X POST http://44.242.236.80:8090/v1/embed \
  -H "Content-Type: application/json" \
  -d '{"texts": ["machine learning for protein folding", "quantum error correction"]}'

Returns: {"embeddings": [[0.023, ...384 floats], [...]], "model": "all-MiniLM-L6-v2", "dimensions": 384}

3. Upsert vectors (use the embeddings from step 2, replace with your namespace name)

curl -X POST http://44.242.236.80:8080/v1/namespaces/<uuid>/vectors \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": [
      {"id": "doc1", "values": [0.023, ...], "attributes": {"title": "ML for proteins"}},
      {"id": "doc2", "values": [...], "attributes": {"title": "Quantum errors"}}
    ]
  }'

4. Search: embed query text, then query

# Embed the query
curl -X POST http://44.242.236.80:8090/v1/embed \
  -H "Content-Type: application/json" \
  -d '{"texts": ["protein structure prediction"]}'

# Query with the resulting vector
curl -X POST http://44.242.236.80:8080/v1/namespaces/my-notes/query \
  -H "Content-Type: application/json" \
  -d '{"vector": [0.023, ...384 floats], "top_k": 5, "consistency": "strong"}'

Full API Reference

Embed API (port 8090)

Embed text → vectors:

POST /v1/embed  {"texts": ["text1", "text2"]}
  • Max 10 texts per request, max 512 characters each
  • Returns 384-dimensional vectors

Zeppelin API (port 8080)

Namespaces:

POST   /v1/namespaces                    Create: {"dimensions": 384} → returns UUID name
GET    /v1/namespaces/:ns                Get info
DELETE /v1/namespaces/:ns                Delete

Vectors:

POST   /v1/namespaces/:ns/vectors        Upsert: {"vectors": [{id, values, attributes}]}
DELETE /v1/namespaces/:ns/vectors        Delete: {"ids": ["id1", "id2"]}

Query:

POST   /v1/namespaces/:ns/query          Vector search: {"vector": [...], "top_k": 10}
POST   /v1/namespaces/:ns/query          BM25 search:   {"rank_by": ["bm25", "field", "query"], "top_k": 10}

Filters

Add "filter" to any query:

{"op": "eq", "field": "category", "value": "science"}
{"op": "and", "filters": [{"op": "gte", "field": "score", "value": 0.8}, {"op": "eq", "field": "type", "value": "article"}]}

Operators: eq, neq, gt, gte, lt, lte, in, not_in, contains, not, and, or

Rate Limits

  • Zeppelin API: 10 req/s per IP, burst 20
  • Embed API: 5 req/s per IP (CPU-intensive)
  • Returns HTTP 429 if exceeded

Client SDKs (Alternative to curl)

Install the official SDK for a better developer experience:

Python:

pip install zeppelin-python
from zeppelin import ZeppelinClient

client = ZeppelinClient("http://44.242.236.80:8080")
ns = client.create_namespace(dimensions=384)  # Returns UUID name — save it!
client.upsert(ns["name"], vectors=[{"id": "doc1", "values": [...], "attributes": {"title": "hello"}}])
results = client.query(ns["name"], vector=[...], top_k=10)

TypeScript:

npm install zeppelin-typescript
import { ZeppelinClient } from 'zeppelin-typescript';

const client = new ZeppelinClient('http://44.242.236.80:8080');
const ns = await client.createNamespace({ dimensions: 384 }); // Returns UUID name — save it!
await client.upsert(ns.name, { vectors: [{ id: 'doc1', values: [...], attributes: { title: 'hello' } }] });
const results = await client.query(ns.name, { vector: [...], topK: 10 });

Both SDKs support: vector search, BM25 full-text search, composable filters, FTS config, typed errors. Repos: zepdb/zeppelin-py | zepdb/zeppelin-typescript

Health Check

curl http://44.242.236.80:8080/healthz     # Zeppelin liveness
curl http://44.242.236.80:8080/readyz      # Zeppelin readiness
curl http://44.242.236.80:8090/health      # Embed service health

Important

  • Always create namespaces with 384 dimensions to match the hosted embed model
  • Namespace names are server-generated UUIDs — save the name from the create response, it cannot be recovered
  • Use "consistency": "strong" when reading your own recently-written data
  • Attributes are optional key-value pairs attached to vectors (useful for filtering)
  • The embed endpoint is for encoding text only — upsert and query go through Zeppelin (port 8080)