fluxvector 0.1.0__tar.gz

fluxvector-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: fluxvector
+Version: 0.1.0
+Summary: Official Python SDK for FluxVector — semantic search API by FluxSoft Labs
+Project-URL: Homepage, https://fluxsoftlabs.com/fluxvector
+Project-URL: Documentation, https://docs.fluxsoftlabs.com/fluxvector
+Project-URL: Repository, https://github.com/fluxsoftlabs/fluxvector-python
+Project-URL: Issues, https://github.com/fluxsoftlabs/fluxvector-python/issues
+Author-email: FluxSoft Labs <hello@fluxsoftlabs.com>
+License-Expression: MIT
+Keywords: ai,embeddings,fluxvector,semantic-search,vector
+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.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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FluxVector Python SDK
+
+Official Python SDK for [FluxVector](https://fluxsoftlabs.com/fluxvector) — semantic search API by FluxSoft Labs.
+
+## Installation
+
+```bash
+pip install fluxvector
+```
+
+## Quick Start
+
+```python
+from fluxvector import FluxVector
+
+fv = FluxVector(api_key="fv_live_abc123")
+
+# Create a collection
+col = fv.collections.create("products", dimension=1536, metric="cosine")
+
+# Upsert vectors (auto-chunks at 1000)
+fv.vectors.upsert("products", [
+    {"id": "p1", "text": "Red running shoes", "metadata": {"price": 89, "brand": "Nike"}},
+    {"id": "p2", "text": "Blue hiking boots", "metadata": {"price": 149, "brand": "Merrell"}},
+    {"id": "p3", "text": "White tennis sneakers", "metadata": {"price": 65, "brand": "Adidas"}},
+])
+
+# Semantic search
+results = fv.search("products", "comfortable shoes for running", top_k=5)
+for r in results:
+    print(f"{r.id}: {r.score:.2f} — {r.text}")
+
+# Search with metadata filters
+results = fv.search("products", "shoes", filter={"price": {"$lt": 100}})
+```
+
+## Async Support
+
+```python
+from fluxvector import AsyncFluxVector
+
+async with AsyncFluxVector(api_key="fv_live_abc123") as fv:
+    results = await fv.search("products", "comfortable shoes")
+    for r in results:
+        print(f"{r.id}: {r.score:.2f}")
+```
+
+## Configuration
+
+```python
+fv = FluxVector(
+    api_key="fv_live_abc123",       # or set FLUXVECTOR_API_KEY env var
+    base_url="https://custom.host", # default: https://fluxvector.dev
+    timeout=30.0,                   # request timeout in seconds
+    max_retries=3,                  # retries on 429 / 5xx with exponential backoff
+)
+```
+
+## API Reference
+
+### Collections
+
+```python
+# Create
+col = fv.collections.create("products", dimension=1536, metric="cosine", description="Product catalog")
+
+# List (cursor pagination)
+page = fv.collections.list(limit=10)
+for col in page:
+    print(col.name)
+# Next page
+if page.has_more:
+    next_page = fv.collections.list(cursor=page.next_cursor)
+
+# Get
+col = fv.collections.get("products")
+
+# Delete
+fv.collections.delete("products")
+```
+
+### Vectors
+
+```python
+# Upsert (auto-chunks at 1000 vectors per request)
+fv.vectors.upsert("products", [
+    {"id": "p1", "text": "Red shoes", "metadata": {"price": 89}},
+    {"id": "p2", "text": "Blue hat", "values": [0.1, 0.2, ...]},  # raw vector
+])
+
+# Query by text
+results = fv.vectors.query("products", text="shoes", top_k=10)
+
+# Query by raw vector
+results = fv.vectors.query("products", vector=[0.1, 0.2, ...], top_k=5)
+
+# Query with filter
+results = fv.vectors.query(
+    "products",
+    text="shoes",
+    filter={"brand": {"$in": ["Nike", "Adidas"]}},
+    include_metadata=True,
+    include_text=True,
+)
+
+# Fetch by IDs
+vectors = fv.vectors.fetch("products", ["p1", "p2"])
+
+# Delete by IDs
+fv.vectors.delete("products", ids=["p1", "p2"])
+
+# Delete by filter
+fv.vectors.delete("products", filter={"brand": {"$eq": "discontinued"}})
+```
+
+### Search
+
+The signature method — one-line semantic search:
+
+```python
+results = fv.search("products", "comfortable running shoes", top_k=10)
+for r in results:
+    print(f"{r.id}: {r.score:.4f} — {r.text}")
+    print(f"  metadata: {r.metadata}")
+```
+
+### Embeddings
+
+```python
+# Single text
+resp = fv.embeddings.create("Hello world")
+print(resp.embedding)  # [0.012, -0.034, ...]
+print(resp.dimension)  # 1536
+
+# Batch
+resp = fv.embeddings.batch(["Hello", "World", "Foo"])
+for emb in resp.embeddings:
+    print(len(emb))  # 1536
+```
+
+### API Keys
+
+```python
+# Create
+key = fv.api_keys.create("Production Key", env="live")
+print(key.key)  # fv_live_... (only shown once)
+
+# List
+keys = fv.api_keys.list()
+for k in keys:
+    print(f"{k.name}: {k.prefix}...")
+
+# Rename
+fv.api_keys.update("key_id", name="New Name")
+
+# Delete
+fv.api_keys.delete("key_id")
+```
+
+### Usage
+
+```python
+# Current usage
+usage = fv.usage.get()
+print(f"Plan: {usage.plan}")
+print(f"Requests: {usage.requests}")
+print(f"Vectors stored: {usage.vectors_stored}")
+
+# Historical usage
+history = fv.usage.history(days=30)
+for day in history:
+    print(f"{day.date}: {day.requests} requests")
+```
+
+## Filter Operators
+
+Use metadata filters with any search or query method:
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$eq` | Equal | `{"status": {"$eq": "active"}}` |
+| `$ne` | Not equal | `{"status": {"$ne": "deleted"}}` |
+| `$gt` | Greater than | `{"price": {"$gt": 50}}` |
+| `$gte` | Greater than or equal | `{"price": {"$gte": 50}}` |
+| `$lt` | Less than | `{"price": {"$lt": 100}}` |
+| `$lte` | Less than or equal | `{"price": {"$lte": 100}}` |
+| `$in` | In array | `{"brand": {"$in": ["Nike", "Adidas"]}}` |
+| `$nin` | Not in array | `{"brand": {"$nin": ["Generic"]}}` |
+
+## Error Handling
+
+```python
+from fluxvector import FluxVector, FluxVectorError, AuthenticationError, RateLimitError, NotFoundError
+
+fv = FluxVector(api_key="fv_live_abc123")
+
+try:
+    results = fv.search("products", "shoes")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited: {e.message}")
+except NotFoundError:
+    print("Collection not found")
+except FluxVectorError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FLUXVECTOR_API_KEY` | Default API key (if not passed to constructor) |
+| `FLUXVECTOR_BASE_URL` | Override base URL for self-hosted instances |
+
+## License
+
+MIT

fluxvector-0.1.0/README.md

@@ -0,0 +1,218 @@
+# FluxVector Python SDK
+
+Official Python SDK for [FluxVector](https://fluxsoftlabs.com/fluxvector) — semantic search API by FluxSoft Labs.
+
+## Installation
+
+```bash
+pip install fluxvector
+```
+
+## Quick Start
+
+```python
+from fluxvector import FluxVector
+
+fv = FluxVector(api_key="fv_live_abc123")
+
+# Create a collection
+col = fv.collections.create("products", dimension=1536, metric="cosine")
+
+# Upsert vectors (auto-chunks at 1000)
+fv.vectors.upsert("products", [
+    {"id": "p1", "text": "Red running shoes", "metadata": {"price": 89, "brand": "Nike"}},
+    {"id": "p2", "text": "Blue hiking boots", "metadata": {"price": 149, "brand": "Merrell"}},
+    {"id": "p3", "text": "White tennis sneakers", "metadata": {"price": 65, "brand": "Adidas"}},
+])
+
+# Semantic search
+results = fv.search("products", "comfortable shoes for running", top_k=5)
+for r in results:
+    print(f"{r.id}: {r.score:.2f} — {r.text}")
+
+# Search with metadata filters
+results = fv.search("products", "shoes", filter={"price": {"$lt": 100}})
+```
+
+## Async Support
+
+```python
+from fluxvector import AsyncFluxVector
+
+async with AsyncFluxVector(api_key="fv_live_abc123") as fv:
+    results = await fv.search("products", "comfortable shoes")
+    for r in results:
+        print(f"{r.id}: {r.score:.2f}")
+```
+
+## Configuration
+
+```python
+fv = FluxVector(
+    api_key="fv_live_abc123",       # or set FLUXVECTOR_API_KEY env var
+    base_url="https://custom.host", # default: https://fluxvector.dev
+    timeout=30.0,                   # request timeout in seconds
+    max_retries=3,                  # retries on 429 / 5xx with exponential backoff
+)
+```
+
+## API Reference
+
+### Collections
+
+```python
+# Create
+col = fv.collections.create("products", dimension=1536, metric="cosine", description="Product catalog")
+
+# List (cursor pagination)
+page = fv.collections.list(limit=10)
+for col in page:
+    print(col.name)
+# Next page
+if page.has_more:
+    next_page = fv.collections.list(cursor=page.next_cursor)
+
+# Get
+col = fv.collections.get("products")
+
+# Delete
+fv.collections.delete("products")
+```
+
+### Vectors
+
+```python
+# Upsert (auto-chunks at 1000 vectors per request)
+fv.vectors.upsert("products", [
+    {"id": "p1", "text": "Red shoes", "metadata": {"price": 89}},
+    {"id": "p2", "text": "Blue hat", "values": [0.1, 0.2, ...]},  # raw vector
+])
+
+# Query by text
+results = fv.vectors.query("products", text="shoes", top_k=10)
+
+# Query by raw vector
+results = fv.vectors.query("products", vector=[0.1, 0.2, ...], top_k=5)
+
+# Query with filter
+results = fv.vectors.query(
+    "products",
+    text="shoes",
+    filter={"brand": {"$in": ["Nike", "Adidas"]}},
+    include_metadata=True,
+    include_text=True,
+)
+
+# Fetch by IDs
+vectors = fv.vectors.fetch("products", ["p1", "p2"])
+
+# Delete by IDs
+fv.vectors.delete("products", ids=["p1", "p2"])
+
+# Delete by filter
+fv.vectors.delete("products", filter={"brand": {"$eq": "discontinued"}})
+```
+
+### Search
+
+The signature method — one-line semantic search:
+
+```python
+results = fv.search("products", "comfortable running shoes", top_k=10)
+for r in results:
+    print(f"{r.id}: {r.score:.4f} — {r.text}")
+    print(f"  metadata: {r.metadata}")
+```
+
+### Embeddings
+
+```python
+# Single text
+resp = fv.embeddings.create("Hello world")
+print(resp.embedding)  # [0.012, -0.034, ...]
+print(resp.dimension)  # 1536
+
+# Batch
+resp = fv.embeddings.batch(["Hello", "World", "Foo"])
+for emb in resp.embeddings:
+    print(len(emb))  # 1536
+```
+
+### API Keys
+
+```python
+# Create
+key = fv.api_keys.create("Production Key", env="live")
+print(key.key)  # fv_live_... (only shown once)
+
+# List
+keys = fv.api_keys.list()
+for k in keys:
+    print(f"{k.name}: {k.prefix}...")
+
+# Rename
+fv.api_keys.update("key_id", name="New Name")
+
+# Delete
+fv.api_keys.delete("key_id")
+```
+
+### Usage
+
+```python
+# Current usage
+usage = fv.usage.get()
+print(f"Plan: {usage.plan}")
+print(f"Requests: {usage.requests}")
+print(f"Vectors stored: {usage.vectors_stored}")
+
+# Historical usage
+history = fv.usage.history(days=30)
+for day in history:
+    print(f"{day.date}: {day.requests} requests")
+```
+
+## Filter Operators
+
+Use metadata filters with any search or query method:
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$eq` | Equal | `{"status": {"$eq": "active"}}` |
+| `$ne` | Not equal | `{"status": {"$ne": "deleted"}}` |
+| `$gt` | Greater than | `{"price": {"$gt": 50}}` |
+| `$gte` | Greater than or equal | `{"price": {"$gte": 50}}` |
+| `$lt` | Less than | `{"price": {"$lt": 100}}` |
+| `$lte` | Less than or equal | `{"price": {"$lte": 100}}` |
+| `$in` | In array | `{"brand": {"$in": ["Nike", "Adidas"]}}` |
+| `$nin` | Not in array | `{"brand": {"$nin": ["Generic"]}}` |
+
+## Error Handling
+
+```python
+from fluxvector import FluxVector, FluxVectorError, AuthenticationError, RateLimitError, NotFoundError
+
+fv = FluxVector(api_key="fv_live_abc123")
+
+try:
+    results = fv.search("products", "shoes")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited: {e.message}")
+except NotFoundError:
+    print("Collection not found")
+except FluxVectorError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FLUXVECTOR_API_KEY` | Default API key (if not passed to constructor) |
+| `FLUXVECTOR_BASE_URL` | Override base URL for self-hosted instances |
+
+## License
+
+MIT

fluxvector-0.1.0/fluxvector/__init__.py

@@ -0,0 +1,49 @@
+"""FluxVector Python SDK — Semantic search by FluxSoft Labs."""
+
+from fluxvector._version import __version__
+from fluxvector.async_client import AsyncFluxVector
+from fluxvector.client import FluxVector
+from fluxvector.errors import (
+    AuthenticationError,
+    FluxVectorError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ValidationError,
+)
+from fluxvector.types import (
+    ApiKey,
+    Collection,
+    EmbedBatchResponse,
+    EmbedResponse,
+    SearchResponse,
+    SearchResult,
+    UpsertResponse,
+    UsageSummary,
+    Vector,
+)
+
+__all__ = [
+    "__version__",
+    "FluxVector",
+    "AsyncFluxVector",
+    # Errors
+    "FluxVectorError",
+    "AuthenticationError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ValidationError",
+    "InternalServerError",
+    # Types
+    "ApiKey",
+    "Collection",
+    "EmbedBatchResponse",
+    "EmbedResponse",
+    "SearchResponse",
+    "SearchResult",
+    "UpsertResponse",
+    "UsageSummary",
+    "Vector",
+]

fluxvector-0.1.0/fluxvector/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

fluxvector-0.1.0/fluxvector/async_client.py

@@ -0,0 +1,139 @@
+"""Asynchronous FluxVector client."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any, Optional
+
+import httpx
+
+from fluxvector._version import __version__
+from fluxvector.errors import ConnectionError as FVConnectionError
+from fluxvector.errors import raise_for_status
+from fluxvector.resources.api_keys import AsyncApiKeysResource
+from fluxvector.resources.collections import AsyncCollectionsResource
+from fluxvector.resources.embeddings import AsyncEmbeddingsResource
+from fluxvector.resources.search import AsyncSearchResource
+from fluxvector.resources.usage import AsyncUsageResource
+from fluxvector.resources.vectors import AsyncVectorsResource
+from fluxvector.types import SearchResponse
+
+_DEFAULT_BASE_URL = "https://fluxvector.dev"
+_DEFAULT_TIMEOUT = 30.0
+_MAX_RETRIES = 3
+_RETRY_STATUSES = {429, 500, 502, 503, 504}
+_BACKOFF_BASE = 0.5
+
+
+class AsyncFluxVector:
+    """Asynchronous FluxVector API client.
+
+    Usage::
+
+        async with AsyncFluxVector(api_key="fv_live_abc123") as fv:
+            results = await fv.search("products", "comfortable shoes")
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _MAX_RETRIES,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("FLUXVECTOR_API_KEY", "")
+        if not self.api_key:
+            raise ValueError(
+                "API key is required. Pass api_key= or set FLUXVECTOR_API_KEY."
+            )
+
+        self.base_url = (base_url or os.environ.get("FLUXVECTOR_BASE_URL", _DEFAULT_BASE_URL)).rstrip("/")
+        self.max_retries = max_retries
+
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": f"fluxvector-python/{__version__}",
+            },
+        )
+
+        # Resources
+        self.collections = AsyncCollectionsResource(self)
+        self.vectors = AsyncVectorsResource(self)
+        self.search = AsyncSearchResource(self)
+        self.embeddings = AsyncEmbeddingsResource(self)
+        self.api_keys = AsyncApiKeysResource(self)
+        self.usage = AsyncUsageResource(self)
+
+    def __repr__(self) -> str:
+        return f"AsyncFluxVector(base_url={self.base_url!r})"
+
+    async def __aenter__(self) -> AsyncFluxVector:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._client.aclose()
+
+    # ── Internal HTTP methods ────────────────────────────────────────────
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Make an HTTP request with retry logic."""
+        last_exc: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._client.request(method, path, **kwargs)
+                if response.status_code in _RETRY_STATUSES and attempt < self.max_retries:
+                    await self._backoff(attempt, response.headers)
+                    continue
+                body = response.json() if response.content else {}
+                raise_for_status(response.status_code, body, dict(response.headers))
+                return body
+            except httpx.HTTPStatusError as exc:
+                last_exc = exc
+                if attempt < self.max_retries:
+                    await self._backoff(attempt)
+                    continue
+                raise
+            except (httpx.ConnectError, httpx.TimeoutException) as exc:
+                last_exc = exc
+                if attempt < self.max_retries:
+                    await self._backoff(attempt)
+                    continue
+                raise FVConnectionError(
+                    f"Failed to connect to {self.base_url}: {exc}"
+                ) from exc
+        raise last_exc  # type: ignore[misc]
+
+    @staticmethod
+    async def _backoff(attempt: int, headers: Optional[Any] = None) -> None:
+        """Exponential backoff with optional Retry-After header support."""
+        if headers and hasattr(headers, "get"):
+            retry_after = headers.get("Retry-After")
+            if retry_after:
+                try:
+                    await asyncio.sleep(float(retry_after))
+                    return
+                except (ValueError, TypeError):
+                    pass
+        await asyncio.sleep(_BACKOFF_BASE * (2 ** attempt))
+
+    async def _get(self, path: str, *, params: Optional[dict] = None) -> Any:
+        return await self._request("GET", path, params=params)
+
+    async def _post(self, path: str, *, json: Optional[dict] = None) -> Any:
+        return await self._request("POST", path, json=json)
+
+    async def _patch(self, path: str, *, json: Optional[dict] = None) -> Any:
+        return await self._request("PATCH", path, json=json)
+
+    async def _delete(self, path: str) -> Any:
+        return await self._request("DELETE", path)