unique-toolkit 2026.36.0.dev3__tar.gz → 2026.36.0.dev5__tar.gz

{unique_toolkit-2026.36.0.dev3 → unique_toolkit-2026.36.0.dev5}/PKG-INFO

@@ -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 → unique_toolkit-2026.36.0.dev5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "2026.36.0.dev3"
+version = "2026.36.0.dev5"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12"

unique_toolkit-2026.36.0.dev5/unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/artifacts.py

@@ -0,0 +1,213 @@
+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"
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class CodeExecutionArtifactMetadata(BaseModel):
+    container_id: str
+    file_id: str
+    filepath: str
+
+
+def _kb_safe_mime(mime: str) -> str:
+    """Return a MIME type the Unique KB will accept.
+
+    Membership is defined by ``FileMimeType`` and ``ImageMimeType`` in
+    ``unique_toolkit._common.utils.files`` (same catalog as path-based helpers
+    like ``FileMimeType.is_valid_mime``, but here we already have a resolved
+    MIME string from ``mimetypes.guess_type``, so we use StrEnum value lookup
+    instead of re-parsing a path).
+
+    The KB GraphQL API rejects many code-file MIME types (e.g. ``text/x-python``
+    for ``.py`` files).  Anything not in those enums is coerced to
+    ``text/plain`` so the file can be stored and downloaded without changing
+    its bytes.
+
+    Other ``image/*`` subtypes (e.g. ``image/jpg``) still pass through unchanged.
+    """
+    try:
+        FileMimeType(mime)
+        return mime
+    except ValueError:
+        pass
+    try:
+        ImageMimeType(mime)
+        return mime
+    except ValueError:
+        pass
+    if mime.startswith("image/"):
+        return mime
+    return "text/plain"
+
+
+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:
+    _LOGGER.info(
+        "Uploading '%s' to knowledge base (%d bytes, mime type %s)",
+        file.filename,
+        len(file_bytes),
+        mime,
+    )
+
+    return await chat_service.upload_to_chat_from_bytes_async(
+        content=file_bytes,
+        content_name=file.filename,
+        mime_type=mime,
+        skip_ingestion=True,
+        hide_in_chat=True,
+        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,
+    )
+
+
+def load_code_execution_metadata(
+    content: Content,
+) -> CodeExecutionArtifactMetadata | None:
+    if (
+        content.metadata is None
+        or _CODE_EXECUTION_ARTIFACT_METADATA_KEY not in content.metadata
+    ):
+        return None
+
+    return CodeExecutionArtifactMetadata.model_validate(
+        content.metadata[_CODE_EXECUTION_ARTIFACT_METADATA_KEY]
+    )

{unique_toolkit-2026.36.0.dev3 → unique_toolkit-2026.36.0.dev5}/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-2026.36.0.dev5/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-2026.36.0.dev5/unique_toolkit/language_model/invocation_stats.py

@@ -0,0 +1,173 @@
+"""Per-invocation LLM usage stats with model identity.
+
+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.
+"""
+
+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
+
+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,
+    populate_by_name=True,
+    protected_namespaces=(),
+)
+
+
+def _normalize_model_name(value: object) -> object:
+    """Canonicalize model_name: known names become the enum, customs stay str.
+
+    Pydantic's smart union keeps string inputs as `str` even when they match a
+    `LanguageModelName` value, so without this the same model could appear as
+    enum or str depending on the caller.
+    """
+    if isinstance(value, str) and not isinstance(value, LanguageModelName):
+        value = value.strip()
+        if not value:
+            raise ValueError("model_name must be a non-empty model name")
+        try:
+            return LanguageModelName(value)
+        except ValueError:
+            return value
+    return value
+
+
+def _validate_source(value: object) -> object:
+    if isinstance(value, str):
+        value = value.strip()
+        if not value:
+            raise ValueError("source must be a non-empty string")
+    return value
+
+
+ModelName = Annotated[LanguageModelName | str, BeforeValidator(_normalize_model_name)]
+Source = Annotated[str, BeforeValidator(_validate_source)]
+
+
+class LanguageModelInvocationStats(BaseModel):
+    """Usage of a single LLM invocation, tied to the model that served it."""
+
+    model_config = model_config
+
+    model_name: ModelName
+    token_usage: LanguageModelTokenUsage
+    source: Source  # e.g. "main_loop", tool/evaluation/postprocessor name
+    cost_usd: float | None = None
+
+    @classmethod
+    def from_usage(
+        cls,
+        model_name: LanguageModelName | str,
+        token_usage: LanguageModelTokenUsage,
+        source: str,
+    ) -> Self:
+        return cls(
+            model_name=model_name,
+            token_usage=token_usage,
+            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/unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/artifacts.py

@@ -1,103 +0,0 @@
-import logging
-from mimetypes import guess_type
-
-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.content.schemas import Content
-
-_CODE_EXECUTION_ARTIFACT_METADATA_KEY: str = "codeExecutionArtifactMetadata"
-
-_LOGGER = logging.getLogger(__name__)
-
-
-class CodeExecutionArtifactMetadata(BaseModel):
-    container_id: str
-    file_id: str
-    filepath: str
-
-
-def _kb_safe_mime(mime: str) -> str:
-    """Return a MIME type the Unique KB will accept.
-
-    Membership is defined by ``FileMimeType`` and ``ImageMimeType`` in
-    ``unique_toolkit._common.utils.files`` (same catalog as path-based helpers
-    like ``FileMimeType.is_valid_mime``, but here we already have a resolved
-    MIME string from ``mimetypes.guess_type``, so we use StrEnum value lookup
-    instead of re-parsing a path).
-
-    The KB GraphQL API rejects many code-file MIME types (e.g. ``text/x-python``
-    for ``.py`` files).  Anything not in those enums is coerced to
-    ``text/plain`` so the file can be stored and downloaded without changing
-    its bytes.
-
-    Other ``image/*`` subtypes (e.g. ``image/jpg``) still pass through unchanged.
-    """
-    try:
-        FileMimeType(mime)
-        return mime
-    except ValueError:
-        pass
-    try:
-        ImageMimeType(mime)
-        return mime
-    except ValueError:
-        pass
-    if mime.startswith("image/"):
-        return mime
-    return "text/plain"
-
-
-async def save_code_execution_artifact(
-    chat_service: ChatService,
-    file: AnnotationContainerFileCitation,
-    file_bytes: bytes,
-) -> 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,
-        len(file_bytes),
-        mime,
-    )
-
-    return await chat_service.upload_to_chat_from_bytes_async(
-        content=file_bytes,
-        content_name=file.filename,
-        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()
-        },
-    )
-
-
-def load_code_execution_metadata(
-    content: Content,
-) -> CodeExecutionArtifactMetadata | None:
-    if (
-        content.metadata is None
-        or _CODE_EXECUTION_ARTIFACT_METADATA_KEY not in content.metadata
-    ):
-        return None
-
-    return CodeExecutionArtifactMetadata.model_validate(
-        content.metadata[_CODE_EXECUTION_ARTIFACT_METADATA_KEY]
-    )