unique-toolkit 2026.24.0.dev9__tar.gz → 2026.24.0.dev11__tar.gz

{unique_toolkit-2026.24.0.dev9 → unique_toolkit-2026.24.0.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 2026.24.0.dev9
+Version: 2026.24.0.dev11
 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.24.0.dev4,<2026.24.0rc0
+Requires-Dist: unique-sdk>=2026.24.0.dev5,<2026.24.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.24.0.dev9 → unique_toolkit-2026.24.0.dev11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "2026.24.0.dev9"
+version = "2026.24.0.dev11"
 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.24.0.dev4,<2026.24.0rc0",
+    "unique-sdk>=2026.24.0.dev5,<2026.24.0rc0",
     "jambo>=0.1.2,<0.2",
     "jinja2>=3.1.6,<4",
     "docxtpl>=0.20.1,<0.21",

unique_toolkit-2026.24.0.dev11/unique_toolkit/agentic/tools/a2a/config.py

@@ -0,0 +1,41 @@
+import logging
+from typing import Self
+
+from pydantic import Field, model_validator
+
+from unique_toolkit.agentic.tools.a2a.evaluation import SubAgentEvaluationConfig
+from unique_toolkit.agentic.tools.a2a.postprocessing import (
+    SubAgentDisplayConfig,
+    SubAgentResponseDisplayMode,
+)
+from unique_toolkit.agentic.tools.a2a.tool import SubAgentToolConfig
+
+_LOGGER = logging.getLogger(__name__)
+
+
+# SubAgentToolConfig with display and evaluation configs
+class ExtendedSubAgentToolConfig(SubAgentToolConfig):
+    response_display_config: SubAgentDisplayConfig = Field(
+        default_factory=SubAgentDisplayConfig,
+        description="Configuration for how to display the sub-agent response.",
+    )
+    evaluation_config: SubAgentEvaluationConfig = Field(
+        default_factory=SubAgentEvaluationConfig,
+        description="Configuration for handling assessments of the sub-agent response.",
+    )
+
+    @model_validator(mode="after")
+    def _ensure_response_display_config_off_when_sub_agent_response_passthrough(
+        self,
+    ) -> Self:
+        if (
+            self.passthrough_config.enabled
+            and self.response_display_config.mode != SubAgentResponseDisplayMode.HIDDEN
+        ):
+            _LOGGER.warning(
+                "SubAgent (assistant_id=%r): `passthrough_config.enabled=True` but `response_display_config.mode` is not HIDDEN. "
+                "Overriding `response_display_config.mode` to HIDDEN.",
+                self.assistant_id,
+            )
+            self.response_display_config.mode = SubAgentResponseDisplayMode.HIDDEN
+        return self

unique_toolkit-2026.24.0.dev11/unique_toolkit/agentic/tools/a2a/tool/__init__.py

@@ -0,0 +1,7 @@
+from unique_toolkit.agentic.tools.a2a.tool.config import (
+    SubAgentPassthroughConfig,
+    SubAgentToolConfig,
+)
+from unique_toolkit.agentic.tools.a2a.tool.service import SubAgentTool
+
+__all__ = ["SubAgentPassthroughConfig", "SubAgentTool", "SubAgentToolConfig"]

{unique_toolkit-2026.24.0.dev9 → unique_toolkit-2026.24.0.dev11}/unique_toolkit/agentic/tools/a2a/tool/config.py

@@ -1,8 +1,9 @@
+import logging
 import re
 from enum import StrEnum
-from typing import Annotated, Generic, Literal, TypeVar
+from typing import Annotated, Generic, Literal, Self, TypeVar
 
-from pydantic import Field, field_validator
+from pydantic import Field, field_validator, model_validator
 from pydantic.main import BaseModel
 
 from unique_toolkit._common.pydantic.rjsf_tags import RJSFMetaTag
@@ -26,6 +27,9 @@ class SystemReminderConfig(BaseModel, Generic[T]):
     type: T
 
 
+_LOGGER = logging.getLogger(__name__)
+
+
 _SYSTEM_REMINDER_FIELD_DESCRIPTION = """
 The reminder to add to the tool response. The reminder can be a Jinja template and can contain the following placeholders:
 - {{ display_name }}: The display name of the sub agent.
@@ -103,6 +107,19 @@ This is the message that will be sent to the sub-agent.
 """.strip()
 
 
+class SubAgentPassthroughConfig(BaseModel):
+    model_config = get_configuration_dict()
+
+    enabled: bool = Field(
+        default=False,
+        description="If set, this sub agent's response will be directly displayed to the user once the agent is called, ending the orchestrator loop.",
+    )
+    include_assessments: bool = Field(
+        default=True,
+        description="If set, this sub agent's assessments will be added to the main agent response.",
+    )
+
+
 class SubAgentToolConfig(BaseToolConfig):
     model_config = get_configuration_dict()
 
@@ -171,10 +188,12 @@ class SubAgentToolConfig(BaseToolConfig):
     poll_interval: Annotated[float, RJSFMetaTag.NumberWidget.updown()] = Field(
         default=1.0,
         description="Time interval in seconds between polling attempts when waiting for sub-agent response.",
+        gt=0,
     )
     max_wait: Annotated[float, RJSFMetaTag.NumberWidget.updown()] = Field(
         default=120.0,
         description="Maximum time in seconds to wait for the sub-agent response before timing out.",
+        gt=0,
     )
     stop_condition: Literal["stoppedStreamingAt", "completedAt"] = Field(
         default="completedAt",
@@ -197,6 +216,11 @@ class SubAgentToolConfig(BaseToolConfig):
         default=False,
         description="If set, the sub-agent response will be interpreted as a list of content chunks.",
     )
+    passthrough_config: SubAgentPassthroughConfig = Field(
+        default_factory=SubAgentPassthroughConfig,
+        description="Configuration for streaming the sub-agent response directly back to the user.",
+        title="Direct Streaming Configuration (Experimental)",
+    )
 
     system_reminders_config: list[
         Annotated[
@@ -207,3 +231,28 @@ class SubAgentToolConfig(BaseToolConfig):
         default=[],
         description="Configuration for the system reminders to add to the tool response.",
     )
+
+    @model_validator(mode="after")
+    def _ensure_response_passthrough_and_returns_content_chunks_mutually_exclusive(
+        self,
+    ) -> Self:
+        if self.passthrough_config.enabled and self.returns_content_chunks:
+            raise ValueError(
+                f"SubAgent (assistant_id={self.assistant_id!r}): "
+                "`passthrough_config.enabled` and `returns_content_chunks` are mutually exclusive."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _ensure_use_sub_agent_references_off_when_tool_response_passthrough(
+        self,
+    ) -> Self:
+        if self.passthrough_config.enabled and self.use_sub_agent_references:
+            _LOGGER.warning(
+                "SubAgent (assistant_id=%r): `passthrough_config.enabled=True` and `use_sub_agent_references=True`. "
+                "`use_sub_agent_references` will be overridden to False.",
+                self.assistant_id,
+            )
+            self.use_sub_agent_references = False
+
+        return self

{unique_toolkit-2026.24.0.dev9 → unique_toolkit-2026.24.0.dev11}/unique_toolkit/agentic/tools/a2a/tool/service.py

@@ -11,6 +11,7 @@ from pydantic import Field, TypeAdapter, create_model
 from unique_sdk.api_resources._space import Space
 from unique_sdk.utils.chat_in_space import send_message_and_wait_for_completion
 
+from unique_toolkit._common.execution import SafeTaskExecutor
 from unique_toolkit._common.referencing import (
     get_all_ref_numbers,
     get_detection_pattern_for_ref,
@@ -41,9 +42,15 @@ from unique_toolkit.agentic.tools.tool_progress_reporter import (
     ToolProgressReporter,
 )
 from unique_toolkit.app import ChatEvent
-from unique_toolkit.chat.schemas import MessageLog, MessageLogStatus
+from unique_toolkit.chat.schemas import (
+    ChatMessageAssessmentLabel,
+    ChatMessageAssessmentStatus,
+    ChatMessageAssessmentType,
+    MessageLog,
+    MessageLogStatus,
+)
 from unique_toolkit.chat.service import ChatService
-from unique_toolkit.content import ContentChunk
+from unique_toolkit.content import ContentChunk, ContentReference
 from unique_toolkit.language_model import (
     LanguageModelFunction,
     LanguageModelToolDescription,
@@ -146,6 +153,10 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
     def tool_format_information_for_user_prompt(self) -> str:
         return self.config.tool_format_information_for_user_prompt
 
+    @override
+    def takes_control(self) -> bool:
+        return self.config.passthrough_config.enabled
+
     @override
     def evaluation_check_list(self) -> list[EvaluationMetricName]:
         return [EvaluationMetricName.SUB_AGENT] if self._should_run_evaluation else []
@@ -215,6 +226,7 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
                 self._should_run_evaluation |= (
                     response["assessment"] is not None
                     and len(response["assessment"]) > 0
+                    and not self.config.passthrough_config.enabled
                 )  # Run evaluation if any sub agent returned an assessment
 
                 self._notify_watcher(response, sequence_number, timestamp)
@@ -273,6 +285,9 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
                     active_message_log=active_message_log,
                 )
 
+                if self.config.passthrough_config.enabled:
+                    await self._display_sub_agent_response(response)
+
                 return ToolCallResponse(
                     id=tool_call.id,
                     name=tool_call.name,
@@ -303,6 +318,68 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
             )
             raise e
 
+    async def _display_sub_agent_response(self, response: Space.Message) -> None:
+        await self._publish_sub_agent_response(response, set_completed_at=True)
+
+        if self.config.passthrough_config.include_assessments:
+            await self._forward_sub_agent_assessments(response["assessment"] or [])
+
+    async def _publish_sub_agent_response(
+        self,
+        response: Space.Message,
+        *,
+        set_completed_at: bool,
+    ) -> None:
+        await self._chat_service.modify_assistant_message_async(
+            content=response["text"],
+            original_content=response["originalText"],
+            references=[
+                ContentReference.from_sdk_reference(ref)
+                for ref in response["references"] or []
+            ],
+            set_completed_at=set_completed_at,
+        )
+
+    async def _publish_sub_agent_response_update(
+        self,
+        response: Space.Message,
+    ) -> None:
+        try:
+            await self._publish_sub_agent_response(response, set_completed_at=False)
+        except Exception:
+            logger.warning(
+                "Failed to publish streaming sub agent passthrough update",
+                exc_info=True,
+            )
+
+    async def _forward_sub_agent_assessments(
+        self,
+        assessments: list[unique_sdk.Space.Assessment],
+    ) -> None:
+        async def _create_one_assessment(
+            assessment: unique_sdk.Space.Assessment,
+        ) -> None:
+            await self._chat_service.create_message_assessment_async(
+                assistant_message_id=self._chat_service._assistant_message_id,
+                status=ChatMessageAssessmentStatus(assessment["status"]),
+                type=ChatMessageAssessmentType(assessment["type"]),
+                title=assessment["title"],
+                explanation=assessment["explanation"],
+                label=ChatMessageAssessmentLabel(assessment["label"]),
+                is_visible=assessment["isVisible"],
+            )
+
+        if not assessments:
+            return
+
+        task_executor = SafeTaskExecutor(logger=logger)
+        await asyncio.gather(
+            *(
+                task_executor.execute_async(_create_one_assessment, a)
+                for a in assessments
+            ),
+        )
+
     async def _get_chat_id(self) -> str | None:
         if not self.config.reuse_chat:
             return None
@@ -388,6 +465,12 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
         active_message_log: MessageLog | None = None,
     ) -> unique_sdk.Space.Message:
         try:
+            on_message_update = (
+                self._publish_sub_agent_response_update
+                if self.config.passthrough_config.enabled
+                else None
+            )
+
             return await send_message_and_wait_for_completion(
                 user_id=self._user_id,
                 assistant_id=self.config.assistant_id,
@@ -403,6 +486,7 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
                     parentChatId=self._event.payload.chat_id,
                     parentAssistantId=self.config.assistant_id,
                 ),
+                on_message_update=on_message_update,
             )
         except TimeoutError as e:
             await self._notify_progress(

{unique_toolkit-2026.24.0.dev9 → unique_toolkit-2026.24.0.dev11}/unique_toolkit/agentic/tools/tool_manager.py

@@ -310,20 +310,65 @@ class _ToolManager(Generic[_ApiMode]):
         if tool.name not in self._tool_choices:
             self._tool_choices.append(tool.name)
 
-    def does_a_tool_take_control(self, tool_calls: list[LanguageModelFunction]) -> bool:
+    def _get_tool_calls_that_take_control(
+        self, tool_calls: list[LanguageModelFunction]
+    ) -> list[LanguageModelFunction]:
+        tools = []
         for tool_call in tool_calls:
             tool_instance = self.get_tool_by_name(tool_call.name)
             if tool_instance and tool_instance.takes_control():
-                return True
-        return False
+                tools.append(tool_call)
+
+        return tools
+
+    def does_a_tool_take_control(self, tool_calls: list[LanguageModelFunction]) -> bool:
+        return len(self._get_tool_calls_that_take_control(tool_calls)) > 0
 
     def get_evaluation_check_list(self) -> list[EvaluationMetricName]:
         return list(self._tool_evaluation_check_list)
 
+    def _take_control_conflict_response(
+        self,
+        tool_call: LanguageModelFunction,
+        take_control_names: list[str],
+    ) -> ToolCallResponse:
+        if tool_call.name in take_control_names:
+            content = (
+                f"ERROR: Tool `{tool_call.name}` directly returns its response to the user and therefore must be called on its own. "
+                "None of the tools in this batch were executed. "
+                f"You may recover by first calling the other tools, then calling `{tool_call.name}` alone."
+            )
+        else:
+            names = ", ".join(f"`{n}`" for n in take_control_names)
+            content = f"ERROR: Not executed because the following tool(s) must be called on their own: {names}"
+
+        return ToolCallResponse(
+            id=tool_call.id,
+            name=tool_call.name,
+            content=content,
+        )
+
     async def execute_selected_tools(
         self,
         tool_calls: list[LanguageModelFunction],
     ) -> list[ToolCallResponse]:
+        if len(tool_calls) > 1:
+            take_control_tools = [
+                t.name for t in self._get_tool_calls_that_take_control(tool_calls)
+            ]
+
+            if len(take_control_tools) > 0:
+                self._logger.warning(
+                    "Tool(s) %s take control and cannot be called alongside other tools. "
+                    "Returning error for all %d tool calls.",
+                    take_control_tools,
+                    len(tool_calls),
+                )
+                return [
+                    self._take_control_conflict_response(tool_call, take_control_tools)
+                    for tool_call in tool_calls
+                ]
+
         tool_call_responses = await self._execute_parallelized(tool_calls)
         return tool_call_responses
 

{unique_toolkit-2026.24.0.dev9 → unique_toolkit-2026.24.0.dev11}/unique_toolkit/content/schemas.py

@@ -223,7 +223,8 @@ class ContentReference(BaseModel):
 
     @classmethod
     def from_sdk_reference(
-        cls, reference: unique_sdk.Message.Reference | unique_sdk.Space.Reference
+        cls,
+        reference: unique_sdk.Message.Reference | unique_sdk.Space.Reference,
     ) -> "ContentReference":
         kwargs: dict[str, Any] = {
             "name": reference["name"],

{unique_toolkit-2026.24.0.dev9 → unique_toolkit-2026.24.0.dev11}/unique_toolkit/experimental/resources/feature_flags/__init__.py

@@ -31,7 +31,12 @@ Define flag name constants in your service to avoid magic strings::
 See README.md for the full evaluation-order diagram and adoption steps.
 """
 
-from .client import BoundFeatureFlagClient, FeatureFlagClient
+from .client import (
+    BoundFeatureFlagClient,
+    FeatureFlagClient,
+    get_feature_flag_client,
+    is_flag_enabled,
+)
 from .schemas import FlagEvaluation
 from .settings import FeatureFlagSettings
 
@@ -40,4 +45,6 @@ __all__ = [
     "FeatureFlagClient",
     "FlagEvaluation",
     "FeatureFlagSettings",
+    "get_feature_flag_client",
+    "is_flag_enabled",
 ]

{unique_toolkit-2026.24.0.dev9 → unique_toolkit-2026.24.0.dev11}/unique_toolkit/experimental/resources/feature_flags/client.py

@@ -114,12 +114,12 @@ class FeatureFlagClient:
             return FlagEvaluation(
                 value=value, reason="cached" if from_cache else "remote"
             )
-        except Exception:
+        except Exception as exc:
             logger.warning(
                 "FeatureFlagClient: fetch failed for '%s' (company=%s) — trying stale cache",
                 flag,
                 company_id,
-                exc_info=True,
+                exc_info=not isinstance(exc, httpx.HTTPError),
             )
             stale_value, stale_hit = self._cache.get_stale(cache_key)
             if stale_hit:
@@ -213,3 +213,37 @@ class BoundFeatureFlagClient:
 
     async def is_enabled(self, flag: str) -> bool:
         return (await self.evaluate(flag)).value
+
+
+def get_feature_flag_client() -> FeatureFlagClient:
+    """Return the process-level :class:`FeatureFlagClient` singleton.
+
+    Built lazily via :meth:`FeatureFlagClient.from_settings` which reads
+    ``CONFIGURATION_BACKEND_URL`` and ``FEATURE_FLAG_SERVICE_ID`` from env.
+    Falls back to env-var defaults on missing config or transport errors.
+    """
+    return FeatureFlagClient.from_settings()
+
+
+async def is_flag_enabled(
+    flag: str,
+    company_id: str,
+    user_id: str | None = None,
+) -> bool:
+    """Evaluate *flag* and log when disabled.
+
+    Convenience wrapper for route handlers that want a single call-site
+    without manually managing the client singleton.
+    """
+    enabled = await get_feature_flag_client().is_enabled(
+        flag, company_id=company_id, user_id=user_id
+    )
+    if not enabled:
+        user_suffix = f" user {user_id}" if user_id else ""
+        logger.info(
+            "Feature flag '%s' disabled for company %s%s.",
+            flag,
+            company_id,
+            user_suffix,
+        )
+    return enabled

unique_toolkit-2026.24.0.dev9/unique_toolkit/agentic/tools/a2a/config.py

@@ -1,17 +0,0 @@
-from pydantic import Field
-
-from unique_toolkit.agentic.tools.a2a.evaluation import SubAgentEvaluationConfig
-from unique_toolkit.agentic.tools.a2a.postprocessing import SubAgentDisplayConfig
-from unique_toolkit.agentic.tools.a2a.tool import SubAgentToolConfig
-
-
-# SubAgentToolConfig with display and evaluation configs
-class ExtendedSubAgentToolConfig(SubAgentToolConfig):
-    response_display_config: SubAgentDisplayConfig = Field(
-        default_factory=SubAgentDisplayConfig,
-        description="Configuration for how to display the sub-agent response.",
-    )
-    evaluation_config: SubAgentEvaluationConfig = Field(
-        default_factory=SubAgentEvaluationConfig,
-        description="Configuration for handling assessments of the sub-agent response.",
-    )

unique_toolkit-2026.24.0.dev9/unique_toolkit/agentic/tools/a2a/tool/__init__.py

@@ -1,4 +0,0 @@
-from unique_toolkit.agentic.tools.a2a.tool.config import SubAgentToolConfig
-from unique_toolkit.agentic.tools.a2a.tool.service import SubAgentTool
-
-__all__ = ["SubAgentTool", "SubAgentToolConfig"]