unique-toolkit 2026.20.0.dev10__tar.gz → 2026.20.0.dev12__tar.gz

{unique_toolkit-2026.20.0.dev10 → unique_toolkit-2026.20.0.dev12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 2026.20.0.dev10
+Version: 2026.20.0.dev12
 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>
@@ -10,13 +10,13 @@ Requires-Dist: pydantic>=2.11.0,<3
 Requires-Dist: pyhumps>=3.8.0,<4
 Requires-Dist: numpy>=2.4.2,<3
 Requires-Dist: tiktoken>=0.12.0,<0.13
-Requires-Dist: tokenizers>=0.21.0,<0.22
+Requires-Dist: tokenizers>=0.21.0,<0.23
 Requires-Dist: pydantic-settings>=2.10.1,<3
 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.20.0.dev9
+Requires-Dist: unique-sdk>=2026.20.0.dev11
 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.20.0.dev10 → unique_toolkit-2026.20.0.dev12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "2026.20.0.dev10"
+version = "2026.20.0.dev12"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12"
@@ -22,13 +22,13 @@ dependencies = [
     "pyhumps>=3.8.0,<4",
     "numpy>=2.4.2,<3",
     "tiktoken>=0.12.0,<0.13",
-    "tokenizers>=0.21.0,<0.22",
+    "tokenizers>=0.21.0,<0.23",
     "pydantic-settings>=2.10.1,<3",
     "sseclient>=0.0.27,<0.0.28",
     "openai>=1.105.0,<3",
     "platformdirs>=4.0.0,<5",
     "pillow>=12.1.1",
-    "unique-sdk>=2026.20.0.dev9",
+    "unique-sdk>=2026.20.0.dev11",
     "jambo>=0.1.2,<0.2",
     "jinja2>=3.1.6,<4",
     "docxtpl>=0.20.1,<0.21",

{unique_toolkit-2026.20.0.dev10 → unique_toolkit-2026.20.0.dev12}/unique_toolkit/agentic/tools/experimental/__init__.py

@@ -3,6 +3,11 @@ from unique_toolkit.agentic.tools.experimental.open_file_tool import (
     OpenFileToolRuntime,
     OpenFileToolRuntimeConfig,
 )
+from unique_toolkit.agentic.tools.experimental.retrieve_search_scope_tool import (
+    DisplayMode,
+    RetrieveSearchScopeConfig,
+    RetrieveSearchScopeTool,
+)
 from unique_toolkit.agentic.tools.experimental.todo import (
     TodoConfig,
     TodoItem,
@@ -14,9 +19,12 @@ from unique_toolkit.agentic.tools.experimental.todo import (
 )
 
 __all__ = [
+    "DisplayMode",
     "OpenFileTool",
     "OpenFileToolRuntime",
     "OpenFileToolRuntimeConfig",
+    "RetrieveSearchScopeConfig",
+    "RetrieveSearchScopeTool",
     "TodoConfig",
     "TodoItem",
     "TodoItemInput",

unique_toolkit-2026.20.0.dev12/unique_toolkit/agentic/tools/experimental/retrieve_search_scope_tool/__init__.py

@@ -0,0 +1,13 @@
+from unique_toolkit.agentic.tools.experimental.retrieve_search_scope_tool.config import (
+    DisplayMode,
+    RetrieveSearchScopeConfig,
+)
+from unique_toolkit.agentic.tools.experimental.retrieve_search_scope_tool.tool import (
+    RetrieveSearchScopeTool,
+)
+
+__all__ = [
+    "DisplayMode",
+    "RetrieveSearchScopeConfig",
+    "RetrieveSearchScopeTool",
+]

unique_toolkit-2026.20.0.dev12/unique_toolkit/agentic/tools/experimental/retrieve_search_scope_tool/config.py

@@ -0,0 +1,118 @@
+from enum import Enum
+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
+
+
+class DisplayMode(str, Enum):
+    """How the file list is presented to the agent."""
+
+    flat = "flat"
+    tree = "tree"
+
+
+DEFAULT_TOOL_DESCRIPTION = (
+    "Retrieves the list of all file names that are currently searchable "
+    "in the knowledge base. "
+    "Generally, this tool should be called before performing internal or web search."
+)
+
+_RETURNS_FLAT = (
+    "Returns all file names that are in the currently searchable knowledge base."
+)
+_RETURNS_TREE = (
+    "Returns a folder tree of all files in the currently searchable knowledge base, "
+    "showing how they are nested in the directory structure."
+)
+
+_TOOL_SYSTEM_PROMPT_TEMPLATE = (
+    "Use RetrieveSearchScope to determine the internally searchable files "
+    "and metadata about them.\n\n"
+    "**When to call the tool:**\n"
+    "1. Before performing Internal Search, verify RetrieveSearchScope has been called. "
+    "If not: call RetrieveSearchScope.\n"
+    "2. Before performing any other search (e.g. web search) it is usually "
+    "sensible to check RetrieveSearchScope to determine if internal search "
+    "is the better option.\n"
+    "**3. Important: Only call RetrieveSearchScope ONCE per conversation.**\n\n"
+    "**How the tool works:**\n"
+    "- {returns_description}\n"
+    "- Useful metadata is passed along with the file names, e.g. openable files "
+    "come with a scope id.\n"
+    "- The return is token-limited: if the file list exceeds the budget, "
+    "the tail is truncated. (Currently, the files end up in the tail arbitrarily)\n\n"
+    "**Use the returned file list to:**\n"
+    "1. Decide whether to use Internal Search or Web Search based on whether "
+    "relevant documents exist.\n"
+    "**IMPORTANT: If the listed files indicate that they contain relevant information "
+    "to a query: ALWAYS perform internal search.**\n"
+    "2. Craft more targeted search queries using the actual file names "
+    "(a file name in the query promotes chunks from that file).\n"
+    "3. Inform the user about available sources when relevant.\n"
+    "4. Files that come with a content id can be opened with a file opener tool."
+)
+
+DEFAULT_TOOL_SYSTEM_PROMPT = _TOOL_SYSTEM_PROMPT_TEMPLATE.format(
+    returns_description=_RETURNS_FLAT,
+)
+
+
+class RetrieveSearchScopeConfig(BaseToolConfig):
+    """Configuration for the RetrieveSearchScope tool."""
+
+    enabled: Annotated[
+        bool,
+        RJSFMetaTag.BooleanWidget.checkbox(
+            help=(
+                "Enable the RetrieveSearchScope tool. When enabled, the agent "
+                "can list all files available in the knowledge base before searching."
+            ),
+        ),
+    ] = Field(
+        default=False,
+        description="Enable the RetrieveSearchScope tool.",
+    )
+
+    display_mode: DisplayMode = Field(
+        default=DisplayMode.flat,
+        description=(
+            "How to present the file list. "
+            "'flat' returns only file names; "
+            "'tree' returns the full folder hierarchy."
+        ),
+    )
+
+    tool_description: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(rows=3),
+    ] = Field(
+        default=DEFAULT_TOOL_DESCRIPTION,
+        description="The tool description shown to the language model.",
+    )
+
+    tool_description_for_system_prompt: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(
+            rows=len(DEFAULT_TOOL_SYSTEM_PROMPT.split("\n"))
+        ),
+    ] = Field(
+        default=DEFAULT_TOOL_SYSTEM_PROMPT,
+        description="Instructions injected into the system prompt to guide when the agent should call this tool.",
+    )
+
+    context_window_fraction_for_file_list: float = Field(
+        default=0.05,
+        ge=0.0,
+        le=1.0,
+        description="Fraction of the context window reserved for the file list (default 5%).",
+    )
+
+    language_model_max_input_tokens: Annotated[
+        int | None, RJSFMetaTag.SpecialWidget.hidden()
+    ] = Field(
+        default=None,
+        description="Language model maximum input tokens. Injected by the orchestrator at validation time.",
+    )

unique_toolkit-2026.20.0.dev12/unique_toolkit/agentic/tools/experimental/retrieve_search_scope_tool/tool.py

@@ -0,0 +1,191 @@
+from logging import getLogger
+
+from typing_extensions import override
+
+from unique_toolkit._common.token import count_tokens
+from unique_toolkit.agentic.evaluation.schemas import EvaluationMetricName
+from unique_toolkit.agentic.tools.experimental.retrieve_search_scope_tool.config import (
+    _RETURNS_FLAT,
+    _RETURNS_TREE,
+    DisplayMode,
+    RetrieveSearchScopeConfig,
+)
+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.unique_settings import UniqueSettings
+from unique_toolkit.chat.service import LanguageModelToolDescription
+from unique_toolkit.content.schemas import ContentInfo
+from unique_toolkit.language_model.schemas import LanguageModelFunction
+from unique_toolkit.services.factory import UniqueServiceFactory
+from unique_toolkit.services.knowledge_base import KnowledgeBaseService
+
+_LOGGER = getLogger(__name__)
+
+_OPENABLE_MIME_PREFIXES = (
+    "application/pdf",
+    "application/msword",
+    "application/vnd.ms-word",
+    "application/vnd.ms-powerpoint",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml",
+    "application/vnd.openxmlformats-officedocument.presentationml",
+)
+
+
+class RetrieveSearchScopeTool(Tool[RetrieveSearchScopeConfig]):
+    name = "RetrieveSearchScope"
+    default_display_name = "Retrieve Search Scope"
+
+    @override
+    def display_name(self) -> str:
+        return self.settings.display_name or self.default_display_name
+
+    @override
+    def tool_description(self) -> LanguageModelToolDescription:
+        return LanguageModelToolDescription(
+            name=self.name,
+            description=self.config.tool_description,
+            parameters={"type": "object", "properties": {}},
+        )
+
+    @override
+    def tool_description_for_system_prompt(self) -> str:
+        prompt = self.config.tool_description_for_system_prompt
+        if self.config.display_mode == DisplayMode.tree:
+            prompt = prompt.replace(_RETURNS_FLAT, _RETURNS_TREE)
+        return prompt
+
+    def evaluation_check_list(self) -> list[EvaluationMetricName]:
+        return []
+
+    def get_evaluation_checks_based_on_tool_response(
+        self, tool_response: ToolCallResponse
+    ) -> list[EvaluationMetricName]:
+        return []
+
+    async def _has_prior_response_in_history(self) -> bool:
+        """Check chat history for an existing RetrieveSearchScope tool response."""
+        # TODO(UN-18756 #6): When tool-call persistence is introduced, verify
+        # that the persisted response carries role="tool" and name="RetrieveSearchScope",
+        # then replace getattr with direct attribute access or adapt to the actual schema.
+        try:
+            history = await self._chat_service.get_full_history_async()
+            for msg in history:
+                if str(msg.role) == "tool" and getattr(msg, "name", None) == self.name:
+                    return True
+        except Exception:
+            _LOGGER.debug(
+                "Could not check history for prior tool response", exc_info=True
+            )
+        return False
+
+    @staticmethod
+    def _format_entry(ci: ContentInfo, prefix: str = "") -> str:
+        if ci.mime_type.startswith(_OPENABLE_MIME_PREFIXES) and ci.id:
+            name_part = f"{ci.key} ({ci.id})"
+        else:
+            name_part = ci.key
+        return f"{prefix}/{name_part}" if prefix else name_part
+
+    async def _build_flat_entries(self, kb_service: KnowledgeBaseService) -> list[str]:
+        content_infos = await kb_service.get_content_infos_async(
+            metadata_filter=kb_service._metadata_filter,
+        )
+        return [self._format_entry(ci) for ci in content_infos]
+
+    async def _build_tree_entries(self, kb_service: KnowledgeBaseService) -> list[str]:
+        resolved = await kb_service.resolve_visible_file_paths_async(
+            metadata_filter=kb_service._metadata_filter,
+        )
+        entries: list[str] = []
+        for ci, path_segments in resolved:
+            folder_path = "/".join(
+                seg for seg in path_segments[:-1] if seg != "_no_folder_path"
+            )
+            entries.append(self._format_entry(ci, prefix=folder_path))
+        return entries
+
+    @override
+    async def run(self, tool_call: LanguageModelFunction) -> ToolCallResponse:
+        if await self._has_prior_response_in_history():
+            return ToolCallResponse(
+                id=tool_call.id or "unknown_id",
+                name=self.name,
+                content="RetrieveSearchScope has already been called in this conversation. "
+                "Refer to the earlier result.",
+            )
+
+        try:
+            settings = UniqueSettings.from_chat_event(self._event)
+            kb_service = UniqueServiceFactory(
+                settings=settings
+            ).knowledge_base_service()
+
+            if self.config.display_mode == DisplayMode.tree:
+                raw_entries = await self._build_tree_entries(kb_service)
+            else:
+                raw_entries = await self._build_flat_entries(kb_service)
+        except Exception:
+            _LOGGER.exception("Failed to retrieve content infos from knowledge base")
+            return ToolCallResponse(
+                id=tool_call.id or "unknown_id",
+                name=self.name,
+                error_message="Failed to retrieve file list from the knowledge base.",
+            )
+
+        total_files = len(raw_entries)
+        if total_files == 0:
+            return ToolCallResponse(
+                id=tool_call.id or "unknown_id",
+                name=self.name,
+                content="No files found in the search scope.",
+            )
+
+        max_input_tokens = self.config.language_model_max_input_tokens
+        if max_input_tokens is None:
+            _LOGGER.warning("language_model_max_input_tokens not set")
+            return ToolCallResponse(
+                id=tool_call.id or "unknown_id",
+                name=self.name,
+                error_message="Max_input_tokens not set.",
+            )
+
+        token_budget = int(
+            max_input_tokens * self.config.context_window_fraction_for_file_list
+        )
+        token_count = 0
+        seen: set[str] = set()
+        display_entries: list[str] = []
+        for entry in raw_entries:
+            if entry in seen:
+                continue
+            seen.add(entry)
+
+            # Uses default cl100k_base tokenizer (not model-specific). Acceptable
+            # for short file names where the difference is negligible.
+            entry_tokens = count_tokens(entry)
+            if token_count + entry_tokens > token_budget:
+                break
+            display_entries.append(entry)
+            token_count += entry_tokens
+
+        if not display_entries:
+            content = "Token limit to low to display search scope."
+        else:
+            omitted = total_files - len(display_entries)
+            file_list = "\n".join(display_entries)
+            content = (
+                f"Listing {len(display_entries)} of {total_files} files in search scope"
+            )
+            if omitted > 0:
+                content += f" ({omitted} omitted due to token budget or deduplication)"
+            content += f":\n\n{file_list}"
+
+        return ToolCallResponse(
+            id=tool_call.id or "unknown_id",
+            name=self.name,
+            content=content,
+        )
+
+
+ToolFactory.register_tool(RetrieveSearchScopeTool, RetrieveSearchScopeConfig)