unique-toolkit 2026.20.0.dev28__tar.gz → 2026.20.0.dev30__tar.gz

{unique_toolkit-2026.20.0.dev28 → unique_toolkit-2026.20.0.dev30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 2026.20.0.dev28
+Version: 2026.20.0.dev30
 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>=2026.20.0.dev23,<2026.20.0rc0
+Requires-Dist: unique-sdk>=2026.20.0.dev25,<2026.20.0rc0
 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.dev28 → unique_toolkit-2026.20.0.dev30}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "2026.20.0.dev28"
+version = "2026.20.0.dev30"
 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>=2026.20.0.dev23,<2026.20.0rc0",
+    "unique-sdk>=2026.20.0.dev25,<2026.20.0rc0",
     "jambo>=0.1.2,<0.2",
     "jinja2>=3.1.6,<4",
     "docxtpl>=0.20.1,<0.21",

{unique_toolkit-2026.20.0.dev28 → unique_toolkit-2026.20.0.dev30}/unique_toolkit/_common/chunk_relevancy_sorter/service.py

@@ -3,7 +3,7 @@ import time
 from collections import Counter
 from typing import Any, overload
 
-from typing_extensions import deprecated
+from typing_extensions import Self, deprecated
 
 from unique_toolkit._common.chunk_relevancy_sorter.config import (
     ChunkRelevancySortConfig,
@@ -39,6 +39,7 @@ from unique_toolkit.agentic.evaluation.schemas import (
 )
 from unique_toolkit.app.performance.async_tasks import run_async_tasks_parallel
 from unique_toolkit.app.schemas import BaseEvent, ChatEvent
+from unique_toolkit.app.unique_settings import UniqueSettings
 from unique_toolkit.content.schemas import ContentChunk
 from unique_toolkit.language_model.infos import LanguageModelInfo
 
@@ -84,6 +85,13 @@ class ChunkRelevancySorter:
     def from_event(cls, event: ChatEvent | BaseEvent[Any]):
         return cls(company_id=event.company_id, user_id=event.user_id)
 
+    @classmethod
+    def from_settings(cls, settings: UniqueSettings) -> Self:
+        return cls(
+            company_id=settings.authcontext.get_confidential_company_id(),
+            user_id=settings.authcontext.get_confidential_user_id(),
+        )
+
     async def run(
         self,
         input_text: str,

unique_toolkit-2026.20.0.dev30/unique_toolkit/_common/metadata_filter_scope.py

@@ -0,0 +1,47 @@
+"""UniqueQL helpers for KB ``folderId`` / ``metadata_filter`` scoping."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from unique_toolkit.content.smart_rules import (
+    Operator,
+    Statement,
+)
+
+_UQL_AND = "and"
+
+
+def build_folder_id_in_clause(scope_ids: list[str]) -> dict[str, Any]:
+    """UniqueQL for selected folders using ``folderId in [scope_ids]``.
+
+    Equivalent to passing ``scope_ids`` directly to the wire-level search API.
+    """
+    if not scope_ids:
+        raise ValueError("scope_ids must be a non-empty list")
+    return Statement(
+        operator=Operator.IN,
+        path=["folderId"],
+        value=scope_ids,
+    ).model_dump(mode="json")
+
+
+def merge_scope_clause_into_metadata_filter(
+    scope_clause: Mapping[str, Any],
+    metadata_filter: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """AND-merge *scope_clause* with *metadata_filter*, flattening a top-level ``and``."""
+    scope_dict = dict(scope_clause)
+    if not metadata_filter:
+        return scope_dict
+    inner_and = metadata_filter.get(_UQL_AND)
+    if isinstance(inner_and, list):
+        return {_UQL_AND: [scope_dict, *inner_and]}
+    return {_UQL_AND: [scope_dict, dict(metadata_filter)]}
+
+
+__all__ = [
+    "build_folder_id_in_clause",
+    "merge_scope_clause_into_metadata_filter",
+]

{unique_toolkit-2026.20.0.dev28 → unique_toolkit-2026.20.0.dev30}/unique_toolkit/_common/pydantic_helpers.py

@@ -1,6 +1,6 @@
 import logging
 import warnings
-from typing import Any, TypeVar, Unpack
+from typing import Annotated, Any, TypeVar, Unpack
 
 import humps
 from pydantic import BaseModel, BeforeValidator, ConfigDict, Field, create_model
@@ -33,6 +33,11 @@ BeforeValidator to replace an incoming None with the field's declared default.
 """
 NoneToDefault = BeforeValidator(_none_to_default)
 
+DeactivatedNone = Annotated[
+    None,
+    Field(title="Deactivated", description="None"),
+]
+
 
 def get_configuration_dict(**kwargs: Unpack[ConfigDict]) -> ConfigDict:
     base: dict[str, object] = {

{unique_toolkit-2026.20.0.dev28 → unique_toolkit-2026.20.0.dev30}/unique_toolkit/agentic/history_manager/history_manager.py

@@ -8,6 +8,7 @@ from pydantic import BaseModel, Field
 from unique_toolkit._common.feature_flags.schema import (
     FeatureExtendedSourceSerialization,
 )
+from unique_toolkit._common.pydantic_helpers import DeactivatedNone
 from unique_toolkit._common.validators import LMI
 from unique_toolkit.agentic.history_manager.loop_token_reducer import LoopTokenReducer
 from unique_toolkit.agentic.history_manager.utils import (
@@ -30,11 +31,6 @@ from unique_toolkit.language_model.schemas import (
     LanguageModelToolMessage,
 )
 
-DeactivatedNone = Annotated[
-    None,
-    Field(title="Deactivated", description="None"),
-]
-
 
 class UploadedContentConfig(BaseModel):
     model_config = get_configuration_dict()

{unique_toolkit-2026.20.0.dev28 → unique_toolkit-2026.20.0.dev30}/unique_toolkit/app/schemas.py

@@ -215,6 +215,20 @@ class Correlation(BaseModel):
     parent_assistant_id: str
 
 
+class ChatEventSkillChoice(BaseModel):
+    model_config = model_config
+
+    name: str = Field(default="", description="Skill name.")
+    scope_id: str = Field(
+        default="",
+        description="Knowledge base scope ID that contains the skill file.",
+    )
+    content_id: str = Field(
+        default="",
+        description="Knowledge base content ID of the ``SKILL.md`` file.",
+    )
+
+
 class ChatEventPayload(BaseModel):
     model_config = model_config
 
@@ -234,6 +248,13 @@ class ChatEventPayload(BaseModel):
         default_factory=list,
         description="A list containing the tool names the user has chosen to be activated.",
     )
+    skill_choices: list[ChatEventSkillChoice] = Field(
+        default_factory=list,
+        description=(
+            "A list containing selected skills with ``scope_id``, "
+            "``content_id``, and ``name``."
+        ),
+    )
     disabled_tools: list[str] = Field(
         default_factory=list,
         description="A list containing the tool names of tools that are disabled at the company level",

{unique_toolkit-2026.20.0.dev28 → unique_toolkit-2026.20.0.dev30}/unique_toolkit/experimental/components/__init__.py

@@ -24,4 +24,7 @@ Planned contents (current home → new home):
   (re-export: :mod:`unique_toolkit.experimental.content_tree`); a derived
   tree/fuzzy-search view over the ``content`` resource; does not wrap an SDK
   endpoint of its own
+* ``internal_search``        ← :mod:`unique_toolkit.experimental.components.internal_search`
+  (UN-19039 / UN-20075); pure-retrieval KB and chat search services plus an
+  optional post-processing pipeline (:class:`InternalSearchPostProcessor`)
 """

unique_toolkit-2026.20.0.dev30/unique_toolkit/experimental/components/_base.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from functools import cached_property
+from pathlib import Path
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+from typing_extensions import Self
+
+from unique_toolkit._common.event_bus import TypedEventBus
+from unique_toolkit.app.unique_settings import UniqueContext, UniqueSettings
+
+RunResult = TypeVar("RunResult", bound=BaseModel)
+Config = TypeVar("Config", bound=BaseModel)
+Context = TypeVar("Context")
+ServiceState = TypeVar("ServiceState")
+ProgressMessage = TypeVar("ProgressMessage")
+Deps = TypeVar("Deps")
+
+
+class _RunMixin(ABC, Generic[RunResult]):
+    @abstractmethod
+    async def run(self) -> RunResult: ...
+
+
+class _ConfigMixin(ABC, Generic[Config]):
+    """Subclasses must set ``_config_model_cls`` so ``from_json`` can deserialize."""
+
+    _config_model_cls: type[Config]
+
+    @classmethod
+    @abstractmethod
+    def from_config(cls, config: Config) -> Self: ...
+
+    @property
+    @abstractmethod
+    def config(self) -> Config: ...
+
+    @classmethod
+    def from_json(cls, file_path: Path) -> Self:
+        parsed = cls._config_model_cls.model_validate_json(file_path.read_text())
+        return cls.from_config(parsed)
+
+
+class _ContextMixin(ABC, Generic[Context]):
+    @property
+    @abstractmethod
+    def context(self) -> Context: ...
+
+
+class _StateMixin(ABC, Generic[ServiceState]):
+    @property
+    @abstractmethod
+    def state(self) -> ServiceState: ...
+
+    @abstractmethod
+    def reset_state(self) -> None: ...
+
+
+class _ProgressMixin(Generic[ProgressMessage]):
+    """Concrete by default — no-op bus unless something subscribes."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._progress_publisher: TypedEventBus[ProgressMessage] = TypedEventBus()
+
+    @property
+    def progress_publisher(self) -> TypedEventBus[ProgressMessage]:
+        return self._progress_publisher
+
+    async def post_progress_message(self, message: ProgressMessage) -> None:
+        await self.progress_publisher.publish_and_wait_async(message)
+
+
+class _DependenciesMixin(ABC, Generic[Deps]):
+    @property
+    @abstractmethod
+    def dependencies(self) -> Deps: ...
+
+
+class BaseService(  # pyright: ignore[reportImplicitAbstractClass]
+    _RunMixin[RunResult],
+    _ConfigMixin[Config],
+    _ContextMixin[UniqueContext],
+    _StateMixin[ServiceState],
+    _ProgressMixin[ProgressMessage],
+    _DependenciesMixin[Deps],
+    Generic[RunResult, Config, ServiceState, ProgressMessage, Deps],
+):
+    """
+    Two-step init: from_config() at startup, bind_settings() per request.
+
+        service = MyService.from_config(config)      # startup
+        service = service.bind_settings(settings)    # per request
+        # or in one shot:
+        service = MyService.from_settings(settings, config=config)
+    """
+
+    _config: Config
+    _context: UniqueContext
+    _state: ServiceState
+    _dependencies: Deps
+
+    @abstractmethod
+    def bind_settings(self, settings: UniqueSettings) -> Self: ...
+
+    @classmethod
+    def from_settings(cls, settings: UniqueSettings, **kwargs) -> Self:
+        config = kwargs.pop("config")
+        return cls.from_config(config).bind_settings(settings)
+
+    @property
+    def config(self) -> Config:
+        return self._config  # type: ignore[attr-defined]
+
+    @property
+    def context(self) -> UniqueContext:
+        return self._context  # type: ignore[attr-defined]
+
+    @context.setter
+    def context(self, value: UniqueContext) -> None:
+        self._context = value
+
+    @property
+    def state(self) -> ServiceState:
+        return self._state  # type: ignore[attr-defined]
+
+    @state.setter
+    def state(self, value: ServiceState) -> None:
+        self._state = value
+
+    @property
+    def dependencies(self) -> Deps:
+        return self._dependencies  # type: ignore[attr-defined]
+
+    @dependencies.setter
+    def dependencies(self, value: Deps) -> None:
+        self._dependencies = value
+
+    @cached_property
+    def logger(self) -> logging.Logger:
+        return logging.getLogger(f"{type(self).__module__}.{type(self).__qualname__}")
+
+
+__all__ = ["BaseService"]

unique_toolkit-2026.20.0.dev30/unique_toolkit/experimental/components/internal_search/__init__.py

@@ -0,0 +1,97 @@
+"""Internal search component — retrieval services and post-processing pipeline.
+
+!!! warning "Experimental"
+    This subpackage lives under :mod:`unique_toolkit.experimental` and its
+    API may change between minor releases.
+
+Provides framework-agnostic knowledge-base and chat search services, plus an
+optional post-processing pipeline for reranking and token-budget windowing.
+
+The search services are pure retrieval primitives: they return all matching
+chunks up to the configured ``limit``. Post-retrieval steps (reranking, token
+windowing, sorting) are handled separately by
+:class:`InternalSearchPostProcessor`.
+
+Typical usage::
+
+    from unique_toolkit.experimental.components.internal_search import (
+        KnowledgeBaseInternalSearchService,
+        KnowledgeBaseInternalSearchConfig,
+        InternalSearchFilterConfig,
+        InternalSearchPostProcessor,
+        PostProcessorConfig,
+    )
+
+    search_config = KnowledgeBaseInternalSearchConfig(
+        filtering=InternalSearchFilterConfig(limit=200),
+        ...,
+    )
+    post_config = PostProcessorConfig(max_tokens_for_sources=30_000, ...)
+
+    search_service = KnowledgeBaseInternalSearchService.from_config(search_config)
+    processor = InternalSearchPostProcessor.from_settings(settings, config=post_config)
+
+    search_service.bind_settings(settings)
+    search_service.state.search_queries = ["my query"]
+    result = await search_service.run()
+
+    chunks = await processor.process(
+        result,
+        query_text="my query",
+        model_info=model_info,
+    )
+"""
+
+from unique_toolkit.experimental.components.internal_search.base import (
+    DEFAULT_LIMIT,
+    InternalSearchBaseService,
+    InternalSearchConfig,
+    InternalSearchProgressMessage,
+    InternalSearchResult,
+    InternalSearchStage,
+    InternalSearchState,
+    SearchStringResult,
+    TInternalSearchDeps,
+)
+from unique_toolkit.experimental.components.internal_search.chat import (
+    ChatInternalSearchConfig,
+    ChatInternalSearchDeps,
+    ChatInternalSearchService,
+)
+from unique_toolkit.experimental.components.internal_search.knowledge_base import (
+    UNSET,
+    KnowledgeBaseInternalSearchConfig,
+    KnowledgeBaseInternalSearchDeps,
+    KnowledgeBaseInternalSearchService,
+    KnowledgeBaseInternalSearchState,
+)
+from unique_toolkit.experimental.components.internal_search.post_processing import (
+    InternalSearchPostProcessor,
+    PostProcessorConfig,
+)
+
+__all__ = [
+    # base
+    "DEFAULT_LIMIT",
+    "InternalSearchBaseService",
+    "InternalSearchConfig",
+    "InternalSearchProgressMessage",
+    "InternalSearchResult",
+    "InternalSearchStage",
+    "InternalSearchState",
+    "SearchStringResult",
+    "TInternalSearchDeps",
+    # chat
+    "ChatInternalSearchConfig",
+    "ChatInternalSearchDeps",
+    "ChatInternalSearchService",
+    # knowledge base
+    "KnowledgeBaseInternalSearchConfig",
+    "KnowledgeBaseInternalSearchDeps",
+    "KnowledgeBaseInternalSearchService",
+    "KnowledgeBaseInternalSearchState",
+    "UNSET",
+    # post-processing
+    "InternalSearchPostProcessor",
+    "PostProcessorConfig",
+]

unique_toolkit-2026.20.0.dev30/unique_toolkit/experimental/components/internal_search/base/__init__.py

@@ -0,0 +1,37 @@
+from .config import (
+    DEFAULT_LIMIT,
+    InternalSearchConfig,
+    InternalSearchFilterConfig,
+    InternalSearchSearchConfig,
+)
+from .schemas import (
+    InternalSearchProgressMessage,
+    InternalSearchResult,
+    InternalSearchStage,
+    InternalSearchState,
+    SearchStringResult,
+    TInternalSearchDeps,
+)
+from .service import InternalSearchBaseService
+from .utils import (
+    append_metadata_in_chunks,
+    clean_search_string,
+    interleave_search_results_round_robin,
+)
+
+__all__ = [
+    "append_metadata_in_chunks",
+    "clean_search_string",
+    "DEFAULT_LIMIT",
+    "InternalSearchBaseService",
+    "InternalSearchConfig",
+    "InternalSearchFilterConfig",
+    "InternalSearchProgressMessage",
+    "InternalSearchResult",
+    "InternalSearchSearchConfig",
+    "InternalSearchStage",
+    "InternalSearchState",
+    "interleave_search_results_round_robin",
+    "SearchStringResult",
+    "TInternalSearchDeps",
+]

unique_toolkit-2026.20.0.dev30/unique_toolkit/experimental/components/internal_search/base/config.py

@@ -0,0 +1,72 @@
+from pydantic import BaseModel, Field
+
+from unique_toolkit._common.config_checker import register_config
+from unique_toolkit.agentic.tools.config import get_configuration_dict
+from unique_toolkit.content.schemas import ContentSearchType
+
+# 200 matches the tool's sort-enabled default — conservative by design.
+# Callers who need higher recall (e.g. multi-query with post-processing) should set
+# limit explicitly in config. The service does not cap by token budget; that is the
+# post-processor's job via pick_content_chunks_for_token_window.
+DEFAULT_LIMIT = 200
+
+
+class InternalSearchSearchConfig(BaseModel):
+    model_config = get_configuration_dict()
+
+    search_type: ContentSearchType = Field(
+        default=ContentSearchType.COMBINED,
+        description="The type of search to perform. Two possible values: `COMBINED` or `VECTOR`.",
+    )
+    search_language: str = Field(
+        default="english",
+        description="The language to use for the search.",
+    )
+    max_search_strings: int = Field(
+        default=10,
+        ge=1,
+        description="The maximum number of search strings to perform in a single tool call.",
+    )
+
+
+class InternalSearchFilterConfig(BaseModel):
+    model_config = get_configuration_dict()
+
+    score_threshold: float = Field(
+        default=0.0,
+        ge=0.0,
+        le=1.0,
+        description="Score threshold to filter chunks on relevancy.",
+    )
+    limit: int = Field(
+        default=DEFAULT_LIMIT,
+        description=(
+            "Maximum number of chunks to return per search query. "
+            "Default is 200 — the conservative baseline. Increase for higher recall "
+            "when a post-processor with token windowing follows."
+        ),
+    )
+
+
+@register_config()
+class InternalSearchConfig(BaseModel):
+    """Retrieval-only config. Token budgeting, reranking and sorting live in PostProcessorConfig."""
+
+    model_config = get_configuration_dict()
+
+    search: InternalSearchSearchConfig = Field(
+        default_factory=InternalSearchSearchConfig,
+        description="Search-related configuration such as query mode, language, and multi-query settings.",
+    )
+    filtering: InternalSearchFilterConfig = Field(
+        default_factory=InternalSearchFilterConfig,
+        description="Result filtering configuration such as retrieval limit and score threshold.",
+    )
+
+
+__all__ = [
+    "InternalSearchConfig",
+    "DEFAULT_LIMIT",
+    "InternalSearchFilterConfig",
+    "InternalSearchSearchConfig",
+]

unique_toolkit-2026.20.0.dev30/unique_toolkit/experimental/components/internal_search/base/schemas.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+from typing_extensions import TypeVar
+
+from unique_toolkit.chat.schemas import MessageLogStatus
+from unique_toolkit.content.schemas import ContentChunk
+
+
+class SearchStringResult(BaseModel):
+    query: str
+    chunks: list[ContentChunk]
+
+
+class InternalSearchStage(StrEnum):
+    RETRIEVING = "retrieving"
+    POSTPROCESSING = "postprocessing"
+    COMPLETED = "completed"
+
+
+class InternalSearchProgressMessage(BaseModel):
+    stage: InternalSearchStage
+    status: MessageLogStatus
+    search_queries: list[str]
+    chunks: list[ContentChunk] | None = None
+
+
+TInternalSearchDeps = TypeVar("TInternalSearchDeps")
+
+
+@dataclass
+class InternalSearchState:
+    search_queries: list[str]
+    content_ids: list[str] | None = None
+
+
+class InternalSearchResult(BaseModel):
+    chunks: list[ContentChunk]
+    """Interleaved flat chunk list — for callers that skip the post-processor."""
+    debug_info: dict[str, Any]
+    search_string_results: list[SearchStringResult] = Field(default_factory=list)
+    """Per-query results before interleaving — for the post-processor's per-query rerank."""
+
+
+__all__ = [
+    "InternalSearchProgressMessage",
+    "InternalSearchResult",
+    "InternalSearchStage",
+    "InternalSearchState",
+    "SearchStringResult",
+    "TInternalSearchDeps",
+]