unique_toolkit 1.20.0__py3-none-any.whl → 1.21.0__py3-none-any.whl

unique_toolkit/agentic/tools/test/test_tool_progress_reporter.py

@@ -7,6 +7,7 @@ from unique_toolkit.agentic.tools.tool_progress_reporter import (
     ProgressState,
     ToolExecutionStatus,
     ToolProgressReporter,
+    ToolProgressReporterConfig,
     ToolWithToolProgressReporter,
     track_tool_progress,
 )
@@ -203,3 +204,226 @@ class TestToolProgressDecorator:
 
         status = tool_progress_reporter.tool_statuses[tool_call.id]
         assert status.state == ProgressState.FAILED
+
+
+class TestToolProgressReporterConfig:
+    """Tests for ToolProgressReporterConfig and custom display configuration."""
+
+    @pytest.mark.ai
+    @pytest.mark.asyncio
+    async def test_config__uses_default_templates__when_no_config_provided(
+        self, chat_service, tool_call
+    ) -> None:
+        """
+        Purpose: Verify that default state-to-display templates are used when no config is provided.
+        Why this matters: Ensures backward compatibility and default behavior.
+        Setup summary: Create reporter without config, add status, verify default template is used.
+        """
+        # Arrange
+        reporter = ToolProgressReporter(chat_service)
+
+        # Act
+        await reporter.notify_from_tool_call(
+            tool_call=tool_call,
+            name="Test Tool",
+            message="Processing data",
+            state=ProgressState.RUNNING,
+        )
+
+        # Assert
+        assert tool_call.id in reporter.tool_statuses
+        chat_service.modify_assistant_message_async.assert_called()
+        call_args = chat_service.modify_assistant_message_async.call_args
+        content = call_args.kwargs["content"]
+        assert "Test Tool" in content
+        assert "🟡" in content  # Default emoji for RUNNING state
+        assert "Processing data" in content
+
+    @pytest.mark.ai
+    @pytest.mark.asyncio
+    async def test_config__uses_custom_templates__when_config_provided(
+        self, chat_service, tool_call
+    ) -> None:
+        """
+        Purpose: Verify that custom templates are used when provided via config.
+        Why this matters: Enables customization of progress display format.
+        Setup summary: Create reporter with custom template, verify custom format is used.
+        """
+        # Arrange
+        custom_config = ToolProgressReporterConfig(
+            state_to_display_template={
+                ProgressState.RUNNING: "⏳ {tool_name}: {message}",
+                ProgressState.FINISHED: "✅ {tool_name}: {message}",
+            }
+        )
+        reporter = ToolProgressReporter(chat_service, config=custom_config)
+
+        # Act
+        await reporter.notify_from_tool_call(
+            tool_call=tool_call,
+            name="My Tool",
+            message="Working on it",
+            state=ProgressState.RUNNING,
+        )
+
+        # Assert
+        chat_service.modify_assistant_message_async.assert_called()
+        call_args = chat_service.modify_assistant_message_async.call_args
+        content = call_args.kwargs["content"]
+        assert "⏳ My Tool: Working on it" in content
+        assert "🟡" not in content  # Default emoji should not appear
+
+    @pytest.mark.ai
+    @pytest.mark.asyncio
+    async def test_config__skips_states_not_in_template__when_state_excluded(
+        self, chat_service, tool_call
+    ) -> None:
+        """
+        Purpose: Verify that states not in the config mapping are not displayed.
+        Why this matters: Allows selective display of only certain states (e.g., hide STARTED).
+        Setup summary: Create config excluding RUNNING state, verify message is not displayed.
+        """
+        # Arrange
+        custom_config = ToolProgressReporterConfig(
+            state_to_display_template={
+                ProgressState.FINISHED: "✅ {tool_name}: {message}",
+                # RUNNING state is intentionally excluded
+            }
+        )
+        reporter = ToolProgressReporter(chat_service, config=custom_config)
+
+        # Act
+        await reporter.notify_from_tool_call(
+            tool_call=tool_call,
+            name="Test Tool",
+            message="Processing",
+            state=ProgressState.RUNNING,
+        )
+
+        # Assert
+        chat_service.modify_assistant_message_async.assert_called()
+        call_args = chat_service.modify_assistant_message_async.call_args
+        content = call_args.kwargs["content"]
+        # Content should not contain the message since RUNNING is excluded
+        assert "Processing" not in content
+        assert "Test Tool" not in content
+
+    @pytest.mark.ai
+    @pytest.mark.asyncio
+    async def test_config__formats_placeholders_correctly__with_multiple_tools(
+        self, chat_service
+    ) -> None:
+        """
+        Purpose: Verify that {tool_name} and {message} placeholders are replaced correctly for multiple tools.
+        Why this matters: Ensures template formatting works correctly in multi-tool scenarios.
+        Setup summary: Add multiple tool statuses with different names/messages, verify formatting.
+        """
+        # Arrange
+        custom_config = ToolProgressReporterConfig(
+            state_to_display_template={
+                ProgressState.RUNNING: "▶️ {tool_name} - {message}",
+                ProgressState.FINISHED: "✓ {tool_name} - {message}",
+            }
+        )
+        reporter = ToolProgressReporter(chat_service, config=custom_config)
+        tool_call_1 = LanguageModelFunction(id="tool_1", name="search")
+        tool_call_2 = LanguageModelFunction(id="tool_2", name="analyze")
+
+        # Act
+        await reporter.notify_from_tool_call(
+            tool_call=tool_call_1,
+            name="Search Tool",
+            message="Searching database",
+            state=ProgressState.RUNNING,
+        )
+        await reporter.notify_from_tool_call(
+            tool_call=tool_call_2,
+            name="Analysis Tool",
+            message="Analyzing results",
+            state=ProgressState.FINISHED,
+        )
+
+        # Assert
+        call_args = chat_service.modify_assistant_message_async.call_args
+        content = call_args.kwargs["content"]
+        assert "▶️ Search Tool - Searching database" in content
+        assert "✓ Analysis Tool - Analyzing results" in content
+
+    @pytest.mark.ai
+    @pytest.mark.asyncio
+    async def test_config__shows_only_finished_state__when_only_finished_configured(
+        self, chat_service, tool_call
+    ) -> None:
+        """
+        Purpose: Verify selective state display shows only FINISHED when it's the only state configured.
+        Why this matters: Use case where user only wants final results, not intermediate steps.
+        Setup summary: Configure only FINISHED state, send STARTED and FINISHED, verify only FINISHED appears.
+        """
+        # Arrange
+        custom_config = ToolProgressReporterConfig(
+            state_to_display_template={
+                ProgressState.FINISHED: "Done: {tool_name} - {message}",
+            }
+        )
+        reporter = ToolProgressReporter(chat_service, config=custom_config)
+
+        # Act - Send STARTED state (should not appear)
+        await reporter.notify_from_tool_call(
+            tool_call=tool_call,
+            name="Test Tool",
+            message="Starting",
+            state=ProgressState.STARTED,
+        )
+
+        # Get first call content
+        first_call_args = chat_service.modify_assistant_message_async.call_args
+        first_content = first_call_args.kwargs["content"]
+
+        # Act - Update to FINISHED state (should appear)
+        await reporter.notify_from_tool_call(
+            tool_call=tool_call,
+            name="Test Tool",
+            message="Completed successfully",
+            state=ProgressState.FINISHED,
+        )
+
+        # Assert
+        final_call_args = chat_service.modify_assistant_message_async.call_args
+        final_content = final_call_args.kwargs["content"]
+
+        # STARTED state should not appear in first call
+        assert "Starting" not in first_content
+
+        # FINISHED state should appear in final call
+        assert "Done: Test Tool - Completed successfully" in final_content
+
+    @pytest.mark.ai
+    @pytest.mark.asyncio
+    async def test_config__handles_empty_template_dict__when_all_states_excluded(
+        self, chat_service, tool_call
+    ) -> None:
+        """
+        Purpose: Verify that an empty template dict results in no messages being displayed.
+        Why this matters: Edge case handling and allows disabling all progress display.
+        Setup summary: Create config with empty dict, verify no tool messages appear.
+        """
+        # Arrange
+        custom_config = ToolProgressReporterConfig(state_to_display_template={})
+        reporter = ToolProgressReporter(chat_service, config=custom_config)
+
+        # Act
+        await reporter.notify_from_tool_call(
+            tool_call=tool_call,
+            name="Test Tool",
+            message="Processing",
+            state=ProgressState.RUNNING,
+        )
+
+        # Assert
+        chat_service.modify_assistant_message_async.assert_called()
+        call_args = chat_service.modify_assistant_message_async.call_args
+        content = call_args.kwargs["content"]
+
+        # Should only have the progress start text and newlines, no actual messages
+        assert "Test Tool" not in content
+        assert "Processing" not in content

unique_toolkit/agentic/tools/tool_progress_reporter.py

@@ -1,11 +1,12 @@
 import re
 from datetime import datetime
-from enum import Enum
+from enum import StrEnum
 from functools import wraps
 from typing import Protocol
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
+from unique_toolkit._common.pydantic_helpers import get_configuration_dict
 from unique_toolkit.chat.service import ChatService
 from unique_toolkit.content.schemas import ContentReference
 from unique_toolkit.language_model.schemas import (
@@ -17,11 +18,11 @@ ARROW = "→ "
 DUMMY_REFERENCE_PLACEHOLDER = "<sup></sup>"
 
 
-class ProgressState(Enum):
-    STARTED = "⚪"
-    RUNNING = "🟡"
-    FAILED = "🔴"
-    FINISHED = "🟢"
+class ProgressState(StrEnum):
+    STARTED = "started"
+    RUNNING = "running"
+    FAILED = "failed"
+    FINISHED = "finished"
 
 
 class ToolExecutionStatus(BaseModel):
@@ -29,15 +30,56 @@ class ToolExecutionStatus(BaseModel):
     message: str
     state: ProgressState
     references: list[ContentReference] = []
-    timestamp: datetime = datetime.now()
+    timestamp: datetime = Field(default_factory=datetime.now)
+
+
+_DEFAULT_STATE_TO_DISPLAY_TEMPLATE = {
+    ProgressState.FINISHED: "{arrow}**{{tool_name}}** 🟢: {{message}}".format(
+        arrow=ARROW
+    ),
+    ProgressState.RUNNING: "{arrow}**{{tool_name}}** 🟡: {{message}}".format(
+        arrow=ARROW
+    ),
+    ProgressState.FAILED: "{arrow}**{{tool_name}}** 🔴: {{message}}".format(
+        arrow=ARROW
+    ),
+    ProgressState.STARTED: "{arrow}**{{tool_name}}** ⚪: {{message}}".format(
+        arrow=ARROW
+    ),
+}
+
+
+state_to_display_template_description = """
+A mapping progress states to display templates.
+The display template is a string that will be used to display the progress status.
+The template can contain the following placeholders:
+- `{tool_name}`: The name of the tool
+- `{message}`: The message to display (sent by the tool)
+
+If a state is not present in the mapping, then updates for that state will not be displayed.
+""".strip()
+
+
+class ToolProgressReporterConfig(BaseModel):
+    model_config = get_configuration_dict()
+
+    state_to_display_template: dict[ProgressState, str] = Field(
+        default=_DEFAULT_STATE_TO_DISPLAY_TEMPLATE,
+        description=state_to_display_template_description,
+    )
 
 
 class ToolProgressReporter:
-    def __init__(self, chat_service: ChatService):
+    def __init__(
+        self,
+        chat_service: ChatService,
+        config: ToolProgressReporterConfig | None = None,
+    ):
         self.chat_service = chat_service
         self.tool_statuses: dict[str, ToolExecutionStatus] = {}
         self._progress_start_text = ""
         self._requires_new_assistant_message = False
+        self._config = config or ToolProgressReporterConfig()
 
     @property
     def requires_new_assistant_message(self):
@@ -77,16 +119,13 @@ class ToolProgressReporter:
             references (list[ContentReference], optional): List of content references. Defaults to [].
             requires_new_assistant_message (bool, optional): Whether a new assistant message is needed when tool call is finished.
             Defaults to False. If yes, the agentic steps will remain in chat history and will be overwritten by the stream response.
-
-        Raises:
-            AssertionError: If tool_call.id is None
         """
-        assert tool_call.id is not None
         self.tool_statuses[tool_call.id] = ToolExecutionStatus(
             name=name,
             message=message,
             state=state,
             references=references,
+            timestamp=self._get_timestamp_for_tool_call(tool_call),
         )
         self.requires_new_assistant_message = (
             self.requires_new_assistant_message or requires_new_assistant_message
@@ -103,7 +142,11 @@ class ToolProgressReporter:
             references = self._correct_reference_sequence(references, start_number)
             all_references.extend(references)
 
-            messages.append(f"{ARROW}**{item.name} {item.state.value}**: {message}")
+            display_message = self._get_tool_status_display_message(
+                name=item.name, message=message, state=item.state
+            )
+            if display_message is not None:
+                messages.append(display_message)
 
         await self.chat_service.modify_assistant_message_async(
             content=self._progress_start_text + "\n\n" + "\n\n".join(messages),
@@ -130,6 +173,28 @@ class ToolProgressReporter:
             reference.sequence_number = i
         return references
 
+    def _get_timestamp_for_tool_call(
+        self, tool_call: LanguageModelFunction
+    ) -> datetime:
+        """
+        Keep the same timestamp if the tool call is already in the statuses.
+        This ensures the display order stays consistent.
+        """
+        if tool_call.id in self.tool_statuses:
+            return self.tool_statuses[tool_call.id].timestamp
+
+        return datetime.now()
+
+    def _get_tool_status_display_message(
+        self, name: str, message: str, state: ProgressState
+    ) -> str | None:
+        if state in self._config.state_to_display_template:
+            return self._config.state_to_display_template[state].format(
+                tool_name=name,
+                message=message,
+            )
+        return None
+
 
 class ToolWithToolProgressReporter(Protocol):
     tool_progress_reporter: ToolProgressReporter

unique_toolkit/language_model/schemas.py

@@ -83,22 +83,21 @@ class LanguageModelStreamResponseMessage(BaseModel):
 class LanguageModelFunction(BaseModel):
     model_config = model_config
 
-    id: str | None = None
+    id: str = Field(default_factory=lambda: uuid4().hex)
     name: str
-    arguments: dict[str, Any] | str | None = None  # type: ignore
+    arguments: dict[str, Any] | None = None
 
     @field_validator("arguments", mode="before")
-    def set_arguments(cls, value):
+    def set_arguments(cls, value: Any) -> Any:
         if isinstance(value, str):
             return json.loads(value)
         return value
 
     @field_validator("id", mode="before")
-    def randomize_id(cls, value):
-        if not value:
+    def randomize_id(cls, value: Any) -> Any:
+        if value is None or value == "":
             return uuid4().hex
-        else:
-            return value
+        return value
 
     @model_serializer()
     def serialize_model(self):
@@ -108,7 +107,7 @@ class LanguageModelFunction(BaseModel):
             seralization["arguments"] = json.dumps(self.arguments)
         return seralization
 
-    def __eq__(self, other: Self) -> bool:
+    def __eq__(self, other: object) -> bool:
         """Compare two tool calls based on name and arguments."""
         if not isinstance(other, LanguageModelFunction):
             return False

{unique_toolkit-1.20.0.dist-info → unique_toolkit-1.21.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: unique_toolkit
-Version: 1.20.0
+Version: 1.21.0
 Summary: 
 License: Proprietary
 Author: Cedric Klinkert
@@ -119,6 +119,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [1.21.0] - 2025-10-30
+- Add option to customize the display of tool progress statuses.
+
+## [1.20.1] - 2025-10-30
+- Fix typing issues in `LanguageModelFunction`.
+
 ## [1.20.0] - 2025-10-30
 - Fix bug where async tasks executed with `SafeTaskExecutor` did not log exceptions.
 - Add option to customize sub agent response display title.

{unique_toolkit-1.20.0.dist-info → unique_toolkit-1.21.0.dist-info}/RECORD

@@ -93,10 +93,10 @@ unique_toolkit/agentic/tools/openai_builtin/code_interpreter/service.py,sha256=R
 unique_toolkit/agentic/tools/openai_builtin/manager.py,sha256=kU4wGit9AnDbkijB7LJEHcGXG8UeTBhiZh4a7lxTGA8,2246
 unique_toolkit/agentic/tools/schemas.py,sha256=0ZR8xCdGj1sEdPE0lfTIG2uSR5zqWoprUa3Seqez4C8,4837
 unique_toolkit/agentic/tools/test/test_mcp_manager.py,sha256=8j5fNQf3qELOcQ0m5fd8OkIFgunL5ILgdWzYD_Ccg1I,18816
-unique_toolkit/agentic/tools/test/test_tool_progress_reporter.py,sha256=dod5QPqgGUInVAGXAbsAKNTEypIi6pUEWhDbJr9YfUU,6307
+unique_toolkit/agentic/tools/test/test_tool_progress_reporter.py,sha256=lZr6QnEn8cuBCAe_a1R1iKX8tL2PRL_p2-sCTBfhrvw,15162
 unique_toolkit/agentic/tools/tool.py,sha256=mFuxc3h4sghClDO8OVL2-6kifiHQ-U7JMYGUyXqTYLE,6338
 unique_toolkit/agentic/tools/tool_manager.py,sha256=DtxJobe_7QKFe6CjnMhCP-mnKO6MjnZeDXsO3jBoC9w,16283
-unique_toolkit/agentic/tools/tool_progress_reporter.py,sha256=ixud9VoHey1vlU1t86cW0-WTvyTwMxNSWBon8I11SUk,7955
+unique_toolkit/agentic/tools/tool_progress_reporter.py,sha256=I3q2SP1c_fwqU7qQLSi-_S4eEyOB8Qmjzf3wN3AfLVI,10270
 unique_toolkit/agentic/tools/utils/__init__.py,sha256=s75sjY5nrJchjLGs3MwSIqhDW08fFXIaX7eRQjFIA4s,346
 unique_toolkit/agentic/tools/utils/execution/__init__.py,sha256=OHiKpqBnfhBiEQagKVWJsZlHv8smPp5OI4dFIexzibw,37
 unique_toolkit/agentic/tools/utils/execution/execution.py,sha256=ocPGGfUwa851207HNTLYiBJ1pNzJp4VhMZ49OPP33gU,8022
@@ -151,7 +151,7 @@ unique_toolkit/language_model/functions.py,sha256=LGX3rR-XjkB-R520jp4w_Azgqf7BsI
 unique_toolkit/language_model/infos.py,sha256=oGbI9kA1jW9SdUUsWuSISD9O5Zm09PIzDIWXDyAnhzA,62649
 unique_toolkit/language_model/prompt.py,sha256=JSawaLjQg3VR-E2fK8engFyJnNdk21zaO8pPIodzN4Q,3991
 unique_toolkit/language_model/reference.py,sha256=nkX2VFz-IrUz8yqyc3G5jUMNwrNpxITBrMEKkbqqYoI,8583
-unique_toolkit/language_model/schemas.py,sha256=oHcJgmNSGpGW6ygjWvEB9iYaHgx250-Mtm-olSSJ-Ek,23760
+unique_toolkit/language_model/schemas.py,sha256=rXEc6lUd5T-32yKFsIM7WYzDdtObweHduR2dKjGCLko,23796
 unique_toolkit/language_model/service.py,sha256=JkYGtCug8POQskTv_aoYkzTMOaPCWRM94y73o3bUttQ,12019
 unique_toolkit/language_model/utils.py,sha256=bPQ4l6_YO71w-zaIPanUUmtbXC1_hCvLK0tAFc3VCRc,1902
 unique_toolkit/protocols/support.py,sha256=ZEnbQL5w2-T_1AeM8OHycZJ3qbdfVI1nXe0nL9esQEw,5544
@@ -166,7 +166,7 @@ unique_toolkit/short_term_memory/service.py,sha256=5PeVBu1ZCAfyDb2HLVvlmqSbyzBBu
 unique_toolkit/smart_rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 unique_toolkit/smart_rules/compile.py,sha256=Ozhh70qCn2yOzRWr9d8WmJeTo7AQurwd3tStgBMPFLA,1246
 unique_toolkit/test_utilities/events.py,sha256=_mwV2bs5iLjxS1ynDCjaIq-gjjKhXYCK-iy3dRfvO3g,6410
-unique_toolkit-1.20.0.dist-info/LICENSE,sha256=GlN8wHNdh53xwOPg44URnwag6TEolCjoq3YD_KrWgss,193
-unique_toolkit-1.20.0.dist-info/METADATA,sha256=clAfPiA8yIUHHPqoIS3JcmZJR_SJGj53uH0UTN_RVwQ,39492
-unique_toolkit-1.20.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-unique_toolkit-1.20.0.dist-info/RECORD,,
+unique_toolkit-1.21.0.dist-info/LICENSE,sha256=GlN8wHNdh53xwOPg44URnwag6TEolCjoq3YD_KrWgss,193
+unique_toolkit-1.21.0.dist-info/METADATA,sha256=Sho8NZxo-o5pg3Y3sd0wxJfy95QmPep8hV_VJa7n2DE,39657
+unique_toolkit-1.21.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+unique_toolkit-1.21.0.dist-info/RECORD,,