vorkath 0.4.0

Official Python SDK for Vorkath (distributed OLTP + vector + BM25).

vorkath (Python)

Official Python SDK for Vorkath - the distributed OLTP + vector + BM25 database. Async-first, sync compatible, fully typed.

pip install vorkath

Requires Python 3.9+. HTTP/2 is enabled when the optional h2 extra is installed (it ships by default with vorkath thanks to httpx[http2]).

Quick start

Sync

import vorkath
from vorkath import filters as f

with vorkath.Client.from_env() as client:
    client.databases.create(name="docs", dimensions=64, metric="l2")
    client.vectors("docs").insert(key="d1", vector=[0.1] * 64)
    hits = client.vectors("docs").search(
        vector=[0.1] * 64,
        k=5,
        filters=f.Eq("source", "wiki") & f.In("lang", ["en", "de"]),
    )
    for hit in hits.results:
        print(hit.key, hit.distance)

Async

import asyncio
import vorkath

async def main() -> None:
    async with vorkath.AsyncClient.from_env() as client:
        await client.databases.create(name="docs", dimensions=64)
        rows = ({"id": i, "vector": [0.1] * 64} for i in range(10_000))
        await client.vectors("docs").bulk_upsert(rows, max_inflight=4)
        hits = await client.vectors("docs").search(vector=[0.1] * 64, k=5)
        for hit in hits.results:
            print(hit.key, hit.distance)

asyncio.run(main())

Managed-search quickstart

The managed-search methods (embed, rerank, search.text) wrap vorkath-backend's /v1/embed, /v1/rerank, and /v1/search endpoints. The backend embeds the query, runs hybrid retrieval, and optionally reranks - all in one round trip.

import vorkath

with vorkath.Client.from_env() as client:
    # One-call canonical pipeline (embed -> retrieve -> rerank).
    res = client.search.text(
        "docs",
        "best hiking trails near seattle",
        k=10,
        mode="hybrid",
        rerank=True,
        rerank_top_n=50,
        filters={"category": "outdoors"},
    )
    print(res.results, res.total_ms, res.degraded)

    # Manage the pipeline yourself:
    embed = client.embed("hello world")
    reranked = client.rerank(
        "best hiking trails",
        ["doc 1", "doc 2", "doc 3"],
        top_n=2,
        return_documents=True,
    )

See examples/managed_search.py and examples/explicit_pipeline.py. Backend contract: vorkath-backend/docs/embedding-and-rerank.md.

Configuration

Env var	Default	Notes
VORKATH_BASE_URL	-	REST root, e.g. http://localhost:8080.
VORKATH_CORE_URL	(= VORKATH_BASE_URL)	Override for hybrid deployments where vector ops route to a self-hosted vorkath core.
VORKATH_API_KEY	-	Bearer token, sent on every request.
VORKATH_TIMEOUT	30 seconds	Per-request timeout.

Client.from_url("vorkaths://<key>@host:port/db") parses everything in one call.

Feature surface

Area	Sync Client	Async AsyncClient
Database CRUD	yes	yes
Vector insert / upsert / search / multi-search / kNN exact / delete	yes	yes
patch_by_filter / delete_by_filter	yes	yes
aggregate (count / sum / avg / min / max / for_each_unique)	yes	yes
Hybrid + BM25 indexes (bm25(db))	yes	yes
Filter DSL (vorkath.filters)	yes	yes
Rank operators (vorkath.rank: Saturate / Decay / Dist / Sum / Mul / Hybrid)	yes	yes
Tokenizer config (vorkath.tokenizer)	yes	yes
Schema CRUD (schema(db).get/set/patch)	yes	yes
Admin (warm_cache, pin, namespace_metadata, copy_from)	yes	yes
Snapshot + restore	yes	yes
SQL execute	yes	yes
CAS writes (if_match, if_none_match, expected_version)	yes	yes
Idempotency keys (auto + override)	yes	yes
Retries with jitter + Retry-After	yes	yes
Connection pool + HTTP/2	yes	yes
Bulk upsert with chunking + bounded inflight	yes	yes (parallel)
Mock transport for tests	vorkath.testing.build_mock_client	build_async_mock_client
OpenTelemetry hook	vorkath.telemetry.instrument_client	instrument_async_client
Managed embed (client.embed)	yes	yes
Managed rerank (client.rerank)	yes	yes
Managed search (client.search.text)	yes	yes
Hybrid core_url deployments	yes	yes

Error hierarchy

VorkathError
+- APIConnectionError
|  +- APITimeoutError
+- APIStatusError
   +- BadRequestError       (400)
   +- AuthenticationError   (401)
   +- PermissionDeniedError (403)
   +- NotFoundError         (404)
   +- ConflictError         (409)
   +- PreconditionFailedError (412)  # CAS failures
   +- RateLimitError        (429)
   +- NotImplementedAPIError (501)
   +- DeadlineExceededError (504)
   +- InternalServerError   (5xx)

Every error carries status_code, request_id, server_message, body, and headers.

Testing your code against the SDK

from vorkath.testing import build_mock_client

client = build_mock_client({
    "GET /healthz": {"status": "ok"},
    "POST /v1/databases": {"success": True, "database": {"db_id": "x"}},
})
assert client.health() is True
print(client.mock_router.calls)  # recorded requests

Versioning

Pre-1.0 (0.x.y): minor bumps may break public API. Patch bumps are non-breaking. From 1.0 onwards, semver is enforced strictly with at least one minor release of deprecation warnings before any removal.

See CHANGELOG.md.

License

Apache-2.0.