Metadata-Version: 2.4
Name: cyborgdb-service
Version: 0.17.0
Summary: REST Server for CyborgDB: The Confidential Vector Database
Author: Cyborg Inc.
License: Proprietary
Project-URL: Homepage, https://www.cyborg.co
Project-URL: Documentation, https://docs.cyborg.co
Keywords: CyborgDB Service
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.68.0
Requires-Dist: uvicorn[standard]>=0.15.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: packaging>=21.0
Requires-Dist: cyborgdb-core<0.18.0,>=0.17.0.dev0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: cachetools>=5.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
Provides-Extra: kms-aws
Requires-Dist: boto3>=1.26.0; extra == "kms-aws"
Provides-Extra: all
Requires-Dist: sentence-transformers>=2.2.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
Requires-Dist: httpx>=0.25.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <a href="https://www.cyborg.co">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cyborginc/cyborgdb-service/main/assets/cyborgdb-logo-dark.svg">
      <img src="https://raw.githubusercontent.com/cyborginc/cyborgdb-service/main/assets/cyborgdb-logo-light.svg" alt="CyborgDB" width="320">
    </picture>
  </a>
</p>

# CyborgDB Service

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

**CyborgDB Service** is the FastAPI-based REST API server for [CyborgDB](https://www.cyborg.co) — the vector database that stays encrypted even while it's searching. It serves encrypted vector ingestion, search, and retrieval over HTTP: vectors stay encrypted through search, and only the result of a query is decrypted. Run it yourself in your own VPC or on-prem.

## Features

- **Encryption-in-use**: Vectors stay encrypted at rest, in transit, and through search — only the query result is decrypted
- **Encrypted ANN**: Disk-backed encrypted DiskIVF index with recall within 2% of a plaintext baseline ([read the benchmarks](https://www.cyborg.co/performance))
- **Filters on encrypted metadata**: Combine vector similarity with equality and range predicates in a single request
- **BYOK / HYOK**: Per-index key wrapping via AWS KMS or AWS Secrets Manager, including cross-account BYOK (see `BYOK.md`)
- **Per-tenant key isolation**: Per-index, per-user keys with cryptographic RBAC; revoke a user and their keys are erased
- **Multiple backing stores**: Embedded RocksDB disk, AWS S3 / S3-compatible object storage (MinIO etc.), or in-memory

## Getting Started

To get started in minutes, check out our [Quickstart Guide](https://docs.cyborg.co/quickstart).

### Installation

1. Install `cyborgdb-service`
```bash
pip install cyborgdb-service
# GPU (CUDA 12): pip install cyborgdb-service-cu12
```

2. [Optional] Set an API key for unlimited usage — without one the service runs in free-tier mode (per-index cap of 1M items)
```bash
export CYBORGDB_API_KEY=your_api_key_here   # optional; unset runs free tier
```

3. [Optional] Choose a storage backend (default: `disk` at `~/.cyborgdb/data`)
```bash
export CYBORGDB_DB_TYPE='memory|disk|s3'   # default: disk
export CYBORGDB_DISK_PATH=/path/to/data    # disk only; default ~/.cyborgdb/data
export CYBORGDB_S3_BUCKET=my-bucket        # s3 only (required)
```

**Tip:** Run `cyborgdb-service --help` for a detailed list of all configuration options.

4. Run the server

```bash
cyborgdb-service
```

### Storage Backends

| Backend | Select with | Notes |
|---------|-------------|-------|
| Disk (default) | `CYBORGDB_DB_TYPE=disk` | Embedded RocksDB. `CYBORGDB_DISK_PATH` sets the data directory (default `~/.cyborgdb/data`). |
| In-memory | `CYBORGDB_DB_TYPE=memory` | No persistence across restarts. |
| S3 | `CYBORGDB_DB_TYPE=s3` | Requires `CYBORGDB_S3_BUCKET`. Optional: `CYBORGDB_S3_REGION`, `CYBORGDB_S3_PREFIX`, `CYBORGDB_S3_ENDPOINT`. |

#### S3 credentials

Each AWS-touching client (S3 storage, KMS) resolves credentials independently:

- **On AWS (ECS/EC2/EKS)** — set nothing; the AWS default credential
  provider chain picks up the instance/task role.
- **Off AWS, real S3** — provide `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`
  env vars or a mounted AWS profile; the default chain picks them up.
- **S3-compatible endpoint (MinIO etc.)** — set `CYBORGDB_S3_ENDPOINT`
  **plus explicit** `CYBORGDB_S3_ACCESS_KEY` / `CYBORGDB_S3_SECRET_KEY`
  (and optionally `CYBORGDB_S3_SESSION_TOKEN`). A custom endpoint is not
  AWS: the AWS chain is never used against it, and startup fails fast if
  the explicit keys are missing. The `CYBORGDB_S3_*` namespace is kept
  separate from `AWS_*` so storage credentials can't collide with KMS
  credentials.

### YAML Configuration File (optional)

Everything settable by environment variable can also live in a YAML file —
see [`cyborgdb.example.yaml`](cyborgdb.example.yaml). The file is resolved
from `CYBORGDB_CONFIG_FILE`, then `./cyborgdb.yaml`, `./cyborgdb.yml`,
`/etc/cyborgdb/cyborgdb.yaml`. Environment variables override the file on
conflict. The YAML file is also where the per-index KMS registry
(`kms.registry:`) is configured.

### API Key Configuration

The `CYBORGDB_API_KEY` is the **cyborgdb-core license key** (not a service-auth credential).
It is **optional** — when unset, the service runs in free-tier mode (per-index cap of 1M
items). To unlock unlimited usage, provide your key using **any** of these methods:

#### Method 1: Environment Variable (Easiest)

```bash
export CYBORGDB_API_KEY=your_api_key_here
cyborgdb-service
```

#### Method 2: .env File

Create a `.env` file in the project root:
```
CYBORGDB_API_KEY=your_api_key_here
```
Then run:
```bash
cyborgdb-service
```

#### Method 3: Inline with Launch
```bash
CYBORGDB_API_KEY=your_api_key_here cyborgdb-service
```

### Service Authentication

Request authentication is controlled by `CYBORGDB_SERVICE_ROOT_KEY` — separate from the
`CYBORGDB_API_KEY` license key above:

- **Unset (default): authentication is disabled** and the service accepts every request.
  Do not run a network-exposed deployment this way.
- **Set: authentication is enabled.** Clients must send the key in the `X-API-Key` header.
  Routes accept the root key or a `cdbk_` user token minted under it, and the root key can
  mint per-user API keys.

```bash
export CYBORGDB_SERVICE_ROOT_KEY=your_root_key_here
# then call the API with:  -H "X-API-Key: your_root_key_here"
```



## Documentation

For more information on CyborgDB, see the [Cyborg Docs](https://docs.cyborg.co).

## License

CyborgDB Service is licensed under the MIT License. The underlying library, CyborgDB Core, is licensed under Cyborg's [Terms of Service](https://www.cyborg.co/terms-of-service).
