chromadb-zerodb 0.1.0__tar.gz

chromadb_zerodb-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/

chromadb_zerodb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AINative Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chromadb_zerodb-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+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

chromadb_zerodb-0.1.0/README.md

@@ -0,0 +1,175 @@
+# 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

chromadb_zerodb-0.1.0/chromadb_zerodb/__init__.py

@@ -0,0 +1,7 @@
+"""chromadb-zerodb: Chroma-compatible API backed by ZeroDB cloud."""
+
+from chromadb_zerodb.client import Client
+from chromadb_zerodb.collection import Collection
+
+__version__ = "0.1.0"
+__all__ = ["Client", "Collection"]

chromadb_zerodb-0.1.0/chromadb_zerodb/client.py

@@ -0,0 +1,147 @@
+"""Chroma-compatible Client backed by ZeroDB cloud."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from chromadb_zerodb.collection import Collection
+from chromadb_zerodb.provision import auto_provision
+
+DEFAULT_BASE_URL = "https://api.ainative.studio"
+
+
+class Client:
+    """Chroma-compatible client backed by ZeroDB cloud storage.
+
+    Drop-in replacement for ``chromadb.Client()`` — no Docker, no server.
+
+    Usage::
+
+        import chromadb_zerodb as chromadb
+
+        client = chromadb.Client()
+        collection = client.create_collection("my_docs")
+        collection.add(documents=["hello world"], ids=["id1"])
+        results = collection.query(query_texts=["hello"], n_results=5)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        project_id: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+    ):
+        self._base_url = base_url.rstrip("/")
+
+        if api_key and project_id:
+            self._api_key = api_key
+            self._project_id = project_id
+        else:
+            self._api_key, self._project_id = auto_provision(self._base_url)
+
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Authorization": f"Bearer {self._api_key}",
+            "X-Project-ID": self._project_id,
+            "Content-Type": "application/json",
+            "User-Agent": "chromadb-zerodb/0.1.0",
+        })
+
+        # Track collections as namespace prefixes
+        self._collections: Dict[str, Dict[str, Any]] = {}
+
+    def _request(self, method: str, path: str, **kwargs) -> requests.Response:
+        """Make an authenticated API request."""
+        url = f"{self._base_url}{path}"
+        resp = self._session.request(method, url, timeout=30, **kwargs)
+        resp.raise_for_status()
+        return resp
+
+    def create_collection(
+        self,
+        name: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Collection:
+        """Create a new collection (or return existing one).
+
+        Args:
+            name: Collection name. Used as a namespace prefix in ZeroDB.
+            metadata: Optional metadata for the collection.
+
+        Returns:
+            A Collection instance.
+        """
+        self._collections[name] = {"metadata": metadata or {}}
+        return Collection(
+            name=name,
+            metadata=metadata,
+            session=self._session,
+            base_url=self._base_url,
+        )
+
+    def get_collection(self, name: str) -> Collection:
+        """Get an existing collection by name.
+
+        Args:
+            name: Collection name.
+
+        Returns:
+            A Collection instance.
+        """
+        return Collection(
+            name=name,
+            metadata=self._collections.get(name, {}).get("metadata"),
+            session=self._session,
+            base_url=self._base_url,
+        )
+
+    def get_or_create_collection(
+        self,
+        name: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Collection:
+        """Get or create a collection.
+
+        Args:
+            name: Collection name.
+            metadata: Optional metadata (used only on creation).
+
+        Returns:
+            A Collection instance.
+        """
+        if name not in self._collections:
+            return self.create_collection(name, metadata)
+        return self.get_collection(name)
+
+    def list_collections(self) -> List[str]:
+        """List all known collection names.
+
+        Returns:
+            List of collection name strings.
+        """
+        return list(self._collections.keys())
+
+    def delete_collection(self, name: str) -> None:
+        """Delete a collection and all its vectors.
+
+        Args:
+            name: Collection name to delete.
+        """
+        collection = self.get_collection(name)
+        collection._delete_all()
+        self._collections.pop(name, None)
+
+    def heartbeat(self) -> int:
+        """Check connectivity to ZeroDB backend.
+
+        Returns:
+            Nanosecond timestamp if healthy.
+        """
+        import time
+        try:
+            self._request("GET", "/health")
+            return int(time.time() * 1e9)
+        except Exception:
+            return 0