unique-toolkit 2026.30.0.dev23__tar.gz → 2026.30.0.dev24__tar.gz

{unique_toolkit-2026.30.0.dev23 → unique_toolkit-2026.30.0.dev24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 2026.30.0.dev23
+Version: 2026.30.0.dev24
 Summary: 
 Author: Cedric Klinkert, Martin Fadler, Sadique Sheik, Fabian Schläpfer, Pascal Hauri, Ejiroghene Oki-Peter, Rami Azouz, Ricardo Visini, Sanzio Monti
 Author-email: Cedric Klinkert <cedric.klinkert@unique.ch>, Martin Fadler <martin.fadler@unique.ch>, Sadique Sheik <sadique@unique.ch>, Fabian Schläpfer <fabian@unique.ch>, Pascal Hauri <pascal@unique.ch>, Ejiroghene Oki-Peter <oki-peter.ejiroghene@unique.ai>, Rami Azouz <rami.ext@unique.ch>, Ricardo Visini <ricardo.visini@unique.ch>, Sanzio Monti <sanzio.monti@unique.ai>
@@ -16,7 +16,7 @@ Requires-Dist: sseclient>=0.0.27,<0.0.28
 Requires-Dist: openai>=1.105.0,<3
 Requires-Dist: platformdirs>=4.0.0,<5
 Requires-Dist: pillow>=12.1.1
-Requires-Dist: unique-sdk>=2026.30.0.dev9,<2026.30.0rc0
+Requires-Dist: unique-sdk>=2026.30.0.dev10,<2026.30.0rc0
 Requires-Dist: jambo>=0.1.2,<0.2
 Requires-Dist: jinja2>=3.1.6,<4
 Requires-Dist: docxtpl>=0.20.1,<0.21

{unique_toolkit-2026.30.0.dev23 → unique_toolkit-2026.30.0.dev24}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "2026.30.0.dev23"
+version = "2026.30.0.dev24"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12"
@@ -28,7 +28,7 @@ dependencies = [
     "openai>=1.105.0,<3",
     "platformdirs>=4.0.0,<5",
     "pillow>=12.1.1",
-    "unique-sdk>=2026.30.0.dev9,<2026.30.0rc0",
+    "unique-sdk>=2026.30.0.dev10,<2026.30.0rc0",
     "jambo>=0.1.2,<0.2",
     "jinja2>=3.1.6,<4",
     "docxtpl>=0.20.1,<0.21",

{unique_toolkit-2026.30.0.dev23 → unique_toolkit-2026.30.0.dev24}/unique_toolkit/agentic_table/__init__.py

@@ -3,6 +3,7 @@ from unique_sdk.api_resources._agentic_table import (
     CellRendererTypes,
     FilterTypes,
     MagicTableActivityResponse,
+    MagicTableArtifactState,
     MagicTableArtifactType,
     MagicTableMetadataEntry,
     RowVerificationStatus,
@@ -12,9 +13,11 @@ from .schemas import (
     AgenticTableSheetState,
     AgreementStatus,
     ArtifactType,
+    CreatedMagicTableSheet,
     LogEntry,
     MagicTableAction,
     MagicTableAddMetadataPayload,
+    MagicTableArtifact,
     MagicTableBasePayload,
     MagicTableCell,
     MagicTableCellMetaData,
@@ -30,20 +33,34 @@ from .schemas import (
     RerunRowMetadata,
     RowMetadataEntry,
     SelectionMethod,
+    SheetMetadataEntryInput,
     SheetType,
 )
-from .service import AgenticTableService
+from .service import (
+    AgenticTableArtifactError,
+    AgenticTableRunNotStartedError,
+    AgenticTableRunTimeoutError,
+    AgenticTableService,
+    LockedAgenticTableError,
+)
 
 __all__ = [
     "AgenticTableService",
+    "AgenticTableArtifactError",
+    "AgenticTableRunNotStartedError",
+    "AgenticTableRunTimeoutError",
     "ActivityStatus",
     "AgenticTableSheetState",
     "AgreementStatus",
     "ArtifactType",
     "CellRendererTypes",
+    "CreatedMagicTableSheet",
     "FilterTypes",
+    "LockedAgenticTableError",
     "LogEntry",
     "MagicTableActivityResponse",
+    "MagicTableArtifact",
+    "MagicTableArtifactState",
     "MagicTableArtifactType",
     "MagicTableAction",
     "MagicTableMetadataEntry",
@@ -64,5 +81,6 @@ __all__ = [
     "RowMetadataEntry",
     "RowVerificationStatus",
     "SelectionMethod",
+    "SheetMetadataEntryInput",
     "SheetType",
 ]

{unique_toolkit-2026.30.0.dev23 → unique_toolkit-2026.30.0.dev24}/unique_toolkit/agentic_table/schemas.py

@@ -10,6 +10,7 @@ from pydantic import (
 from unique_sdk import (
     AgenticTableSheetState,
     AgreementStatus,
+    MagicTableArtifactState,
     MagicTableArtifactType,
     SelectionMethod,
 )
@@ -401,3 +402,53 @@ class MagicTableSheet(BaseModel):
     magic_table_sheet_metadata: list[RowMetadataEntry] = Field(
         default_factory=list, description="The metadata for the sheet"
     )
+
+
+class CreatedMagicTableSheet(BaseModel):
+    """Response of `POST /magic-table` (create sheet in a space)."""
+
+    model_config = get_configuration_dict()
+    sheet_id: str
+    due_diligence_id: str = Field(
+        description="Identifier of the due-diligence record backing this sheet."
+    )
+    name: str
+    state: AgenticTableSheetState
+    chat_id: str | None = Field(
+        default=None, description="Chat that owns the sheet (may be null)."
+    )
+    created_by: str
+    company_id: str
+    created_at: str
+    due_at: str | None = None
+
+
+class MagicTableArtifact(BaseModel):
+    """Export artifact of a sheet as returned by `GET /magic-table/{tableId}/artifacts`."""
+
+    model_config = get_configuration_dict()
+    id: str
+    name: str | None = None
+    content_id: str | None = Field(
+        default=None,
+        description="Content id of the generated file. Only present once the artifact is DONE; download it via the Content API.",
+    )
+    mime_type: str | None = None
+    artifact_type: MagicTableArtifactType
+    artifact_state: MagicTableArtifactState = Field(
+        description="IN_PROGRESS while the agent is generating the export, DONE when ready."
+    )
+    created_at: str
+    updated_at: str
+
+
+class SheetMetadataEntryInput(BaseModel):
+    """Input entry for creating sheet metadata (key/value pairs) on a sheet."""
+
+    model_config = get_configuration_dict()
+    key: str
+    value: str
+    exact_filter: bool = Field(
+        default=False,
+        description="Whether the metadata is to be used for strict filtering",
+    )

{unique_toolkit-2026.30.0.dev23 → unique_toolkit-2026.30.0.dev24}/unique_toolkit/agentic_table/service.py

@@ -1,4 +1,6 @@
+import asyncio
 import logging
+import time
 from typing import Any, cast
 
 from typing_extensions import deprecated
@@ -8,6 +10,7 @@ from unique_sdk import (
     AgreementStatus,
     CellRendererTypes,
     FilterTypes,
+    MagicTableArtifactState,
     MagicTableArtifactType,
     RowVerificationStatus,
     SelectionMethod,
@@ -16,11 +19,14 @@ from unique_sdk import AgenticTableCell as SDKAgenticTableCell
 from unique_sdk.api_resources._agentic_table import ActivityStatus
 
 from .schemas import (
+    CreatedMagicTableSheet,
     LogEntry,
     MagicTableAction,
+    MagicTableArtifact,
     MagicTableCell,
     MagicTableSheet,
     RowMetadataEntry,
+    SheetMetadataEntryInput,
 )
 
 
@@ -47,6 +53,18 @@ class LockedAgenticTableError(Exception):
     pass
 
 
+class AgenticTableRunNotStartedError(TimeoutError):
+    """Raised by ``wait_for_run`` when the sheet never left IDLE within the start timeout."""
+
+
+class AgenticTableRunTimeoutError(TimeoutError):
+    """Raised by ``wait_for_run``/``wait_for_artifacts`` when the operation did not complete in time."""
+
+
+class AgenticTableArtifactError(Exception):
+    """Raised by ``wait_for_artifacts`` when an artifact ends up in the ERROR state."""
+
+
 class AgenticTableService:
     """
     Provides methods to interact with the Agentic Table.
@@ -69,6 +87,51 @@ class AgenticTableService:
         self._company_id = company_id
         self.table_id = table_id
         self.logger = logger
+        self.created_sheet: CreatedMagicTableSheet | None = None
+
+    @classmethod
+    async def create_sheet(
+        cls,
+        user_id: str,
+        company_id: str,
+        assistant_id: str,
+        name: str | None = None,
+        due_at: str | None = None,
+        logger: logging.Logger = logging.getLogger(__name__),
+    ) -> "AgenticTableService":
+        """Create a new Agentic Table sheet in a space and return a service bound to it.
+
+        Args:
+            user_id: The user creating the sheet (must have access to the space).
+            company_id: The company id.
+            assistant_id: The space (assistant) to create the sheet in.
+            name: Optional sheet name.
+            due_at: Optional due date (ISO 8601 string).
+
+        Returns:
+            AgenticTableService: A service bound to the new sheet. The full creation
+            response (including ``due_diligence_id``) is available on ``created_sheet``.
+        """
+        params: dict[str, str] = {"assistantId": assistant_id}
+        if name is not None:
+            params["name"] = name
+        if due_at is not None:
+            params["dueAt"] = due_at
+        # ``Unpack[CreateSheet]`` + dynamic keys: basedpyright cannot tie ``params`` to optional fields.
+        created = await AgenticTable.create_sheet(
+            user_id=user_id,
+            company_id=company_id,
+            **cast(Any, params),
+        )
+        sheet = CreatedMagicTableSheet.model_validate(created)
+        service = cls(
+            user_id=user_id,
+            company_id=company_id,
+            table_id=sheet.sheet_id,
+            logger=logger,
+        )
+        service.created_sheet = sheet
+        return service
 
     async def set_cell(
         self,
@@ -519,3 +582,252 @@ class AgenticTableService:
                 status=status,
                 locked=locked,
             )
+
+    async def import_questions_and_sources(
+        self,
+        question_file_ids: list[str] | None = None,
+        question_texts: list[str] | None = None,
+        source_file_ids: list[str] | None = None,
+        context: str | None = None,
+    ) -> None:
+        """Import questions and source files into the sheet (`POST .../metadata`).
+
+        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. Rejected while the
+        sheet is PROCESSING.
+
+        Args:
+            question_file_ids: Content ids of questionnaire files to import.
+            question_texts: Question texts to import directly.
+            source_file_ids: Content ids of source (knowledge) files to answer from.
+            context: Optional free-text context passed to the agent.
+
+        Raises:
+            Exception: If the API reports a non-success status.
+        """
+        params: dict[str, Any] = {}
+        if question_file_ids is not None:
+            params["questionFileIds"] = question_file_ids
+        if question_texts is not None:
+            params["questionTexts"] = question_texts
+        if source_file_ids is not None:
+            params["sourceFileIds"] = source_file_ids
+        if context is not None:
+            params["context"] = context
+        result = await AgenticTable.add_metadata(
+            user_id=self._user_id,
+            company_id=self._company_id,
+            tableId=self.table_id,
+            **cast(Any, params),
+        )
+        if not result.get("status"):
+            raise Exception(result.get("message") or "Failed to import metadata")
+
+    async def generate_artifacts(
+        self,
+        artifact_types: list[MagicTableArtifactType],
+    ) -> None:
+        """Trigger export generation (`POST .../generate-artifact`).
+
+        Generation is asynchronous: this only initiates it. Use ``wait_for_artifacts``
+        (or poll ``list_artifacts``) to detect completion, then download the artifact's
+        ``content_id`` via the Content API.
+
+        Raises:
+            Exception: If the API reports a non-success status.
+        """
+        result = await AgenticTable.generate_artifact(
+            user_id=self._user_id,
+            company_id=self._company_id,
+            tableId=self.table_id,
+            artifactTypes=artifact_types,
+        )
+        if not result.get("status"):
+            raise Exception(
+                result.get("message") or "Failed to trigger artifact generation"
+            )
+
+    async def list_artifacts(self) -> list[MagicTableArtifact]:
+        """List export artifacts of the sheet (`GET .../artifacts`)."""
+        artifacts = await AgenticTable.list_artifacts(
+            user_id=self._user_id,
+            company_id=self._company_id,
+            tableId=self.table_id,
+        )
+        return [MagicTableArtifact.model_validate(artifact) for artifact in artifacts]
+
+    async def create_sheet_metadata(
+        self,
+        entries: list[SheetMetadataEntryInput],
+    ) -> None:
+        """Create sheet metadata entries (key/value pairs) on the sheet.
+
+        Raises:
+            Exception: If the API reports a non-success status.
+        """
+        result = await AgenticTable.create_sheet_metadata(
+            user_id=self._user_id,
+            company_id=self._company_id,
+            tableId=self.table_id,
+            entries=[
+                cast(
+                    Any,
+                    entry.model_dump(by_alias=True, exclude_none=True),
+                )
+                for entry in entries
+            ],
+        )
+        if not result.get("status"):
+            raise Exception(result.get("message") or "Failed to create sheet metadata")
+
+    async def delete_sheet_metadata(self, metadata_id: str) -> None:
+        """Delete a sheet metadata entry by its id.
+
+        Raises:
+            Exception: If the API reports a non-success status.
+        """
+        result = await AgenticTable.delete_sheet_metadata(
+            user_id=self._user_id,
+            company_id=self._company_id,
+            tableId=self.table_id,
+            metadataId=metadata_id,
+        )
+        if not result.get("status"):
+            raise Exception(result.get("message") or "Failed to delete sheet metadata")
+
+    async def wait_for_run(
+        self,
+        start_timeout: float = 120.0,
+        completion_timeout: float = 3600.0,
+        poll_interval: float = 5.0,
+    ) -> AgenticTableSheetState:
+        """Wait for an agent run to start and complete, by polling the sheet state.
+
+        Two-phase poll:
+        1. Wait until the sheet enters PROCESSING (the agent picked up the trigger).
+           Terminal state left over from an earlier run is not treated as a new
+           run. If PROCESSING is never observed within ``start_timeout``, raise
+           ``AgenticTableRunNotStartedError`` — most likely the trigger did not
+           start a run (e.g. no new questions were imported).
+        2. Wait until the sheet returns to IDLE or STOPPED_BY_USER (the run
+           finished), up to ``completion_timeout``.
+
+        Because the API exposes only the current state, a complete
+        PROCESSING-to-IDLE transition between two polls cannot be observed.
+        Keep ``poll_interval`` shorter than the expected minimum run duration.
+
+        Args:
+            start_timeout: Max seconds to wait for the run to start (phase 1).
+            completion_timeout: Max seconds to wait for the run to finish (phase 2).
+            poll_interval: Seconds between state polls.
+
+        Returns:
+            AgenticTableSheetState: The terminal state (IDLE or STOPPED_BY_USER).
+
+        Raises:
+            AgenticTableRunNotStartedError: The sheet never entered PROCESSING in phase 1.
+            AgenticTableRunTimeoutError: The run did not finish within ``completion_timeout``.
+        """
+        deadline = time.monotonic() + start_timeout
+        while True:
+            state = await AgenticTable.get_sheet_state(
+                user_id=self._user_id,
+                company_id=self._company_id,
+                tableId=self.table_id,
+            )
+            if state == AgenticTableSheetState.PROCESSING:
+                break
+            if time.monotonic() >= deadline:
+                raise AgenticTableRunNotStartedError(
+                    f"Sheet {self.table_id} never entered PROCESSING within {start_timeout}s. "
+                    "Did the trigger start a run (e.g. were new questions imported)?"
+                )
+            await asyncio.sleep(poll_interval)
+
+        self.logger.debug("Sheet %s run started (state=%s)", self.table_id, state)
+
+        deadline = time.monotonic() + completion_timeout
+        while state == AgenticTableSheetState.PROCESSING:
+            if time.monotonic() >= deadline:
+                raise AgenticTableRunTimeoutError(
+                    f"Sheet {self.table_id} still PROCESSING after {completion_timeout}s."
+                )
+            await asyncio.sleep(poll_interval)
+            state = await AgenticTable.get_sheet_state(
+                user_id=self._user_id,
+                company_id=self._company_id,
+                tableId=self.table_id,
+            )
+
+        self.logger.debug("Sheet %s run finished (state=%s)", self.table_id, state)
+        return state
+
+    async def wait_for_artifacts(
+        self,
+        artifact_types: list[MagicTableArtifactType],
+        timeout: float = 600.0,
+        poll_interval: float = 5.0,
+    ) -> list[MagicTableArtifact]:
+        """Wait until artifacts of the given types are DONE, by polling ``list_artifacts``.
+
+        Artifact records are upserted per type: triggering an export flips the record
+        of that type to IN_PROGRESS and back to DONE when the file is ready. A
+        terminal state is accepted only after IN_PROGRESS has been observed for
+        that artifact type, so a result left over from an earlier generation is
+        not mistaken for the newly triggered one.
+
+        Because the API exposes only the current artifact state, a complete
+        IN_PROGRESS-to-terminal transition between two polls cannot be observed.
+        Keep ``poll_interval`` shorter than the expected minimum generation time.
+
+        Args:
+            artifact_types: The artifact types to wait for (as passed to ``generate_artifacts``).
+            timeout: Max seconds to wait for all requested artifacts to be DONE.
+            poll_interval: Seconds between polls.
+
+        Returns:
+            list[MagicTableArtifact]: The DONE artifacts, one per requested type.
+
+        Raises:
+            AgenticTableArtifactError: An artifact of a requested type is in the ERROR state.
+            AgenticTableRunTimeoutError: Not all artifacts were DONE within ``timeout``.
+        """
+        wanted = set(artifact_types)
+        started: set[MagicTableArtifactType] = set()
+        deadline = time.monotonic() + timeout
+        while True:
+            artifacts = await self.list_artifacts()
+            current = {
+                a.artifact_type: a for a in artifacts if a.artifact_type in wanted
+            }
+            started.update(
+                artifact_type
+                for artifact_type, artifact in current.items()
+                if artifact.artifact_state == MagicTableArtifactState.IN_PROGRESS
+            )
+            failed = [
+                artifact
+                for artifact_type, artifact in current.items()
+                if artifact_type in started
+                and artifact.artifact_state == MagicTableArtifactState.ERROR
+            ]
+            if failed:
+                raise AgenticTableArtifactError(
+                    f"Artifact generation failed for {[a.artifact_type for a in failed]} "
+                    f"on sheet {self.table_id}."
+                )
+            done = {
+                artifact_type: artifact
+                for artifact_type, artifact in current.items()
+                if artifact_type in started
+                and artifact.artifact_state == MagicTableArtifactState.DONE
+            }
+            if wanted <= set(done.keys()):
+                return [done[t] for t in artifact_types]
+            if time.monotonic() >= deadline:
+                missing = sorted(t.value for t in wanted - set(done.keys()))
+                raise AgenticTableRunTimeoutError(
+                    f"Artifacts {missing} not DONE within {timeout}s on sheet {self.table_id}."
+                )
+            await asyncio.sleep(poll_interval)