Metadata-Version: 2.1
Name: casper-client
Version: 0.1.0
Summary: Client library for the Casper Vector Database
Home-page: https://github.com/AlexRyzhickov/Casper
License: Apache-2.0
Keywords: vector,search,neural,matching,client
Author: Alexander Ryzhikov
Author-email: makseljoinb@gmail.com
Requires-Python: >=3.10
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: grpcio (>=1.41.0)
Requires-Dist: httpx (>=0.24.0)
Requires-Dist: protobuf (>=3.20.0)
Project-URL: Repository, https://github.com/casper-vdb/python-client
Description-Content-Type: text/markdown

# Casper Python client

Python client library for the [Casper Vector Database](https://github.com/casper-vdb/Casper).

## Installation

```bash
pip install casper-client
```

## Quick start

```python
import os
import random
import math

from casper_client import CasperClient

def gen_vec(dim: int) -> list[float]:
    vec = [random.uniform(-1.0, 1.0) for _ in range(dim)]
    norm = math.sqrt(sum(x * x for x in vec)) or 1.0
    return [x / norm for x in vec]


def main() -> None:
    host = os.getenv("CASPER_HOST", "http://127.0.0.1")
    http_port = int(os.getenv("CASPER_HTTP_PORT", "8080"))
    grpc_port = int(os.getenv("CASPER_GRPC_PORT", "50051"))

    client = CasperClient(host=host, http_port=http_port, grpc_port=grpc_port)

    # 1) Health
    client.health()
    print("Health: OK")

    collection = "example_collection"
    dim = 128

    # 2) Create collection
    client.create_collection(collection, dim=dim, max_size=10_000)
    print(f"Collection created: {collection}")

    # 3) Insert vectors
    for vid in range(1, 6):
        client.insert_vector(collection, id=vid, vector=gen_vec(dim))
    print("Inserted vectors: 1..5")

    # 4) Batch insert more vectors
    batch = [{"id": vid, "vector": gen_vec(dim)} for vid in range(6, 11)]
    client.batch_update(collection, insert=batch, delete=[])
    print("Batch inserted vectors: 6..10")

    # 5) Create HNSW index
    client.create_hnsw_index(
        collection,
        metric="inner-product",
        quantization="i8",
        m=16,
        m0=32,
        ef_construction=200,
        normalization=True,
    )
    print("HNSW index created")

    # 6) Search (binary output is default)
    hits = client.search(collection, query=gen_vec(dim), limit=10)
    print(f"Search hits: {len(hits)}")
    for i, h in enumerate(hits[:5], start=1):
        print(f"  {i}. id={h.id} score={h.score}")

    # 7) Get vector by id
    v1 = client.get_vector(collection, id=1)
    print(f"Vector 1 dim: {len(v1.vector)}")

    # 8) Delete a vector
    client.delete_vector(collection, id=10)
    print("Vector 10 deleted")

    # 9) List collections
    cols = client.list_collections()
    print(f"Collections: {len(cols.collections)}")

    # 10) Cleanup
    client.delete_index(collection)
    client.delete_collection(collection)
    print("Cleanup done")

    client.close()


if __name__ == "__main__":
    main()
```

## Examples

Run the example provided in this repository:

```bash
python examples/example.py
```

The example demonstrates:
- Collection management (create, delete, list, info)
- Vector operations (insert, batch update, search, get, delete)
- Index management (create/delete HNSW)
- Matrix operations (gRPC upload, HTTP listing/info/delete)
- PQ operations (create/list/get/delete)

## License

Licensed under the [Apache License Version 2.0](LICENSE).
