Metadata-Version: 2.4
Name: vorkath
Version: 0.4.0
Summary: Official Python SDK for Vorkath (distributed OLTP + vector + BM25).
Author: Vorkath contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/blinkofficial/vorkath-sdk-python
Project-URL: Documentation, https://github.com/blinkofficial/vorkath/tree/main/docs/sdk
Project-URL: Repository, https://github.com/blinkofficial/vorkath-sdk-python
Project-URL: Issues, https://github.com/blinkofficial/vorkath-sdk-python/issues
Project-URL: Changelog, https://github.com/blinkofficial/vorkath-sdk-python/blob/main/CHANGELOG.md
Keywords: vorkath,vector-database,vector-search,bm25,full-text-search,ann,rag,embeddings,oltp,sql
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx[http2]<1.0,>=0.27
Requires-Dist: typing-extensions>=4.7; python_version < "3.11"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Requires-Dist: pytest-cov>=4; extra == "test"
Provides-Extra: dev
Requires-Dist: vorkath[test]; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pyright>=1.1; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# vorkath (Python)

Official Python SDK for [Vorkath](https://github.com/blinkofficial/vorkath) -
the distributed OLTP + vector + BM25 database. Async-first, sync
compatible, fully typed.

```bash
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

```python
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

```python
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.

```python
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`](./examples/managed_search.py) and
[`examples/explicit_pipeline.py`](./examples/explicit_pipeline.py).
Backend contract: [`vorkath-backend/docs/embedding-and-rerank.md`](../../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

```python
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`](https://github.com/blinkofficial/vorkath-sdk-python/blob/main/CHANGELOG.md).

## License

[Apache-2.0](https://github.com/blinkofficial/vorkath-sdk-python/blob/main/LICENSE).
