docforge-sdk 0.1.0__py3-none-any.whl

docforge_sdk/resources/auth.py

@@ -0,0 +1,264 @@
+# ====== Code Summary ======
+# The auth (API-key management) resource. All URL/body logic lives once in the pure _AuthSpecs mixin,
+# so AsyncAuth and SyncAuth have identical public surfaces whose bodies differ ONLY by ``await``. The
+# rotate path preserves the backend's "absent != null" contract by dumping with exclude_unset (see
+# _AuthSpecs._rotate_spec) and only threading through the fields the caller actually set.
+
+# ====== Standard Library Imports ======
+from datetime import datetime
+from types import EllipsisType
+
+# ====== Local Project Imports ======
+from .._requestspec import RequestSpec
+from ..models._shared import KeyPermissions
+from ..models.auth import CreatedKey, CreateKeyRequest, KeyInfo, RotateKeyRequest
+from ._base import AsyncResource, SyncResource, _ResourceMixin
+
+
+class _AuthSpecs(_ResourceMixin):
+    """
+    Pure ``RequestSpec`` builders for the auth endpoints — the single source of URL/body logic.
+
+    Shared verbatim by the async and sync resources so neither ever hand-rolls a URL or a body dump.
+    """
+
+    _KEYS_PATH = "/auth/keys"
+
+    def _create_spec(self, request: CreateKeyRequest) -> RequestSpec:
+        """
+        Build the spec for creating a key.
+
+        Args:
+            request (CreateKeyRequest): The create-key body.
+
+        Returns:
+            RequestSpec: A POST to the keys collection carrying the full body.
+        """
+        return RequestSpec("POST", self._KEYS_PATH, json=request.model_dump(mode="json"))
+
+    def _list_spec(self) -> RequestSpec:
+        """
+        Build the spec for listing keys.
+
+        Returns:
+            RequestSpec: A GET on the keys collection.
+        """
+        return RequestSpec("GET", self._KEYS_PATH)
+
+    def _revoke_spec(self, key_id: str) -> RequestSpec:
+        """
+        Build the spec for revoking a key.
+
+        Args:
+            key_id (str): The id of the key to revoke.
+
+        Returns:
+            RequestSpec: A DELETE on the key resource.
+        """
+        return RequestSpec("DELETE", f"{self._KEYS_PATH}/{key_id}")
+
+    def _rotate_spec(self, key_id: str, request: RotateKeyRequest) -> RequestSpec:
+        """
+        Build the spec for rotating a key, preserving the "absent != null" body contract.
+
+        The body is dumped with ``exclude_unset=True`` so a field the caller never set is omitted
+        (the backend then clones it from the source key), while an explicitly provided ``None`` is
+        serialised as JSON ``null``.
+
+        Args:
+            key_id (str): The id of the key to rotate.
+            request (RotateKeyRequest): The rotate body carrying only the caller-set fields.
+
+        Returns:
+            RequestSpec: A POST to the key's rotate endpoint with a minimal, intent-preserving body.
+        """
+        return RequestSpec(
+            "POST",
+            f"{self._KEYS_PATH}/{key_id}/rotate",
+            json=request.model_dump(mode="json", exclude_unset=True),
+        )
+
+    @staticmethod
+    def _build_rotate_request(
+        name: str | None | EllipsisType,
+        permissions: KeyPermissions | None | EllipsisType,
+        expires_at: datetime | None | EllipsisType,
+    ) -> RotateKeyRequest:
+        """
+        Build a RotateKeyRequest from only the caller-supplied fields (``...`` = not supplied).
+
+        Using ``model_validate`` on a dict of provided fields sets ``model_fields_set`` to exactly
+        those keys, which is what makes the later ``exclude_unset`` dump omit the untouched ones.
+
+        Args:
+            name (str | None | EllipsisType): New label, or ``...`` to leave unset.
+            permissions (KeyPermissions | None | EllipsisType): New scope, or ``...`` to leave unset.
+            expires_at (datetime | None | EllipsisType): New expiry, or ``...`` to leave unset.
+
+        Returns:
+            RotateKeyRequest: A request whose set fields are exactly the supplied ones.
+        """
+        # 1. Collect only the fields the caller actually passed (Ellipsis means "not supplied").
+        provided: dict[str, object] = {}
+        if name is not ...:
+            provided["name"] = name
+        if permissions is not ...:
+            provided["permissions"] = permissions
+        if expires_at is not ...:
+            provided["expires_at"] = expires_at
+
+        # 2. Validate from the dict so model_fields_set carries exactly the supplied keys.
+        return RotateKeyRequest.model_validate(provided)
+
+
+class AsyncAuth(AsyncResource, _AuthSpecs):
+    """Asynchronous API-key management (create / list / revoke / rotate)."""
+
+    async def create_key(
+        self,
+        name: str,
+        permissions: KeyPermissions | None = None,
+        expires_at: datetime | None = None,
+    ) -> CreatedKey:
+        """
+        Create an API key and return its plaintext exactly once.
+
+        Args:
+            name (str): Human-readable label for the key.
+            permissions (KeyPermissions | None): Scope; ``None`` = full access (root).
+            expires_at (datetime | None): Absolute expiry; ``None`` = never expires.
+
+        Returns:
+            CreatedKey: The key metadata plus the one-time plaintext (never recoverable later).
+        """
+        return await self._transport.request(
+            self._create_spec(
+                CreateKeyRequest(name=name, permissions=permissions, expires_at=expires_at)
+            ),
+            CreatedKey,
+        )
+
+    async def list_keys(self) -> list[KeyInfo]:
+        """
+        List the account's API keys — metadata only, never a secret.
+
+        Returns:
+            list[KeyInfo]: Every key with its revocation state.
+        """
+        return await self._transport.request(self._list_spec(), list[KeyInfo])
+
+    async def revoke_key(self, key_id: str) -> None:
+        """
+        Soft-revoke an API key (idempotent).
+
+        Args:
+            key_id (str): The id of the key to revoke.
+        """
+        return await self._transport.request(self._revoke_spec(key_id), type(None))
+
+    async def rotate_key(
+        self,
+        key_id: str,
+        name: str | None | EllipsisType = ...,
+        permissions: KeyPermissions | None | EllipsisType = ...,
+        expires_at: datetime | None | EllipsisType = ...,
+    ) -> CreatedKey:
+        """
+        Rotate an API key: issue a fresh secret (optionally re-scoped) and revoke the old one.
+
+        Only the arguments you pass are sent; an omitted argument (left as ``...``) is cloned from the
+        source key by the backend, while an explicit ``None`` sets that field to its null meaning
+        (full access / never expires).
+
+        Args:
+            key_id (str): The active key to rotate.
+            name (str | None | EllipsisType): New label; omit to keep the source name.
+            permissions (KeyPermissions | None | EllipsisType): New scope; omit to keep, ``None`` for
+                full access.
+            expires_at (datetime | None | EllipsisType): New expiry; omit to keep, ``None`` for never.
+
+        Returns:
+            CreatedKey: The replacement key metadata plus its one-time plaintext.
+        """
+        return await self._transport.request(
+            self._rotate_spec(key_id, self._build_rotate_request(name, permissions, expires_at)),
+            CreatedKey,
+        )
+
+
+class SyncAuth(SyncResource, _AuthSpecs):
+    """Synchronous API-key management (create / list / revoke / rotate)."""
+
+    def create_key(
+        self,
+        name: str,
+        permissions: KeyPermissions | None = None,
+        expires_at: datetime | None = None,
+    ) -> CreatedKey:
+        """
+        Create an API key and return its plaintext exactly once.
+
+        Args:
+            name (str): Human-readable label for the key.
+            permissions (KeyPermissions | None): Scope; ``None`` = full access (root).
+            expires_at (datetime | None): Absolute expiry; ``None`` = never expires.
+
+        Returns:
+            CreatedKey: The key metadata plus the one-time plaintext (never recoverable later).
+        """
+        return self._transport.request(
+            self._create_spec(
+                CreateKeyRequest(name=name, permissions=permissions, expires_at=expires_at)
+            ),
+            CreatedKey,
+        )
+
+    def list_keys(self) -> list[KeyInfo]:
+        """
+        List the account's API keys — metadata only, never a secret.
+
+        Returns:
+            list[KeyInfo]: Every key with its revocation state.
+        """
+        return self._transport.request(self._list_spec(), list[KeyInfo])
+
+    def revoke_key(self, key_id: str) -> None:
+        """
+        Soft-revoke an API key (idempotent).
+
+        Args:
+            key_id (str): The id of the key to revoke.
+        """
+        return self._transport.request(self._revoke_spec(key_id), type(None))
+
+    def rotate_key(
+        self,
+        key_id: str,
+        name: str | None | EllipsisType = ...,
+        permissions: KeyPermissions | None | EllipsisType = ...,
+        expires_at: datetime | None | EllipsisType = ...,
+    ) -> CreatedKey:
+        """
+        Rotate an API key: issue a fresh secret (optionally re-scoped) and revoke the old one.
+
+        Only the arguments you pass are sent; an omitted argument (left as ``...``) is cloned from the
+        source key by the backend, while an explicit ``None`` sets that field to its null meaning
+        (full access / never expires).
+
+        Args:
+            key_id (str): The active key to rotate.
+            name (str | None | EllipsisType): New label; omit to keep the source name.
+            permissions (KeyPermissions | None | EllipsisType): New scope; omit to keep, ``None`` for
+                full access.
+            expires_at (datetime | None | EllipsisType): New expiry; omit to keep, ``None`` for never.
+
+        Returns:
+            CreatedKey: The replacement key metadata plus its one-time plaintext.
+        """
+        return self._transport.request(
+            self._rotate_spec(key_id, self._build_rotate_request(name, permissions, expires_at)),
+            CreatedKey,
+        )
+
+
+__all__ = ["AsyncAuth", "SyncAuth"]

docforge_sdk/resources/blobs.py

@@ -0,0 +1,63 @@
+# ====== Code Summary ======
+# The blobs resource — fetch a content-addressed blob's raw bytes with its registered mime type. The
+# endpoint streams bytes (not JSON), so both shells route through the transport's get_bytes_typed
+# helper and wrap its (bytes, mime) pair into a BlobContent. Path logic lives once in _BlobsSpecs.
+
+# ====== Local Project Imports ======
+from ..models.blobs import BlobContent
+from ._base import AsyncResource, SyncResource, _ResourceMixin
+
+
+class _BlobsSpecs(_ResourceMixin):
+    """Pure path builder for the blobs endpoint — the single source of URL logic."""
+
+    _BLOBS_PATH = "/blobs"
+
+    def _blob_path(self, content_hash: str) -> str:
+        """
+        Build the API-relative path for a content-addressed blob.
+
+        Args:
+            content_hash (str): The blob's content hash (its key).
+
+        Returns:
+            str: The path to the blob resource.
+        """
+        return f"{self._BLOBS_PATH}/{content_hash}"
+
+
+class AsyncBlobs(AsyncResource, _BlobsSpecs):
+    """Asynchronous content-addressed blob fetch."""
+
+    async def get(self, content_hash: str) -> BlobContent:
+        """
+        Fetch a blob's raw bytes and its server-registered media type.
+
+        Args:
+            content_hash (str): The blob's content hash (its key).
+
+        Returns:
+            BlobContent: The raw bytes paired with the registered mime type.
+        """
+        content, mime_type = await self._transport.get_bytes_typed(self._blob_path(content_hash))
+        return BlobContent(content=content, mime_type=mime_type)
+
+
+class SyncBlobs(SyncResource, _BlobsSpecs):
+    """Synchronous content-addressed blob fetch."""
+
+    def get(self, content_hash: str) -> BlobContent:
+        """
+        Fetch a blob's raw bytes and its server-registered media type.
+
+        Args:
+            content_hash (str): The blob's content hash (its key).
+
+        Returns:
+            BlobContent: The raw bytes paired with the registered mime type.
+        """
+        content, mime_type = self._transport.get_bytes_typed(self._blob_path(content_hash))
+        return BlobContent(content=content, mime_type=mime_type)
+
+
+__all__ = ["AsyncBlobs", "SyncBlobs"]

docforge_sdk/resources/collections.py

@@ -0,0 +1,204 @@
+# ====== Code Summary ======
+# The collections resource (CRUD over a collection's full contract). All URL/body logic lives once in
+# the pure _CollectionsSpecs mixin, so AsyncCollections and SyncCollections have identical public
+# surfaces whose bodies differ ONLY by ``await``.
+
+# ====== Local Project Imports ======
+from .._requestspec import RequestSpec
+from ..models.collections import (
+    CollectionModel,
+    CreateCollectionRequest,
+    UpdateCollectionRequest,
+)
+from ._base import AsyncResource, SyncResource, _ResourceMixin
+
+
+class _CollectionsSpecs(_ResourceMixin):
+    """Pure ``RequestSpec`` builders for the collections endpoints — the single source of URL/body logic."""
+
+    _COLLECTIONS_PATH = "/collections"
+
+    def _list_spec(self) -> RequestSpec:
+        """
+        Build the spec for listing collections.
+
+        Returns:
+            RequestSpec: A GET on the collections collection.
+        """
+        return RequestSpec("GET", self._COLLECTIONS_PATH)
+
+    def _get_spec(self, collection_id: str) -> RequestSpec:
+        """
+        Build the spec for fetching one collection.
+
+        Args:
+            collection_id (str): The collection's UUID.
+
+        Returns:
+            RequestSpec: A GET on the collection resource.
+        """
+        return RequestSpec("GET", f"{self._COLLECTIONS_PATH}/{collection_id}")
+
+    def _create_spec(self, request: CreateCollectionRequest) -> RequestSpec:
+        """
+        Build the spec for creating a collection.
+
+        Args:
+            request (CreateCollectionRequest): The create body (contract + schema + pipeline).
+
+        Returns:
+            RequestSpec: A POST to the collections collection carrying the full body.
+        """
+        return RequestSpec("POST", self._COLLECTIONS_PATH, json=request.model_dump(mode="json"))
+
+    def _update_spec(self, collection_id: str, request: UpdateCollectionRequest) -> RequestSpec:
+        """
+        Build the spec for patching a collection, sending only the caller-set fields.
+
+        Args:
+            collection_id (str): The collection to patch.
+            request (UpdateCollectionRequest): The patch body (partial by design).
+
+        Returns:
+            RequestSpec: A PATCH on the collection resource with a minimal body.
+        """
+        return RequestSpec(
+            "PATCH",
+            f"{self._COLLECTIONS_PATH}/{collection_id}",
+            json=request.model_dump(mode="json", exclude_unset=True),
+        )
+
+    def _delete_spec(self, collection_id: str) -> RequestSpec:
+        """
+        Build the spec for deleting a collection.
+
+        Args:
+            collection_id (str): The collection to delete.
+
+        Returns:
+            RequestSpec: A DELETE on the collection resource.
+        """
+        return RequestSpec("DELETE", f"{self._COLLECTIONS_PATH}/{collection_id}")
+
+
+class AsyncCollections(AsyncResource, _CollectionsSpecs):
+    """Asynchronous collection management (list / get / create / update / delete)."""
+
+    async def list(self) -> list[CollectionModel]:
+        """
+        List every collection with its full schema.
+
+        Returns:
+            list[CollectionModel]: All contracts, schema included.
+        """
+        return await self._transport.request(self._list_spec(), list[CollectionModel])
+
+    async def get(self, collection_id: str) -> CollectionModel:
+        """
+        Fetch one collection's full contract.
+
+        Args:
+            collection_id (str): The collection's UUID.
+
+        Returns:
+            CollectionModel: Identity, limits, schema and config blobs.
+        """
+        return await self._transport.request(self._get_spec(collection_id), CollectionModel)
+
+    async def create(self, request: CreateCollectionRequest) -> CollectionModel:
+        """
+        Create a collection from its contract, schema and (optional) pipeline.
+
+        Args:
+            request (CreateCollectionRequest): The create body.
+
+        Returns:
+            CollectionModel: The created contract.
+        """
+        return await self._transport.request(self._create_spec(request), CollectionModel)
+
+    async def update(self, collection_id: str, request: UpdateCollectionRequest) -> CollectionModel:
+        """
+        Patch identity/limits, the metadata schema and/or the config blobs.
+
+        Args:
+            collection_id (str): The collection to patch.
+            request (UpdateCollectionRequest): The partial patch body.
+
+        Returns:
+            CollectionModel: The updated contract.
+        """
+        return await self._transport.request(
+            self._update_spec(collection_id, request), CollectionModel
+        )
+
+    async def delete(self, collection_id: str) -> None:
+        """
+        Delete a collection.
+
+        Args:
+            collection_id (str): The collection to delete.
+        """
+        return await self._transport.request(self._delete_spec(collection_id), type(None))
+
+
+class SyncCollections(SyncResource, _CollectionsSpecs):
+    """Synchronous collection management (list / get / create / update / delete)."""
+
+    def list(self) -> list[CollectionModel]:
+        """
+        List every collection with its full schema.
+
+        Returns:
+            list[CollectionModel]: All contracts, schema included.
+        """
+        return self._transport.request(self._list_spec(), list[CollectionModel])
+
+    def get(self, collection_id: str) -> CollectionModel:
+        """
+        Fetch one collection's full contract.
+
+        Args:
+            collection_id (str): The collection's UUID.
+
+        Returns:
+            CollectionModel: Identity, limits, schema and config blobs.
+        """
+        return self._transport.request(self._get_spec(collection_id), CollectionModel)
+
+    def create(self, request: CreateCollectionRequest) -> CollectionModel:
+        """
+        Create a collection from its contract, schema and (optional) pipeline.
+
+        Args:
+            request (CreateCollectionRequest): The create body.
+
+        Returns:
+            CollectionModel: The created contract.
+        """
+        return self._transport.request(self._create_spec(request), CollectionModel)
+
+    def update(self, collection_id: str, request: UpdateCollectionRequest) -> CollectionModel:
+        """
+        Patch identity/limits, the metadata schema and/or the config blobs.
+
+        Args:
+            collection_id (str): The collection to patch.
+            request (UpdateCollectionRequest): The partial patch body.
+
+        Returns:
+            CollectionModel: The updated contract.
+        """
+        return self._transport.request(self._update_spec(collection_id, request), CollectionModel)
+
+    def delete(self, collection_id: str) -> None:
+        """
+        Delete a collection.
+
+        Args:
+            collection_id (str): The collection to delete.
+        """
+        return self._transport.request(self._delete_spec(collection_id), type(None))
+
+
+__all__ = ["AsyncCollections", "SyncCollections"]

docforge_sdk/resources/documents.py

@@ -0,0 +1,153 @@
+# ====== Code Summary ======
+# The documents resource: multipart upload (admission) and the searchability toggle. Upload routes
+# through the transport's multipart helper; the toggle is a plain PATCH. All URL/body/multipart logic
+# lives once in the pure _DocumentsSpecs mixin so the async/sync shells differ ONLY by ``await``.
+
+# ====== Standard Library Imports ======
+import json
+from pathlib import Path
+from typing import Any
+
+# ====== Local Project Imports ======
+from .._requestspec import RequestSpec
+from ..models.documents import DocumentEnabledResponse, EnabledPatch, UploadAccepted
+from ._base import AsyncResource, SyncResource, _ResourceMixin
+
+
+class _DocumentsSpecs(_ResourceMixin):
+    """Pure request builders for the documents endpoints — the single source of URL/body/multipart logic."""
+
+    _DOCUMENTS_PATH = "/documents"
+
+    @staticmethod
+    def _upload_parts(
+        collection_id: str,
+        file: str | Path | bytes,
+        metadata: dict[str, Any] | None,
+        filename: str | None,
+    ) -> tuple[dict[str, Any], dict[str, str]]:
+        """
+        Build the multipart ``files`` and ``data`` parts of an upload from a path or raw bytes.
+
+        Args:
+            collection_id (str): The target collection's UUID.
+            file (str | Path | bytes): A local file path or the raw bytes to ingest.
+            metadata (dict[str, Any] | None): Declared metadata; serialised to the JSON form field.
+            filename (str | None): Override name; defaults to the path's name, else ``"upload"``.
+
+        Returns:
+            tuple[dict[str, Any], dict[str, str]]: The httpx ``files`` mapping and the form ``data``.
+        """
+        # 1. Resolve raw bytes + a filename from either a local path or in-memory bytes.
+        if isinstance(file, bytes):
+            content, resolved_name = file, (filename or "upload")
+        else:
+            path = Path(file)
+            content, resolved_name = path.read_bytes(), (filename or path.name)
+
+        # 2. Assemble the multipart file part and the accompanying form fields.
+        files = {"file": (resolved_name, content)}
+        data = {"collection_id": collection_id, "metadata": json.dumps(metadata or {})}
+        return files, data
+
+    def _set_enabled_spec(self, document_id: str, enabled: bool) -> RequestSpec:
+        """
+        Build the spec for toggling a document's searchability.
+
+        Args:
+            document_id (str): The document to toggle.
+            enabled (bool): The desired searchability state.
+
+        Returns:
+            RequestSpec: A PATCH on the document's ``/enabled`` sub-resource.
+        """
+        return RequestSpec(
+            "PATCH",
+            f"{self._DOCUMENTS_PATH}/{document_id}/enabled",
+            json=EnabledPatch(enabled=enabled).model_dump(mode="json"),
+        )
+
+
+class AsyncDocuments(AsyncResource, _DocumentsSpecs):
+    """Asynchronous document admission and searchability control."""
+
+    async def upload(
+        self,
+        collection_id: str,
+        file: str | Path | bytes,
+        metadata: dict[str, Any] | None = None,
+        filename: str | None = None,
+    ) -> UploadAccepted:
+        """
+        Upload a document for asynchronous ingestion.
+
+        Args:
+            collection_id (str): The target collection's UUID.
+            file (str | Path | bytes): A local file path or the raw bytes to ingest.
+            metadata (dict[str, Any] | None): Declared metadata (field → value).
+            filename (str | None): Override name; defaults to the path's name, else ``"upload"``.
+
+        Returns:
+            UploadAccepted: The admitted document id, its ingestion job id and the duplicate flag.
+        """
+        files, data = self._upload_parts(collection_id, file, metadata, filename)
+        return await self._transport.upload(self._DOCUMENTS_PATH, files, data, UploadAccepted)
+
+    async def set_enabled(self, document_id: str, enabled: bool) -> DocumentEnabledResponse:
+        """
+        Toggle a document's searchability (hides or reveals all its chunks).
+
+        Args:
+            document_id (str): The document to toggle.
+            enabled (bool): True to make searchable, False to hide from search.
+
+        Returns:
+            DocumentEnabledResponse: The document id and its new searchability state.
+        """
+        return await self._transport.request(
+            self._set_enabled_spec(document_id, enabled), DocumentEnabledResponse
+        )
+
+
+class SyncDocuments(SyncResource, _DocumentsSpecs):
+    """Synchronous document admission and searchability control."""
+
+    def upload(
+        self,
+        collection_id: str,
+        file: str | Path | bytes,
+        metadata: dict[str, Any] | None = None,
+        filename: str | None = None,
+    ) -> UploadAccepted:
+        """
+        Upload a document for asynchronous ingestion.
+
+        Args:
+            collection_id (str): The target collection's UUID.
+            file (str | Path | bytes): A local file path or the raw bytes to ingest.
+            metadata (dict[str, Any] | None): Declared metadata (field → value).
+            filename (str | None): Override name; defaults to the path's name, else ``"upload"``.
+
+        Returns:
+            UploadAccepted: The admitted document id, its ingestion job id and the duplicate flag.
+        """
+        files, data = self._upload_parts(collection_id, file, metadata, filename)
+        return self._transport.upload(self._DOCUMENTS_PATH, files, data, UploadAccepted)
+
+    def set_enabled(self, document_id: str, enabled: bool) -> DocumentEnabledResponse:
+        """
+        Toggle a document's searchability (hides or reveals all its chunks).
+
+        Args:
+            document_id (str): The document to toggle.
+            enabled (bool): True to make searchable, False to hide from search.
+
+        Returns:
+            DocumentEnabledResponse: The document id and its new searchability state.
+        """
+        return self._transport.request(
+            self._set_enabled_spec(document_id, enabled), DocumentEnabledResponse
+        )
+
+
+__all__ = ["AsyncDocuments", "SyncDocuments"]