fastembed-cloud 0.1.0__tar.gz

fastembed_cloud-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.

fastembed_cloud-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: fastembed-cloud
+Version: 0.1.0
+Summary: Cloud embeddings via AINative API — drop-in fastembed replacement, no model downloads
+Author-email: AINative Studio <support@ainative.studio>
+License: MIT
+Project-URL: Homepage, https://github.com/AINative-Studio/fastembed-cloud
+Project-URL: Documentation, https://docs.ainative.studio/embeddings
+Project-URL: Repository, https://github.com/AINative-Studio/fastembed-cloud
+Project-URL: Issues, https://github.com/AINative-Studio/fastembed-cloud/issues
+Keywords: fastembed,fastembed-alternative,embeddings,text-embeddings,cloud-embeddings,free-embeddings,ainative,zerodb,bge,baai,onnx-alternative,vector-embeddings,semantic-search,similarity-search,sentence-transformers-alternative,auto-provisioning,serverless,no-download,claude,cursor,windsurf,rag,retrieval-augmented-generation
+Classifier: Development Status :: 4 - Beta
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: local
+Requires-Dist: fastembed>=0.3.0; extra == "local"
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.20; extra == "numpy"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Dynamic: license-file
+
+# fastembed-cloud
+
+Cloud text embeddings via AINative API. Drop-in replacement for [fastembed](https://github.com/qdrant/fastembed) — same interface, no model downloads, no ONNX runtime.
+
+## Why?
+
+fastembed is great, but requires downloading 100MB+ ONNX models locally. `fastembed-cloud` gives you the same API backed by a free cloud service — zero setup, zero downloads.
+
+| | fastembed | fastembed-cloud |
+|---|---|---|
+| First-run latency | 30-120s (model download) | 0s |
+| Disk usage | 100MB-1GB per model | 0 |
+| ONNX runtime | Required | Not needed |
+| Offline support | Yes | No (cloud API) |
+| Cost | Free (local compute) | Free (AINative API) |
+
+## Install
+
+```bash
+pip install fastembed-cloud
+```
+
+## Quick Start
+
+```python
+from fastembed_cloud import CloudTextEmbedding
+
+# Auto-provisions a free API key on first run
+model = CloudTextEmbedding()
+
+# Single query
+embedding = model.query_embed("What is semantic search?")
+print(f"Dimensions: {len(embedding)}")  # 384
+
+# Batch embedding
+docs = ["First document", "Second document", "Third document"]
+embeddings = model.embed(docs)
+print(f"Embedded {len(embeddings)} documents")
+```
+
+## Models
+
+| Model | Dimensions | ID |
+|---|---|---|
+| BGE-small-en-v1.5 | 384 | `BAAI/bge-small-en-v1.5` (default) |
+| BGE-base-en-v1.5 | 768 | `BAAI/bge-base-en-v1.5` |
+| BGE-large-en-v1.5 | 1024 | `BAAI/bge-large-en-v1.5` |
+| BGE-M3 (multilingual) | 1024 | `bge-m3` |
+
+```python
+model = CloudTextEmbedding(model_name="bge-m3")
+embedding = model.query_embed("Multilingual embedding")
+print(len(embedding))  # 1024
+```
+
+## Smart Hybrid: Local + Cloud
+
+`TextEmbedding` automatically uses local fastembed if installed, cloud otherwise:
+
+```python
+from fastembed_cloud import TextEmbedding
+
+model = TextEmbedding()
+print(model.is_cloud)  # True if fastembed not installed
+
+embeddings = model.embed(["works either way"])
+```
+
+Install fastembed alongside for local-first with cloud fallback:
+
+```bash
+pip install fastembed-cloud[local]
+```
+
+## Authentication
+
+Credentials are resolved in this order:
+
+1. `api_key` parameter: `CloudTextEmbedding(api_key="your-key")`
+2. `AINATIVE_API_KEY` environment variable
+3. `ZERODB_API_KEY` environment variable (shared with ZeroDB ecosystem)
+4. `~/.zerodb/credentials.json` (auto-saved from any ZeroDB tool)
+5. Auto-provisioning (free 72-hour account, claim to keep permanently)
+
+### Auto-Provisioning
+
+On first use with no credentials, fastembed-cloud automatically provisions a free account:
+
+```
+$ python -c "from fastembed_cloud import CloudTextEmbedding; CloudTextEmbedding().query_embed('test')"
+
+  No API key found — provisioning a free AINative account for embeddings...
+
+  Auto-provisioned! Free embeddings API ready.
+
+  API Key:   zdb_abc12345...
+  Expires:   72 hours
+  Saved to:  ~/.zerodb/credentials.json
+
+  To keep access permanently, claim your account:
+  https://ainative.studio/signup
+```
+
+## Batch Embedding
+
+Handles large datasets efficiently with automatic batching:
+
+```python
+model = CloudTextEmbedding(batch_size=100)
+
+# Automatically batches into chunks of 100
+large_dataset = ["document " + str(i) for i in range(10000)]
+embeddings = model.embed(large_dataset)
+```
+
+## Use with Vector Databases
+
+### Qdrant
+
+```python
+from qdrant_client import QdrantClient
+from fastembed_cloud import CloudTextEmbedding
+
+client = QdrantClient(":memory:")
+model = CloudTextEmbedding()
+
+docs = ["AI is transforming healthcare", "Machine learning for finance"]
+embeddings = model.embed(docs)
+
+client.add(
+    collection_name="my_docs",
+    documents=docs,
+    embeddings=embeddings,
+)
+```
+
+### ChromaDB
+
+```python
+import chromadb
+from fastembed_cloud import CloudTextEmbedding
+
+client = chromadb.Client()
+collection = client.create_collection("my_docs")
+model = CloudTextEmbedding()
+
+docs = ["First doc", "Second doc"]
+embeddings = model.embed(docs)
+
+collection.add(
+    documents=docs,
+    embeddings=embeddings,
+    ids=["id1", "id2"],
+)
+```
+
+## API Reference
+
+### CloudTextEmbedding
+
+Always uses the cloud API.
+
+```python
+CloudTextEmbedding(
+    model_name="BAAI/bge-small-en-v1.5",  # Model to use
+    api_key=None,                           # API key (auto-resolved)
+    base_url=None,                          # API URL (default: api.ainative.studio)
+    batch_size=64,                          # Max texts per API call
+    normalize=True,                         # Normalize to unit vectors
+)
+```
+
+**Methods:**
+- `embed(documents, batch_size=None)` — Embed a list of texts. Returns `list[list[float]]`.
+- `query_embed(query)` — Embed a single query. Returns `list[float]`.
+- `passage_embed(texts)` — Alias for `embed()` (fastembed compatibility).
+
+**Properties:**
+- `dim` — Embedding dimensions (e.g., 384 for bge-small).
+- `model_name` — Resolved model name.
+
+### TextEmbedding
+
+Smart hybrid: local fastembed if available, cloud otherwise.
+
+```python
+TextEmbedding(
+    model_name="BAAI/bge-small-en-v1.5",
+    api_key=None,
+    **kwargs,
+)
+```
+
+**Properties:**
+- `is_cloud` — `True` if using cloud API, `False` if using local fastembed.
+
+## License
+
+MIT

fastembed_cloud-0.1.0/README.md

@@ -0,0 +1,199 @@
+# fastembed-cloud
+
+Cloud text embeddings via AINative API. Drop-in replacement for [fastembed](https://github.com/qdrant/fastembed) — same interface, no model downloads, no ONNX runtime.
+
+## Why?
+
+fastembed is great, but requires downloading 100MB+ ONNX models locally. `fastembed-cloud` gives you the same API backed by a free cloud service — zero setup, zero downloads.
+
+| | fastembed | fastembed-cloud |
+|---|---|---|
+| First-run latency | 30-120s (model download) | 0s |
+| Disk usage | 100MB-1GB per model | 0 |
+| ONNX runtime | Required | Not needed |
+| Offline support | Yes | No (cloud API) |
+| Cost | Free (local compute) | Free (AINative API) |
+
+## Install
+
+```bash
+pip install fastembed-cloud
+```
+
+## Quick Start
+
+```python
+from fastembed_cloud import CloudTextEmbedding
+
+# Auto-provisions a free API key on first run
+model = CloudTextEmbedding()
+
+# Single query
+embedding = model.query_embed("What is semantic search?")
+print(f"Dimensions: {len(embedding)}")  # 384
+
+# Batch embedding
+docs = ["First document", "Second document", "Third document"]
+embeddings = model.embed(docs)
+print(f"Embedded {len(embeddings)} documents")
+```
+
+## Models
+
+| Model | Dimensions | ID |
+|---|---|---|
+| BGE-small-en-v1.5 | 384 | `BAAI/bge-small-en-v1.5` (default) |
+| BGE-base-en-v1.5 | 768 | `BAAI/bge-base-en-v1.5` |
+| BGE-large-en-v1.5 | 1024 | `BAAI/bge-large-en-v1.5` |
+| BGE-M3 (multilingual) | 1024 | `bge-m3` |
+
+```python
+model = CloudTextEmbedding(model_name="bge-m3")
+embedding = model.query_embed("Multilingual embedding")
+print(len(embedding))  # 1024
+```
+
+## Smart Hybrid: Local + Cloud
+
+`TextEmbedding` automatically uses local fastembed if installed, cloud otherwise:
+
+```python
+from fastembed_cloud import TextEmbedding
+
+model = TextEmbedding()
+print(model.is_cloud)  # True if fastembed not installed
+
+embeddings = model.embed(["works either way"])
+```
+
+Install fastembed alongside for local-first with cloud fallback:
+
+```bash
+pip install fastembed-cloud[local]
+```
+
+## Authentication
+
+Credentials are resolved in this order:
+
+1. `api_key` parameter: `CloudTextEmbedding(api_key="your-key")`
+2. `AINATIVE_API_KEY` environment variable
+3. `ZERODB_API_KEY` environment variable (shared with ZeroDB ecosystem)
+4. `~/.zerodb/credentials.json` (auto-saved from any ZeroDB tool)
+5. Auto-provisioning (free 72-hour account, claim to keep permanently)
+
+### Auto-Provisioning
+
+On first use with no credentials, fastembed-cloud automatically provisions a free account:
+
+```
+$ python -c "from fastembed_cloud import CloudTextEmbedding; CloudTextEmbedding().query_embed('test')"
+
+  No API key found — provisioning a free AINative account for embeddings...
+
+  Auto-provisioned! Free embeddings API ready.
+
+  API Key:   zdb_abc12345...
+  Expires:   72 hours
+  Saved to:  ~/.zerodb/credentials.json
+
+  To keep access permanently, claim your account:
+  https://ainative.studio/signup
+```
+
+## Batch Embedding
+
+Handles large datasets efficiently with automatic batching:
+
+```python
+model = CloudTextEmbedding(batch_size=100)
+
+# Automatically batches into chunks of 100
+large_dataset = ["document " + str(i) for i in range(10000)]
+embeddings = model.embed(large_dataset)
+```
+
+## Use with Vector Databases
+
+### Qdrant
+
+```python
+from qdrant_client import QdrantClient
+from fastembed_cloud import CloudTextEmbedding
+
+client = QdrantClient(":memory:")
+model = CloudTextEmbedding()
+
+docs = ["AI is transforming healthcare", "Machine learning for finance"]
+embeddings = model.embed(docs)
+
+client.add(
+    collection_name="my_docs",
+    documents=docs,
+    embeddings=embeddings,
+)
+```
+
+### ChromaDB
+
+```python
+import chromadb
+from fastembed_cloud import CloudTextEmbedding
+
+client = chromadb.Client()
+collection = client.create_collection("my_docs")
+model = CloudTextEmbedding()
+
+docs = ["First doc", "Second doc"]
+embeddings = model.embed(docs)
+
+collection.add(
+    documents=docs,
+    embeddings=embeddings,
+    ids=["id1", "id2"],
+)
+```
+
+## API Reference
+
+### CloudTextEmbedding
+
+Always uses the cloud API.
+
+```python
+CloudTextEmbedding(
+    model_name="BAAI/bge-small-en-v1.5",  # Model to use
+    api_key=None,                           # API key (auto-resolved)
+    base_url=None,                          # API URL (default: api.ainative.studio)
+    batch_size=64,                          # Max texts per API call
+    normalize=True,                         # Normalize to unit vectors
+)
+```
+
+**Methods:**
+- `embed(documents, batch_size=None)` — Embed a list of texts. Returns `list[list[float]]`.
+- `query_embed(query)` — Embed a single query. Returns `list[float]`.
+- `passage_embed(texts)` — Alias for `embed()` (fastembed compatibility).
+
+**Properties:**
+- `dim` — Embedding dimensions (e.g., 384 for bge-small).
+- `model_name` — Resolved model name.
+
+### TextEmbedding
+
+Smart hybrid: local fastembed if available, cloud otherwise.
+
+```python
+TextEmbedding(
+    model_name="BAAI/bge-small-en-v1.5",
+    api_key=None,
+    **kwargs,
+)
+```
+
+**Properties:**
+- `is_cloud` — `True` if using cloud API, `False` if using local fastembed.
+
+## License
+
+MIT

fastembed_cloud-0.1.0/fastembed_cloud/__init__.py

@@ -0,0 +1,24 @@
+"""
+fastembed-cloud — Cloud embeddings via AINative API.
+
+Drop-in replacement for fastembed that generates embeddings via API
+instead of downloading and running ONNX models locally.
+
+Usage:
+    from fastembed_cloud import CloudTextEmbedding
+
+    model = CloudTextEmbedding()
+    embeddings = model.embed(["hello world", "semantic search"])
+
+Or use the smart TextEmbedding that prefers local fastembed when installed:
+
+    from fastembed_cloud import TextEmbedding
+
+    model = TextEmbedding()
+    embeddings = model.embed(["hello world"])
+"""
+
+from fastembed_cloud.embedding import CloudTextEmbedding, TextEmbedding
+
+__version__ = "0.1.0"
+__all__ = ["CloudTextEmbedding", "TextEmbedding"]