unique-toolkit 2026.28.0.dev6__tar.gz → 2026.28.0.dev8__tar.gz

{unique_toolkit-2026.28.0.dev6 → unique_toolkit-2026.28.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 2026.28.0.dev6
+Version: 2026.28.0.dev8
 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.28.0.dev8,<2026.28.0rc0
+Requires-Dist: unique-sdk>=2026.28.0.dev11,<2026.28.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.28.0.dev6 → unique_toolkit-2026.28.0.dev8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "2026.28.0.dev6"
+version = "2026.28.0.dev8"
 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.28.0.dev8,<2026.28.0rc0",
+    "unique-sdk>=2026.28.0.dev11,<2026.28.0rc0",
     "jambo>=0.1.2,<0.2",
     "jinja2>=3.1.6,<4",
     "docxtpl>=0.20.1,<0.21",

{unique_toolkit-2026.28.0.dev6 → unique_toolkit-2026.28.0.dev8}/unique_toolkit/_common/chunk_relevancy_sorter/service.py

@@ -71,7 +71,7 @@ class ChunkRelevancySorter:
         company_id: str | None = None,
         user_id: str | None = None,
     ):
-        if isinstance(event, (ChatEvent, BaseEvent)):
+        if isinstance(event, BaseEvent):
             self.chunk_relevancy_evaluator = ContextRelevancyEvaluator.from_event(event)
         else:
             [company_id, user_id] = validate_required_values([company_id, user_id])

{unique_toolkit-2026.28.0.dev6 → unique_toolkit-2026.28.0.dev8}/unique_toolkit/agentic/evaluation/context_relevancy/service.py

@@ -81,7 +81,7 @@ class ContextRelevancyEvaluator:
         company_id: str | None = None,
         user_id: str | None = None,
     ):
-        if isinstance(event, (ChatEvent, BaseEvent)):
+        if isinstance(event, BaseEvent):
             self.language_model_service = LanguageModelService.from_event(event)
         else:
             [company_id, user_id] = validate_required_values([company_id, user_id])

{unique_toolkit-2026.28.0.dev6 → unique_toolkit-2026.28.0.dev8}/unique_toolkit/agentic/tools/experimental/retrieve_search_scope_tool/tool.py

@@ -116,7 +116,7 @@ class RetrieveSearchScopeTool(Tool[RetrieveSearchScopeConfig]):
             )
 
         try:
-            settings = UniqueSettings.from_chat_event(self._event)
+            settings = UniqueSettings.from_chat_event(self.event)
             kb_service = UniqueServiceFactory(
                 settings=settings
             ).knowledge_base_service()

unique_toolkit-2026.28.0.dev8/unique_toolkit/agentic/tools/run_context.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+from typing_extensions import Self
+
+from unique_toolkit.app.schemas import ChatEvent
+
+
+class ToolRunContext(BaseModel):
+    """Tool-manager runtime state decoupled from a raw :class:`ChatEvent`."""
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    tool_choices: list[str] = Field(default_factory=list)
+    disabled_tools: list[str] = Field(default_factory=list)
+    tool_init_event: ChatEvent | None = None
+
+    @classmethod
+    def from_chat_event(cls, event: ChatEvent) -> Self:
+        return cls(
+            tool_choices=list(event.payload.tool_choices),
+            disabled_tools=list(event.payload.disabled_tools),
+            tool_init_event=event,
+        )

{unique_toolkit-2026.28.0.dev6 → unique_toolkit-2026.28.0.dev8}/unique_toolkit/agentic/tools/tool.py

@@ -18,7 +18,8 @@ from unique_toolkit.app.schemas import ChatEvent
 from unique_toolkit.language_model import LanguageModelToolDescription
 
 if TYPE_CHECKING:
-    pass
+    from unique_toolkit.language_model.service import LanguageModelService
+    from unique_toolkit.services.chat_service import ChatService
 from unique_toolkit.language_model.schemas import (
     LanguageModelFunction,
 )
@@ -169,6 +170,9 @@ class Tool(ABC, Generic[ConfigType]):
     def __init__(self, config: ConfigType) -> None: ...
 
     @overload
+    @deprecated(
+        "Passing event is deprecated. Use Tool(config) and inject context in run()."
+    )
     def __init__(
         self,
         config: ConfigType,
@@ -176,17 +180,32 @@ class Tool(ABC, Generic[ConfigType]):
         tool_progress_reporter: ToolProgressReporter | None = ...,
     ) -> None: ...
 
+    @overload
+    def __init__(
+        self,
+        config: ConfigType,
+        *,
+        chat_service: ChatService,
+        language_model_service: LanguageModelService,
+        tool_progress_reporter: ToolProgressReporter | None = ...,
+    ) -> None: ...
+
     def __init__(
         self,
         config: ConfigType,
         event: ChatEvent | None = None,
         tool_progress_reporter: ToolProgressReporter | None = None,
+        *,
+        chat_service: ChatService | None = None,
+        language_model_service: LanguageModelService | None = None,
     ) -> None:
         """Initialize the tool.
 
-        Preferred (decoupled): `Tool(config)` — configuration only.
+        Preferred (decoupled): ``Tool(config)`` — configuration only.
 
-        Backward compatible: `Tool(config, event, tool_progress_reporter)` — creates
+        Service injection: ``Tool(config, chat_service=..., language_model_service=...)``.
+
+        Backward compatible: ``Tool(config, event, tool_progress_reporter)`` — creates
         deprecated chat_service, language_model_service, message_step_logger for
         legacy subclasses.
         """
@@ -200,6 +219,25 @@ class Tool(ABC, Generic[ConfigType]):
         self.logger = getLogger(f"{module_name}.{__name__}")
         self.debug_info: dict[str, Any] = {}
 
+        if (chat_service is None) != (language_model_service is None):
+            raise ValueError(
+                "chat_service and language_model_service must be injected together; "
+                "supplying only one is not supported."
+            )
+
+        if chat_service is not None and language_model_service is not None:
+            from unique_toolkit.agentic.message_log_manager.service import (
+                MessageStepLogger,
+            )
+
+            self._tool_progress_reporter = tool_progress_reporter
+            self._chat_service = chat_service
+            self._language_model_service = language_model_service
+            self._message_step_logger = MessageStepLogger(
+                chat_service=self._chat_service,
+            )
+            return
+
         if event is not None:
             from unique_toolkit.agentic.message_log_manager.service import (
                 MessageStepLogger,
@@ -220,11 +258,12 @@ class Tool(ABC, Generic[ConfigType]):
         "Never reuse event. Dangerous. Prefer Tool(config) and inject context in run()."
     )
     def event(self) -> ChatEvent:
-        if not hasattr(self, "_event"):
+        chat_event = getattr(self, "_event", None)
+        if chat_event is None:
             raise AttributeError(
                 "event not available (tool was initialized with config only). "
             )
-        return self._event
+        return chat_event
 
     @property
     @deprecated(

{unique_toolkit-2026.28.0.dev6 → unique_toolkit-2026.28.0.dev8}/unique_toolkit/agentic/tools/tool_manager.py

@@ -12,6 +12,7 @@ from openai.types.responses import (
     response_create_params,
 )
 from pydantic import BaseModel, Field
+from typing_extensions import Self
 
 from unique_toolkit._common.execution import (
     Result,
@@ -31,6 +32,7 @@ from unique_toolkit.agentic.tools.openai_builtin.base import (
     OpenAIBuiltInToolName,
 )
 from unique_toolkit.agentic.tools.openai_builtin.manager import OpenAIBuiltInToolManager
+from unique_toolkit.agentic.tools.run_context import ToolRunContext
 from unique_toolkit.agentic.tools.schemas import ToolCallResponse, ToolPrompts
 from unique_toolkit.agentic.tools.tool import Tool
 from unique_toolkit.agentic.tools.tool_progress_reporter import ToolProgressReporter
@@ -88,13 +90,62 @@ class _ToolManager(Generic[_ApiMode]):
         a2a_manager: A2AManager,
         api_mode: _ApiMode,
         builtin_tool_manager: OpenAIBuiltInToolManager | None = None,
+    ) -> None:
+        self._setup(
+            logger=logger,
+            config=config,
+            run_context=ToolRunContext.from_chat_event(event),
+            tool_progress_reporter=tool_progress_reporter,
+            mcp_manager=mcp_manager,
+            a2a_manager=a2a_manager,
+            api_mode=api_mode,
+            builtin_tool_manager=builtin_tool_manager,
+        )
+
+    @classmethod
+    def from_run_context(
+        cls,
+        logger: Logger,
+        config: ToolManagerConfig,
+        *,
+        run_context: ToolRunContext,
+        tool_progress_reporter: ToolProgressReporter,
+        mcp_manager: MCPManager,
+        a2a_manager: A2AManager,
+        api_mode: _ApiMode,
+        builtin_tool_manager: OpenAIBuiltInToolManager | None = None,
+    ) -> Self:
+        instance = cls.__new__(cls)
+        instance._setup(
+            logger=logger,
+            config=config,
+            run_context=run_context,
+            tool_progress_reporter=tool_progress_reporter,
+            mcp_manager=mcp_manager,
+            a2a_manager=a2a_manager,
+            api_mode=api_mode,
+            builtin_tool_manager=builtin_tool_manager,
+        )
+        return instance
+
+    def _setup(
+        self,
+        *,
+        logger: Logger,
+        config: ToolManagerConfig,
+        run_context: ToolRunContext,
+        tool_progress_reporter: ToolProgressReporter,
+        mcp_manager: MCPManager,
+        a2a_manager: A2AManager,
+        api_mode: _ApiMode,
+        builtin_tool_manager: OpenAIBuiltInToolManager | None,
     ) -> None:
         self._logger = logger
         self._config = config
         self._tool_progress_reporter = tool_progress_reporter
         self._tools: list[Tool[Any] | OpenAIBuiltInTool[Any]] = []
-        self._tool_choices = event.payload.tool_choices
-        self._disabled_tools = event.payload.disabled_tools
+        self._tool_choices = run_context.tool_choices
+        self._disabled_tools = run_context.disabled_tools
         self._exclusive_tools = [
             tool.name for tool in self._config.tools if tool.is_exclusive
         ]
@@ -104,17 +155,33 @@ class _ToolManager(Generic[_ApiMode]):
         self._a2a_manager = a2a_manager
         self._builtin_tool_manager = builtin_tool_manager
         self._api_mode = api_mode
-        self._init__tools(event)
-
-    def _init__tools(self, event: ChatEvent) -> None:
+        self._sub_agents: list[SubAgentTool] = []
+        self._builtin_tools: list[OpenAIBuiltInTool[Any]] = []
+        self._mcp_tools: list[Tool[Any]] = []
+        self._internal_tools: list[Tool[Any]] = []
+        self.available_tools: list[
+            Tool[Any] | OpenAIBuiltInTool[Any] | SubAgentTool
+        ] = []
+        self._init__tools(run_context.tool_init_event)
+
+    def _init__tools(self, tool_init_event: ChatEvent | None) -> None:
         tool_choices = self._tool_choices
         tool_configs = self._config.tools
         self._logger.info("Initializing tool definitions...")
         self._logger.info(f"Tool choices: {tool_choices}")
 
-        tool_configs, sub_agents = self._a2a_manager.get_all_sub_agents(
-            tool_configs, event
-        )
+        if tool_init_event is not None:
+            tool_configs, sub_agents = self._a2a_manager.get_all_sub_agents(
+                tool_configs,
+                tool_init_event,
+            )
+        else:
+            tool_configs = [
+                tool_config
+                for tool_config in tool_configs
+                if not tool_config.is_sub_agent
+            ]
+            sub_agents = []
         self._sub_agents = sub_agents
 
         registered_tool_names = set(t.name for t in self._sub_agents)
@@ -133,18 +200,27 @@ class _ToolManager(Generic[_ApiMode]):
         registered_tool_names.update(t.name for t in self._mcp_tools)
 
         # Build internal tools from configurations
-        self._internal_tools = [
-            ToolFactory.build_tool_with_settings(
-                t.name,
-                t,
-                t.configuration,
-                event,
-                tool_progress_reporter=self._tool_progress_reporter,
-            )
-            for t in tool_configs
-            if t.name not in registered_tool_names  # Skip already handled tools
-            and t.name not in OpenAIBuiltInToolName  # Safeguard
-        ]
+        self._internal_tools.clear()
+        for t in tool_configs:
+            if t.name in registered_tool_names:
+                continue
+            if t.name in OpenAIBuiltInToolName:
+                continue
+            if tool_init_event is not None:
+                built_tool = ToolFactory.build_tool_with_settings(
+                    t.name,
+                    t,
+                    t.configuration,
+                    tool_init_event,
+                    tool_progress_reporter=self._tool_progress_reporter,
+                )
+            else:
+                self._logger.info(
+                    "Skipping internal tool '%s' (requires chat event for initialization)",
+                    t.name,
+                )
+                continue
+            self._internal_tools.append(built_tool)
 
         # Combine all types of tools
         self.available_tools = (
@@ -607,6 +683,30 @@ class ToolManager(_ToolManager[Literal["completions"]]):
             builtin_tool_manager=None,
         )
 
+    @classmethod
+    def from_run_context(
+        cls,
+        logger: Logger,
+        config: ToolManagerConfig,
+        *,
+        run_context: ToolRunContext,
+        tool_progress_reporter: ToolProgressReporter,
+        mcp_manager: MCPManager,
+        a2a_manager: A2AManager,
+        api_mode: Literal["completions"] = "completions",
+        builtin_tool_manager: OpenAIBuiltInToolManager | None = None,
+    ) -> Self:
+        return super().from_run_context(
+            logger=logger,
+            config=config,
+            run_context=run_context,
+            tool_progress_reporter=tool_progress_reporter,
+            mcp_manager=mcp_manager,
+            a2a_manager=a2a_manager,
+            api_mode=api_mode,
+            builtin_tool_manager=builtin_tool_manager,
+        )
+
 
 class ResponsesApiToolManager(_ToolManager[Literal["responses"]]):
     def __init__(
@@ -631,6 +731,33 @@ class ResponsesApiToolManager(_ToolManager[Literal["responses"]]):
             builtin_tool_manager=builtin_tool_manager,
         )
 
+    @classmethod
+    def from_run_context(
+        cls,
+        logger: Logger,
+        config: ToolManagerConfig,
+        *,
+        run_context: ToolRunContext,
+        tool_progress_reporter: ToolProgressReporter,
+        mcp_manager: MCPManager,
+        a2a_manager: A2AManager,
+        api_mode: Literal["responses"] = "responses",
+        builtin_tool_manager: OpenAIBuiltInToolManager | None = None,
+    ) -> Self:
+        if builtin_tool_manager is None:
+            msg = "builtin_tool_manager is required for ResponsesApiToolManager"
+            raise ValueError(msg)
+        return super().from_run_context(
+            logger=logger,
+            config=config,
+            run_context=run_context,
+            tool_progress_reporter=tool_progress_reporter,
+            mcp_manager=mcp_manager,
+            a2a_manager=a2a_manager,
+            api_mode=api_mode,
+            builtin_tool_manager=builtin_tool_manager,
+        )
+
     def get_required_include_params(self) -> list[ResponseIncludable]:
         """Return Responses API include params required by all active built-in tools."""
         return self._builtin_tool_manager.get_required_include_params()

{unique_toolkit-2026.28.0.dev6 → unique_toolkit-2026.28.0.dev8}/unique_toolkit/agentic_table/schemas.py

@@ -1,5 +1,5 @@
 from enum import StrEnum
-from typing import Annotated, Any, Generic, Literal, TypeVar
+from typing import Annotated, Any, Generic, Literal, TypeVar, override
 
 from pydantic import (
     AliasChoices,
@@ -20,13 +20,13 @@ from unique_sdk.api_resources._agentic_table import (
     SheetType,
 )
 
+from unique_toolkit._common.exception import ConfigurationException
 from unique_toolkit._common.pydantic_helpers import get_configuration_dict
 from unique_toolkit.app.schemas import (
-    ChatEvent,
-    ChatEventAssistantMessage,
-    ChatEventUserMessage,
-    Correlation,
+    AssistantWebhookEvent,
+    BaseEventPayload,
 )
+from unique_toolkit.app.unique_settings import UniqueChatEventFilterOptions
 from unique_toolkit.language_model.schemas import (
     LanguageModelMessageRole,
     LanguageModelMessages,
@@ -112,27 +112,27 @@ A = TypeVar("A", bound=MagicTableAction)
 T = TypeVar("T", bound=BaseMetadata)
 
 
-class MagicTableBasePayload(BaseModel, Generic[A, T]):
+class MagicTableBasePayload(BaseEventPayload, Generic[A, T]):
+    """Magic-table-specific payload.
+
+    Inherits the common envelope fields (``name``, ``chat_id``, ``assistant_id``,
+    ``configuration``, ``metadata_filter``, ``correlation``) from
+    :class:`BaseEventPayload` and adds magic-table-only fields.
+
+    Note: previously this carried stub-empty ``user_message`` /
+    ``assistant_message`` defaults so that ``MagicTableEvent`` could pose as
+    a ``ChatEvent``. That coupling is gone; magic-table flows that need a
+    chat context should construct a :class:`UniqueContext` explicitly.
+    """
+
     model_config = get_configuration_dict()
-    name: str = Field(description="The name of the module")
-    sheet_name: str
 
+    # Optional on magic-table (BaseEventPayload requires it for chat).
+    configuration: dict[str, Any] = Field(default_factory=dict)
+    sheet_name: str
     action: A
-    chat_id: str
-    assistant_id: str
     table_id: str
-    user_message: ChatEventUserMessage = Field(
-        default=ChatEventUserMessage(
-            id="", text="", original_text="", created_at="", language=""
-        )
-    )
-    assistant_message: ChatEventAssistantMessage = Field(
-        default=ChatEventAssistantMessage(id="", created_at="")
-    )
-    configuration: dict[str, Any] = {}
     metadata: T
-    metadata_filter: dict[str, Any] | None = None
-    correlation: Correlation | None = None
 
 
 ########### Specialized Payload definitions ###########
@@ -263,10 +263,48 @@ PayloadTypes = (
 MagicTablePayloadTypes = Annotated[PayloadTypes, Field(discriminator="action")]
 
 
-class MagicTableEvent(ChatEvent):
-    # TODO(UN-19532): investigate making ChatEvent generic to avoid these overrides
+class MagicTableEvent(
+    AssistantWebhookEvent[UniqueChatEventFilterOptions, MagicTablePayloadTypes]
+):
+    """Magic-table webhook event, sibling of :class:`ChatEvent`.
+
+    No longer extends ``ChatEvent``; both events are siblings under
+    :class:`AssistantWebhookEvent`. This makes ``isinstance(magic_table_event,
+    ChatEvent)`` correctly return ``False`` and prevents silently passing a
+    magic-table event to services that require chat-only fields.
+    """
+
     event: MagicTableEventTypes  # pyright: ignore[reportIncompatibleVariableOverride]
-    payload: MagicTablePayloadTypes  # pyright: ignore[reportIncompatibleVariableOverride]
+
+    @override
+    def filter_event(
+        self, *, filter_options: UniqueChatEventFilterOptions | None = None
+    ) -> bool:
+        if filter_options is None:
+            return False
+
+        if not filter_options.assistant_ids and not filter_options.references_in_code:
+            raise ConfigurationException(
+                "No filter options provided, all events will be filtered! \n"
+                "Please define: \n"
+                " - 'UNIQUE_CHAT_EVENT_FILTER_OPTIONS_ASSISTANT_IDS' \n"
+                " - 'UNIQUE_CHAT_EVENT_FILTER_OPTIONS_REFERENCES_IN_CODE' \n"
+                "in your environment variables."
+            )
+
+        if (
+            filter_options.assistant_ids
+            and self.payload.assistant_id not in filter_options.assistant_ids
+        ):
+            return True
+
+        if (
+            filter_options.references_in_code
+            and self.payload.name not in filter_options.references_in_code
+        ):
+            return True
+
+        return super().filter_event(filter_options=filter_options)
 
 
 class LogDetail(BaseModel):

unique_toolkit-2026.28.0.dev8/unique_toolkit/agentic_table/synthetic_chat_event.py

@@ -0,0 +1,67 @@
+"""Synthetic :class:`ChatEvent` for magic-table runs with chat-typed toolkit APIs."""
+
+from unique_toolkit.agentic_table.schemas import MagicTableEvent
+from unique_toolkit.app.schemas import (
+    ChatEvent,
+    ChatEventAssistantMessage,
+    ChatEventPayload,
+    ChatEventUserMessage,
+    EventName,
+)
+from unique_toolkit.app.unique_settings import (
+    MAGIC_TABLE_STREAMING_ASSISTANT_MESSAGE_ID,
+    MAGIC_TABLE_STREAMING_USER_MESSAGE_ID,
+)
+
+_MAGIC_TABLE_STREAMING_MESSAGE_CREATED_AT = "1970-01-01T00:00:00Z"
+
+
+def build_synthetic_chat_event(
+    event: MagicTableEvent,
+    *,
+    event_id: str | None = None,
+    description: str = "magic-table",
+) -> ChatEvent:
+    """Build a :class:`ChatEvent` for evaluators/tools that still require chat typing.
+
+    Discouraged for new code: prefer :meth:`UniqueContext.from_magic_table_event`
+    and ``Service.from_context(...)`` / :meth:`ToolManager.from_run_context`
+    so callers do not depend on a fabricated chat envelope.
+
+    Magic-table runs create messages dynamically; placeholder message ids are
+    sufficient for search tooling and hallucination evaluation scoping.
+    """
+    payload = event.payload
+    chat_id = payload.chat_id
+    if not chat_id:
+        msg = (
+            "Magic-table event is missing chat_id; "
+            "chat-scoped services cannot be built."
+        )
+        raise ValueError(msg)
+    return ChatEvent(
+        id=event_id or event.id,
+        event=EventName.EXTERNAL_MODULE_CHOSEN,
+        user_id=event.user_id,
+        company_id=event.company_id,
+        payload=ChatEventPayload(
+            name=payload.name,
+            chat_id=chat_id,
+            assistant_id=payload.assistant_id,
+            description=description,
+            configuration=payload.configuration,
+            metadata_filter=payload.metadata_filter,
+            correlation=payload.correlation,
+            user_message=ChatEventUserMessage(
+                id=MAGIC_TABLE_STREAMING_USER_MESSAGE_ID,
+                text="",
+                original_text="",
+                created_at=_MAGIC_TABLE_STREAMING_MESSAGE_CREATED_AT,
+                language="EN",
+            ),
+            assistant_message=ChatEventAssistantMessage(
+                id=MAGIC_TABLE_STREAMING_ASSISTANT_MESSAGE_ID,
+                created_at=_MAGIC_TABLE_STREAMING_MESSAGE_CREATED_AT,
+            ),
+        ),
+    )