provably-sdk 0.1.0__py3-none-any.whl

provably/__init__.py

@@ -0,0 +1,55 @@
+"""Python SDK for the Provably API."""
+
+from provably._answer_model import AggregateAnswer, QueryAnswer, ResultsetAnswer, TabularData
+from provably._auth_api import Organization, OrganizationType
+from provably._config import (
+    MemoryTokenStore,
+    OAuthTokens,
+    ProvablyConfig,
+    ProvablyConfigError,
+    TokenStore,
+    configure,
+)
+from provably._errors import (
+    ProvablyAPIError,
+    ProvablyAuthError,
+    ProvablyConnectionError,
+    ProvablyDataError,
+    ProvablyError,
+    ProvablyNotFoundError,
+    ProvablyResourceAlreadyExistsError,
+    ProvablyUnauthorizedError,
+)
+from provably.auth_service import ProvablyAuthService, auth_service
+from provably.connection import ConnectionInfo
+from provably.oauth_login import browser_login
+from provably.service import ProvablyService, service
+
+__all__ = [
+    "AggregateAnswer",
+    "ConnectionInfo",
+    "MemoryTokenStore",
+    "OAuthTokens",
+    "Organization",
+    "OrganizationType",
+    "ProvablyAPIError",
+    "ProvablyAuthError",
+    "ProvablyAuthService",
+    "ProvablyConfig",
+    "ProvablyConfigError",
+    "ProvablyConnectionError",
+    "ProvablyDataError",
+    "ProvablyError",
+    "ProvablyNotFoundError",
+    "ProvablyResourceAlreadyExistsError",
+    "ProvablyService",
+    "ProvablyUnauthorizedError",
+    "QueryAnswer",
+    "ResultsetAnswer",
+    "TabularData",
+    "TokenStore",
+    "auth_service",
+    "browser_login",
+    "configure",
+    "service",
+]

provably/_answer_model.py

@@ -0,0 +1,78 @@
+"""Data validation and serialization contracts for the Rust API layers."""
+
+from typing import Any, Literal
+
+import msgspec
+import structlog
+from pydantic import BaseModel, Field, model_validator
+
+_log = structlog.get_logger(__name__)
+
+__all__ = ["QueryAnswer", "TabularData", "AggregateAnswer", "ResultsetAnswer"]
+
+
+def _safe_deserialize(cell: Any) -> Any:
+    """Helper to cleanly parse stringified JSON containers using high-speed C decoding."""
+    if isinstance(cell, str) and cell.strip().startswith(("{", "[")):
+        try:
+            return msgspec.json.decode(cell)
+        except Exception as e:
+            _log.debug("safe_deserialize_fallback", error=str(e))
+            return cell
+    return cell
+
+
+class TabularData(BaseModel):
+    columns: list[dict[str, Any]] = Field(default_factory=list)
+    rows: list[list[Any]] = Field(default_factory=list)
+
+    def extract_value(self) -> Any:
+        """Unpacks tabular results down to the core target payload."""
+        if not self.rows:
+            return {"columns": self.columns, "rows": self.rows}
+
+        row0 = self.rows[0]
+        # Extracted column names are normalized to lowercase
+        col_names = [str(c.get("name") or "").lower() for c in self.columns]
+
+        # Target 1: Extract intercept record payloads cleanly if present
+        if "raw_response" in col_names:
+            return _safe_deserialize(row0[col_names.index("raw_response")])
+
+        # Target 2: Single cell scalar
+        if len(col_names) == 1 and len(row0) == 1:
+            return _safe_deserialize(row0[0])
+
+        return {"columns": self.columns, "rows": self.rows}
+
+
+class AggregateAnswer(BaseModel):
+    type: Literal["aggregate"]
+    value: str
+
+    def extract_value(self) -> Any:
+        return _safe_deserialize(self.value)
+
+
+class ResultsetAnswer(BaseModel):
+    type: Literal["resultset"]
+    value: TabularData
+
+    def extract_value(self) -> Any:
+        return self.value.extract_value()
+
+
+class QueryAnswer(BaseModel):
+    """Wrapper mapping the structure of QueryAnswer enum."""
+
+    root: AggregateAnswer | ResultsetAnswer = Field(..., discriminator="type")
+
+    @model_validator(mode="before")
+    @classmethod
+    def wrap_root(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "root" not in data:
+            return {"root": data}
+        return data
+
+    def flatten(self) -> Any:
+        return self.root.extract_value()

provably/_api.py

@@ -0,0 +1,407 @@
+"""Provably API — named methods for every endpoint.
+
+:class:`ProvablyAPI` covers five resource groups:
+- **Middlewares** — create the Provably middleware for an org
+- **Databases / Schemas / Tables / Columns** — onboard and inspect the connected database
+- **Collections** — manage query collections
+- **Integrations** — register external integrations
+- **Queries & Proofs** — run queries, generate proofs, poll status
+"""
+
+import functools
+import uuid
+from typing import Any
+
+from provably._config import ProvablyConfig, ProvablyConfigError, current
+from provably._http import get_http
+
+
+class ProvablyAPI:
+    """Provably API endpoints."""
+
+    def __init__(self, config: ProvablyConfig | None = None) -> None:
+        c = config or current().config()
+        self.org_id = c.org_id
+        self.app = c.app_url
+
+    def _generic_path(self) -> str:
+        return "/api/v1"
+
+    def _org_path(self) -> str:
+        if self.org_id is None:
+            raise ProvablyConfigError("No organisation configured; pass org_id to provably.configure()")
+        return f"/api/v1/organizations/{self.org_id}"
+
+    # ------------------------------------------------------------------
+    # Feedback
+    # ------------------------------------------------------------------
+    async def create_feedback(self, body: dict[str, Any], files: dict[str, Any] | None = None) -> None:
+        """
+        Send a feedback.
+        """
+        path = "/api/v1/feedback"
+
+        await get_http().post_multipart(path, body, files=files)
+        return
+
+    # ------------------------------------------------------------------
+    # Organizations
+    # ------------------------------------------------------------------
+
+    async def list_organizations(self) -> list[dict[str, Any]]:
+        """
+        List all organizations accessible to the authenticated user (via API key).
+
+        Returns:
+            list[dict[str, Any]]: List of organization objects (each contains at least ``id`` and ``name``).
+        """
+        path = "/api/v1/organizations"
+        result: list[dict[str, Any]] = await get_http().get(path)
+        return result
+
+    # ------------------------------------------------------------------
+    # Sandboxes
+    # ------------------------------------------------------------------
+
+    async def create_sandbox(self, org_id: uuid.UUID, *, token: str | None = None) -> dict[str, Any]:
+        """
+        Create a hosted sandbox database for the given organisation.
+
+        Args:
+            org_id: The ID of the organisation that owns the sandbox.
+            token: Optional JWT token for authentication (used during init).
+
+        Returns:
+            dict[str, Any]: Sandbox record with ``status`` and ``connection_uri``.
+        """
+        path = "/api/v1/sandboxes"
+        result: dict[str, Any] = await get_http().post(path, {"org_id": str(org_id)}, token=token)
+        return result
+
+    async def get_sandbox(self, *, token: str | None = None) -> dict[str, Any]:
+        """
+        Retrieve the current sandbox for the authenticated user.
+
+        Args:
+            token: Optional JWT token for authentication (used during init).
+
+        Returns:
+            dict[str, Any]: Sandbox record with ``status`` and ``connection_uri``.
+        """
+        path = "/api/v1/sandboxes"
+        result: dict[str, Any] = await get_http().get(path, token=token)
+        return result
+
+    async def delete_sandbox(self, *, token: str | None = None) -> None:
+        """
+        Delete the sandbox for the authenticated user.
+
+        Args:
+            token: Optional JWT token for authentication (used during init).
+        """
+        path = "/api/v1/sandboxes"
+        await get_http().delete(path, token=token)
+
+    # ------------------------------------------------------------------
+    # Middlewares
+    # ------------------------------------------------------------------
+
+    async def create_middleware(self) -> dict[str, Any]:
+        """
+        Create the Provably middleware for the configured org.
+
+        Returns:
+            dict[str, Any]: The raw JSON response from the API.
+        """
+        path = f"{self._org_path()}/middlewares/provably"
+
+        result: dict[str, Any] = await get_http().post(path)
+        return result
+
+    async def list_middlewares(self) -> list[dict[str, Any]]:
+        """
+        List all middlewares.
+
+        Returns:
+            Any: The raw JSON response from the API.
+        """
+        path = f"{self._org_path()}/middlewares"
+
+        result: list[dict[str, Any]] = await get_http().get(path)
+        return result
+
+    # ------------------------------------------------------------------
+    # Databases
+    # ------------------------------------------------------------------
+
+    async def create_database(self, middleware_id: uuid.UUID, body: dict[str, Any]) -> dict[str, Any]:
+        """
+        Onboard a database to a middleware.
+
+        Args:
+            middleware_id: The ID of the middleware to attach the database to.
+            body: The database connection payload.
+
+        Returns:
+            httpx.Response: The raw HTTP response from the API.
+        """
+        path = f"{self._org_path()}/middlewares/{middleware_id}/databases"
+
+        result: dict[str, Any] = await get_http().post(path, body)
+        return result
+
+    async def list_databases(self, middleware_id: uuid.UUID) -> list[dict[str, Any]]:
+        """
+        List all databases attached to a middleware.
+
+        Args:
+            middleware_id: The ID of the middleware to query.
+
+        Returns:
+            Any: The raw JSON response from the API.
+        """
+        path = f"{self._org_path()}/middlewares/{middleware_id}/databases"
+
+        result: list[dict[str, Any]] = await get_http().get(path)
+        return result
+
+    # ------------------------------------------------------------------
+    # Schemas / Tables / Columns
+    # ------------------------------------------------------------------
+
+    async def list_columns_from_database(
+        self,
+        middleware_id: uuid.UUID,
+        database_id: uuid.UUID,
+        schema_id: uuid.UUID,
+        table_id: uuid.UUID,
+    ) -> list[dict[str, Any]]:
+        """
+        List all columns in a table.
+
+        Args:
+            middleware_id: The ID of the middleware owning the database.
+            database_id: The ID of the database containing the schema.
+            schema_id: The ID of the schema containing the table.
+            table_id: The ID of the table to inspect.
+
+        Returns:
+            list[dict[str, Any]]: The raw JSON response from the API.
+        """
+        path = (
+            f"{self._org_path()}/middlewares/{middleware_id}"
+            f"/databases/{database_id}/schemas/{schema_id}/tables/{table_id}/columns"
+        )
+        result: list[dict[str, Any]] = await get_http().get(path)
+        return result
+
+    # ------------------------------------------------------------------
+    # Data
+    # ------------------------------------------------------------------
+
+    async def get_data(self) -> dict[str, Any]:
+        """
+        Retrieve data for the configured org.
+
+        Returns:
+            dict[str, Any]: The raw JSON response from the API.
+        """
+        path = f"{self._org_path()}/data"
+        result: dict[str, Any] = await get_http().get(path)
+        return result
+
+    # ------------------------------------------------------------------
+    # Collections
+    # ------------------------------------------------------------------
+
+    async def list_collections(self) -> list[dict[str, Any]]:
+        """
+        List all collections for the configured org.
+
+        Returns:
+            list[dict[str, Any]]: The raw JSON response from the API.
+        """
+        path = f"{self._org_path()}/collections"
+        result: list[dict[str, Any]] = await get_http().get(path)
+        return result
+
+    async def create_collection(self, body: dict[str, Any]) -> dict[str, Any]:
+        """
+        Create a new collection for the configured org.
+
+        Args:
+            body: The collection creation payload.
+
+        Returns:
+            httpx.Response: The raw HTTP response from the API.
+        """
+        path = f"{self._org_path()}/collections"
+
+        result: dict[str, Any] = await get_http().post(path, body)
+        return result
+
+    # ------------------------------------------------------------------
+    # Integrations
+    # ------------------------------------------------------------------
+
+    async def ensure_integration(self, body: dict[str, Any]) -> dict[str, Any]:
+        """
+        Idempotent get-or-create an integration for the configured org.
+
+        Reuses an existing enabled integration with the same name linked to the
+        exact requested collections, returning its full key instead of minting a
+        duplicate.
+
+        Args:
+            body: The integration registration payload.
+
+        Returns:
+            dict[str, Any]: The raw JSON response from the API.
+        """
+        path = f"{self._org_path()}/integrations/ensure"
+
+        result: dict[str, Any] = await get_http().post(path, body)
+        return result
+
+    async def list_integrations(self, query: str | None = None) -> list[dict[str, Any]]:
+        """
+        List all integrations for the configured org.
+
+        Args:
+            query: Optional search string to filter integrations by name.
+
+        Returns:
+            list[dict[str, Any]]: The raw JSON response from the API.
+        """
+        path = f"{self._org_path()}/integrations"
+        params = {"query": query} if query is not None else None
+        result: list[dict[str, Any]] = await get_http().get(path, params=params)
+        return result
+
+    # ------------------------------------------------------------------
+    # Preprocess
+    # ------------------------------------------------------------------
+
+    async def start_preprocess(self, middleware_id: uuid.UUID, table_id: uuid.UUID) -> dict[str, Any]:
+        """
+        Start a preprocessing job for a table.
+
+        Args:
+            middleware_id: The ID of the middleware owning the table.
+            table_id: The ID of the table to preprocess.
+
+        Returns:
+            dict[str, Any]: The raw JSON response from the API.
+        """
+        path = f"{self._org_path()}/middlewares/{middleware_id}/tables/{table_id}/preprocess"
+
+        result: dict[str, Any] = await get_http().post(path, {"force": True})
+        return result
+
+    async def get_preprocess_status(self, middleware_id: uuid.UUID, table_id: uuid.UUID) -> dict[str, Any]:
+        """
+        Get the preprocessing status for a table.
+
+        Args:
+            middleware_id: The ID of the middleware owning the table.
+            table_id: The ID of the table to check.
+
+        Returns:
+            dict[str, Any]: The raw JSON response from the API.
+        """
+        path = f"{self._org_path()}/middlewares/{middleware_id}/tables/{table_id}/preprocess"
+
+        result: dict[str, Any] = await get_http().get(path)
+        return result
+
+    # ------------------------------------------------------------------
+    # Queries / Proofs
+    # ------------------------------------------------------------------
+
+    async def run_query(self, middleware_id: uuid.UUID, collection_id: uuid.UUID, sql: str) -> dict[str, Any]:
+        """
+        Run a SQL query through a middleware and request a proof.
+
+        Args:
+            middleware_id: The ID of the middleware to execute the query against.
+            collection_id: The ID of the collection to associate the query with.
+            sql: The SQL query string to execute.
+
+        Returns:
+            dict[str, Any]: The raw JSON response from the API.
+        """
+        path = f"{self._org_path()}/middlewares/{middleware_id}/query"
+
+        result: dict[str, Any] = await get_http().post(
+            path, {"query": sql, "require_proof": True, "collection_id": str(collection_id)}
+        )
+        return result
+
+    async def get_query(self, query_id: uuid.UUID, *, api_key: str | None = None) -> dict[str, Any]:
+        """
+        Retrieve a query record by ID.
+
+        Args:
+            query_id: The ID of the query to retrieve.
+            api_key: Optional API key override for this request.
+
+        Returns:
+            dict[str, Any]: The raw JSON response from the API.
+        """
+        path = f"{self._org_path()}/queries/{query_id}"
+
+        result: dict[str, Any] = await get_http().get(path, api_key=api_key)
+        return result
+
+    async def get_query_proof(self, proof_id: uuid.UUID, *, api_key: str | None = None) -> bytes:
+        """
+        Download the raw proof data by proof ID.
+
+        Args:
+            proof_id: The ID of the proof to retrieve.
+            api_key: Optional API key override for this request.
+
+        Returns:
+            bytes: The raw proof content.
+        """
+        path = f"{self._generic_path()}/proof_requests/{proof_id}/download"
+
+        return await get_http().get_raw(path, api_key=api_key)
+
+    async def verify_proof(self, query_id: uuid.UUID, *, api_key: str | None = None) -> dict[str, Any]:
+        """
+        Request verification for an existing query proof.
+
+        Args:
+            query_id: The unique identifier of the query whose proof needs
+                verification.
+            api_key: Optional API key override for this request.
+
+        Returns:
+            dict[str, Any]: A response confirming the verification
+                task has been successfully initiated.
+
+        Raises:
+            ProvablyAPIError: If the query does not exist or verification
+                cannot be initiated.
+        """
+        path = f"{self._org_path()}/queries/{query_id}/verify"
+
+        result: dict[str, Any] = await get_http().post(path, {}, api_key=api_key)
+        return result
+
+    # ------------------------------------------------------------------
+    # URL helpers
+    # ------------------------------------------------------------------
+
+    def query_record_url(self, query_record_id: uuid.UUID) -> str:
+        """Provably Data Admin URL for a query record."""
+        if not query_record_id:
+            raise ValueError("query_record_id is required")
+        return f"{self.app}/org/{self.org_id}/query-record/{query_record_id}"
+
+
+@functools.lru_cache(maxsize=1)
+def get_api() -> ProvablyAPI:
+    """Return the shared :class:`ProvablyAPI`, constructed on first call."""
+    return ProvablyAPI()