decompressed-sdk 0.2.0__py3-none-any.whl

decompressed_sdk/__init__.py

@@ -0,0 +1,139 @@
+"""
+Decompressed SDK - Version-First Vector Data Platform.
+
+This SDK implements "Snowflake for vectors" semantics where datasets
+are version-aware and all operations require explicit version pinning.
+
+Example:
+    from decompressed_sdk import DecompressedClient
+    
+    client = DecompressedClient(
+        base_url="https://api.decompressed.io",
+        api_key="your-api-key"
+    )
+    
+    # Get dataset reference
+    dataset = client.datasets.get("my-dataset")
+    
+    # Pin to specific version for reproducible operations
+    v1 = dataset.version(1)
+    info = v1.info()
+    results = v1.search([[0.1, 0.2, 0.3]], top_k=10)
+    
+    # Compare versions (LLM regression testing)
+    diff = v1.compare_to(2)
+    
+    # Time travel
+    yesterday = dataset.at("2024-01-28T00:00:00Z")
+"""
+
+from .client import DecompressedClient
+from .auth import ApiKeyAuth, JwtAuth, AuthStrategy
+from .errors import (
+    DecompressedError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+)
+
+# Re-export types for convenience
+from .types import (
+    # Datasets
+    Dataset,
+    DatasetInfo,
+    DatasetQueryResponse,
+    DatasetVersion,
+    UploadSession,
+    AppendSession,
+    JobStatus,
+    UploadResult,
+    AppendResult,
+    # Versions (NEW - core of version-first design)
+    DatasetRef,
+    VersionedDataset,
+    DatasetEvent,
+    VersionInfo,
+    VersionComparison,
+    # Materializations
+    Materialization,
+    MaterializationType,
+    MaterializationStatus,
+    CreateMaterializationResponse,
+    MaterializationEstimate,
+    MaterializationDownloadFile,
+    MaterializationDownloadResponse,
+    # Connectors
+    Connector,
+    # Syncs
+    SyncJob,
+    SyncResult,
+    SyncValidation,
+    SyncState,
+    # Embeddings
+    SourceReference,
+    EmbeddingJob,
+    EmbeddingJobStatus,
+    EmbeddingResult,
+    # Search
+    SearchMatch,
+    SearchResponse,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # Client
+    "DecompressedClient",
+    # Auth
+    "ApiKeyAuth",
+    "JwtAuth",
+    "AuthStrategy",
+    # Errors
+    "DecompressedError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    # Types - Datasets
+    "Dataset",
+    "DatasetInfo",
+    "DatasetQueryResponse",
+    "DatasetVersion",
+    "UploadSession",
+    "AppendSession",
+    "JobStatus",
+    "UploadResult",
+    "AppendResult",
+    # Types - Versions (NEW)
+    "DatasetRef",
+    "VersionedDataset",
+    "DatasetEvent",
+    "VersionInfo",
+    "VersionComparison",
+    # Types - Materializations
+    "Materialization",
+    "MaterializationType",
+    "MaterializationStatus",
+    "CreateMaterializationResponse",
+    "MaterializationEstimate",
+    "MaterializationDownloadFile",
+    "MaterializationDownloadResponse",
+    # Types - Connectors
+    "Connector",
+    # Types - Syncs
+    "SyncJob",
+    "SyncResult",
+    "SyncValidation",
+    "SyncState",
+    # Types - Embeddings
+    "SourceReference",
+    "EmbeddingJob",
+    "EmbeddingJobStatus",
+    "EmbeddingResult",
+    # Types - Search
+    "SearchMatch",
+    "SearchResponse",
+]

decompressed_sdk/auth.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Protocol
+
+
+class AuthStrategy(Protocol):
+    def headers(self) -> Dict[str, str]:
+        ...
+
+
+@dataclass(frozen=True)
+class ApiKeyAuth:
+    api_key: str
+
+    def __post_init__(self) -> None:
+        if not self.api_key:
+            raise ValueError("API key is required")
+
+    def headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+
+@dataclass(frozen=True)
+class JwtAuth:
+    jwt: str
+
+    def __post_init__(self) -> None:
+        if not self.jwt:
+            raise ValueError("JWT is required")
+
+    def headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self.jwt}"}

decompressed_sdk/client.py

@@ -0,0 +1,165 @@
+"""
+Decompressed SDK Client - Version-First Design.
+
+This client implements "Snowflake for vectors" semantics where datasets
+are version-aware and all operations require explicit version pinning.
+
+Example:
+    from decompressed_sdk import DecompressedClient
+    
+    client = DecompressedClient(
+        base_url="https://api.decompressed.io",
+        api_key="your-api-key"
+    )
+    
+    # Get dataset reference
+    dataset = client.datasets.get("my-dataset")
+    
+    # Pin to specific version for reproducible operations
+    v1 = dataset.version(1)
+    info = v1.info()
+    results = v1.search([[0.1, 0.2, 0.3]], top_k=10)
+    
+    # Or use latest explicitly
+    latest = dataset.latest()
+    
+    # Time travel to a specific point
+    yesterday = dataset.at("2024-01-28T00:00:00Z")
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import requests
+
+from .auth import ApiKeyAuth, AuthStrategy, JwtAuth
+from .errors import raise_for_status
+from .resources.datasets import DatasetsResource
+from .resources.materializations import MaterializationsResource
+from .resources.connectors import ConnectorsResource
+from .resources.syncs import SyncsResource
+from .resources.embeddings import EmbeddingsResource
+
+
+class DecompressedClient:
+    """
+    Decompressed SDK client with version-first design.
+    
+    All dataset operations require explicit version pinning to ensure
+    reproducibility and auditability.
+    
+    Args:
+        base_url: API base URL (e.g., "https://api.decompressed.io")
+        api_key: API key for authentication
+        jwt: JWT token for authentication (alternative to api_key)
+        session: Optional requests.Session for connection pooling
+        timeout_seconds: Request timeout in seconds
+        
+    Example:
+        client = DecompressedClient(
+            base_url="https://api.decompressed.io",
+            api_key="dcp_..."
+        )
+        
+        # Get dataset and pin to version
+        dataset = client.datasets.get("embeddings-v2")
+        v3 = dataset.version(3)
+        
+        # All operations use version 3
+        info = v3.info()
+        results = v3.search([[0.1, 0.2, 0.3]])
+    """
+    
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: Optional[str] = None,
+        jwt: Optional[str] = None,
+        session: Optional[requests.Session] = None,
+        timeout_seconds: float = 60.0,
+    ) -> None:
+        if api_key and jwt:
+            raise ValueError("Provide only one of api_key or jwt")
+
+        self._base_url = base_url.rstrip("/")
+        self._timeout_seconds = timeout_seconds
+
+        self._auth: Optional[AuthStrategy] = None
+        if api_key:
+            self._auth = ApiKeyAuth(api_key)
+        if jwt:
+            self._auth = JwtAuth(jwt)
+
+        self._session = session or requests.Session()
+
+        # Resource accessors
+        self.datasets = DatasetsResource(self)
+        self.connectors = ConnectorsResource(self)
+        self.syncs = SyncsResource(self)
+        self.embeddings = EmbeddingsResource(self)
+
+    def materializations(self, dataset_id: str) -> MaterializationsResource:
+        """
+        Get a MaterializationsResource for managing materializations of a dataset.
+
+        Args:
+            dataset_id: The dataset ID or name
+
+        Returns:
+            MaterializationsResource for the dataset
+        """
+        return MaterializationsResource(self, dataset_id)
+
+    def request(self, method: str, path: str, json: Any = None) -> Any:
+        """Make an authenticated request to the API."""
+        headers: Dict[str, str] = {"Accept": "application/json"}
+        if self._auth:
+            headers.update(self._auth.headers())
+
+        url = f"{self._base_url}{path}"
+        resp = self._session.request(
+            method=method,
+            url=url,
+            headers=headers,
+            json=json,
+            timeout=self._timeout_seconds,
+        )
+
+        if resp.status_code >= 400:
+            request_id = resp.headers.get("x-request-id")
+            try:
+                body = resp.json()
+            except Exception:
+                body = resp.text
+            raise_for_status(resp.status_code, body, request_id)
+
+        if resp.status_code == 204:
+            return None
+
+        return resp.json()
+
+    def request_raw(self, method: str, path: str) -> requests.Response:
+        """Make an authenticated request and return raw response (for binary data)."""
+        headers: Dict[str, str] = {}
+        if self._auth:
+            headers.update(self._auth.headers())
+
+        url = f"{self._base_url}{path}"
+        resp = self._session.request(
+            method=method,
+            url=url,
+            headers=headers,
+            timeout=self._timeout_seconds,
+        )
+
+        if resp.status_code >= 400:
+            request_id = resp.headers.get("x-request-id")
+            try:
+                body = resp.json()
+            except Exception:
+                body = resp.text
+            raise_for_status(resp.status_code, body, request_id)
+
+        return resp

decompressed_sdk/errors.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class DecompressedError(Exception):
+    message: str
+    status: Optional[int] = None
+    request_id: Optional[str] = None
+    details: Any = None
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class AuthenticationError(DecompressedError):
+    pass
+
+
+class PermissionError(DecompressedError):
+    pass
+
+
+class NotFoundError(DecompressedError):
+    pass
+
+
+class ValidationError(DecompressedError):
+    pass
+
+
+class RateLimitError(DecompressedError):
+    pass
+
+
+class ServerError(DecompressedError):
+    pass
+
+
+def raise_for_status(status: int, body: Any, request_id: Optional[str]) -> None:
+    message = None
+    if isinstance(body, dict):
+        message = body.get("detail") or body.get("message")
+    if not message:
+        message = f"HTTP {status}"
+
+    if status == 401:
+        raise AuthenticationError(message, status=status, request_id=request_id, details=body)
+    if status == 403:
+        raise PermissionError(message, status=status, request_id=request_id, details=body)
+    if status == 404:
+        raise NotFoundError(message, status=status, request_id=request_id, details=body)
+    if status == 422:
+        raise ValidationError(message, status=status, request_id=request_id, details=body)
+    if status == 429:
+        raise RateLimitError(message, status=status, request_id=request_id, details=body)
+    if status >= 500:
+        raise ServerError(message, status=status, request_id=request_id, details=body)
+
+    raise DecompressedError(message, status=status, request_id=request_id, details=body)

decompressed_sdk/resources/__init__.py

@@ -0,0 +1,24 @@
+"""Decompressed SDK resource modules.
+
+Version-first design:
+- DraftVersion: Mutable staging area before commit
+- CommittedVersion: Immutable, addressable forever
+"""
+
+from .datasets import DatasetsResource
+from .versions import DraftVersion, CommittedVersion, VersionedDatasetResource
+from .materializations import MaterializationsResource
+from .connectors import ConnectorsResource
+from .syncs import SyncsResource
+from .embeddings import EmbeddingsResource
+
+__all__ = [
+    "DatasetsResource",
+    "DraftVersion",
+    "CommittedVersion",
+    "VersionedDatasetResource",  # Backward compat alias
+    "MaterializationsResource",
+    "ConnectorsResource",
+    "SyncsResource",
+    "EmbeddingsResource",
+]

decompressed_sdk/resources/connectors.py

@@ -0,0 +1,39 @@
+"""Connectors resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import DecompressedClient
+
+from ..types.connectors import Connector
+
+
+def _filter_dataclass_kwargs(model: type, data: Dict[str, Any]) -> Dict[str, Any]:
+    """Filter dict to only include fields defined in the dataclass."""
+    allowed = getattr(model, "__dataclass_fields__", None)
+    if not allowed:
+        return data
+    return {k: v for k, v in data.items() if k in allowed}
+
+
+class ConnectorsResource:
+    """Manage connectors (vector databases, external services)."""
+    
+    def __init__(self, client: "DecompressedClient") -> None:
+        self._client = client
+
+    def list(self) -> List[Connector]:
+        """List all connectors."""
+        data = self._client.request("GET", "/api/v1/connectors")
+        return [Connector(**_filter_dataclass_kwargs(Connector, item)) for item in data]
+
+    def get(self, connector_id: str) -> Connector:
+        """Get a connector by ID."""
+        data = self._client.request("GET", f"/api/v1/connectors/{connector_id}")
+        return Connector(**_filter_dataclass_kwargs(Connector, data))
+
+    def test(self, connector_id: str) -> Dict[str, Any]:
+        """Test a connector's connection."""
+        return self._client.request("POST", f"/api/v1/connectors/{connector_id}/test")