unique_toolkit 1.64.7__tar.gz → 1.65.0__tar.gz

{unique_toolkit-1.64.7 → unique_toolkit-1.65.0}/PKG-INFO

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

{unique_toolkit-1.64.7 → unique_toolkit-1.65.0}/pyproject.toml

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

unique_toolkit-1.65.0/unique_toolkit/agentic/tools/experimental/__init__.py

@@ -0,0 +1,11 @@
+from unique_toolkit.agentic.tools.experimental.open_file_tool import (
+    OpenFileTool,
+    OpenFileToolRuntime,
+    OpenFileToolRuntimeConfig,
+)
+
+__all__ = [
+    "OpenFileTool",
+    "OpenFileToolRuntime",
+    "OpenFileToolRuntimeConfig",
+]

unique_toolkit-1.65.0/unique_toolkit/agentic/tools/experimental/open_file_tool/__init__.py

@@ -0,0 +1,11 @@
+from unique_toolkit.agentic.tools.experimental.open_file_tool.runtime import (
+    OpenFileToolRuntime,
+    OpenFileToolRuntimeConfig,
+)
+from unique_toolkit.agentic.tools.experimental.open_file_tool.tool import OpenFileTool
+
+__all__ = [
+    "OpenFileTool",
+    "OpenFileToolRuntime",
+    "OpenFileToolRuntimeConfig",
+]

unique_toolkit-1.65.0/unique_toolkit/agentic/tools/experimental/open_file_tool/config.py

@@ -0,0 +1,97 @@
+from typing import Annotated
+
+from pydantic import Field
+
+from unique_toolkit._common.pydantic.rjsf_tags import RJSFMetaTag
+from unique_toolkit.agentic.tools.schemas import BaseToolConfig
+
+DEFAULT_TOOL_DESCRIPTION = """Open one or more documents so you can read and reason over their full content. ALWAYS call this tool for any file you want to answer questions about — the text chunks from InternalSearch are lossy extracts and miss tables, charts, layout, and context. Opening the full file gives you far superior information.
+"""
+
+DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT = """When the user asks you to work with, analyze, summarize, or reason over a document, you MUST open it with OpenFile before answering. The text chunks returned by InternalSearch are extracted fragments — they lose tables, charts, formatting, and cross-page context. Opening the full file gives you the complete document with all visual and structural information intact.
+
+Workflow:
+1. Use InternalSearch to find relevant documents and identify their content_ids.
+2. Call OpenFile with the content_ids of the files you need.
+3. The full files will be available in the next iteration for you to read.
+4. Answer the user's question using the full file content, referencing the InternalSearch source numbers for citations.
+
+You should still cite source numbers from InternalSearch in your answer (e.g. [source0]), but base your reasoning on the full opened file when available.
+"""
+
+DEFAULT_TOOL_PARAMETER_CONTENT_IDS_DESCRIPTION = """List of content_ids of the documents to open. Each content_id is found in search results as the 'content_id' field (starts with 'cont_')."""
+
+
+class OpenFileToolConfig(BaseToolConfig):
+    """Configuration for the OpenFile tool."""
+
+    enabled: Annotated[
+        bool,
+        RJSFMetaTag.BooleanWidget.checkbox(
+            help=(
+                "Master switch for all Open File Tool. When disabled, "
+                "none of the other flags in this config block take effect."
+            ),
+        ),
+    ] = Field(
+        default=False,
+        description="Enable the Open File Tool.",
+    )
+
+    send_files_in_payload: Annotated[
+        bool,
+        RJSFMetaTag.BooleanWidget.checkbox(
+            help=(
+                "Enable the OpenFile tool for knowledge-base files. When the agent "
+                "finds files via InternalSearch, it can call OpenFile with the "
+                "content_id to include the full document in the LLM context "
+                "(unique://content/<id> URLs, resolved to base64 by the backend). "
+                "Only takes effect when use_responses_api is also True."
+            ),
+        ),
+    ] = Field(
+        default=False,
+        description="Enable the OpenFile tool for knowledge-base files.",
+    )
+
+    send_uploaded_files_in_payload: Annotated[
+        bool,
+        RJSFMetaTag.BooleanWidget.checkbox(
+            help=(
+                "Attach uploaded files directly to the LLM payload as full "
+                "documents (unique://content/<id> URLs, resolved to base64 by the "
+                "backend). When enabled, uploaded files bypass InternalSearch and "
+                "are included automatically from iteration 1. "
+                "Only takes effect when use_responses_api is also True."
+            ),
+        ),
+    ] = Field(
+        default=False,
+        description="Attach uploaded files directly to the LLM payload.",
+    )
+
+    tool_description: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(rows=3),
+    ] = Field(
+        default=DEFAULT_TOOL_DESCRIPTION,
+        description="The description of the tool that will be included in the system prompt.",
+    )
+
+    tool_description_for_system_prompt: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(rows=7),
+    ] = Field(
+        default=DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT,
+        description="The description of the tool that will be included in the system prompt.",
+    )
+
+    tool_parameter_description_content_ids: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(
+            rows=len(DEFAULT_TOOL_PARAMETER_CONTENT_IDS_DESCRIPTION.split("\n"))
+        ),
+    ] = Field(
+        default=DEFAULT_TOOL_PARAMETER_CONTENT_IDS_DESCRIPTION,
+        description="The description of the tool parameter 'content_ids'.",
+    )

unique_toolkit-1.65.0/unique_toolkit/agentic/tools/experimental/open_file_tool/runtime.py

@@ -0,0 +1,390 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from logging import Logger
+from typing import Any
+
+from unique_toolkit.agentic.evaluation.schemas import EvaluationMetricName
+from unique_toolkit.agentic.message_log_manager.service import MessageStepLogger
+from unique_toolkit.agentic.tools.tool_manager import (
+    ResponsesApiToolManager,
+    ToolManager,
+)
+from unique_toolkit.content.schemas import Content
+from unique_toolkit.language_model.schemas import (
+    LanguageModelAssistantMessage,
+    LanguageModelFunction,
+    LanguageModelMessageRole,
+    LanguageModelMessages,
+    LanguageModelToolMessage,
+    LanguageModelUserMessage,
+)
+
+
+@dataclass(frozen=True)
+class OpenFileToolRuntimeConfig:
+    """Flat configuration for the OpenFileTool runtime.
+
+    The orchestrator is responsible for mapping its own nested config
+    (e.g. ``UniqueAIConfig``) into this structure.
+    """
+
+    enabled: bool = False
+    send_files_in_payload: bool = False
+    send_uploaded_files_in_payload: bool = False
+    use_responses_api: bool = False
+
+
+class OpenFileToolRuntime:
+    """Runtime helper for the experimental OpenFile payload flow."""
+
+    _OPEN_FILE_TOOL_NAME = "OpenFile"
+    _RETRY_SIGNALS = (
+        "too large",
+        "payload too large",
+        "request entity too large",
+        "content_length_exceeded",
+        "max_tokens",
+        "context_length_exceeded",
+        "413",
+        "request too large",
+        "403 forbidden",
+        "application-gateway",
+    )
+    _FILE_TOO_LARGE_TOOL_RESPONSE = (
+        "ERROR: The file is too large to open. "
+        "Could not include the document in the context. "
+        "Please inform the user that the file is too large to process directly "
+        "and suggest asking an admin to include the document in the knowledge base."
+    )
+    _OPEN_FILE_SYSTEM_REMINDER = (
+        "<|system_reminder|>Documents were found in the search results. "
+        "For any file you want to reference or reason over, call the OpenFile tool "
+        "with the content_id from the search results. The document name is shown "
+        "inside <|document|>...<|/document|> tags in the content field. "
+        "The full file provides far better information than the extracted text "
+        "chunks (tables, charts, layout, and cross-page context are preserved)."
+        "<|/system_reminder|>"
+    )
+
+    def __init__(
+        self,
+        logger: Logger,
+        config: OpenFileToolRuntimeConfig,
+        content_service: Any,
+        tool_manager: ResponsesApiToolManager | ToolManager,
+        message_step_logger: MessageStepLogger,
+        agent_file_registry: list[str],
+    ) -> None:
+        self._logger = logger
+        self._config = config
+        self._content_service = content_service
+        self._tool_manager = tool_manager
+        self._message_step_logger = message_step_logger
+        self._agent_file_registry = agent_file_registry
+        self._cached_uploaded_documents: list[Content] | None = None
+        self._file_payload_attachments_disabled = False
+
+    def should_attach_content_files(self) -> bool:
+        if self._file_payload_attachments_disabled:
+            return False
+
+        return self._is_feature_enabled() and (
+            self._kb_file_payload_enabled() or self._uploaded_file_payload_enabled()
+        )
+
+    def inject_content_files_into_user_message(
+        self, messages: LanguageModelMessages
+    ) -> LanguageModelMessages:
+        file_parts = self._collect_content_file_parts()
+        if not file_parts:
+            return messages
+
+        for index in range(len(messages.root) - 1, -1, -1):
+            message = messages.root[index]
+            if message.role != LanguageModelMessageRole.USER:
+                continue
+
+            content_parts: list[dict[str, Any]] = []
+            if isinstance(message.content, str):
+                content_parts.append({"type": "text", "text": message.content})
+            elif isinstance(message.content, list):
+                content_parts.extend(
+                    part for part in message.content if isinstance(part, dict)
+                )
+
+            if not content_parts:
+                content_parts = [{"type": "text", "text": ""}]
+
+            messages.root[index] = LanguageModelUserMessage(
+                content=content_parts + file_parts
+            )
+            break
+
+        return messages
+
+    def should_retry_without_files(self, exc: Exception) -> bool:
+        if self._file_payload_attachments_disabled:
+            return False
+        if not self._is_feature_enabled():
+            return False
+        if (
+            not self._kb_file_payload_enabled()
+            and not self._uploaded_file_payload_enabled()
+        ):
+            return False
+
+        has_kb_files = self._kb_file_payload_enabled() and bool(
+            self._agent_file_registry
+        )
+        has_uploaded_files = self._uploaded_file_payload_enabled() and bool(
+            self._get_uploaded_documents()
+        )
+        if not has_kb_files and not has_uploaded_files:
+            return False
+
+        error_text = str(exc).lower()
+        return any(signal in error_text for signal in self._RETRY_SIGNALS)
+
+    def prepare_retry_messages(
+        self, messages: LanguageModelMessages
+    ) -> LanguageModelMessages:
+        self._tool_manager.exclude_tool(self._OPEN_FILE_TOOL_NAME)
+        self._file_payload_attachments_disabled = True
+
+        messages = self.strip_file_parts_from_messages(messages)
+
+        if self._kb_file_payload_enabled():
+            self._strip_open_file_messages(messages)
+        if self._uploaded_file_payload_enabled():
+            self._inject_uploaded_file_fallback_messages(messages)
+
+        self._agent_file_registry.clear()
+        return messages
+
+    async def report_file_fallback_step(self) -> None:
+        await self._message_step_logger.create_message_log_entry_async(
+            text=(
+                "**Open File:** The file is too large to open. "
+                "Please ask an admin to include the document in the knowledge base."
+            ),
+            references=[],
+        )
+
+    def filter_evaluation_names(
+        self, evaluation_names: list[EvaluationMetricName]
+    ) -> list[EvaluationMetricName]:
+        if not self._agent_file_registry:
+            return evaluation_names
+
+        filtered_names = [
+            name
+            for name in evaluation_names
+            if name != EvaluationMetricName.HALLUCINATION
+        ]
+        if len(filtered_names) != len(evaluation_names):
+            self._logger.info(
+                "OpenFile was used - skipping hallucination check "
+                "(LLM has full file content, not just search chunks)."
+            )
+        return filtered_names
+
+    def inject_open_file_reminder(self, tool_call_responses: list[Any]) -> None:
+        if not self._tool_manager.get_tool_by_name(self._OPEN_FILE_TOOL_NAME):
+            return
+
+        for response in tool_call_responses:
+            if response.name != "InternalSearch":
+                continue
+
+            has_pdf_chunks = any(
+                chunk.key and chunk.key.split(" : ")[0].lower().endswith(".pdf")
+                for chunk in (response.content_chunks or [])
+            )
+            if not has_pdf_chunks:
+                continue
+
+            existing_reminder = response.system_reminder or ""
+            response.system_reminder = (
+                f"{existing_reminder}\n{self._OPEN_FILE_SYSTEM_REMINDER}".strip()
+            )
+
+    def get_uploaded_documents(self) -> list[Content]:
+        return self._get_uploaded_documents()
+
+    @staticmethod
+    def strip_file_parts_from_messages(
+        messages: LanguageModelMessages,
+    ) -> LanguageModelMessages:
+        for index, message in enumerate(messages.root):
+            if message.role != LanguageModelMessageRole.USER:
+                continue
+            if not isinstance(message.content, list):
+                continue
+
+            content_parts = [
+                part
+                for part in message.content
+                if not (isinstance(part, dict) and part.get("type") == "file")
+            ]
+            if len(content_parts) == len(message.content):
+                continue
+
+            messages.root[index] = LanguageModelUserMessage(content=content_parts)
+
+        return messages
+
+    def _is_feature_enabled(self) -> bool:
+        return self._config.use_responses_api and self._config.enabled
+
+    def _kb_file_payload_enabled(self) -> bool:
+        return self._config.send_files_in_payload
+
+    def _uploaded_file_payload_enabled(self) -> bool:
+        return self._config.send_uploaded_files_in_payload
+
+    def _get_uploaded_documents(self) -> list[Content]:
+        if self._cached_uploaded_documents is None:
+            now = datetime.now(timezone.utc)
+            all_documents = self._content_service.get_documents_uploaded_to_chat()
+            uploaded_documents = [
+                document
+                for document in all_documents
+                if (document.expired_at is None or document.expired_at > now)
+                and document.key.lower().endswith(".pdf")
+            ]
+            self._cached_uploaded_documents = sorted(
+                uploaded_documents,
+                key=lambda document: (
+                    document.created_at is None,
+                    document.created_at or datetime.max.replace(tzinfo=timezone.utc),
+                ),
+            )
+        return self._cached_uploaded_documents
+
+    def _collect_content_file_parts(self) -> list[dict[str, dict[str, str] | str]]:
+        if self._file_payload_attachments_disabled:
+            return []
+
+        seen_ids: set[str] = set()
+        file_parts: list[dict[str, dict[str, str] | str]] = []
+
+        if self._uploaded_file_payload_enabled():
+            for document in self._get_uploaded_documents():
+                if not document.id or document.id in seen_ids:
+                    continue
+
+                seen_ids.add(document.id)
+                file_parts.append(
+                    {
+                        "type": "file",
+                        "file": {
+                            "filename": document.key or document.id,
+                            "file_data": f"unique://content/{document.id}",
+                        },
+                    }
+                )
+
+        if self._kb_file_payload_enabled():
+            for content_id in self._agent_file_registry:
+                if content_id in seen_ids:
+                    continue
+
+                seen_ids.add(content_id)
+                file_parts.append(
+                    {
+                        "type": "file",
+                        "file": {
+                            "filename": content_id,
+                            "file_data": f"unique://content/{content_id}",
+                        },
+                    }
+                )
+
+        return file_parts
+
+    @staticmethod
+    def _is_empty_assistant_content(
+        content: str | list[dict[str, Any]] | None,
+    ) -> bool:
+        if content is None:
+            return True
+        if isinstance(content, str):
+            return not content.strip()
+        if isinstance(content, list):
+            return len(content) == 0
+        return False
+
+    def _strip_open_file_messages(self, messages: LanguageModelMessages) -> None:
+        open_file_call_ids: set[str] = set()
+
+        for message in messages.root:
+            if not isinstance(message, LanguageModelAssistantMessage):
+                continue
+            if not message.tool_calls:
+                continue
+
+            for tool_call in message.tool_calls:
+                if tool_call.function.name == self._OPEN_FILE_TOOL_NAME:
+                    open_file_call_ids.add(tool_call.id or tool_call.function.id)
+
+        if not open_file_call_ids:
+            return
+
+        messages.root[:] = [
+            message
+            for message in messages.root
+            if not (
+                isinstance(message, LanguageModelToolMessage)
+                and message.tool_call_id in open_file_call_ids
+            )
+        ]
+
+        for message in messages.root:
+            if not isinstance(message, LanguageModelAssistantMessage):
+                continue
+            if not message.tool_calls:
+                continue
+
+            message.tool_calls = [
+                tool_call
+                for tool_call in message.tool_calls
+                if tool_call.function.name != self._OPEN_FILE_TOOL_NAME
+            ]
+            if not message.tool_calls:
+                message.tool_calls = None
+
+        messages.root[:] = [
+            message
+            for message in messages.root
+            if not (
+                isinstance(message, LanguageModelAssistantMessage)
+                and not message.tool_calls
+                and self._is_empty_assistant_content(message.content)
+            )
+        ]
+
+    def _inject_uploaded_file_fallback_messages(
+        self, messages: LanguageModelMessages
+    ) -> None:
+        uploaded_documents = self._get_uploaded_documents()
+        if not uploaded_documents:
+            return
+
+        content_ids = [document.id for document in uploaded_documents if document.id]
+        if not content_ids:
+            return
+
+        function = LanguageModelFunction(
+            name=self._OPEN_FILE_TOOL_NAME,
+            arguments={"content_ids": content_ids},
+        )
+        assistant_message = LanguageModelAssistantMessage.from_functions([function])
+        tool_message = LanguageModelToolMessage(
+            content=self._FILE_TOO_LARGE_TOOL_RESPONSE,
+            name=self._OPEN_FILE_TOOL_NAME,
+            tool_call_id=function.id,
+        )
+        messages.root.append(assistant_message)
+        messages.root.append(tool_message)

unique_toolkit-1.65.0/unique_toolkit/agentic/tools/experimental/open_file_tool/tool.py

@@ -0,0 +1,108 @@
+from unique_toolkit.agentic.evaluation.schemas import EvaluationMetricName
+from unique_toolkit.agentic.tools.experimental.open_file_tool.config import (
+    OpenFileToolConfig,
+)
+from unique_toolkit.agentic.tools.factory import ToolFactory
+from unique_toolkit.agentic.tools.schemas import ToolCallResponse
+from unique_toolkit.agentic.tools.tool import Tool
+from unique_toolkit.app.schemas import ChatEvent
+from unique_toolkit.language_model.schemas import (
+    LanguageModelFunction,
+    LanguageModelToolDescription,
+)
+
+
+class OpenFileTool(Tool[OpenFileToolConfig]):
+    """Tool that lets the agent open a knowledge-base file so the full document
+    is included in the LLM payload (unique://content/<id> URL).
+
+    The agent calls this with the content_id it sees in search results.  The
+    shared registry is then read by OpenFileToolRuntime on every subsequent
+    loop iteration.
+    """
+
+    name = "OpenFile"
+
+    def __init__(
+        self,
+        event: ChatEvent,
+        registry: list[str],
+        config: OpenFileToolConfig,
+    ) -> None:
+        super().__init__(config, event)
+        self._registry = registry
+
+    def display_name(self) -> str:
+        return "Open File"
+
+    def tool_description(self) -> LanguageModelToolDescription:
+        return LanguageModelToolDescription(
+            name=self.name,
+            description=self.config.tool_description,
+            parameters={
+                "type": "object",
+                "properties": {
+                    "content_ids": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": self.config.tool_parameter_description_content_ids,
+                    }
+                },
+                "required": ["content_ids"],
+            },
+        )
+
+    def tool_description_for_system_prompt(self) -> str:
+        return self.config.tool_description_for_system_prompt
+
+    async def run(self, tool_call: LanguageModelFunction) -> ToolCallResponse:
+        args = tool_call.arguments or {}
+        content_ids: list[str] = args.get("content_ids", [])
+
+        if not isinstance(content_ids, list) or not content_ids:
+            return ToolCallResponse(
+                id=tool_call.id,  # type: ignore
+                name=self.name,
+                error_message="content_ids must be a non-empty list of content IDs.",
+            )
+
+        invalid = [cid for cid in content_ids if not cid.startswith("cont_")]
+        if invalid:
+            return ToolCallResponse(
+                id=tool_call.id,  # type: ignore
+                name=self.name,
+                error_message=(
+                    f"Invalid content_id(s): {invalid}. "
+                    "All IDs must start with 'cont_'."
+                ),
+            )
+
+        added = []
+        for content_id in content_ids:
+            if content_id not in self._registry:
+                self._registry.append(content_id)
+                added.append(content_id)
+
+        already = [cid for cid in content_ids if cid not in added]
+        parts = []
+        if added:
+            parts.append(f"Added: {added}")
+        if already:
+            parts.append(f"Already registered: {already}")
+
+        return ToolCallResponse(
+            id=tool_call.id,  # type: ignore
+            name=self.name,
+            content=f"Files will be included in the LLM context. {' | '.join(parts)}",
+        )
+
+    def evaluation_check_list(self) -> list[EvaluationMetricName]:
+        return []
+
+    def get_evaluation_checks_based_on_tool_response(
+        self, tool_response: ToolCallResponse
+    ) -> list[EvaluationMetricName]:
+        return []
+
+
+ToolFactory.register_tool(OpenFileTool, OpenFileToolConfig)