# WaffleDB Python SDK - Dead Simple, Fully Featured

Vector search with 2 lines of code. Auto-creates everything. Handles every use case.

## Installation

\\\ash
pip install waffledb
\\\

## 5-Minute Start

### 1. Start Server
\\\ash
docker run -p 8080:8080 waffledb
\\\

### 2. Add & Search
\\\python
from waffledb import client

# Add vectors (collection auto-creates!)
client.add("docs", 
    ids=["doc1", "doc2"],
    embeddings=[[0.1]*384, [0.2]*384],
    metadata=[{"title": "A"}, {"title": "B"}]
)

# Search
results = client.search("docs", [0.15]*384)
for r in results:
    print(f"{r.id}: {r.score:.4f}")
\\\

Done! No setup, no config, everything auto-created.

---

## Core API

| Method | Purpose |
|--------|---------|
| \client.add(collection, ids, embeddings, metadata)\ | Add/insert vectors |
| \client.search(collection, embedding, limit)\ | Find similar |
| \client.delete(collection, ids)\ | Remove vectors |
| \client.get(collection, id)\ | Get one vector |
| \client.update(collection, id, embedding)\ | Update embedding |
| \client.update_metadata(collection, id, metadata)\ | Update metadata |
| \client.batch_search(collection, queries)\ | Multi-query |
| \client.list()\ | List collections |
| \client.info(collection)\ | Collection stats |
| \client.drop(collection)\ | Delete collection |
| \client.snapshot(collection, name)\ | Backup |
| \client.health()\ | Server health |

---

## Real World Examples

### RAG / Semantic Search
\\\python
from waffledb import client

docs = load_documents()
client.add("kb", ids=[d["id"] for d in docs], embeddings=[d["emb"] for d in docs], metadata=[{"text": d["text"]} for d in docs])

results = client.search("kb", embed("What is Python?"), limit=5)
context = "\n".join(r.metadata["text"] for r in results)
answer = llm.ask(f"Based on: {context}")
\\\

### Recommendations
\\\python
from waffledb import client

users = load_users()
client.add("users", ids=[u["id"] for u in users], embeddings=[u["emb"] for u in users], metadata=[{"name": u["name"]} for u in users])

similar = client.search("users", user_embedding, limit=10)
print([r.metadata["name"] for r in similar])
\\\

### Product Search
\\\python
from waffledb import client

products = load_products()
client.add("products", ids=[p["id"] for p in products], embeddings=[p["emb"] for p in products], metadata=[{"name": p["name"], "price": p["price"]} for p in products])

results = client.search("products", embed("blue running shoes under 100"), limit=20)
for r in results:
    if r.metadata["price"] < 100:
        print(f"{r.metadata['name']}: \")
\\\

### Image Search
\\\python
from waffledb import client

images = load_images()
client.add("images", ids=[img["id"] for img in images], embeddings=[img["emb"] for img in images], metadata=[{"url": img["url"]} for img in images])

results = client.search("images", image_embedding, limit=20)
for r in results:
    print(r.metadata["url"])
\\\

### Duplicate Detection
\\\python
from waffledb import client

docs = load_docs()
client.add("documents", ids=[d["id"] for d in docs], embeddings=[d["emb"] for d in docs], metadata=[{"text": d["text"]} for d in docs])

for doc in docs:
    similar = client.search("documents", doc["emb"], limit=5)
    duplicates = [r for r in similar[1:] if r.score > 0.95]
    if duplicates:
        print(f"Doc {doc['id']} duplicated: {[r.id for r in duplicates]}")
\\\

### Time Series Patterns
\\\python
from waffledb import client

windows = extract_time_windows(data)
client.add("patterns", ids=[w["id"] for w in windows], embeddings=[w["emb"] for w in windows], metadata=[{"ts": w["ts"]} for w in windows])

current = extract_window(latest_data)
similar = client.search("patterns", current["emb"], limit=10)
if similar[0].score < 0.8:
    print("Anomaly detected!")
\\\

### Multi-Tenant
\\\python
from waffledb import client

for tenant in tenants:
    docs = load_tenant_docs(tenant.id)
    client.add(f"tenant_{tenant.id}", ids=[d["id"] for d in docs], embeddings=[d["emb"] for d in docs])

results = client.search(f"tenant_{tenant_id}", query_emb)
\\\

---

## Configuration

\\\python
from waffledb import WaffleClient

client = WaffleClient("http://server:8080", timeout=60)
\\\

---

**Dead simple. Fully featured. 49.5K vectors/sec.**
