unique_toolkit 1.80.2__tar.gz → 1.81.0__tar.gz

{unique_toolkit-1.80.2 → unique_toolkit-1.81.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 1.80.2
+Version: 1.81.0
 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>=0.11.6,<0.12
+Requires-Dist: unique-sdk>=0.11.12,<0.12
 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-1.80.2 → unique_toolkit-1.81.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "1.80.2"
+version = "1.81.0"
 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>=0.11.6,<0.12",
+    "unique-sdk>=0.11.12,<0.12",
     "jambo>=0.1.2,<0.2",
     "jinja2>=3.1.6,<4",
     "docxtpl>=0.20.1,<0.21",

{unique_toolkit-1.80.2 → unique_toolkit-1.81.0}/unique_toolkit/agentic/tools/openai_builtin/code_interpreter/config.py

@@ -49,6 +49,8 @@ Handling User Queries:
 - Whenever the user query requires using the python tool, you must always think first about the steps required.
 - CRITICAL: If any step generates a plot or visualization, that code block MUST include `plt.savefig('/mnt/data/<filename>.png', bbox_inches='tight')` and `plt.close()` as the final lines. Code that only calls `plt.show()` without saving will NOT display the image to the user.
 - CRITICAL: NEVER reference a `sandbox:/mnt/data/<filename>` link unless you have already executed code in this response that saved that exact file. Referencing a file that was not created by executed code will result in a broken link.
+- CRITICAL: For Excel files (`.xls`, `.xlsx`) and CSV files uploaded to the chat, ALWAYS use this tool to read and process them (e.g. `pandas.read_excel`, `pandas.read_csv`, `openpyxl`). Do NOT rely on the chat's text content or prior ingestion for spreadsheet data — the raw file contents are only accessible via code execution from `/mnt/data/<filename>`.
+- For calculation, retrieval, or exploratory-analysis answers, return the result concisely in the chat as markdown (key numbers inline, short tables where useful). Do NOT produce a separate artifact file (HTML, PDF, etc.) unless the user explicitly asked for a downloadable output or the request clearly calls for a dashboard/report.
 - Use the tool multiple times:
     - You MUST NOT guess anything about the structure of the data / files uploaded. Rather, you MUST perform some data exploration first.
         - Example: User uploads an excel files and asks a question about it. First Read the data, explore the columns, columns types, etc. Then use the tool to answer the user's query.
@@ -118,6 +120,8 @@ Handling User Queries:
 - CRITICAL: If any step generates a plot or visualization, that code block MUST include `plt.savefig('/mnt/data/<filename>.png', bbox_inches='tight')` and `plt.close()` as the final lines. Code that only calls `plt.show()` without saving will NOT display the image to the user.
 - CRITICAL: NEVER reference a `sandbox:/mnt/data/<filename>` link unless you have already executed code in this response that saved that exact file. Referencing a file that was not created by executed code will result in a broken link.
 - CRITICAL: The sandbox has NO internet access. NEVER use `requests`, `httpx`, `urllib`, or any other HTTP library to fetch data from the web — these calls will always fail. If the user's query requires live web data (e.g. market prices, news, APIs), you MUST retrieve it using the web search tool first and then pass the result into the code interpreter.
+- CRITICAL: For Excel files (`.xls`, `.xlsx`) and CSV files uploaded to the chat, ALWAYS use this tool to read and process them (e.g. `pandas.read_excel`, `pandas.read_csv`, `openpyxl`). Do NOT rely on the chat's text content or prior ingestion for spreadsheet data — the raw file contents are only accessible via code execution from `/mnt/data/<filename>`.
+- For calculation, retrieval, or exploratory-analysis answers, return the result concisely in the chat as markdown (key numbers inline, short tables where useful). Do NOT produce a separate artifact file (HTML, PDF, etc.) unless the user explicitly asked for a downloadable output or the request clearly calls for a dashboard/report.
 - Use the tool multiple times:
     - You MUST NOT guess anything about the structure of the data / files uploaded. Rather, you MUST perform some data exploration first.
         - Example: User uploads an excel files and asks a question about it. First Read the data, explore the columns, columns types, etc. Then use the tool to answer the user's query.
@@ -129,7 +133,7 @@ Handling User Queries:
 
 
 DEFAULT_TOOL_DESCRIPTION_FOR_USER_PROMPT = ""
-DEFAULT_TOOL_DESCRIPTION = "Use this tool to run python code, e.g to generate plots, process excel files, perform calculations, etc."
+DEFAULT_TOOL_DESCRIPTION = "Use this tool to run Python code: generate plots, process Excel/CSV files, perform calculations, create dashboards and data visualizations. ALWAYS use this tool when the user uploads a file (especially Excel/CSV) or asks for any chart, plot, graph, dashboard, analysis, visualization, or equation. Do not answer plotting or graphing requests with text or ASCII art — always produce a real image via the tool."
 
 
 @register_config()

{unique_toolkit-1.80.2 → unique_toolkit-1.81.0}/unique_toolkit/agentic_table/__init__.py

@@ -2,6 +2,9 @@ from unique_sdk.api_resources._agentic_table import (
     ActivityStatus,
     CellRendererTypes,
     FilterTypes,
+    MagicTableActivityResponse,
+    MagicTableArtifactType,
+    MagicTableMetadataEntry,
     RowVerificationStatus,
 )
 
@@ -40,7 +43,10 @@ __all__ = [
     "CellRendererTypes",
     "FilterTypes",
     "LogEntry",
+    "MagicTableActivityResponse",
+    "MagicTableArtifactType",
     "MagicTableAction",
+    "MagicTableMetadataEntry",
     "MagicTableAddMetadataPayload",
     "MagicTableBasePayload",
     "MagicTableCell",

{unique_toolkit-1.80.2 → unique_toolkit-1.81.0}/unique_toolkit/agentic_table/schemas.py

@@ -10,6 +10,7 @@ from pydantic import (
 from unique_sdk import (
     AgenticTableSheetState,
     AgreementStatus,
+    MagicTableArtifactType,
     SelectionMethod,
 )
 from unique_sdk import LogDetail as SDKLogDetail
@@ -150,15 +151,13 @@ class MagicTableUpdateCellPayload(
     data: str
 
 
-class ArtifactType(StrEnum):
-    QUESTIONS = "QUESTIONS"
-    FULL_REPORT = "FULL_REPORT"
-    AGENTIC_REPORT = "AGENTIC_REPORT"
+# Same wire values as ``MagicTableArtifactType`` / public ``POST .../artifact`` (unique-sdk 0.11.12+).
+ArtifactType = MagicTableArtifactType
 
 
 class ArtifactData(BaseModel):
     model_config = get_configuration_dict()
-    artifact_type: ArtifactType
+    artifact_type: MagicTableArtifactType
 
 
 class MagicTableGenerateArtifactPayload(
@@ -344,7 +343,10 @@ class MagicTableSheet(BaseModel):
         description="The total number of rows in the sheet",
         alias="magicTableRowCount",
     )
-    chat_id: str
+    chat_id: str | None = Field(
+        default=None,
+        description="Chat that owns the sheet when returned by the API (may be omitted).",
+    )
     created_by: str
     company_id: str
     created_at: str

{unique_toolkit-1.80.2 → unique_toolkit-1.81.0}/unique_toolkit/agentic_table/service.py

@@ -1,4 +1,5 @@
 import logging
+from typing import Any, cast
 
 from typing_extensions import deprecated
 from unique_sdk import (
@@ -7,6 +8,7 @@ from unique_sdk import (
     AgreementStatus,
     CellRendererTypes,
     FilterTypes,
+    MagicTableArtifactType,
     RowVerificationStatus,
     SelectionMethod,
 )
@@ -14,7 +16,6 @@ from unique_sdk import AgenticTableCell as SDKAgenticTableCell
 from unique_sdk.api_resources._agentic_table import ActivityStatus
 
 from .schemas import (
-    ArtifactType,
     LogEntry,
     MagicTableAction,
     MagicTableCell,
@@ -23,6 +24,25 @@ from .schemas import (
 )
 
 
+def _sheet_batch_cells_include_row_metadata_from_api(
+    cells: list[SDKAgenticTableCell],
+) -> bool:
+    """True when `get_sheet_data` already returned per-cell ``rowMetadata`` (UN-19884+).
+
+    Used to skip N+1 ``get_cell`` hydration. If the batch is empty, there is nothing
+    to hydrate, so we treat that as satisfied.
+
+    When the gateway does not yet populate ``rowMetadata`` on sheet payloads, the
+    first cell typically omits the key entirely — then callers fall back to
+    ``get_cell`` per distinct row (legacy compat; removable after deprecation).
+    """
+    if not cells:
+        return True
+    first = cells[0]
+    rm = first.get("rowMetadata")
+    return "rowMetadata" in first and isinstance(rm, list)
+
+
 class LockedAgenticTableError(Exception):
     pass
 
@@ -106,7 +126,7 @@ class AgenticTableService:
             tableId=self.table_id,
             rowOrder=row,
             columnOrder=column,
-            includeRowMetadata=include_row_metadata,  # type: ignore[arg-type]
+            includeRowMetadata=include_row_metadata,
         )
         return MagicTableCell.model_validate(cell_data)
 
@@ -198,27 +218,32 @@ class AgenticTableService:
 
     async def set_artifact(
         self,
-        artifact_type: ArtifactType,
+        artifact_type: MagicTableArtifactType,
         content_id: str,
-        mime_type: str,
-        name: str,
+        mime_type: str | None = None,
+        name: str | None = None,
     ):
         """Upload/set report files to the Agentic Table.
 
         Args:
-            artifact_type (ArtifactType): The type of artifact to set.
-            content_id (str): The content ID of the artifact.
-            mime_type (str): The MIME type of the artifact.
-            name (str): The name of the artifact.
+            artifact_type: The type of artifact to set (``MagicTableArtifactType`` / public API).
+            content_id: The content ID of the artifact.
+            mime_type: The MIME type of the artifact (optional on the wire; include when known).
+            name: The display name of the artifact (optional on the wire; include when known).
         """
+        extras: dict[str, str] = {}
+        if mime_type is not None:
+            extras["mimeType"] = mime_type
+        if name is not None:
+            extras["name"] = name
+        # ``Unpack[SetArtifact]`` + dynamic keys: basedpyright cannot tie ``extras`` to optional fields.
         await AgenticTable.set_artifact(
             user_id=self._user_id,
             company_id=self._company_id,
             tableId=self.table_id,
-            artifactType=artifact_type.value,  # pyright: ignore[reportArgumentType]
+            artifactType=artifact_type,
             contentId=content_id,
-            mimeType=mime_type,
-            name=name,
+            **cast(Any, extras),
         )
 
     @deprecated("Use set_column_style instead.")
@@ -282,7 +307,12 @@ class AgenticTableService:
             includeCells=False,
             includeLogHistory=False,
         )
-        return sheet_info["magicTableRowCount"]
+        row_count = sheet_info.get("magicTableRowCount")
+        if row_count is None:
+            raise RuntimeError(
+                "Expected magicTableRowCount in sheet response when includeRowCount=True"
+            )
+        return row_count
 
     async def get_sheet(
         self,
@@ -316,7 +346,11 @@ class AgenticTableService:
             includeLogHistory=False,
             includeCellMetaData=False,
         )
-        total_rows = sheet_info["magicTableRowCount"]
+        total_rows = sheet_info.get("magicTableRowCount")
+        if total_rows is None:
+            raise RuntimeError(
+                "Expected magicTableRowCount in sheet response when includeRowCount=True"
+            )
         if end_row is None or end_row > total_rows:
             end_row = total_rows
         if start_row > end_row:
@@ -328,50 +362,69 @@ class AgenticTableService:
         cells = []
         for row in range(start_row, end_row, batch_size):
             end_row_batch = min(row + batch_size, end_row)
-            sheet_partial = await AgenticTable.get_sheet_data(
-                user_id=self._user_id,
-                company_id=self._company_id,
-                tableId=self.table_id,
-                includeCells=True,
-                includeLogHistory=include_log_history,
-                includeRowCount=False,
-                includeCellMetaData=include_cell_meta_data,  # renderer, selection, agreement status
-                startRow=row,
-                endRow=end_row_batch - 1,
-            )
+            if include_row_metadata:
+                sheet_partial = await AgenticTable.get_sheet_data(
+                    user_id=self._user_id,
+                    company_id=self._company_id,
+                    tableId=self.table_id,
+                    includeCells=True,
+                    includeLogHistory=include_log_history,
+                    includeRowCount=False,
+                    includeCellMetaData=include_cell_meta_data,  # renderer, selection, agreement status
+                    startRow=row,
+                    endRow=end_row_batch - 1,
+                    includeRowMetadata=True,
+                )
+            else:
+                sheet_partial = await AgenticTable.get_sheet_data(
+                    user_id=self._user_id,
+                    company_id=self._company_id,
+                    tableId=self.table_id,
+                    includeCells=True,
+                    includeLogHistory=include_log_history,
+                    includeRowCount=False,
+                    includeCellMetaData=include_cell_meta_data,  # renderer, selection, agreement status
+                    startRow=row,
+                    endRow=end_row_batch - 1,
+                )
             if "magicTableCells" in sheet_partial:
-                if include_row_metadata:
-                    # If include_row_metadata is true, we need to get the row metadata for each cell.
-                    row_metadata_map = {}
-                    # TODO: @thea-unique This routine is not efficient and would be nice if we had this data passed on in get_sheet_data.
-                    for cell in sheet_partial["magicTableCells"]:
+                batch_cells = sheet_partial["magicTableCells"]
+                if (
+                    include_row_metadata
+                    and not _sheet_batch_cells_include_row_metadata_from_api(
+                        batch_cells
+                    )
+                ):
+                    # Legacy: gateways before UN-19884 omit rowMetadata on sheet cells; hydrate
+                    # via get_cell until all environments expose rowMetadata on GET sheet. This
+                    # branch can be removed after an agreed deprecation window.
+                    self.logger.debug(
+                        "Magic table sheet cells lack rowMetadata; hydrating row metadata via get_cell."
+                    )
+                    row_metadata_map: dict[int, list[RowMetadataEntry]] = {}
+                    for cell in batch_cells:
                         row_order = cell.get("rowOrder")  # type: ignore[assignment]
                         if row_order is not None and row_order not in row_metadata_map:  # pyright: ignore[reportUnnecessaryComparison]
                             column_order = cell.get("columnOrder")  # type: ignore[assignment]
-                            self.logger.info(
-                                f"Getting row metadata for cell {row_order}, {column_order}"
-                            )
                             cell_with_row_metadata = await self.get_cell(
                                 row_order,
                                 column_order,
                             )
                             if cell_with_row_metadata.row_metadata:
-                                print(cell_with_row_metadata.row_metadata)
                                 row_metadata_map[cell_with_row_metadata.row_order] = (
                                     cell_with_row_metadata.row_metadata
                                 )
                                 cell["rowMetadata"] = (  # pyright: ignore[reportGeneralTypeIssues]
                                     cell_with_row_metadata.row_metadata
                                 )
-                    # Assign row_metadata to all cells
-                    for cell in sheet_partial["magicTableCells"]:
+                    for cell in batch_cells:
                         row_order = cell.get("rowOrder")  # type: ignore[assignment]
                         if row_order is not None and row_order in row_metadata_map:  # pyright: ignore[reportUnnecessaryComparison]
                             cell["rowMetadata"] = row_metadata_map[  # pyright: ignore[reportGeneralTypeIssues]
                                 row_order
                             ]
 
-                cells.extend(sheet_partial["magicTableCells"])
+                cells.extend(batch_cells)
 
         sheet_info["magicTableCells"] = cells
         return MagicTableSheet.model_validate(sheet_info)
@@ -387,12 +440,10 @@ class AgenticTableService:
             user_id=self._user_id,
             company_id=self._company_id,
             tableId=self.table_id,
-            includeSheetMetadata=True,  # pyright: ignore[reportCallIssue]
+            includeSheetMetadata=True,
         )
-        return [
-            RowMetadataEntry.model_validate(metadata)
-            for metadata in sheet_info["magicTableSheetMetadata"]
-        ]
+        raw_metadata = sheet_info.get("magicTableSheetMetadata") or []
+        return [RowMetadataEntry.model_validate(metadata) for metadata in raw_metadata]
 
     async def set_cell_metadata(
         self,
@@ -436,17 +487,29 @@ class AgenticTableService:
         self,
         row_orders: list[int],
         status: RowVerificationStatus,
+        locked: bool | None = None,
     ):
         """Update the verification status of multiple rows at once.
 
         Args:
-            row_orders (list[int]): The row indexes to update.
-            status (RowVerificationStatus): The verification status to set.
+            row_orders: The row indexes to update.
+            status: The verification status to set (``NEEDS_REVIEW``, etc.; matches public API).
+            locked: When set, forwarded as ``locked`` on ``POST .../rows/bulk-update-status``.
         """
-        await AgenticTable.bulk_update_status(
-            user_id=self._user_id,
-            company_id=self._company_id,
-            tableId=self.table_id,
-            rowOrders=row_orders,
-            status=status,
-        )
+        if locked is None:
+            await AgenticTable.bulk_update_status(
+                user_id=self._user_id,
+                company_id=self._company_id,
+                tableId=self.table_id,
+                rowOrders=row_orders,
+                status=status,
+            )
+        else:
+            await AgenticTable.bulk_update_status(
+                user_id=self._user_id,
+                company_id=self._company_id,
+                tableId=self.table_id,
+                rowOrders=row_orders,
+                status=status,
+                locked=locked,
+            )