GitHub - nickswami/dasein-python-sdk: Dasein managed vector index service - Python SDK

The managed vector index that compresses 12×, queries 10× faster, and lifts R@10 by +22pt over static hybrid. Hybrid dense + BM25 • Per-query dynamic α fusion • Zero embedding infrastructure

Live Demo • Quick Start • Hybrid Search • Dynamic Hybrid • Query Batch • API Reference • Benchmarks • Dynamic Hybrid Results

pip install dasein-ai  # not "dasein" — the package name is dasein-ai

from dasein import Client

client = Client(api_key="dsk_...")  # get a free key at https://api.daseinai.ai/auth/github

# Create a hybrid index (semantic + keyword search)
index = client.create_index("my-docs", index_type="hybrid", model="bge-large-en-v1.5")

# Upsert documents — metadata values can be strings, ints, or floats
index.upsert([
    {"id": "doc1", "text": "SpaceX launched Starship on its 5th test flight",
     "metadata": {"source": "reuters", "category": "space", "year": 2025, "priority": 1}},
    {"id": "doc2", "text": "GPT-5 achieves superhuman reasoning on ARC-AGI",
     "metadata": {"source": "arxiv", "category": "ai", "year": 2025, "priority": 2}},
    {"id": "doc3", "text": "Fed holds rates steady amid cooling inflation",
     "metadata": {"source": "bloomberg", "category": "finance", "year": 2025, "priority": 3}},
    {"id": "doc4", "text": "Python 3.13 ships with a JIT compiler",
     "metadata": {"source": "pep", "category": "code", "year": 2024, "priority": 1}},
])

# Hybrid search — semantic similarity + BM25 keyword matching
results = index.query("what is machine learning?", top_k=5, mode="hybrid")

# Filter by metadata — all operators are true pre-filters (no recall penalty)
results = index.query("recent breakthroughs", top_k=5, filter={"year": {"$gte": 2025}}, include_metadata=True)
results = index.query("top stories", top_k=5, filter={"source": {"$in": ["reuters", "bloomberg"]}, "priority": 1}, include_metadata=True)
results = index.query("tech news", top_k=5, filter={"$or": [{"category": "ai"}, {"category": "code"}]}, include_metadata=True)

for r in results:
    print(f"{r.id}: {r.score:.4f} — {r.metadata}")

# Hybrid index — supports both query modes
index = client.create_index("my-docs", index_type="hybrid", model="bge-large-en-v1.5")

# Dense-only index — only supports mode="dense"
index = client.create_index("my-docs", index_type="dense", model="bge-large-en-v1.5")

# Dense: pure semantic similarity
results = index.query("financial derivatives risk models", top_k=10, mode="dense")

# Hybrid: semantic + BM25 keyword matching, fused and re-ranked
results = index.query("AAPL earnings Q3 2025", top_k=10, mode="hybrid")

# Exact keyword matching — only docs that contain all your terms
results = index.query("AAPL earnings Q3 2025", top_k=10, mode="hybrid", exact=True)

# Phrase matching — only docs containing "machine learning" as an exact phrase
results = index.query("machine learning", top_k=10, mode="hybrid", phrase=True)

# Fuzzy matching — handles typos (edit distance 1)
results = index.query("machin lerning", top_k=10, mode="hybrid", fuzzy=True)

# Tune the dense vs BM25 balance (0.0 = all dense, 1.0 = all BM25, default 0.5)
results = index.query("AAPL earnings", top_k=10, mode="hybrid", alpha=0.7)  # lean keyword-heavy

results = index.query("AAPL earnings Q3 2025",
                      top_k=10, mode="hybrid", dynamic_hybrid=True)

# embed the query in YOUR encoder's space (whatever you already use)
qvec = my_encoder.encode("who founded apple?")

alpha = client.predict_alpha("who founded apple?", query_vector=qvec)
# blend your own rankings at this alpha
fused = rrf_fuse(my_dense_hits, my_bm25_hits, alpha=alpha)

index.upsert([
    {
        "id": "doc1",
        "text": "SpaceX launched Starship",
        "metadata": {
            "source": "reuters",
            "category": "space",
            "year": 2025,
            "priority": 1,
            "rating": 9.2,
        },
    },
])

# Simple equality
results = index.query("rocket launch", top_k=10, filter={"source": "reuters"})
results = index.query("rocket launch", top_k=10, filter={"category": "space", "year": 2025})

# Equality (default — bare values are $eq)
filter={"genre": "sci-fi"}
filter={"genre": {"$eq": "sci-fi"}}  # equivalent explicit form

# Not equal
filter={"status": {"$ne": "archived"}}

# In set
filter={"category": {"$in": ["ai", "finance", "health"]}}

# Not in set
filter={"source": {"$nin": ["spam", "test"]}}

# Exists / not exists
filter={"author": {"$exists": True}}

# Numeric range
filter={"year": {"$gte": 2020, "$lte": 2025}}
filter={"rating": {"$gt": 7.5}}

# OR across keys
filter={"$or": [{"category": "ai"}, {"priority": 1}]}

# Combine (AND by default)
filter={"source": "reuters", "year": {"$gte": 2024}, "category": {"$in": ["tech", "science"]}}

import httpx, time

resp = httpx.post("https://api.daseinai.ai/auth/device/start").json()
print(f"Go to {resp['verification_uri']} and enter code: {resp['user_code']}")

while True:
    time.sleep(resp.get("interval", 5))
    poll = httpx.post(
        "https://api.daseinai.ai/auth/device/poll",
        json={"device_code": resp["device_code"]},
    ).json()
    if poll.get("api_key"):
        print(f"API key: {poll['api_key']}")
        break

index = client.create_index("my-docs", index_type="hybrid", model="bge-large-en-v1.5", dim=256)

from dasein import Client

client = Client(
    api_key="dsk_...",       # required
    base_url=None,           # override API URL (default: Dasein Cloud)
    timeout=30.0,            # request timeout in seconds
    max_retries=3,           # retries on 429/503
)

index = client.create_index(
    name="my-index",
    index_type="hybrid",             # REQUIRED CHOICE: "dense" or "hybrid"
    model="bge-large-en-v1.5",      # None for bring-your-own-vectors
    dim=None,                        # truncate to lower dim for MRL models (e.g., 256)
)

indexes = client.list_indexes()
for idx in indexes:
    print(idx["index_id"], idx["name"], idx["status"], idx["vector_count"])

index = client.get_index("index_id")

client.delete_index("index_id")

alpha = client.predict_alpha(
    text="who founded apple?",
    query_vector=my_dense_vec,  # strongly recommended: your encoder's output
    model_id=None,              # used to embed `text` ONLY if query_vector is None
)

responses = client.query_batch([
    {"index_id": "abc", "text":   "hello",       "top_k": 10},
    {"index_id": "def", "vector": my_vec,        "top_k": 5, "include_vectors": True},
    {"index_id": "ghi", "text":   "rate limit",  "top_k": 20, "mode": "hybrid"},
])

index.upsert([
    {"id": "doc1", "text": "Hello world", "metadata": {"type": "greeting"}},
    {"id": "doc2", "text": "Goodbye world", "metadata": {"type": "farewell"}},
])

from dasein import UpsertItem

index.upsert([
    UpsertItem(id="doc1", text="Hello world", metadata={"type": "greeting"}),
    UpsertItem(id="doc2", vector=[0.1, 0.2, ...]),
])

results = index.query(
    text="search query",         # or vector=[0.1, 0.2, ...]
    top_k=10,
    mode="hybrid",               # "dense" or "hybrid" (hybrid requires index_type="hybrid")
    filter={"key": "value"},     # optional metadata filter (supports operators — see Filtering)
    exact=False,                 # exact keyword matching (hybrid only)
    phrase=False,                # exact phrase matching (hybrid only)
    fuzzy=False,                 # typo-tolerant matching (hybrid only)
    alpha=0.5,                   # dense vs BM25 balance (0=dense, 1=BM25)
    dynamic_hybrid=False,        # let Dasein pick alpha per query (hybrid only, top_k<=100)
    include_text=False,          # return stored text (off by default)
    include_metadata=False,      # return stored metadata (off by default)
    include_vectors=False,       # return approximate vectors (off by default)
)

# Default — IDs and scores only, pure RAM, maximum QPS
results = index.query("quarterly earnings", top_k=10)
for r in results:
    print(r.id, r.score)

# Include metadata
results = index.query("quarterly earnings", top_k=10, include_metadata=True)
for r in results:
    print(r.id, r.score, r.metadata)

# Full hydration — metadata + original text
results = index.query("quarterly earnings", top_k=10, include_text=True, include_metadata=True)
for r in results:
    print(r.id, r.score, r.text, r.metadata)

# Include approximate vectors (reconstructed from RAM, no disk I/O)
results = index.query("quarterly earnings", top_k=10, include_vectors=True)
for r in results:
    # r.vector is a numpy.ndarray (float32) when numpy is installed,
    # or a list[float] otherwise. np.asarray(r.vector) works for both.
    print(r.id, r.score, len(r.vector))

# Each entry takes the same keys as Index.query(...)
batch = [
    {"vector": v, "top_k": 10, "include_vectors": True}
    for v in my_query_vectors
]  # up to 4096
responses = index.query_batch(batch)

for q_idx, resp in enumerate(responses):
    for r in resp:
        print(q_idx, r.id, r.score)

# Every key that query() takes works inside query_batch() entries:
batch = [
    {"text": "rocket launch",    "top_k": 5,  "mode": "hybrid"},
    {"text": "quarterly earnings","top_k": 10, "filter": {"year": {"$gte": 2024}},
     "include_metadata": True},
    {"vector": my_vec,           "top_k": 20, "include_vectors": True},
]
responses = index.query_batch(batch)

# 256 queries scattered across many indexes in one round-trip.
batch = []
for idx_id, qvec in zip(index_ids, query_vectors):
    batch.append({
        "index_id":        idx_id,
        "vector":          qvec,
        "top_k":           10,
        "mode":            "hybrid",
        "include_vectors": True,
    })
responses = client.query_batch(batch)

for sent, resp in zip(batch, responses):
    if resp.error:              # per-slot failure — doesn't fail the batch
        print(sent["index_id"], "FAILED:", resp.error)
        continue
    for r in resp:
        print(sent["index_id"], r.id, r.score, r.vector[:4])

batch = [
    {"index_id": "abc-001", "text": "climate policy", "top_k": 10, "mode": "hybrid"},
    {"index_id": "def-002", "text": "interest rates", "top_k": 5,  "mode": "dense"},
    {"index_id": "ghi-003", "vector": pre_embedded,   "top_k": 20, "include_vectors": True},
]
responses = client.query_batch(batch)

index.delete(["doc1", "doc2"])

result = index.upsert_and_wait(documents, timeout=120.0)

info = index.status()
print(info.status)        # created, building, built, active, etc.
print(info.vector_count)

from dasein.exceptions import (
    DaseinError,             # base — catch-all for any Dasein error, including plain 403 Forbidden
    DaseinAuthError,         # 401, or 403 mentioning credentials / API key / revoked
    DaseinQuotaError,        # 403 — billing/plan/trial/subscription/embed limit
    DaseinNotFoundError,     # 404 — index doesn't exist
    DaseinRateLimitError,    # 429 — transient rate limit exceeded (has retry_after)
    DaseinUnavailableError,  # 503/504 — service temporarily unavailable (has retry_after)
    DaseinBuildError,        # build failed
)