Metadata-Version: 2.4
Name: chromadb-zerodb
Version: 0.1.0
Summary: Chroma-compatible API backed by ZeroDB cloud. No Docker, no server, instant vector DB.
Project-URL: Homepage, https://github.com/AINative-Studio/chromadb-zerodb
Project-URL: Documentation, https://docs.ainative.studio
Project-URL: Repository, https://github.com/AINative-Studio/chromadb-zerodb
Project-URL: Issues, https://github.com/AINative-Studio/chromadb-zerodb/issues
Author-email: AINative Studio <hello@ainative.studio>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-database,ainative,auto-provisioning,chroma-alternative,chromadb,chromadb-alternative,claude,cloud-vector-db,cursor,embeddings,free-vector-database,hosted-chroma,milvus-alternative,no-docker,pinecone-alternative,qdrant-alternative,rag,retrieval-augmented-generation,semantic-search,serverless,similarity-search,vector-database,vector-store,weaviate-alternative,windsurf,zerodb
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Requires-Dist: requests>=2.28
Description-Content-Type: text/markdown

# chromadb-zerodb

**Chroma-compatible API backed by ZeroDB cloud. No Docker, no server, instant vector DB.**

Drop-in replacement for `chromadb` — same `Collection` API, but vectors are stored in ZeroDB cloud. Auto-provisions on first use. Free tier included.

## Why?

| | chromadb | chromadb-zerodb |
|---|---------|----------------|
| **Setup** | Docker server or in-memory (lost on restart) | `pip install` and go |
| **Persistence** | Requires server config | Cloud-persisted automatically |
| **Embeddings** | Bring your own | Free BAAI BGE models included |
| **Scaling** | Self-managed | Managed infrastructure |
| **Cost** | Server hosting | Free tier, pay as you grow |

## Install

```bash
pip install chromadb-zerodb
```

## Quick Start

```python
import chromadb_zerodb as chromadb

# Auto-provisions a free project on first use
client = chromadb.Client()

# Create a collection
collection = client.create_collection("my_docs")

# Add documents (auto-embedded with free BGE models)
collection.add(
    documents=[
        "Python is a great programming language",
        "JavaScript powers the web",
        "Rust is fast and memory-safe",
    ],
    ids=["doc1", "doc2", "doc3"],
    metadatas=[
        {"topic": "python"},
        {"topic": "javascript"},
        {"topic": "rust"},
    ],
)

# Query by text
results = collection.query(
    query_texts=["best language for beginners"],
    n_results=2,
)

print(results["documents"])  # [["Python is a great...", "JavaScript powers..."]]
print(results["distances"])  # [[0.05, 0.12]]
```

## Migration from chromadb

Change one import:

```python
# Before
import chromadb
client = chromadb.Client()

# After
import chromadb_zerodb as chromadb
client = chromadb.Client()
```

Everything else stays the same.

## Authentication

Three ways to authenticate (checked in order):

1. **Constructor arguments:**
   ```python
   client = chromadb.Client(api_key="zdb_...", project_id="proj_...")
   ```

2. **Environment variables:**
   ```bash
   export ZERODB_API_KEY=zdb_...
   export ZERODB_PROJECT_ID=proj_...
   ```

3. **Auto-provision:** If neither is set, a free project is created automatically. Credentials are cached in `~/.zerodb/credentials.json`.

## API Reference

### Client

```python
client = chromadb.Client(api_key=None, project_id=None, base_url=None)

client.create_collection(name, metadata=None)    # -> Collection
client.get_collection(name)                       # -> Collection
client.get_or_create_collection(name, metadata=None)  # -> Collection
client.list_collections()                         # -> List[str]
client.delete_collection(name)                    # -> None
client.heartbeat()                                # -> int (nanosecond timestamp)
```

### Collection

```python
collection.add(
    ids=None,           # auto-generated if omitted
    documents=None,     # auto-embedded if provided
    embeddings=None,    # or pass pre-computed vectors
    metadatas=None,
)

collection.query(
    query_texts=None,
    query_embeddings=None,
    n_results=10,
    where=None,         # metadata filter
)
# Returns: {"ids": [[...]], "documents": [[...]], "metadatas": [[...]], "distances": [[...]]}

collection.get(ids=None, where=None)
# Returns: {"ids": [...], "documents": [...], "metadatas": [...]}

collection.update(ids, documents=None, embeddings=None, metadatas=None)
collection.upsert(ids, documents=None, embeddings=None, metadatas=None)
collection.delete(ids=None, where=None)
collection.count()  # -> int
```

## Bring Your Own Embeddings

```python
collection.add(
    ids=["id1"],
    embeddings=[[0.1, 0.2, 0.3, ...]],  # your vectors
    documents=["the original text"],
    metadatas=[{"source": "my_model"}],
)

collection.query(
    query_embeddings=[[0.1, 0.2, 0.3, ...]],
    n_results=5,
)
```

## Metadata Filtering

```python
results = collection.query(
    query_texts=["search term"],
    where={"topic": "python"},
    n_results=5,
)
```

## How It Works

- **Collections** are namespaced via ID prefixes (`collection_name::doc_id`)
- **Auto-embedding** uses ZeroDB's free BAAI BGE-M3 model
- **Storage** is ZeroDB's managed vector database (same infra as ZeroDB MCP)
- **Credentials** are cached at `~/.zerodb/credentials.json`

## Links

- [ZeroDB Documentation](https://docs.ainative.studio)
- [ZeroDB MCP Server](https://pypi.org/project/zerodb-mcp/)
- [AINative Studio](https://ainative.studio)

## License

MIT
