unique_toolkit 1.20.1__py3-none-any.whl → 1.21.1__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,242 @@ 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={
+                "started": "⚪ {tool_name}: {message}",
+                "running": "⏳ {tool_name}: {message}",
+                "finished": "✅ {tool_name}: {message}",
+                "failed": "❌ {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_with_empty_template__when_state_hidden(
+        self, chat_service, tool_call
+    ) -> None:
+        """
+        Purpose: Verify that states with empty string templates are not displayed.
+        Why this matters: Allows selective display of only certain states (e.g., hide STARTED).
+        Setup summary: Create config with empty string for RUNNING state, verify message is not displayed.
+        """
+        # Arrange
+        custom_config = ToolProgressReporterConfig(
+            state_to_display_template={
+                "started": "",
+                "running": "",  # Empty string hides RUNNING state
+                "finished": "✅ {tool_name}: {message}",
+                "failed": "❌ {tool_name}: {message}",
+            }
+        )
+        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 template is empty
+        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={
+                "started": "○ {tool_name} - {message}",
+                "running": "▶️ {tool_name} - {message}",
+                "finished": "✓ {tool_name} - {message}",
+                "failed": "✗ {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 other states use empty templates.
+        Why this matters: Use case where user only wants final results, not intermediate steps.
+        Setup summary: Configure only FINISHED with content, send STARTED and FINISHED, verify only FINISHED appears.
+        """
+        # Arrange
+        custom_config = ToolProgressReporterConfig(
+            state_to_display_template={
+                "started": "",  # Empty template hides STARTED
+                "running": "",  # Empty template hides RUNNING
+                "finished": "Done: {tool_name} - {message}",
+                "failed": "Failed: {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_all_empty_templates__when_all_states_hidden(
+        self, chat_service, tool_call
+    ) -> None:
+        """
+        Purpose: Verify that all empty string templates result in no messages being displayed.
+        Why this matters: Edge case handling and allows disabling all progress display.
+        Setup summary: Create config with all empty templates, verify no tool messages appear.
+        """
+        # Arrange
+        custom_config = ToolProgressReporterConfig(
+            state_to_display_template={
+                "started": "",
+                "running": "",
+                "finished": "",
+                "failed": "",
+            }
+        )
+        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 typing import Protocol, TypedDict
 
-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,54 @@ class ToolExecutionStatus(BaseModel):
     message: str
     state: ProgressState
     references: list[ContentReference] = []
-    timestamp: datetime = datetime.now()
+    timestamp: datetime = Field(default_factory=datetime.now)
+
+
+class StateToDisplayTemplate(TypedDict):
+    started: str
+    running: str
+    failed: str
+    finished: str
+
+
+_DEFAULT_STATE_TO_DISPLAY_TEMPLATE: StateToDisplayTemplate = {
+    "started": "{arrow}**{{tool_name}}** ⚪: {{message}}".format(arrow=ARROW),
+    "running": "{arrow}**{{tool_name}}** 🟡: {{message}}".format(arrow=ARROW),
+    "finished": "{arrow}**{{tool_name}}** 🟢: {{message}}".format(arrow=ARROW),
+    "failed": "{arrow}**{{tool_name}}** 🔴: {{message}}".format(arrow=ARROW),
+}
+
+
+state_to_display_template_description = """
+Display templates for the different progress states.
+The template is a string that will be used to display the progress status.
+It can contain the following placeholders:
+- `{tool_name}`: The name of the tool
+- `{message}`: The message to display (sent by the tool)
+""".strip()
+
+
+class ToolProgressReporterConfig(BaseModel):
+    model_config = get_configuration_dict()
+
+    state_to_display_template: StateToDisplayTemplate = Field(
+        default=_DEFAULT_STATE_TO_DISPLAY_TEMPLATE,
+        description=state_to_display_template_description,
+        title="Display Templates",
+    )
 
 
 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 +117,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 +140,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 +171,31 @@ 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:
+        display_message = self._config.state_to_display_template[state.value].format(
+            tool_name=name,
+            message=message,
+        )
+        # Don't display empty messages
+        if display_message.strip() == "":
+            return None
+
+        return display_message
+
 
 class ToolWithToolProgressReporter(Protocol):
     tool_progress_reporter: ToolProgressReporter

{unique_toolkit-1.20.1.dist-info → unique_toolkit-1.21.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: unique_toolkit
-Version: 1.20.1
+Version: 1.21.1
 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.1] - 2025-10-30
+- Improve Spaces 2.0 display of tool progress reporter configuration.
+
+## [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`.
 

{unique_toolkit-1.20.1.dist-info → unique_toolkit-1.21.1.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=XHNezB8itj9KzpQgD0cwRtp2AgRUfUkQsHc3bTyPj6c,15801
 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=GaR0oqDUJZvBB9WCUVYYh0Zvs6U-LMygJCCrqPlitgA,10296
 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
@@ -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.1.dist-info/LICENSE,sha256=GlN8wHNdh53xwOPg44URnwag6TEolCjoq3YD_KrWgss,193
-unique_toolkit-1.20.1.dist-info/METADATA,sha256=CscyMf-zTg-Z4iZB6X6mmaqgMyBwGW55bGmVHYnSc7E,39566
-unique_toolkit-1.20.1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-unique_toolkit-1.20.1.dist-info/RECORD,,
+unique_toolkit-1.21.1.dist-info/LICENSE,sha256=GlN8wHNdh53xwOPg44URnwag6TEolCjoq3YD_KrWgss,193
+unique_toolkit-1.21.1.dist-info/METADATA,sha256=anvdaQ88ZJ6rRjaHBHGuIs_gYO9qNWyE0qnCYzKzPPs,39753
+unique_toolkit-1.21.1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+unique_toolkit-1.21.1.dist-info/RECORD,,