polyembed 0.0.1__py3-none-any.whl

polyembed/__init__.py

@@ -0,0 +1,19 @@
+from polyembed.client import (
+    AuthenticationError,
+    EmbedResponse,
+    PolyEmbed,
+    PolyEmbedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+__all__ = [
+    "AuthenticationError",
+    "EmbedResponse",
+    "PolyEmbed",
+    "PolyEmbedError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+]

polyembed/client.py

@@ -0,0 +1,224 @@
+"""PolyEmbed Python SDK — embeddings API client with retry and timeout."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Literal
+
+import httpx
+
+
+class PolyEmbedError(Exception):
+    """Base exception for PolyEmbed SDK errors."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class AuthenticationError(PolyEmbedError):
+    """Invalid, revoked, or expired API key (401)."""
+
+
+class ValidationError(PolyEmbedError):
+    """Invalid request parameters (400)."""
+
+
+class RateLimitError(PolyEmbedError):
+    """Rate limit exceeded (429)."""
+
+
+class ServerError(PolyEmbedError):
+    """Server-side error (500/502/503/504)."""
+
+
+@dataclass
+class EmbedResponse:
+    """Full response from the embed endpoint."""
+
+    embedding: list[float]
+    model: str
+    shielded: bool
+    dimensions: int
+
+
+RETRYABLE_STATUS_CODES = {429, 502, 503, 504}
+
+
+class PolyEmbed:
+    """Client for the PolyEmbed embeddings API.
+
+    Args:
+        api_key: API key in the format pe_<team>_<token>.
+        base_url: Base URL of the PolyEmbed service.
+        timeout: Request timeout in seconds.
+        max_retries: Maximum number of retries on transient failures.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://polyembed.com",
+        timeout: float = 30,
+        max_retries: int = 3,
+    ):
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    def embed(
+        self,
+        text: str,
+        input_type: Literal["document", "query"],
+        model: Literal["base", "enhanced"] = "base",
+        shielded: bool = False,
+        raw: bool = False,
+    ) -> list[float] | EmbedResponse:
+        """Generate an embedding for a single text.
+
+        Args:
+            text: Text to embed. Long texts are automatically split and averaged.
+            input_type: "document" for indexing, "query" for search.
+            model: Embedding model. "base" (default) or "enhanced".
+            shielded: Apply per-team property-preserving encryption.
+            raw: If True, return full EmbedResponse instead of just the vector.
+
+        Returns:
+            list[float] (1024 dimensions) or EmbedResponse if raw=True.
+
+        Raises:
+            AuthenticationError: Invalid or expired API key.
+            ValidationError: Invalid request parameters.
+            RateLimitError: Rate limit exceeded.
+            ServerError: Server-side error after all retries exhausted.
+        """
+        data = self._request(
+            "/api/v1/embed/",
+            {"text": text, "input_type": input_type, "model": model, "shielded": shielded},
+        )
+        if raw:
+            return EmbedResponse(
+                embedding=data["embedding"],
+                model=data["model"],
+                shielded=data["shielded"],
+                dimensions=data["dimensions"],
+            )
+        return data["embedding"]
+
+    def embed_batch(
+        self,
+        texts: list[str],
+        input_type: Literal["document", "query"],
+        model: Literal["base", "enhanced"] = "base",
+        shielded: bool = False,
+    ) -> list[list[float]]:
+        """Generate embeddings for multiple texts in one request.
+
+        Args:
+            texts: List of texts to embed (1-100 items).
+            input_type: "document" for indexing, "query" for search.
+            model: Embedding model. "base" (default) or "enhanced".
+            shielded: Apply per-team property-preserving encryption.
+
+        Returns:
+            List of embeddings in the same order as input texts.
+
+        Raises:
+            AuthenticationError: Invalid or expired API key.
+            ValidationError: Invalid request parameters or batch too large.
+            RateLimitError: Rate limit exceeded.
+            ServerError: Server-side error after all retries exhausted.
+        """
+        data = self._request(
+            "/api/v1/embed/batch/",
+            {"texts": texts, "input_type": input_type, "model": model, "shielded": shielded},
+        )
+        return data["embeddings"]
+
+    def _request(self, path: str, payload: dict) -> dict:
+        """Make a POST request with retry logic."""
+        last_error: Exception | None = None
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._client.post(path, json=payload)
+            except httpx.TimeoutException as e:
+                last_error = ServerError(f"Request timed out: {e}", status_code=None)
+                if attempt < self._max_retries:
+                    time.sleep(self._backoff(attempt))
+                    continue
+                raise last_error from e
+            except httpx.HTTPError as e:
+                last_error = ServerError(f"Connection error: {e}", status_code=None)
+                if attempt < self._max_retries:
+                    time.sleep(self._backoff(attempt))
+                    continue
+                raise last_error from e
+
+            if response.status_code == 200:
+                return response.json()
+
+            # Non-retryable errors — raise immediately
+            if response.status_code == 400:
+                raise ValidationError(self._detail(response), status_code=400)
+            if response.status_code == 401:
+                raise AuthenticationError(self._detail(response), status_code=401)
+
+            # Retryable errors
+            if response.status_code in RETRYABLE_STATUS_CODES:
+                last_error = (
+                    RateLimitError(self._detail(response), status_code=429)
+                    if response.status_code == 429
+                    else ServerError(self._detail(response), status_code=response.status_code)
+                )
+                if attempt < self._max_retries:
+                    wait = self._retry_after(response) or self._backoff(attempt)
+                    time.sleep(wait)
+                    continue
+                raise last_error
+
+            # Unknown status code — raise as server error, no retry
+            raise ServerError(self._detail(response), status_code=response.status_code)
+
+        raise last_error or ServerError("Request failed after all retries")
+
+    def _backoff(self, attempt: int) -> float:
+        """Exponential backoff: 0.5s, 1s, 2s, ..."""
+        return 0.5 * (2**attempt)
+
+    def _retry_after(self, response: httpx.Response) -> float | None:
+        """Parse Retry-After header if present."""
+        value = response.headers.get("Retry-After")
+        if value is None:
+            return None
+        try:
+            return float(value)
+        except ValueError:
+            return None
+
+    def _detail(self, response: httpx.Response) -> str:
+        """Extract error detail from response."""
+        try:
+            return response.json().get("detail", response.text)
+        except Exception:
+            return response.text
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

polyembed-0.0.1.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: polyembed
+Version: 0.0.1
+Summary: Python SDK for the PolyEmbed embeddings API
+Author: Brainpolo
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx
+Description-Content-Type: text/markdown
+
+# polyembed
+
+Python SDK for the [PolyEmbed](https://polyembed.com) embeddings API by Brainpolo.
+
+## Install
+
+```bash
+pip install polyembed
+```
+
+## Usage
+
+```python
+from polyembed import PolyEmbed
+
+client = PolyEmbed(api_key="pe_<team>_<key>")
+
+# Single embedding
+embedding = client.embed("hello world", input_type="document")
+# [0.0229, 0.0319, ...]  (1024 floats)
+
+# Batch (1-100 texts)
+embeddings = client.embed_batch(
+    ["text one", "text two"],
+    input_type="document",
+)
+
+# Shielded (encrypted, non-reversible)
+embedding = client.embed(
+    "classified report",
+    input_type="document",
+    shielded=True,
+)
+
+# Full response metadata
+from polyembed import EmbedResponse
+
+response = client.embed("hello", input_type="query", raw=True)
+response.embedding   # list[float]
+response.model       # "base"
+response.shielded    # False
+response.dimensions  # 1024
+```
+
+## Configuration
+
+```python
+client = PolyEmbed(
+    api_key="pe_...",
+    base_url="https://polyembed.com",  # default
+    timeout=30,                         # seconds
+    max_retries=3,                      # retries on 429/5xx
+)
+```
+
+## Error handling
+
+```python
+from polyembed import AuthenticationError, ValidationError, RateLimitError, ServerError
+
+try:
+    embedding = client.embed("hello", input_type="document")
+except AuthenticationError:
+    # 401 — invalid or expired API key
+except ValidationError:
+    # 400 — invalid parameters
+except RateLimitError:
+    # 429 — rate limit exceeded (retried automatically)
+except ServerError:
+    # 500/502/503/504 — server error (retried automatically)
+```
+
+## Context manager
+
+```python
+with PolyEmbed(api_key="pe_...") as client:
+    embedding = client.embed("hello", input_type="document")
+```

polyembed-0.0.1.dist-info/RECORD

@@ -0,0 +1,5 @@
+polyembed/__init__.py,sha256=d8elOyOozM6zQXkaF7oM-k9l1S8v4Yrxtvje2ngns60,336
+polyembed/client.py,sha256=T7_CfR40mxwRzYKJweQdghH38WAh_Xnla98tc2fizNA,7514
+polyembed-0.0.1.dist-info/METADATA,sha256=M4IgHyGe0qXcsfIgQiBD6_drUcUsN8iV2zD-gsdmWXk,1950
+polyembed-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+polyembed-0.0.1.dist-info/RECORD,,

polyembed-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any