Metadata-Version: 2.2
Name: cyborgdb-core
Version: 0.17.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"
Requires-Dist: sentence-transformers>=2.2.0; extra == "langchain"
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
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 supports in-memory, local-disk, and S3 backing stores, 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
- **Multiple Backing Stores**: Works with in-memory, local disk, and S3 storage
- **Cloud Ready**: Supports AWS S3 (and S3-compatible stores like MinIO) out of the box

## 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 memory storage (no API key required for free-tier usage)
# You can replace this with cyborgdb.StorageConfig.disk(...) or .s3(...)
client = cyborgdb.Client(storage_config=cyborgdb.StorageConfig.memory())

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

# Generate an encryption key for the index
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)

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

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

## Connecting to Different Backing Stores

### Disk (local RocksDB)

```python
storage_config = cyborgdb.StorageConfig.disk("/tmp/cyborgdb_disk")
client = cyborgdb.Client(storage_config=storage_config)
```

### S3

```python
storage_config = cyborgdb.StorageConfig.s3(
    "my-bucket",
    region="us-east-1",
    # Omit credentials= to use the AWS default credential chain
    credentials=cyborgdb.S3Credentials(access_key="...", secret_key="..."),
)
client = cyborgdb.Client(storage_config=storage_config)
```

## Documentation

For more detailed documentation, visit:
- [CyborgDB Documentation](https://docs.cyborg.co)
- [API Reference](https://docs.cyborg.co/versions/v0.17.x/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)