Metadata-Version: 2.2
Name: cyborgdb-core
Version: 0.18.0
Summary: Core Python Library for CyborgDB: The Confidential Vector Database
Author: Cyborg Inc.
License: Proprietary
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
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
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C++
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries
Project-URL: Homepage, https://www.cyborg.co
Project-URL: Documentation, https://docs.cyborg.co
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24.0
Requires-Dist: requests>=2.25.0
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Description-Content-Type: text/markdown

# CyborgDB Core

![PyPI - Version](https://img.shields.io/pypi/v/cyborgdb_core)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cyborgdb_core)

**CyborgDB** is the first Confidential Vector Database that enables you to ingest & search vectors embeddings in a privacy-preserving manner, without revealing the contents of the vectors themselves. It runs on a local-disk backing store with a configurable in-memory cache, or on S3, and enables you to add, query and retrieve vector embeddings with transparent end-to-end encryption.

## Why Confidential?

Vector Search is at the heart of popular AI applications like RAG, recommendation systems, and semantic search. CyborgDB leverages cryptographic hashing and symmetric encryption to enable Approximate Nearest-Neighbor (ANN) search over encrypted space, keeping your vector embeddings secure throughout their lifecycle.

## Key Features

- **End-to-End Encryption**: Vector embeddings remain encrypted throughout their lifecycle, including at search time
- **Zero-Trust Design**: Novel architecture keeps confidential inference data secure
- **High Performance**: GPU-accelerated indexing and retrieval with CUDA support
- **Familiar API**: Easy integration with existing AI workflows
- **Built-in Embedding**: Upsert and query with text; embedding runs in-process, with no PyTorch or other extra dependencies
- **Durable + Fast**: Disk-backed storage with a configurable in-memory cache — enable all cache flags for memory-tier read performance with durability

## API Key (Optional)

`cyborgdb-core` works out of the box with no API key — the client runs in free-tier mode with a per-index cap of 1,000,000 items. For unlimited usage, get an API key from [db.cyborg.co](https://www.cyborgdb.co): sign up for a free account, create an API key, and pass it to the client.

## Installation

```bash
# Install CyborgDB Core (CPU):
pip install cyborgdb-core

# Install CyborgDB Core (CUDA):
pip install cyborgdb-core-cu12
```

## Quickstart

```python
import cyborgdb_core as cyborgdb
import secrets

# Create a client with disk storage (no API key required for free-tier usage).
storage_config = cyborgdb.StorageConfig.disk()
client = cyborgdb.Client(storage_config=storage_config)

# For unlimited usage, pass your CyborgDB API key:
# client = cyborgdb.Client("cyborgdb_000000", storage_config)

# Generate an encryption key for all index operations.
index_key = secrets.token_bytes(32)

# Create an encrypted index
index = client.create_index("my_index", index_key)

# Add items to the encrypted index
items = [
    {"id": "item_1", "vector": [0.1, 0.2, 0.3, 0.4], "contents": "Hello!"},
    {"id": "item_2", "vector": [0.5, 0.6, 0.7, 0.8], "contents": "Bonjour!"},
    {"id": "item_3", "vector": [0.9, 0.10, 0.11, 0.12], "contents": "Hola!"}
]

index.upsert(items, index_key=index_key)

# Query the encrypted index
query_vector = [0.1, 0.2, 0.3, 0.4]
results = index.query(query_vector, include=["distance"], index_key=index_key)

# Print the results
for result in results:
    print(f"ID: {result['id']}, Distance: {result['distance']}")
```

## Backing Store Configuration

### Disk

```python
# Uncached: every read hits disk.
storage_config = cyborgdb.StorageConfig.disk("./cyborgdb-data")

# Cached: warm reads served from RAM (memory-tier performance, durable on disk).
storage_config = cyborgdb.StorageConfig.disk(
    "./cyborgdb-data",
    cache_vectors=True, cache_metadata=True, cache_ids=True, cache_metadata_index=True,
)
client = cyborgdb.Client(storage_config=storage_config)
```

### S3

```python
storage_config = cyborgdb.StorageConfig.s3(
    "my-bucket", region="us-east-1", prefix="cyborgdb/",
)
client = cyborgdb.Client(storage_config=storage_config)
```

Credentials come from the AWS default provider chain unless you pass
`credentials=cyborgdb.S3Credentials(...)`. All stores are RAM-cached over S3, so the
`cache_*` flags are disk-only. `Client(...)` probes the bucket once at construction —
a wrong bucket, endpoint, or bad credentials fail there rather than on a later index
operation.

## Text Embedding

Create an index with an `embedding_model` and CyborgDB embeds text for you: items without a `vector` are embedded from their `contents`, and `query_contents` takes the place of a query vector. The dimension comes from the model.

```python
index = client.create_index("my_text_index", index_key, embedding_model="all-MiniLM-L6-v2")

index.upsert([
    {"id": "fox", "contents": "The quick brown fox jumps over the lazy dog."},
    {"id": "revenue", "contents": "Quarterly revenue grew eleven percent."},
], index_key=index_key)

results = index.query(query_contents="a fox leaping over a dog", top_k=1, index_key=index_key)
```

`cyborgdb.supported_embedding_models()` lists the available models (see [cyborgdb-embed](https://github.com/cyborginc/cyborgdb-embed) for the full list). Names may omit the `sentence-transformers/` prefix.

## Documentation

For more detailed documentation, visit:
- [CyborgDB Documentation](https://docs.cyborg.co)
- [API Reference](https://docs.cyborg.co/versions/latest/embedded/python/introduction)

## System Requirements

- Python 3.10 - 3.14
- Operating Systems: Linux, macOS, or WSL

## License

CyborgDB is provided under a commercial license with a perpetual free tier. Contact [Cyborg](https://www.cyborg.co/contact) or visit the [pricing page](https://www.cyborg.co/pricing) for more information.

## About Cyborg

Cyborg is dedicated to making AI safe and secure. We develop solutions that enable organizations to leverage AI while maintaining the confidentiality and privacy of their data.

[Visit our website](https://www.cyborg.co) | [Contact Us](https://www.cyborg.co/contact)