Metadata-Version: 2.4
Name: vantadb-litellm
Version: 0.8.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: litellm>=1.0,<2
Summary: LiteLLM embedding gateway + VantaDB storage — unified embedding provider with local vector search
Keywords: vantadb,litellm,embeddings,vector-store,rag,ai-memory,gateway
Author: VantaDB Team
License: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/ness-e/Vantadb/tree/main/providers/litellm
Project-URL: Homepage, https://github.com/ness-e/Vantadb
Project-URL: Issues, https://github.com/ness-e/Vantadb/issues
Project-URL: Repository, https://github.com/ness-e/Vantadb

# VantaDB × LiteLLM

PyO3 cdylib that exposes a `VantaDBLiteLLM` class — a unified embedding provider that generates embeddings through LiteLLM's `embedding()` gateway and stores/searches them in VantaDB.

## Install

> **Not on PyPI yet.** The `vantadb-litellm` wheel builds on all release
> platforms; it goes live with the first `providers-v*` tag release. Until
> then, build from a repo checkout.

### From PyPI (after the first release)

```bash
pip install vantadb-litellm
```

The LiteLLM SDK is installed automatically (`litellm>=1.0,<2`).

### From source

Requires Python 3.11+ and the LiteLLM SDK. Build the extension with
[maturin](https://www.maturin.rs/):

```bash
pip install litellm
maturin develop --release
```

## Quickstart

```python
from vantadb_litellm import VantaDBLiteLLM

store = VantaDBLiteLLM("/tmp/vantadb-litellm", timeout=30)
emb = store.embed(["hello world"])
rid = store.store("hello world", emb[0], metadata={"lang": "en"})
results = store.search("litellm_store", emb[0], top_k=5)
print(rid, results)
```

## API

| Method | Signature | Description |
|--------|-----------|-------------|
| `embed` | `embed(texts) -> list[list[float]]` | Generate embeddings via `litellm.embedding()`; forwards `timeout` (seconds) when set. |
| `store` | `store(text, embedding, metadata=None, key=None) -> str` | Store a record; returns `"<namespace>:<key>"`. `key` upserts at a deterministic key, else auto-generated. Metadata values must be `str`/`bool`/`int`/`float`. |
| `search` | `search(namespace, query_embedding, text_query=None, filters=None, distance_metric=None, top_k=10) -> list[dict]` | Hybrid vector + BM25 search (`distance_metric`: `"cosine"` or `"euclidean"`/`"l2"`). Returns full records plus `score`. |
| `get` | `get(namespace, key) -> dict \| None` | Retrieve a single record, or `None` if not found. |
| `list` | `list(namespace, limit=100, cursor=None) -> dict` | Paginated listing: `{"records": [...], "next_cursor": int \| None}`. |
| `delete` | `delete(key, namespace=None) -> bool` | Delete a record by key; defaults to the instance namespace. |
| `list_namespaces` | `list_namespaces() -> list[str]` | All namespaces containing at least one record. |

Constructor options: `VantaDBLiteLLM(db_path, api_key=None, model="text-embedding-3-small", namespace="litellm_store", timeout=None)`.

