unique-sdk 2026.20.0.dev4__tar.gz → 2026.20.0.dev6__tar.gz

{unique_sdk-2026.20.0.dev4 → unique_sdk-2026.20.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.20.0.dev4
+Version: 2026.20.0.dev6
 Summary: 
 Author: Martin Fadler, Konstantin Krauss, Andreas Hauri
 Author-email: Martin Fadler <martin.fadler@unique.ch>, Konstantin Krauss <konstantin@unique.ch>, Andreas Hauri <andreas@unique.ch>

{unique_sdk-2026.20.0.dev4 → unique_sdk-2026.20.0.dev6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_sdk"
-version = "2026.20.0.dev4"
+version = "2026.20.0.dev6"
 description = ""
 readme = "README.md"
 license = { text = "MIT" }

{unique_sdk-2026.20.0.dev4 → unique_sdk-2026.20.0.dev6}/unique_sdk/__init__.py

@@ -101,6 +101,7 @@ from unique_sdk.api_resources._benchmarking import (
     Benchmarking as Benchmarking,
 )
 from unique_sdk.api_resources._scheduled_task import ScheduledTask as ScheduledTask
+from unique_sdk.api_resources._module import Module as Module
 
 # Unique QL
 from unique_sdk._unique_ql import UQLOperator as UQLOperator

unique_sdk-2026.20.0.dev6/unique_sdk/api_resources/_module.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import builtins
+from typing import Any, Literal, NotRequired, TypedDict, Unpack, cast
+from urllib.parse import quote_plus
+
+from unique_sdk._api_resource import APIResource
+from unique_sdk._request_options import RequestOptions
+from unique_sdk._util import classproperty
+
+
+class Module(APIResource["Module"]):
+    """An assistant module that configures behaviour, tools, and instructions.
+
+    Modules are attached to assistants (spaces) and define their capabilities,
+    configuration, and tool definitions.  They control weight/priority, whether
+    the module is external, and whether custom instructions are enabled.
+    """
+
+    @classproperty
+    def OBJECT_NAME(cls) -> Literal["module"]:
+        return "module"
+
+    RESOURCE_URL = "/modules"
+
+    @classmethod
+    def class_url(cls) -> str:
+        return cls.RESOURCE_URL
+
+    class ListParams(RequestOptions):
+        assistantId: NotRequired[str | None]
+
+    class CreateParams(RequestOptions):
+        assistantId: str
+        name: str
+        description: NotRequired[str | None]
+        weight: NotRequired[int | None]
+        isExternal: NotRequired[bool | None]
+        isCustomInstructionEnabled: NotRequired[bool | None]
+        configuration: NotRequired[dict[str, Any] | None]
+        toolDefinition: NotRequired[dict[str, Any] | None]
+        moduleTemplateId: NotRequired[str | None]
+
+    class ModifyParams(RequestOptions):
+        name: NotRequired[str | None]
+        description: NotRequired[str | None]
+        weight: NotRequired[int | None]
+        isExternal: NotRequired[bool | None]
+        isCustomInstructionEnabled: NotRequired[bool | None]
+        configuration: NotRequired[dict[str, Any] | None]
+        toolDefinition: NotRequired[dict[str, Any] | None]
+
+    class DeletedObject(TypedDict):
+        id: str
+        object: str
+        deleted: bool
+
+    id: str
+    name: str
+    description: str | None
+    toolDefinition: dict[str, Any] | None
+    configuration: dict[str, Any] | None
+    assistantId: str
+    weight: int | None
+    isExternal: bool
+    isCustomInstructionEnabled: bool
+    moduleTemplateId: str | None
+    createdAt: str
+    updatedAt: str
+
+    @classmethod
+    def list(
+        cls,
+        *,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Module.ListParams"],
+    ) -> builtins.list["Module"]:
+        result = cls._static_request(
+            "get",
+            cls.RESOURCE_URL,
+            user_id,
+            company_id,
+            params or None,
+        )
+        if isinstance(result, builtins.list):
+            data = result
+        else:
+            data = result.get("data", []) if hasattr(result, "get") else []
+        return cast(builtins.list["Module"], data)
+
+    @classmethod
+    async def list_async(
+        cls,
+        *,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Module.ListParams"],
+    ) -> builtins.list["Module"]:
+        result = await cls._static_request_async(
+            "get",
+            cls.RESOURCE_URL,
+            user_id,
+            company_id,
+            params or None,
+        )
+        if isinstance(result, builtins.list):
+            data = result
+        else:
+            data = result.get("data", []) if hasattr(result, "get") else []
+        return cast(builtins.list["Module"], data)
+
+    @classmethod
+    def retrieve(
+        cls,
+        *,
+        user_id: str,
+        company_id: str,
+        id: str,
+    ) -> "Module":
+        url = "%s/%s" % (cls.RESOURCE_URL, quote_plus(id))
+        return cast(
+            "Module",
+            cls._static_request("get", url, user_id, company_id),
+        )
+
+    @classmethod
+    async def retrieve_async(
+        cls,
+        *,
+        user_id: str,
+        company_id: str,
+        id: str,
+    ) -> "Module":
+        url = "%s/%s" % (cls.RESOURCE_URL, quote_plus(id))
+        return cast(
+            "Module",
+            await cls._static_request_async("get", url, user_id, company_id),
+        )
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Module.CreateParams"],
+    ) -> "Module":
+        return cast(
+            "Module",
+            cls._static_request(
+                "post",
+                cls.RESOURCE_URL,
+                user_id,
+                company_id,
+                params,
+            ),
+        )
+
+    @classmethod
+    async def create_async(
+        cls,
+        *,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Module.CreateParams"],
+    ) -> "Module":
+        return cast(
+            "Module",
+            await cls._static_request_async(
+                "post",
+                cls.RESOURCE_URL,
+                user_id,
+                company_id,
+                params,
+            ),
+        )
+
+    @classmethod
+    def modify(
+        cls,
+        *,
+        user_id: str,
+        company_id: str,
+        id: str,
+        **params: Unpack["Module.ModifyParams"],
+    ) -> "Module":
+        url = "%s/%s" % (cls.RESOURCE_URL, quote_plus(id))
+        return cast(
+            "Module",
+            cls._static_request("patch", url, user_id, company_id, params),
+        )
+
+    @classmethod
+    async def modify_async(
+        cls,
+        *,
+        user_id: str,
+        company_id: str,
+        id: str,
+        **params: Unpack["Module.ModifyParams"],
+    ) -> "Module":
+        url = "%s/%s" % (cls.RESOURCE_URL, quote_plus(id))
+        return cast(
+            "Module",
+            await cls._static_request_async("patch", url, user_id, company_id, params),
+        )
+
+    @classmethod
+    def delete(
+        cls,
+        *,
+        user_id: str,
+        company_id: str,
+        id: str,
+    ) -> "Module.DeletedObject":
+        url = "%s/%s" % (cls.RESOURCE_URL, quote_plus(id))
+        return cast(
+            "Module.DeletedObject",
+            cls._static_request("delete", url, user_id, company_id),
+        )
+
+    @classmethod
+    async def delete_async(
+        cls,
+        *,
+        user_id: str,
+        company_id: str,
+        id: str,
+    ) -> "Module.DeletedObject":
+        url = "%s/%s" % (cls.RESOURCE_URL, quote_plus(id))
+        return cast(
+            "Module.DeletedObject",
+            await cls._static_request_async("delete", url, user_id, company_id),
+        )

{unique_sdk-2026.20.0.dev4 → unique_sdk-2026.20.0.dev6}/unique_sdk/utils/file_io.py

@@ -44,17 +44,6 @@ def download_file(url: str, filename: str):
 _PREVIEW_PDF_MIME_TYPE = "application/pdf"
 
 
-def _derive_preview_pdf_filename(displayed_filename: str) -> str:
-    """Return ``<stem>_preview.pdf`` for *displayed_filename*.
-
-    Keeps the preview blob filename predictable and collision-free with
-    the original (which has the user-visible extension), while still
-    making it obvious in storage which content the preview belongs to.
-    """
-    stem = displayed_filename.rsplit(".", 1)[0] or displayed_filename
-    return f"{stem}_preview.pdf"
-
-
 def _put_preview_pdf(write_url: str, preview_pdf_path: str) -> None:
     """PUT *preview_pdf_path* bytes to the SAS URL returned by upsert."""
     with open(preview_pdf_path, "rb") as preview_file:
@@ -85,17 +74,25 @@ def upload_file(
     ingestion_config: Content.IngestionConfig | None = None,
     metadata: dict[str, Any] | None = None,
     preview_pdf_path: str | None = None,
-    preview_pdf_filename: str | None = None,
 ):
     """Upload *path_to_file* as a Unique :class:`Content`.
 
     When ``preview_pdf_path`` is provided, the caller gets a single-call
-    Office → PDF preview flow: we attach a ``previewPdfFileName`` to the
-    upserted content (so the platform mints a ``pdfPreviewWriteUrl``),
-    PUT the original blob, then PUT the PDF preview blob. The chat side
-    panel will pick the preview up automatically when rendering
-    PowerPoint / Word / similar formats whose in-browser preview is
-    unreliable.
+    Office → PDF preview flow: the SDK does a two-upsert handshake — a
+    first upsert to obtain the content id, then a finalize upsert that
+    registers ``previewPdfFileName = f"{content.id}_pdfPreview"`` on
+    the row and mints a ``pdfPreviewWriteUrl`` SAS URL the SDK PUTs the
+    PDF bytes to.
+
+    Naming the preview blob ``${content.id}_pdfPreview`` matches the
+    convention used by the platform's ingestion worker
+    (``next/services/node-ingestion-worker/src/pdf-preview-converter/pdf-preview-converter.service.ts``)
+    and is collision-free across uploads sharing a ``displayed_filename``
+    because content ids are globally unique. The platform stores the
+    ``previewPdfFileName`` value verbatim — collision-free naming is a
+    client contract, not a server invariant — so every client of
+    node-ingestion (workers, SDKs, integrations) MUST follow this
+    convention.
 
     Args:
         userId: Acting user id.
@@ -112,15 +109,14 @@ def upload_file(
         metadata: Free-form metadata.
         preview_pdf_path: Optional path to a sibling PDF that should be
             rendered as the side-panel preview for this content. When
-            set, the upsert registers ``previewPdfFileName`` on the row
-            and the PDF bytes are PUT to ``pdfPreviewWriteUrl`` after the
-            original upload.
-        preview_pdf_filename: Optional override for the blob filename
-            stored against ``previewPdfFileName``. Defaults to
-            ``<displayed_filename without extension>_preview.pdf`` so
-            the preview blob is uniquely identifiable in storage.
+            set, the SDK derives the blob name from the upserted
+            content id, registers it on the row via the finalize
+            upsert, and PUTs the PDF bytes to the SAS URL the server
+            returns in ``pdfPreviewWriteUrl``. Naming is the SDK's
+            responsibility — there is no override kwarg, by design,
+            so all callers land on the same ``${content.id}_pdfPreview``
+            convention as the ingestion worker.
     """
-    # check that chatid or scope_or_unique_path is provided
     if not chat_id and not scope_or_unique_path:
         raise ValueError("chat_id or scope_or_unique_path must be provided")
 
@@ -129,32 +125,13 @@ def upload_file(
             f"preview_pdf_path does not point to a readable file: {preview_pdf_path}"
         )
 
-    # A filename without a path would register a phantom preview on the
-    # Content row (the upsert mints a pdfPreviewWriteUrl, but we never
-    # PUT any bytes), leaving the side panel pointing at a nonexistent
-    # blob. Treat it as a programmer mistake and fail fast.
-    if preview_pdf_filename is not None and preview_pdf_path is None:
-        raise ValueError(
-            "preview_pdf_filename was provided without preview_pdf_path; "
-            "pass the PDF path so the preview blob actually gets uploaded."
-        )
-
     size = os.path.getsize(path_to_file)
-    resolved_preview_filename = (
-        (preview_pdf_filename or _derive_preview_pdf_filename(displayed_filename))
-        if preview_pdf_path is not None
-        else None
-    )
-    # Only forward ``previewPdfFileName`` when we actually have one.
-    # Sending ``None`` would serialize as ``"previewPdfFileName": null``,
-    # which the server treats as a clearing operation and would erase
-    # an existing preview on a re-upload that doesn't ship one.
-    preview_kwargs: _PreviewKwargs = (
-        {"previewPdfFileName": resolved_preview_filename}
-        if resolved_preview_filename is not None
-        else {}
-    )
 
+    # Step 1 — first upsert WITHOUT ``previewPdfFileName``. The id we
+    # need to derive a collision-free preview blob name does not exist
+    # yet; deriving from ``displayed_filename`` instead would race
+    # across uploads sharing the same key (two ``report.pptx`` uploads
+    # in the same company would overwrite each other's preview blob).
     createdContent = Content.upsert(
         user_id=userId,
         company_id=companyId,
@@ -168,12 +145,10 @@ def upload_file(
         },
         scopeId=scope_or_unique_path,
         chatId=chat_id,
-        **preview_kwargs,
     )
 
+    # Step 2 — PUT the original bytes to the SAS URL minted by Step 1.
     uploadUrl = createdContent.writeUrl
-
-    # upload to azure blob storage SAS url uploadUrl the pdf file translatedFile make sure it is treated as a application/pdf
     if uploadUrl is None:  # guard: writeUrl is Optional, basedpyright needs narrowing
         raise ValueError("createdContent.writeUrl is None")
     with open(path_to_file, "rb") as file:
@@ -186,28 +161,24 @@ def upload_file(
             },
         )
 
-    # Attach the optional preview-PDF blob in the same call. We do this
-    # *before* the second upsert so the byteSize patch and the preview
-    # don't race; if the SAS URL is missing we surface a clear error
-    # (the server only mints it when previewPdfFileName is set, so a
-    # missing URL signals a server-side regression).
-    if preview_pdf_path is not None:
-        # ``getattr`` so an older gateway that omits the field falls
-        # through to the RuntimeError below instead of raising the
-        # opaque ``AttributeError`` that ``UniqueObject.__getattr__``
-        # produces on a missing key.
-        preview_write_url = getattr(createdContent, "pdfPreviewWriteUrl", None)
-        if not preview_write_url:
-            raise RuntimeError(
-                "preview_pdf_path was provided but the upsert response carries "
-                "no pdfPreviewWriteUrl — refusing to silently drop the preview. "
-                "Verify the API gateway and node-ingestion expose "
-                "previewPdfFileName on the upsert mutation."
-            )
-        _put_preview_pdf(preview_write_url, preview_pdf_path)
+    # Step 3 — finalize upsert: ``byteSize`` + ``fileUrl`` flip the row
+    # to bytes-on-blob, and (only when we have a preview to attach)
+    # ``previewPdfFileName = f"{content.id}_pdfPreview"`` registers the
+    # preview blob name on the row so the ``pdfPreviewWriteUrl`` field
+    # resolver mints the SAS URL on this response.
+    #
+    # ``previewPdfFileName`` is forwarded as a conditional kwarg rather
+    # than always-set-to-None; serializing ``"previewPdfFileName": null``
+    # would tell the server to clear the field, which would silently
+    # regress an existing-row re-upload that does not attach a preview.
+    preview_kwargs: _PreviewKwargs = (
+        {"previewPdfFileName": f"{createdContent.id}_pdfPreview"}
+        if preview_pdf_path is not None
+        else {}
+    )
 
     if chat_id:
-        unique_sdk.Content.upsert(
+        finalizedContent = unique_sdk.Content.upsert(
             user_id=userId,
             company_id=companyId,
             input={
@@ -224,7 +195,7 @@ def upload_file(
             **preview_kwargs,
         )
     else:
-        unique_sdk.Content.upsert(
+        finalizedContent = unique_sdk.Content.upsert(
             user_id=userId,
             company_id=companyId,
             input={
@@ -241,6 +212,27 @@ def upload_file(
             **preview_kwargs,
         )
 
+    # Step 4 — PUT the preview bytes (if requested). The SAS URL comes
+    # from the FINALIZE response, not the first one, because the first
+    # upsert did not carry ``previewPdfFileName`` and so could not have
+    # minted ``pdfPreviewWriteUrl``.
+    #
+    # ``getattr`` so an older gateway that omits the field falls
+    # through to the descriptive ``RuntimeError`` below instead of the
+    # opaque ``AttributeError`` that ``UniqueObject.__getattr__`` would
+    # otherwise raise on a missing key.
+    if preview_pdf_path is not None:
+        preview_write_url = getattr(finalizedContent, "pdfPreviewWriteUrl", None)
+        if not preview_write_url:
+            raise RuntimeError(
+                "preview_pdf_path was provided but the finalize upsert "
+                "response carries no pdfPreviewWriteUrl — refusing to "
+                "silently drop the preview. Verify the API gateway and "
+                "node-ingestion expose previewPdfFileName on the upsert "
+                "mutation."
+            )
+        _put_preview_pdf(preview_write_url, preview_pdf_path)
+
     return createdContent