unique_toolkit 2026.28.0.dev1__py3-none-any.whl → 2026.28.0.dev2__py3-none-any.whl

unique_toolkit/agentic/tools/experimental/__init__.py

@@ -1,3 +1,7 @@
+from unique_toolkit.agentic.tools.experimental.ask_user_tool import (
+    AskUserTool,
+    AskUserToolConfig,
+)
 from unique_toolkit.agentic.tools.experimental.open_file_tool import (
     OpenFileTool,
     OpenFileToolRuntime,
@@ -19,6 +23,8 @@ from unique_toolkit.agentic.tools.experimental.todo import (
 )
 
 __all__ = [
+    "AskUserTool",
+    "AskUserToolConfig",
     "DisplayMode",
     "OpenFileTool",
     "OpenFileToolRuntime",

unique_toolkit/agentic/tools/experimental/ask_user_tool/__init__.py

@@ -0,0 +1,14 @@
+from unique_toolkit.agentic.tools.experimental.ask_user_tool.config import (
+    AskUserToolConfig,
+)
+from unique_toolkit.agentic.tools.experimental.ask_user_tool.tool import (
+    AskUserTool,
+)
+from unique_toolkit.agentic.tools.factory import ToolFactory
+
+ToolFactory.register_tool(AskUserTool, AskUserToolConfig)
+
+__all__ = [
+    "AskUserTool",
+    "AskUserToolConfig",
+]

unique_toolkit/agentic/tools/experimental/ask_user_tool/config.py

@@ -0,0 +1,138 @@
+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
+from unique_toolkit.elicitation import (
+    ElicitationCancelledException,
+    ElicitationDeclinedException,
+    ElicitationExpiredException,
+)
+
+_DEFAULT_TOOL_DESCRIPTION = """
+Ask the user a question through a structured form and block until they answer. Use whenever you need information, a decision, or confirmation before continuing correctly: clarifying questions, confirmation before destructive or irreversible work, missing parameters, or choosing among plausible options. Do not ask the user in normal chat text while this tool is available—call AskUser, wait for the result, then continue. If unsure which interpretation, scope, or value applies, call AskUser instead of guessing. Destructive actions must include an explicit confirmation field. Form and chat anchoring are handled for you; the call blocks until the user responds, declines, cancels, or times out.
+""".strip()
+
+_DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT = """
+- If your next message would ask the user for information, a decision, or confirmation, call AskUser instead of writing the question in chat.
+- If more than one reasonable reading of the request exists, call AskUser before acting—do not silently pick a default.
+- Destructive or irreversible actions require an explicit confirmation field (e.g. boolean `confirm`) in `response_schema`.
+""".strip()
+
+_DEFAULT_MESSAGE_DESCRIPTION = "The question or prompt shown to the user"
+
+_DEFAULT_RESPONSE_SCHEMA_DESCRIPTION = """
+JSON Schema object (root type "object") for the form shown to the user; you construct it. Single string property for free-text; boolean for a confirmation; string + enum for one choice (dropdown); array with items.enum for choose-many. Mark needed fields required and add short property descriptions (shown as help text). Prefer one small form over many calls.
+Examples:
+    - free-text: {"type":"object","properties":{"answer":{"type":"string"}},"required":["answer"]};
+    - confirm: {"type":"object","properties":{"confirm":{"type":"boolean"}},"required":["confirm"]};
+    - choice: {"type":"object","properties":{"region":{"type":"string","enum":["EU","US"]}},"required":["region"]};
+    - multi: {"type":"object","properties":{"topics":{"type":"array","items":{"type":"string","enum":["a","b"]}}}}.
+""".strip()
+
+_TIMEOUT_SECONDS_MIN = 1
+_TIMOUT_SECONDS_MAX = 3600
+
+_POLLING_SECONDS_MIN = 0.5
+_POLLING_SECONDS_MAX = 60
+
+
+class AskUserToolConfig(BaseToolConfig):
+    tool_description: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(
+            rows=len(_DEFAULT_TOOL_DESCRIPTION.splitlines())
+        ),
+    ] = Field(
+        default=_DEFAULT_TOOL_DESCRIPTION,
+        description="Description shown to the model for this tool.",
+    )
+
+    tool_description_for_system_prompt: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(
+            rows=len(_DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT.splitlines())
+        ),
+    ] = Field(
+        default=_DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT,
+        description="Extra system guidance about when and how to use AskUser.",
+    )
+
+    message_description: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(
+            rows=len(_DEFAULT_MESSAGE_DESCRIPTION.splitlines())
+        ),
+    ] = Field(
+        default=_DEFAULT_MESSAGE_DESCRIPTION,
+        description="Description of the `message` parameter shown to the model.",
+        title="`message` tool input field description",
+    )
+
+    response_schema_description: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(
+            rows=len(_DEFAULT_MESSAGE_DESCRIPTION.splitlines())
+        ),
+    ] = Field(
+        default=_DEFAULT_RESPONSE_SCHEMA_DESCRIPTION,
+        description="Description of the `response_schema` parameter shown to the model.",
+        title="`response_schema` tool input field description",
+    )
+
+    declined_message: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(
+            rows=len(ElicitationDeclinedException.INSTRUCTION.splitlines())
+        ),
+    ] = Field(
+        default=ElicitationDeclinedException.INSTRUCTION,
+        description="Message returned to the model when the user declines the request.",
+        title="Declined response",
+    )
+
+    cancelled_message: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(
+            rows=len(ElicitationCancelledException.INSTRUCTION.splitlines())
+        ),
+    ] = Field(
+        default=ElicitationCancelledException.INSTRUCTION,
+        description="Message returned to the model when the user cancels the request.",
+        title="Cancelled response",
+    )
+
+    expired_message: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(
+            rows=len(ElicitationExpiredException.INSTRUCTION.splitlines())
+        ),
+    ] = Field(
+        default=ElicitationExpiredException.INSTRUCTION,
+        description="Message returned to the model when the request expires before the user responds.",
+        title="Expired response",
+    )
+
+    timeout_seconds: Annotated[
+        int,
+        RJSFMetaTag.NumberWidget.updown(
+            min=_TIMEOUT_SECONDS_MIN, max=_TIMOUT_SECONDS_MAX
+        ),
+    ] = Field(
+        default=300,
+        ge=_TIMEOUT_SECONDS_MIN,
+        le=_TIMOUT_SECONDS_MAX,
+        description="Maximum seconds to wait for the user to respond.",
+    )
+    poll_interval_seconds: Annotated[
+        float,
+        RJSFMetaTag.NumberWidget.updown(
+            min=_POLLING_SECONDS_MIN, max=_POLLING_SECONDS_MAX, step=0.5
+        ),
+    ] = Field(
+        default=1.0,
+        ge=_POLLING_SECONDS_MIN,
+        le=_POLLING_SECONDS_MAX,
+        description="Seconds to wait between attempts when checking whether user has responded.",
+    )

unique_toolkit/agentic/tools/experimental/ask_user_tool/tool.py

@@ -0,0 +1,149 @@
+import asyncio
+import json
+import logging
+from typing import Annotated, override
+
+from pydantic import BaseModel, Field, JsonValue, StringConstraints
+
+from unique_toolkit.agentic.evaluation.schemas import EvaluationMetricName
+from unique_toolkit.agentic.tools.experimental.ask_user_tool.config import (
+    AskUserToolConfig,
+)
+from unique_toolkit.agentic.tools.schemas import ToolCallResponse
+from unique_toolkit.agentic.tools.tool import Tool
+from unique_toolkit.agentic.tools.tool_progress_reporter import ToolProgressReporter
+from unique_toolkit.app.schemas import ChatEvent
+from unique_toolkit.elicitation import (
+    ElicitationCancelledException,
+    ElicitationDeclinedException,
+    ElicitationExpiredException,
+    ElicitationMode,
+)
+from unique_toolkit.language_model.schemas import (
+    LanguageModelFunction,
+    LanguageModelToolDescription,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+MessageType = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
+ResponseSchemaType = dict[str, JsonValue]
+
+
+class AskUserToolInput(BaseModel):
+    message: MessageType
+    response_schema: ResponseSchemaType
+
+
+class AskUserTool(Tool[AskUserToolConfig]):
+    name = "AskUser"
+    DISPLAY_NAME = "Ask User"
+
+    def __init__(
+        self,
+        config: AskUserToolConfig,
+        event: ChatEvent,
+        tool_progress_reporter: ToolProgressReporter | None = None,
+    ) -> None:
+        super().__init__(
+            config=config, event=event, tool_progress_reporter=tool_progress_reporter
+        )
+        self._lock = asyncio.Lock()
+
+    @override
+    def display_name(self) -> str:
+        return self.DISPLAY_NAME
+
+    @override
+    def tool_description(self) -> LanguageModelToolDescription:
+        class AskUserToolInputWithDescriptions(AskUserToolInput):
+            message: MessageType = Field(description=self.config.message_description)
+            response_schema: ResponseSchemaType = Field(
+                description=self.config.response_schema_description
+            )
+
+        return LanguageModelToolDescription(
+            name=self.name,
+            description=self.config.tool_description,
+            parameters=AskUserToolInputWithDescriptions,
+        )
+
+    @override
+    def tool_description_for_system_prompt(self) -> str:
+        return self.config.tool_description_for_system_prompt
+
+    @override
+    def is_capability(self) -> bool:
+        return True
+
+    @override
+    def evaluation_check_list(self) -> list[EvaluationMetricName]:
+        return []
+
+    @override
+    def get_evaluation_checks_based_on_tool_response(
+        self,
+        tool_response: ToolCallResponse,
+    ) -> list[EvaluationMetricName]:
+        return []
+
+    @override
+    async def run(self, tool_call: LanguageModelFunction) -> ToolCallResponse:
+        # When multiple elicitation calls are created, the frontend will render them one by one
+        # We need to lock the execution of the tool so that the timeout starts when the user
+        # actually sees the elicitation call
+        async with self._lock:
+            return await self._run(tool_call)
+
+    async def _run(self, tool_call: LanguageModelFunction) -> ToolCallResponse:
+        params = AskUserToolInput.model_validate(tool_call.arguments)
+
+        service = self.chat_service.elicitation
+
+        _LOGGER.info("Creating elicitation request")
+
+        created = await service.create_async(
+            mode=ElicitationMode.FORM,
+            message=params.message,
+            tool_name=self.display_name(),
+            json_schema=params.response_schema,
+            expires_in_seconds=self.config.timeout_seconds,
+        )
+
+        _LOGGER.info("Elicitation request (id %s) successfully created", created.id)
+
+        try:
+            elicitation = await service.wait_for_response_async(
+                elicitation_id=created.id,
+                timeout_seconds=self.config.timeout_seconds,
+                poll_interval_seconds=self.config.poll_interval_seconds,
+            )
+        except ElicitationDeclinedException:
+            _LOGGER.info("Elicitation with id %s was declined", created.id)
+            return ToolCallResponse(
+                id=tool_call.id,
+                name=self.name,
+                content=self.config.declined_message,
+            )
+        except ElicitationCancelledException:
+            _LOGGER.info("Elicitation with id %s was cancelled", created.id)
+            return ToolCallResponse(
+                id=tool_call.id,
+                name=self.name,
+                content=self.config.cancelled_message,
+            )
+        except ElicitationExpiredException:
+            _LOGGER.info("Elicitation with id %s has expired", created.id)
+            return ToolCallResponse(
+                id=tool_call.id,
+                name=self.name,
+                content=self.config.expired_message,
+            )
+
+        _LOGGER.info("User responded to elicitation request")
+
+        return ToolCallResponse(
+            id=tool_call.id,
+            name=self.name,
+            content=json.dumps(elicitation.response_content, ensure_ascii=False),
+        )

unique_toolkit/elicitation/service.py

@@ -1,7 +1,13 @@
+import asyncio
 from typing import Any
 
 from unique_toolkit._common.validate_required_values import validate_required_values
 from unique_toolkit.app.schemas import ChatEvent, Correlation
+from unique_toolkit.elicitation.exceptions import (
+    ElicitationCancelledException,
+    ElicitationDeclinedException,
+    ElicitationExpiredException,
+)
 from unique_toolkit.elicitation.functions import (
     create_elicitation,
     create_elicitation_async,
@@ -18,6 +24,7 @@ from unique_toolkit.elicitation.schemas import (
     ElicitationList,
     ElicitationMode,
     ElicitationResponseResult,
+    ElicitationStatus,
 )
 
 
@@ -235,6 +242,45 @@ class ElicitationService:
             elicitation_id=elicitation_id,
         )
 
+    async def wait_for_response_async(
+        self,
+        *,
+        elicitation_id: str,
+        timeout_seconds: int,
+        poll_interval_seconds: float = 1.0,
+    ) -> Elicitation:
+        """
+        Poll an elicitation until the user accepts it.
+
+        Args:
+            elicitation_id (str): The elicitation ID to poll.
+            timeout_seconds (int): How long to wait before giving up.
+            poll_interval_seconds (float): Seconds between polls.
+
+        Returns:
+            Elicitation: The accepted elicitation.
+
+        Raises:
+            ElicitationDeclinedException: If the user declined.
+            ElicitationCancelledException: If the user cancelled.
+            ElicitationExpiredException: If the request expired or timed out.
+        """
+        num_trials = int(timeout_seconds / poll_interval_seconds) + 1
+        for _ in range(num_trials):
+            elicitation = await self.get_async(elicitation_id)
+            match elicitation.status:
+                case ElicitationStatus.ACCEPTED:
+                    return elicitation
+                case ElicitationStatus.DECLINED:
+                    raise ElicitationDeclinedException()
+                case ElicitationStatus.CANCELLED:
+                    raise ElicitationCancelledException()
+                case ElicitationStatus.EXPIRED:
+                    raise ElicitationExpiredException()
+                case _:
+                    await asyncio.sleep(poll_interval_seconds)
+        raise ElicitationExpiredException()
+
     # List Pending Methods
     ############################################################################
 

{unique_toolkit-2026.28.0.dev1.dist-info → unique_toolkit-2026.28.0.dev2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 2026.28.0.dev1
+Version: 2026.28.0.dev2
 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.dev2,<2026.28.0rc0
+Requires-Dist: unique-sdk>=2026.28.0.dev3,<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.dev1.dist-info → unique_toolkit-2026.28.0.dev2.dist-info}/RECORD

@@ -175,7 +175,10 @@ unique_toolkit/agentic/tools/a2a/tool/service.py,sha256=mRrDYBEMYgk36xqLwtolRh9r
 unique_toolkit/agentic/tools/a2a/tool/test/test_service_utils.py,sha256=x4leRxnGgqD-XyXPkW2z1ekv4Ja7EStXd-24LGadPZA,24858
 unique_toolkit/agentic/tools/agent_chunks_hanlder.py,sha256=eO0g46wZOQlmWqYYVGiszRVe8K2LX-9qW30ZCdGg5eE,1943
 unique_toolkit/agentic/tools/config.py,sha256=LUKSENFvBuOPyllCGEmoO8Q_1HpAw4hZuTxfNmyFHWA,3905
-unique_toolkit/agentic/tools/experimental/__init__.py,sha256=SiH0_ELGwQUinX2qjZ4ziroJLqpmowYWLEzCxhqUm88,800
+unique_toolkit/agentic/tools/experimental/__init__.py,sha256=ArEcXHGPtMRNsDnsyo9v1fev0EZWdJ6D7NWdPEFLQKM,956
+unique_toolkit/agentic/tools/experimental/ask_user_tool/__init__.py,sha256=B8srRVw4vMLa4dZE5yoF1Bqpjlv8moh_m-dP2BVRjDc,375
+unique_toolkit/agentic/tools/experimental/ask_user_tool/config.py,sha256=z95ZaxkMvsmjVaUYWWZrvpD21-Us1KNUrMgXzpF4uo4,5923
+unique_toolkit/agentic/tools/experimental/ask_user_tool/tool.py,sha256=yTjONO1Ieh3YsHJzebNstd73YoK40V6wG9o_8-avk30,5111
 unique_toolkit/agentic/tools/experimental/open_file_tool/__init__.py,sha256=hPkz1tbiup8-QM62QMLWA1PpUmzX5VsNUnXsXw1_dMY,319
 unique_toolkit/agentic/tools/experimental/open_file_tool/config.py,sha256=FQylVpCkOw06PSnfODOBwWARRrAI7UoUELzApWNVb2w,4342
 unique_toolkit/agentic/tools/experimental/open_file_tool/runtime.py,sha256=SOIFV2N8USPGHNBnzId2nJPhZiJ3kGO5AwAiKJBNhdI,14383
@@ -269,7 +272,7 @@ unique_toolkit/elicitation/constants.py,sha256=ab24uagL6ynOKQrLMUChkFxI7dUyBYCoh
 unique_toolkit/elicitation/exceptions.py,sha256=hF17eW4GGrtHw0lo77YfZdyIy65SGaWhxoJPx46GK7c,4082
 unique_toolkit/elicitation/functions.py,sha256=RWIglWH9SpiGunqiU7hO2TXkqASkAfk4CfJ3m4uJewU,11417
 unique_toolkit/elicitation/schemas.py,sha256=ugss-r0r8O9XwGpYAkklnLDLvp1XVyzHS521HU8BOjY,5735
-unique_toolkit/elicitation/service.py,sha256=bzS6RC27z1fX8_eXBgH8WursZ1FJJt-yTMCNEh7Xj0g,10793
+unique_toolkit/elicitation/service.py,sha256=cdJ8XVQhvhb_AkZQyd7IrkZ9ktLKs_TZlglNIpcUD-0,12507
 unique_toolkit/embedding/__init__.py,sha256=uUyzjonPvuDCYsvXCIt7ErQXopLggpzX-MEQd3_e2kE,250
 unique_toolkit/embedding/constants.py,sha256=Lj8-Lcy1FvuC31PM9Exq7vaFuxQV4pEI1huUMFX-J2M,52
 unique_toolkit/embedding/functions.py,sha256=OWzY-iPNBjwXgSNNXDmu89Lzu-PAMG3Q7igtUcFrcc8,1944
@@ -399,6 +402,6 @@ unique_toolkit/short_term_memory/service.py,sha256=Qo-c9yxzC1ZEEHJyIG_vnRs_ef0SK
 unique_toolkit/smart_rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 unique_toolkit/smart_rules/compile.py,sha256=vRe0aMJWuVIK-VsqomgxQImzke7MDmwgSxxJfYCa7zw,1386
 unique_toolkit/test_utilities/events.py,sha256=FLrhMh0A_mQutAUjoD0FdMcVQ4Gq31r35OVGzRjvLro,6760
-unique_toolkit-2026.28.0.dev1.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
-unique_toolkit-2026.28.0.dev1.dist-info/METADATA,sha256=9_-Pt8xbGisiMP1DrYdlrlrn5yIYHbS0Bbo_5ZOWn-Q,7426
-unique_toolkit-2026.28.0.dev1.dist-info/RECORD,,
+unique_toolkit-2026.28.0.dev2.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+unique_toolkit-2026.28.0.dev2.dist-info/METADATA,sha256=-L08qC8wJBPOovWUmGDdBRkhEdhxxYe-8LGLw6dW_Rs,7426
+unique_toolkit-2026.28.0.dev2.dist-info/RECORD,,