unique-sdk 2026.30.0.dev8__tar.gz → 2026.30.0.dev10__tar.gz

{unique_sdk-2026.30.0.dev8 → unique_sdk-2026.30.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.30.0.dev8
+Version: 2026.30.0.dev10
 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.30.0.dev8 → unique_sdk-2026.30.0.dev10}/pyproject.toml

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

{unique_sdk-2026.30.0.dev8 → unique_sdk-2026.30.0.dev10}/unique_sdk/__init__.py

@@ -136,7 +136,11 @@ from .api_resources._agentic_table import (
     AgreementStatus as AgreementStatus,
     RowVerificationStatus as RowVerificationStatus,
     MagicTableAction as MagicTableAction,
+    MagicTableActionResult as MagicTableActionResult,
     MagicTableActivityResponse as MagicTableActivityResponse,
+    MagicTableArtifact as MagicTableArtifact,
+    MagicTableArtifactState as MagicTableArtifactState,
     MagicTableArtifactType as MagicTableArtifactType,
     MagicTableMetadataEntry as MagicTableMetadataEntry,
+    CreatedAgenticTableSheet as CreatedAgenticTableSheet,
 )

{unique_sdk-2026.30.0.dev8 → unique_sdk-2026.30.0.dev10}/unique_sdk/api_resources/_agentic_table.py

@@ -102,6 +102,14 @@ class MagicTableArtifactType(StrEnum):
     AGENTIC_REPORT = "AGENTIC_REPORT"
 
 
+class MagicTableArtifactState(StrEnum):
+    """Artifact generation state (matches `MagicTableArtifactState`)."""
+
+    IN_PROGRESS = "IN_PROGRESS"
+    DONE = "DONE"
+    ERROR = "ERROR"
+
+
 class MagicTableMetadataEntry(TypedDict, total=False):
     """Row or sheet metadata entry as returned by the public magic-table API."""
 
@@ -146,6 +154,54 @@ class MagicTableActivityResponse(TypedDict):
     status: bool
 
 
+class MagicTableActionResult(TypedDict, total=False):
+    """Generic `{status, message?}` response from lifecycle mutations (import, generate-artifact, sheet metadata writes)."""
+
+    status: bool
+    message: str | None
+
+
+class _CreatedAgenticTableSheetRequired(TypedDict):
+    sheetId: str
+    dueDiligenceId: str
+    name: str
+    state: AgenticTableSheetState
+    createdBy: str
+    companyId: str
+    createdAt: str
+
+
+class CreatedAgenticTableSheet(_CreatedAgenticTableSheetRequired, total=False):
+    """Response body from `POST /magic-table` (create sheet)."""
+
+    chatId: str | None
+    dueAt: str | None
+
+
+class MagicTableArtifact(TypedDict, total=False):
+    """Artifact entry from `GET /magic-table/{tableId}/artifacts`.
+
+    ``contentId`` is only present once ``artifactState`` is ``DONE``; download the
+    file via the Content API.
+    """
+
+    id: str
+    name: str | None
+    contentId: str | None
+    mimeType: str | None
+    artifactType: MagicTableArtifactType
+    artifactState: MagicTableArtifactState
+    createdAt: str
+    updatedAt: str
+
+
+class MagicTableArtifactList(TypedDict):
+    """List envelope returned by `GET /magic-table/{tableId}/artifacts` (`{object: "list", data: [...]}`)."""
+
+    object: Literal["list"]
+    data: list[MagicTableArtifact]
+
+
 class _AgenticTableSheetRequired(TypedDict):
     sheetId: str
     name: str
@@ -238,6 +294,39 @@ class AgenticTable(APIResource["AgenticTable"]):
         status: RowVerificationStatus
         locked: NotRequired[bool]
 
+    class CreateSheet(RequestOptions):
+        """Body for `POST /magic-table` (create a new sheet in a space)."""
+
+        assistantId: str
+        name: NotRequired[str]
+        dueAt: NotRequired[str]
+
+    class AddMetaData(RequestOptions):
+        """Body for `POST /magic-table/{tableId}/metadata` (import questions/sources).
+
+        Delta semantics: ids/texts already on the sheet are silently skipped. The
+        agent run is only triggered when new questions (file ids or texts) are
+        provided; adding only sources does not trigger a run.
+        """
+
+        tableId: str
+        questionFileIds: NotRequired[list[str]]
+        questionTexts: NotRequired[list[str]]
+        sourceFileIds: NotRequired[list[str]]
+        context: NotRequired[str]
+
+    class GenerateArtifact(RequestOptions):
+        """Body for `POST /magic-table/{tableId}/generate-artifact` (trigger export)."""
+
+        tableId: str
+        artifactTypes: list[MagicTableArtifactType]
+
+    class CreateSheetMetadata(RequestOptions):
+        """Body for `POST /magic-table/{tableId}/sheet/metadata` (create sheet metadata entries)."""
+
+        tableId: str
+        entries: list[MagicTableMetadataEntry]
+
     @classmethod
     async def set_cell(
         cls,
@@ -435,3 +524,143 @@ class AgenticTable(APIResource["AgenticTable"]):
                 params,
             ),
         )
+
+    @classmethod
+    async def create_sheet(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["AgenticTable.CreateSheet"],
+    ) -> CreatedAgenticTableSheet:
+        """Create a new Agentic Table sheet in a space (`POST /magic-table`).
+
+        The caller must have access to the space (``assistantId``). The response
+        includes ``sheetId`` (use it as ``tableId`` for all subsequent calls) and
+        ``dueDiligenceId``.
+        """
+        return cast(
+            CreatedAgenticTableSheet,
+            await cls._static_request_async(
+                "post",
+                "/magic-table",
+                user_id,
+                company_id,
+                params,
+            ),
+        )
+
+    @classmethod
+    async def add_metadata(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["AgenticTable.AddMetaData"],
+    ) -> MagicTableActionResult:
+        """Import question files/texts and source files (`POST /magic-table/{tableId}/metadata`).
+
+        Triggers the agent when new questions are included. Rejected with 422 while
+        the sheet is ``PROCESSING``.
+        """
+        url = f"/magic-table/{params['tableId']}/metadata"
+        params.pop("tableId")
+        return cast(
+            MagicTableActionResult,
+            await cls._static_request_async(
+                "post",
+                url,
+                user_id,
+                company_id,
+                params,
+            ),
+        )
+
+    @classmethod
+    async def generate_artifact(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["AgenticTable.GenerateArtifact"],
+    ) -> MagicTableActionResult:
+        """Trigger export generation (`POST /magic-table/{tableId}/generate-artifact`).
+
+        Generation is asynchronous: poll `list_artifacts` until the artifact of the
+        requested type reaches state ``DONE``, then download its ``contentId`` via
+        the Content API.
+        """
+        url = f"/magic-table/{params['tableId']}/generate-artifact"
+        params.pop("tableId")
+        return cast(
+            MagicTableActionResult,
+            await cls._static_request_async(
+                "post",
+                url,
+                user_id,
+                company_id,
+                params,
+            ),
+        )
+
+    @classmethod
+    async def list_artifacts(
+        cls,
+        user_id: str,
+        company_id: str,
+        tableId: str,
+    ) -> list[MagicTableArtifact]:
+        """List export artifacts of a sheet (`GET /magic-table/{tableId}/artifacts`).
+
+        The route responds with a ``{object: "list", data: [...]}`` envelope; this
+        method unwraps it and returns the artifact entries.
+        """
+        url = f"/magic-table/{tableId}/artifacts"
+        response = cast(
+            MagicTableArtifactList,
+            await cls._static_request_async(
+                "get",
+                url,
+                user_id,
+                company_id,
+            ),
+        )
+        return response["data"]
+
+    @classmethod
+    async def create_sheet_metadata(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["AgenticTable.CreateSheetMetadata"],
+    ) -> MagicTableActionResult:
+        """Create sheet metadata entries (`POST /magic-table/{tableId}/sheet/metadata`)."""
+        url = f"/magic-table/{params['tableId']}/sheet/metadata"
+        params.pop("tableId")
+        return cast(
+            MagicTableActionResult,
+            await cls._static_request_async(
+                "post",
+                url,
+                user_id,
+                company_id,
+                params,
+            ),
+        )
+
+    @classmethod
+    async def delete_sheet_metadata(
+        cls,
+        user_id: str,
+        company_id: str,
+        tableId: str,
+        metadataId: str,
+    ) -> MagicTableActionResult:
+        """Delete a sheet metadata entry (`DELETE /magic-table/{tableId}/sheet/metadata/{metadataId}`)."""
+        url = f"/magic-table/{tableId}/sheet/metadata/{metadataId}"
+        return cast(
+            MagicTableActionResult,
+            await cls._static_request_async(
+                "delete",
+                url,
+                user_id,
+                company_id,
+            ),
+        )

{unique_sdk-2026.30.0.dev8 → unique_sdk-2026.30.0.dev10}/unique_sdk/utils/chat_in_space.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import asyncio
 import warnings
 from collections.abc import Awaitable, Callable, Sequence
@@ -11,6 +13,17 @@ from unique_sdk.utils.file_io import (
 )
 
 
+def get_message_invocations(message: Space.Message) -> list[dict[str, Any]]:
+    """Per-LLM-invocation stats for a completed Space message, read from
+    `debugInfo.llm_invocations` (a plain list, one entry per LLM call).
+
+    Each entry has `modelName`, `tokenUsage`, and `source` keys.
+    """
+    debug_info = message.get("debugInfo") or {}
+    llm_invocations = debug_info.get("llm_invocations")
+    return llm_invocations if isinstance(llm_invocations, list) else []
+
+
 async def send_message_and_wait_for_completion(
     user_id: str,
     company_id: str,
@@ -23,10 +36,10 @@ async def send_message_and_wait_for_completion(
     poll_interval: float = 1.0,
     max_wait: float = 60.0,
     stop_condition: Literal["stoppedStreamingAt", "completedAt"] = "stoppedStreamingAt",
-    correlation: "Space.Correlation | None" = None,
+    correlation: Space.Correlation | None = None,
     auto_approve_elicitation: bool | None = None,
-    on_message_update: Callable[["Space.Message"], Awaitable[None]] | None = None,
-) -> "Space.Message":
+    on_message_update: Callable[[Space.Message], Awaitable[None]] | None = None,
+) -> Space.Message:
     """
     Sends a prompt asynchronously and polls for completion. (until stoppedStreamingAt is not None)
 
@@ -42,6 +55,13 @@ async def send_message_and_wait_for_completion(
         poll_interval: Seconds between polls.
         max_wait: Maximum seconds to wait for completion.
         stop_condition: Defines when to expect a response back, when the assistant stop streaming or when it completes the message. (default: "stoppedStreamingAt")
+            Note: `debugInfo.llm_invocations` (see `get_message_invocations`) is written
+            near the very end of the orchestrator's run -- after postprocessors and
+            evaluations, which happen after the visible text stream ends. With the default
+            `"stoppedStreamingAt"`, or even `"completedAt"` (set slightly before the debugInfo
+            write completes), the returned message's invocations can still be incomplete
+            immediately after this function returns. Re-fetch the message after a short delay
+            if you need the full invocation list.
         correlation: Optional correlation data to link this message to a parent message in another chat.
             Should contain: parentMessageId, parentChatId, parentAssistantId.
         auto_approve_elicitation: When True, automatically approves elicitation requests during
@@ -91,6 +111,11 @@ async def send_message_and_wait_for_completion(
                 last_update_signature = update_signature
         if answer.get(stop_condition) is not None:
             try:
+                # debugInfo/llm_invocations is written via update_debug_info_async(),
+                # which always targets the original USER message, not the
+                # assistant reply (assistant=False in
+                # ChatService._construct_message_modify_params) — re-fetch by
+                # `message_id`, not the polled assistant message's own id.
                 user_message = await Message.retrieve_async(
                     user_id, company_id, message_id, chatId=chat_id
                 )
@@ -116,7 +141,7 @@ async def chat_against_file(
     poll_interval: float = 1.0,
     max_wait: float = 60.0,
     should_delete_chat: bool = True,
-) -> "Space.Message":
+) -> Space.Message:
     """
     Chat against a file by uploading it, sending a message and waiting for a reply.
     Args: