unique_toolkit 2026.36.0.dev3__py3-none-any.whl → 2026.36.0.dev5__py3-none-any.whl

unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/artifacts.py

@@ -1,11 +1,21 @@
+import asyncio
 import logging
+import tempfile
 from mimetypes import guess_type
+from pathlib import Path
+from typing import Any
 
+import unique_sdk.utils.file_io as file_io
 from openai.types.responses.response_output_text import AnnotationContainerFileCitation
 from pydantic import BaseModel
 
 from unique_toolkit import ChatService
 from unique_toolkit._common.utils.files import FileMimeType, ImageMimeType
+from unique_toolkit.agentic.tools.openai_builtin.code_interpreter.postprocessors.office_preview import (
+    OFFICE_PREVIEW_MIME_TYPES,
+    convert_office_bytes_to_preview_pdf,
+    office_extension,
+)
 from unique_toolkit.content.schemas import Content
 
 _CODE_EXECUTION_ARTIFACT_METADATA_KEY: str = "codeExecutionArtifactMetadata"
@@ -50,22 +60,24 @@ def _kb_safe_mime(mime: str) -> str:
     return "text/plain"
 
 
-async def save_code_execution_artifact(
+def _artifact_metadata(
+    file: AnnotationContainerFileCitation,
+) -> dict[str, Any]:
+    return {
+        _CODE_EXECUTION_ARTIFACT_METADATA_KEY: CodeExecutionArtifactMetadata(
+            container_id=file.container_id,
+            file_id=file.file_id,
+            filepath=f"/mnt/data/{file.filename}",
+        ).model_dump()
+    }
+
+
+async def _upload_artifact_bytes(
     chat_service: ChatService,
     file: AnnotationContainerFileCitation,
     file_bytes: bytes,
+    mime: str,
 ) -> Content:
-    raw_mime = guess_type(file.filename)[0] or "text/plain"
-    mime = _kb_safe_mime(raw_mime)
-
-    if mime != raw_mime:
-        _LOGGER.info(
-            "MIME type '%s' is not supported by the Unique KB; "
-            "uploading '%s' as 'text/plain' so the file can be stored and downloaded.",
-            raw_mime,
-            file.filename,
-        )
-
     _LOGGER.info(
         "Uploading '%s' to knowledge base (%d bytes, mime type %s)",
         file.filename,
@@ -79,13 +91,111 @@ async def save_code_execution_artifact(
         mime_type=mime,
         skip_ingestion=True,
         hide_in_chat=True,
-        metadata={
-            _CODE_EXECUTION_ARTIFACT_METADATA_KEY: CodeExecutionArtifactMetadata(
-                container_id=file.container_id,
-                file_id=file.file_id,
-                filepath=f"/mnt/data/{file.filename}",
-            ).model_dump()
-        },
+        metadata=_artifact_metadata(file),
+    )
+
+
+async def _upload_office_artifact_with_preview(
+    chat_service: ChatService,
+    file: AnnotationContainerFileCitation,
+    file_bytes: bytes,
+    mime: str,
+) -> Content | None:
+    """Upload an Office artifact with a PDF preview, or ``None`` to fall back."""
+    with tempfile.TemporaryDirectory(prefix="code-interpreter-preview-") as tmp:
+        output_dir = Path(tmp)
+        preview_path = await convert_office_bytes_to_preview_pdf(
+            filename=file.filename,
+            file_bytes=file_bytes,
+            tmp_dir=output_dir,
+            logger=_LOGGER,
+        )
+        if preview_path is None:
+            _LOGGER.warning(
+                "Code interpreter Office artifact '%s' could not be converted "
+                "to PDF; uploading without preview.",
+                file.filename,
+            )
+            return None
+
+        source_path = output_dir / Path(file.filename).name
+        _LOGGER.info(
+            "Uploading code interpreter Office artifact '%s' with PDF preview '%s'",
+            file.filename,
+            preview_path.name,
+        )
+
+        uploaded = await asyncio.to_thread(
+            file_io.upload_file,
+            chat_service._user_id,
+            chat_service._company_id,
+            str(source_path),
+            file.filename,
+            mime,
+            chat_id=chat_service._chat_id,
+            ingestion_config={
+                "uniqueIngestionMode": "SKIP_INGESTION",
+                "hideInChat": True,
+            },
+            metadata=_artifact_metadata(file),
+            preview_pdf_path=str(preview_path),
+        )
+
+    return Content.model_validate(uploaded, by_alias=True, by_name=True)
+
+
+async def save_code_execution_artifact(
+    chat_service: ChatService,
+    file: AnnotationContainerFileCitation,
+    file_bytes: bytes,
+    *,
+    attach_office_preview: bool = False,
+) -> Content:
+    """Upload a code-interpreter artifact to the chat knowledge base.
+
+    ``attach_office_preview`` is opt-in (default ``False``) so existing
+    Unique AI callers keep the historical bytes-only upload. When ``True``,
+    Word / PowerPoint / Excel files are converted to a sibling PDF and
+    uploaded with ``preview_pdf_path``. Conversion is best-effort: if
+    LibreOffice is missing or conversion fails, the original bytes are
+    uploaded instead. Upload failures are not retried via the bytes path,
+    because ``file_io.upload_file`` may already have created a content row.
+    """
+    if attach_office_preview:
+        extension = office_extension(file.filename)
+        if extension is not None:
+            mime = _kb_safe_mime(OFFICE_PREVIEW_MIME_TYPES[extension])
+            content = await _upload_office_artifact_with_preview(
+                chat_service=chat_service,
+                file=file,
+                file_bytes=file_bytes,
+                mime=mime,
+            )
+            if content is not None:
+                return content
+            return await _upload_artifact_bytes(
+                chat_service=chat_service,
+                file=file,
+                file_bytes=file_bytes,
+                mime=mime,
+            )
+
+    raw_mime = guess_type(file.filename)[0] or "text/plain"
+    mime = _kb_safe_mime(raw_mime)
+
+    if mime != raw_mime:
+        _LOGGER.info(
+            "MIME type '%s' is not supported by the Unique KB; "
+            "uploading '%s' as 'text/plain' so the file can be stored and downloaded.",
+            raw_mime,
+            file.filename,
+        )
+
+    return await _upload_artifact_bytes(
+        chat_service=chat_service,
+        file=file,
+        file_bytes=file_bytes,
+        mime=mime,
     )
 
 

unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/generated_files.py

@@ -117,6 +117,15 @@ class DisplayCodeInterpreterFilesPostProcessorConfig(BaseModel):
         "Applies per SDK attempt. The OpenAI SDK default of 600s is too generous "
         "for small generated files; a shorter timeout lets us retry sooner.",
     )
+    attach_office_preview: SkipJsonSchema[bool] = Field(
+        default=False,
+        description=(
+            "When True, convert Word/PowerPoint/Excel artifacts to a sibling "
+            "PDF and attach it as the chat side-panel preview. Default False "
+            "keeps the historical bytes-only upload. Conversion is best-effort "
+            "and falls back to the original file."
+        ),
+    )
 
 
 class _ContentInfo(NamedTuple):
@@ -762,6 +771,7 @@ class DisplayCodeInterpreterFilesPostProcessor(
                 chat_service=self._chat_service,
                 file=container_file,
                 file_bytes=file_bytes,
+                attach_office_preview=self._config.attach_office_preview,
             )
             upload_ms = (time.monotonic() - upload_t0) * 1000
             if upload_ms > 2000:

unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/office_preview.py

@@ -0,0 +1,154 @@
+"""LibreOffice PDF previews for code-interpreter Office artifacts.
+
+When the OpenAI code interpreter emits a Word, PowerPoint, or Excel file,
+the chat UI can render a sibling PDF in the side panel far more reliably
+than the Office binary. Conversion is best-effort: if ``soffice`` is
+missing, times out, or rejects the file, callers upload the original
+without a preview.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+_SOFFICE_TIMEOUT_SECONDS = 180
+
+# Canonical MIME types so slim containers without ``/etc/mime.types`` still
+# upload Office files with a KB-accepted type instead of falling back to
+# ``text/plain`` via ``mimetypes.guess_type``.
+OFFICE_PREVIEW_MIME_TYPES: dict[str, str] = {
+    ".doc": "application/msword",
+    ".docx": (
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+    ),
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".pptx": (
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+    ),
+    ".xls": "application/vnd.ms-excel",
+    ".xlsx": ("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"),
+}
+
+
+def office_extension(filename: str) -> str | None:
+    """Return the lowercased Office suffix, or ``None`` if not previewable."""
+    suffix = Path(filename).suffix.lower()
+    return suffix if suffix in OFFICE_PREVIEW_MIME_TYPES else None
+
+
+def _resolve_soffice_binary() -> str | None:
+    return shutil.which("soffice") or shutil.which("libreoffice")
+
+
+def _run_soffice(
+    soffice: str,
+    source: Path,
+    output_dir: Path,
+    logger: logging.Logger,
+) -> None:
+    """Invoke headless ``soffice`` to convert *source* into *output_dir*.
+
+    Uses an isolated ``UserInstallation`` profile so concurrent LibreOffice
+    invocations do not collide on ``$HOME/.config/libreoffice``.
+    """
+    with tempfile.TemporaryDirectory(
+        prefix=".libreoffice-profile-",
+        dir=output_dir,
+    ) as profile_dir:
+        proc = subprocess.run(
+            [
+                soffice,
+                f"-env:UserInstallation={Path(profile_dir).resolve().as_uri()}",
+                "--headless",
+                "--convert-to",
+                "pdf",
+                "--outdir",
+                str(output_dir),
+                str(source),
+            ],
+            capture_output=True,
+            text=True,
+            timeout=_SOFFICE_TIMEOUT_SECONDS,
+        )
+    if proc.returncode != 0:
+        logger.warning(
+            "office_preview: soffice exited %d for '%s' "
+            "(stdout=%d bytes, stderr=%d bytes)",
+            proc.returncode,
+            source.name,
+            len((proc.stdout or "").strip()),
+            len((proc.stderr or "").strip()),
+        )
+        raise subprocess.CalledProcessError(
+            proc.returncode, proc.args, proc.stdout, proc.stderr
+        )
+
+
+async def convert_office_bytes_to_preview_pdf(
+    filename: str,
+    file_bytes: bytes,
+    tmp_dir: Path,
+    logger: logging.Logger,
+) -> Path | None:
+    """Write *file_bytes* into *tmp_dir* and convert to a sibling preview PDF.
+
+    The original file is written as ``tmp_dir / Path(filename).name`` so the
+    caller can pass that path to the SDK uploader. The preview is rendered
+    into ``tmp_dir / .previews / <stem>.pdf`` so it cannot collide with a
+    same-named PDF the interpreter also produced.
+
+    Returns the preview path, or ``None`` when conversion is unavailable or
+    fails. Never raises for expected conversion problems.
+    """
+    safe_filename = Path(filename).name
+    source_path = tmp_dir / safe_filename
+    source_path.write_bytes(file_bytes)
+
+    soffice = _resolve_soffice_binary()
+    if soffice is None:
+        logger.warning(
+            "office_preview: soffice/libreoffice not found on PATH — "
+            "uploading '%s' without a PDF preview.",
+            safe_filename,
+        )
+        return None
+
+    previews_dir = tmp_dir / ".previews"
+    previews_dir.mkdir(exist_ok=True)
+    target = previews_dir / f"{source_path.stem}.pdf"
+
+    try:
+        await asyncio.to_thread(
+            _run_soffice, soffice, source_path, previews_dir, logger
+        )
+    except subprocess.TimeoutExpired:
+        logger.warning(
+            "office_preview: soffice timed out after %ds for '%s' — "
+            "uploading original only",
+            _SOFFICE_TIMEOUT_SECONDS,
+            safe_filename,
+        )
+        return None
+    except subprocess.CalledProcessError:
+        return None
+    except Exception:
+        logger.exception(
+            "office_preview: unexpected error for '%s' — uploading original only",
+            safe_filename,
+        )
+        return None
+
+    if target.is_file():
+        return target
+
+    logger.warning(
+        "office_preview: soffice returned 0 but '%s' is missing for '%s'",
+        target.name,
+        safe_filename,
+    )
+    return None

unique_toolkit/language_model/invocation_stats.py

@@ -3,9 +3,18 @@
 Lives in its own module (not ``schemas.py``) because it needs
 ``LanguageModelName`` from ``infos.py``, which itself imports from
 ``schemas.py``.
+
+:class:`InvocationStatsCollector` collects those stats for one namespaced
+run. ``record_token_usage`` swallows all exceptions around parsing and
+:meth:`LanguageModelInvocationStats.from_usage`: usage is optional
+billing metadata and must not abort a tool run.
 """
 
-from typing import Annotated, Self
+import logging
+from collections.abc import Iterable, Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from typing import Annotated, Any, Self
 
 from humps import camelize
 from pydantic import BaseModel, BeforeValidator, ConfigDict
@@ -14,6 +23,8 @@ from unique_toolkit.language_model.infos import LanguageModelName
 from unique_toolkit.language_model.model_costs import calculate_invocation_cost_usd
 from unique_toolkit.language_model.schemas import LanguageModelTokenUsage
 
+_LOGGER = logging.getLogger(__name__)
+
 # `protected_namespaces=()` allows the `model_name` field name.
 model_config = ConfigDict(
     alias_generator=camelize,
@@ -75,3 +86,88 @@ class LanguageModelInvocationStats(BaseModel):
             source=source,
             cost_usd=calculate_invocation_cost_usd(str(model_name), token_usage),
         )
+
+
+class InvocationStatsCollector:
+    """Run-scoped collector with a namespaced ContextVar so nested tools don't mix.
+
+    Instantiate once per namespace and share that instance.
+    """
+
+    def __init__(self, namespace: str) -> None:
+        self._namespace = namespace
+        self._var: ContextVar[list[LanguageModelInvocationStats] | None] = ContextVar(
+            f"{namespace}_invocation_stats", default=None
+        )
+
+    @contextmanager
+    def scope(self) -> Iterator[list[LanguageModelInvocationStats]]:
+        """Collect stats for one run and isolate concurrent runs."""
+        invocation_stats: list[LanguageModelInvocationStats] = []
+        token: Token[list[LanguageModelInvocationStats] | None] = self._var.set(
+            invocation_stats
+        )
+        try:
+            yield invocation_stats
+        finally:
+            self._var.reset(token)
+
+    def record_invocation_stats(
+        self,
+        invocation_stats: Iterable[LanguageModelInvocationStats],
+    ) -> None:
+        """Record already-built stats when a run scope is active. No-op otherwise."""
+        current_invocation_stats = self._var.get()
+        if current_invocation_stats is not None:
+            current_invocation_stats.extend(invocation_stats)
+
+    def record_token_usage(
+        self,
+        *,
+        model_name: str,
+        usage: Any,
+        source: str,
+    ) -> None:
+        """Record provider usage when a run scope and usage are available.
+
+        Swallows all exceptions: this metadata is optional and must not abort
+        the calling tool.
+        """
+        invocation_stats = self._var.get()
+        if invocation_stats is None or usage is None:
+            return
+
+        try:
+            token_usage = LanguageModelTokenUsage.model_validate(usage)
+            invocation_stats.append(
+                LanguageModelInvocationStats.from_usage(
+                    model_name=model_name,
+                    token_usage=token_usage,
+                    source=source,
+                )
+            )
+        except Exception:
+            _LOGGER.warning(
+                "Unable to parse %s token usage for %s",
+                self._namespace,
+                source,
+                exc_info=True,
+            )
+
+    def record_language_model_response(
+        self,
+        *,
+        model_name: str,
+        response: Any,
+        source: str,
+    ) -> None:
+        """Record usage from ``.usage``, ``.usage_metadata``, or ``response_metadata``."""
+        usage = getattr(response, "usage", None)
+        if usage is None:
+            usage = getattr(response, "usage_metadata", None)
+        if usage is None:
+            response_metadata = getattr(response, "response_metadata", None)
+            if isinstance(response_metadata, dict):
+                usage = response_metadata.get("token_usage")
+
+        self.record_token_usage(model_name=model_name, usage=usage, source=source)

{unique_toolkit-2026.36.0.dev3.dist-info → unique_toolkit-2026.36.0.dev5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 2026.36.0.dev3
+Version: 2026.36.0.dev5
 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>

{unique_toolkit-2026.36.0.dev3.dist-info → unique_toolkit-2026.36.0.dev5.dist-info}/RECORD

@@ -216,9 +216,10 @@ unique_toolkit/agentic/tools/openai_builtin/code_interpreter/builder/_memory.py,
 unique_toolkit/agentic/tools/openai_builtin/code_interpreter/builder/builder.py,sha256=QFvfJT7PE6XIf1mftURptTevOmYBp5Ln_eIsro5O7s8,6546
 unique_toolkit/agentic/tools/openai_builtin/code_interpreter/config.py,sha256=C4Vrj_xLgLB8AEUz-cp0JpXAIwYwz-VaSRh-xAG7PW8,2381
 unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/__init__.py,sha256=SzEiUqxIw8D4_51SvTt-8oTOYTGirYkmH4J6SgojzME,634
-unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/artifacts.py,sha256=wAgDrcXZbCdDbNWNpbMigBUXySzbKQXSfg3KsZfAWfs,3115
+unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/artifacts.py,sha256=0ZnEOh8aKH-oUPPXWR3yeVuf_IxKZSxg8GLtEcpG_fA,6832
 unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/code_display.py,sha256=WC__H2lhprchVVKsQzPeckhq-EcYg1ePYtrHIAoVzpQ,3165
-unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/generated_files.py,sha256=CJ9qVZ720ekyYUyUezsXpQEteNcmYJxw_Jb-JRdhSqI,63127
+unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/generated_files.py,sha256=7jvYG13oYI00ohrvTnrqIJszkRBZVbTSjtcjEtlEEGQ,63610
+unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/office_preview.py,sha256=5DtJWkzJwEFsh2uyHjT5qU5G277qXaHun1JRCYVhZFE,4951
 unique_toolkit/agentic/tools/openai_builtin/code_interpreter/schemas.py,sha256=W7egCmYrPrzic0aXsu9wY5fvQ8y_cl4Tzq_cjVs0mZs,542
 unique_toolkit/agentic/tools/openai_builtin/code_interpreter/tool/__init__.py,sha256=r6yXmGTLJzXNq5laHOlre9veu--VbCQVlDRVm2QUGzI,326
 unique_toolkit/agentic/tools/openai_builtin/code_interpreter/tool/config.py,sha256=sbLV-fYt_veBAdonqAHY9sm-eHxpjIZgc1KVbm03pZY,19042
@@ -393,7 +394,7 @@ unique_toolkit/language_model/constants.py,sha256=B-topqW0r83dkC_25DeQfnPk3n53qz
 unique_toolkit/language_model/default_language_model.py,sha256=mcyuFs_V6tp52C8xJSHiEHO4kFGj6xed1gvozvCRD7k,1181
 unique_toolkit/language_model/functions.py,sha256=W6JC4LUh-LZ9waDgph--xVmKeQ7Ls6NRAqDx9DwQdeY,26691
 unique_toolkit/language_model/infos.py,sha256=zs0UFhds4UkSRr3zxyTJ-jJ9u2O2x9VgZx3a9d4zbYU,146221
-unique_toolkit/language_model/invocation_stats.py,sha256=XAM_qckI-BoMBSgDpVcxFD1cFSdi1-GHZToHz_jLynM,2491
+unique_toolkit/language_model/invocation_stats.py,sha256=CQbpUz394IsVd8eNTB1gPSMt5f0UXmkN1amNsqtAW6U,5857
 unique_toolkit/language_model/model_costs.py,sha256=WM1u2fWAKpPB_creS-ew8YAzc1V8oiaCbvhpSJaO8B0,3789
 unique_toolkit/language_model/prompt.py,sha256=JSawaLjQg3VR-E2fK8engFyJnNdk21zaO8pPIodzN4Q,3991
 unique_toolkit/language_model/reference.py,sha256=T3wr2jP_uRg5wKVIbKqLbxJlcgxfbZQGq3XdjbQ2kSo,6984
@@ -420,6 +421,6 @@ unique_toolkit/short_term_memory/service.py,sha256=2JMBEBn6GoyK-a0xvdcWpPft-3C74
 unique_toolkit/smart_rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 unique_toolkit/smart_rules/compile.py,sha256=vRe0aMJWuVIK-VsqomgxQImzke7MDmwgSxxJfYCa7zw,1386
 unique_toolkit/test_utilities/events.py,sha256=FLrhMh0A_mQutAUjoD0FdMcVQ4Gq31r35OVGzRjvLro,6760
-unique_toolkit-2026.36.0.dev3.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
-unique_toolkit-2026.36.0.dev3.dist-info/METADATA,sha256=N_GK3be7pU2tpG8QFDTk617VgXay6etkRsmYpX3qPsg,7821
-unique_toolkit-2026.36.0.dev3.dist-info/RECORD,,
+unique_toolkit-2026.36.0.dev5.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+unique_toolkit-2026.36.0.dev5.dist-info/METADATA,sha256=XnRiUVEB6mURHDnoA_QevRw7qH1IadNMN1XBKSUgiLg,7821
+unique_toolkit-2026.36.0.dev5.dist-info/RECORD,,