unique_toolkit 1.15.0__py3-none-any.whl → 1.16.1__py3-none-any.whl

unique_toolkit/agentic/debug_info_manager/debug_info_manager.py

@@ -1,3 +1,5 @@
+from typing import Any
+
 from unique_toolkit.agentic.tools.schemas import ToolCallResponse
 
 
@@ -5,14 +7,22 @@ class DebugInfoManager:
     def __init__(self):
         self.debug_info = {"tools": []}
 
-    def extract_tool_debug_info(self, tool_call_responses: list[ToolCallResponse]):
+    def extract_tool_debug_info(
+        self,
+        tool_call_responses: list[ToolCallResponse],
+        loop_iteration_index: int | None = None,
+    ):
         for tool_call_response in tool_call_responses:
-            self.debug_info["tools"].append(
-                {"name": tool_call_response.name, "data": tool_call_response.debug_info}
-            )
+            tool_info = {
+                "name": tool_call_response.name,
+                "info": tool_call_response.debug_info,
+            }
+            if loop_iteration_index is not None:
+                tool_info["info"]["loop_iteration"] = loop_iteration_index
+            self.debug_info["tools"].append(tool_info)
 
-    def add(self, key, value):
+    def add(self, key: str, value: Any) -> None:
         self.debug_info = self.debug_info | {key: value}
 
-    def get(self):
+    def get(self) -> dict[str, Any]:
         return self.debug_info

unique_toolkit/agentic/debug_info_manager/test/test_debug_info_manager.py

@@ -0,0 +1,278 @@
+"""
+Test suite for DebugInfoManager class.
+
+This test suite validates the DebugInfoManager's ability to:
+1. Initialize with empty debug info
+2. Extract tool debug info from ToolCallResponse objects
+3. Handle loop iteration indices
+4. Add arbitrary key-value pairs to debug info
+5. Retrieve the complete debug info dictionary
+"""
+
+from unique_toolkit.agentic.debug_info_manager.debug_info_manager import (
+    DebugInfoManager,
+)
+from unique_toolkit.agentic.tools.schemas import ToolCallResponse
+
+
+class TestDebugInfoManager:
+    """Test suite for DebugInfoManager functionality."""
+
+    def test_init__initializes_empty_debug_info__on_creation(self):
+        """Test that DebugInfoManager initializes with empty tools list."""
+        manager = DebugInfoManager()
+
+        assert manager.debug_info == {"tools": []}
+        assert manager.get() == {"tools": []}
+
+    def test_extract_tool_debug_info__adds_single_tool__with_valid_response(self):
+        """Test extracting debug info from a single ToolCallResponse."""
+        manager = DebugInfoManager()
+        tool_call_response = ToolCallResponse(
+            id="tool_1",
+            name="TestTool",
+            debug_info={"execution_time": "100ms", "status": "success"},
+        )
+
+        manager.extract_tool_debug_info([tool_call_response])
+
+        debug_info = manager.get()
+        assert len(debug_info["tools"]) == 1
+        assert debug_info["tools"][0]["name"] == "TestTool"
+        assert debug_info["tools"][0]["info"]["execution_time"] == "100ms"
+        assert debug_info["tools"][0]["info"]["status"] == "success"
+
+    def test_extract_tool_debug_info__adds_multiple_tools__with_multiple_responses(
+        self,
+    ):
+        """Test extracting debug info from multiple ToolCallResponse objects."""
+        manager = DebugInfoManager()
+        tool_call_responses = [
+            ToolCallResponse(
+                id="tool_1",
+                name="SearchTool",
+                debug_info={"query": "test query", "results": 5},
+            ),
+            ToolCallResponse(
+                id="tool_2",
+                name="CalculatorTool",
+                debug_info={"operation": "add", "result": 42},
+            ),
+            ToolCallResponse(
+                id="tool_3",
+                name="WeatherTool",
+                debug_info={"location": "New York", "temperature": "72F"},
+            ),
+        ]
+
+        manager.extract_tool_debug_info(tool_call_responses)
+
+        debug_info = manager.get()
+        assert len(debug_info["tools"]) == 3
+        assert debug_info["tools"][0]["name"] == "SearchTool"
+        assert debug_info["tools"][1]["name"] == "CalculatorTool"
+        assert debug_info["tools"][2]["name"] == "WeatherTool"
+
+    def test_extract_tool_debug_info__preserves_order__with_sequential_calls(self):
+        """Test that multiple calls to extract_tool_debug_info preserve order."""
+        manager = DebugInfoManager()
+
+        # First call
+        manager.extract_tool_debug_info(
+            [ToolCallResponse(id="tool_1", name="Tool1", debug_info={"step": 1})]
+        )
+
+        # Second call
+        manager.extract_tool_debug_info(
+            [ToolCallResponse(id="tool_2", name="Tool2", debug_info={"step": 2})]
+        )
+
+        # Third call
+        manager.extract_tool_debug_info(
+            [ToolCallResponse(id="tool_3", name="Tool3", debug_info={"step": 3})]
+        )
+
+        debug_info = manager.get()
+        assert len(debug_info["tools"]) == 3
+        assert debug_info["tools"][0]["info"]["step"] == 1
+        assert debug_info["tools"][1]["info"]["step"] == 2
+        assert debug_info["tools"][2]["info"]["step"] == 3
+
+    def test_extract_tool_debug_info__adds_loop_iteration__when_index_provided(self):
+        """Test that loop_iteration_index is added to debug info when provided."""
+        manager = DebugInfoManager()
+        tool_call_response = ToolCallResponse(
+            id="tool_1", name="IterativeTool", debug_info={"status": "processing"}
+        )
+
+        manager.extract_tool_debug_info([tool_call_response], loop_iteration_index=3)
+
+        debug_info = manager.get()
+        assert debug_info["tools"][0]["info"]["loop_iteration"] == 3
+        assert debug_info["tools"][0]["info"]["status"] == "processing"
+
+    def test_extract_tool_debug_info__omits_loop_iteration__when_index_is_none(self):
+        """Test that loop_iteration is not added when index is None."""
+        manager = DebugInfoManager()
+        tool_call_response = ToolCallResponse(
+            id="tool_1", name="SingleRunTool", debug_info={"status": "complete"}
+        )
+
+        manager.extract_tool_debug_info([tool_call_response], loop_iteration_index=None)
+
+        debug_info = manager.get()
+        assert "loop_iteration" not in debug_info["tools"][0]["info"]
+        assert debug_info["tools"][0]["info"]["status"] == "complete"
+
+    def test_extract_tool_debug_info__handles_empty_debug_info__gracefully(self):
+        """Test extracting from ToolCallResponse with empty debug_info dict."""
+        manager = DebugInfoManager()
+        tool_call_response = ToolCallResponse(
+            id="tool_1", name="MinimalTool", debug_info={}
+        )
+
+        manager.extract_tool_debug_info([tool_call_response])
+
+        debug_info = manager.get()
+        assert len(debug_info["tools"]) == 1
+        assert debug_info["tools"][0]["name"] == "MinimalTool"
+        assert debug_info["tools"][0]["info"] == {}
+
+    def test_extract_tool_debug_info__handles_empty_list__without_error(self):
+        """Test that passing an empty list doesn't cause errors."""
+        manager = DebugInfoManager()
+
+        manager.extract_tool_debug_info([])
+
+        debug_info = manager.get()
+        assert debug_info["tools"] == []
+
+    def test_add__adds_new_key_value_pair__to_debug_info(self):
+        """Test adding a new key-value pair to debug_info."""
+        manager = DebugInfoManager()
+
+        manager.add("execution_summary", {"total_time": "500ms", "total_calls": 5})
+
+        debug_info = manager.get()
+        assert "execution_summary" in debug_info
+        assert debug_info["execution_summary"]["total_time"] == "500ms"
+        assert debug_info["execution_summary"]["total_calls"] == 5
+
+    def test_add__preserves_tools_list__when_adding_new_keys(self):
+        """Test that add() preserves the tools list."""
+        manager = DebugInfoManager()
+        manager.extract_tool_debug_info(
+            [
+                ToolCallResponse(
+                    id="tool_1", name="TestTool", debug_info={"test": "data"}
+                )
+            ]
+        )
+
+        manager.add("metadata", {"version": "1.0"})
+
+        debug_info = manager.get()
+        assert len(debug_info["tools"]) == 1
+        assert debug_info["tools"][0]["name"] == "TestTool"
+        assert debug_info["metadata"]["version"] == "1.0"
+
+    def test_add__overwrites_existing_key__when_key_exists(self):
+        """Test that add() overwrites an existing key."""
+        manager = DebugInfoManager()
+        manager.add("status", "in_progress")
+        manager.add("status", "completed")
+
+        debug_info = manager.get()
+        assert debug_info["status"] == "completed"
+
+    def test_add__adds_multiple_keys__with_sequential_calls(self):
+        """Test adding multiple key-value pairs with sequential calls."""
+        manager = DebugInfoManager()
+
+        manager.add("key1", "value1")
+        manager.add("key2", {"nested": "value2"})
+        manager.add("key3", [1, 2, 3])
+
+        debug_info = manager.get()
+        assert debug_info["key1"] == "value1"
+        assert debug_info["key2"]["nested"] == "value2"
+        assert debug_info["key3"] == [1, 2, 3]
+
+    def test_get__returns_complete_debug_info__with_mixed_data(self):
+        """Test get() returns complete debug info with tools and custom keys."""
+        manager = DebugInfoManager()
+
+        # Add tool debug info
+        manager.extract_tool_debug_info(
+            [ToolCallResponse(id="tool_1", name="Tool1", debug_info={"data": "test"})],
+            loop_iteration_index=0,
+        )
+
+        # Add custom keys
+        manager.add("start_time", "2025-10-16T10:00:00")
+        manager.add("end_time", "2025-10-16T10:01:00")
+
+        debug_info = manager.get()
+
+        assert "tools" in debug_info
+        assert "start_time" in debug_info
+        assert "end_time" in debug_info
+        assert len(debug_info["tools"]) == 1
+        assert debug_info["start_time"] == "2025-10-16T10:00:00"
+
+    def test_integration__complete_workflow__with_all_operations(self):
+        """Integration test: complete workflow using all DebugInfoManager methods."""
+        manager = DebugInfoManager()
+
+        # Initial state
+        assert manager.get() == {"tools": []}
+
+        # Add some metadata
+        manager.add("session_id", "abc-123")
+        manager.add("user_id", "user-456")
+
+        # First tool call (loop iteration 0)
+        manager.extract_tool_debug_info(
+            [
+                ToolCallResponse(
+                    id="tool_1",
+                    name="SearchTool",
+                    debug_info={"query": "AI research", "hits": 100},
+                )
+            ],
+            loop_iteration_index=0,
+        )
+
+        # Second tool call (loop iteration 1)
+        manager.extract_tool_debug_info(
+            [
+                ToolCallResponse(
+                    id="tool_2",
+                    name="AnalysisTool",
+                    debug_info={"processed": 50, "relevant": 10},
+                ),
+                ToolCallResponse(
+                    id="tool_3",
+                    name="SummaryTool",
+                    debug_info={"paragraphs": 3, "words": 250},
+                ),
+            ],
+            loop_iteration_index=1,
+        )
+
+        # Add final summary
+        manager.add("summary", {"total_tools": 3, "total_iterations": 2})
+
+        # Verify complete debug info
+        debug_info = manager.get()
+
+        assert debug_info["session_id"] == "abc-123"
+        assert debug_info["user_id"] == "user-456"
+        assert len(debug_info["tools"]) == 3
+        assert debug_info["tools"][0]["name"] == "SearchTool"
+        assert debug_info["tools"][0]["info"]["loop_iteration"] == 0
+        assert debug_info["tools"][1]["name"] == "AnalysisTool"
+        assert debug_info["tools"][1]["info"]["loop_iteration"] == 1
+        assert debug_info["tools"][2]["name"] == "SummaryTool"
+        assert debug_info["tools"][2]["info"]["loop_iteration"] == 1
+        assert debug_info["summary"]["total_tools"] == 3

unique_toolkit/agentic/postprocessor/postprocessor_manager.py

@@ -6,6 +6,7 @@ from unique_toolkit.agentic.tools.utils.execution.execution import SafeTaskExecu
 from unique_toolkit.chat.service import ChatService
 from unique_toolkit.language_model.schemas import (
     LanguageModelStreamResponse,
+    ResponsesLanguageModelStreamResponse,
 )
 
 
@@ -26,7 +27,30 @@ class Postprocessor(ABC):
             "Subclasses must implement this method to apply post-processing to the response."
         )
 
-    async def remove_from_text(self, text) -> str:
+    async def remove_from_text(self, text: str) -> str:
+        raise NotImplementedError(
+            "Subclasses must implement this method to remove post-processing from the message."
+        )
+
+
+class ResponsesApiPostprocessor(ABC):
+    def __init__(self, name: str):
+        self.name = name
+
+    def get_name(self) -> str:
+        return self.name
+
+    async def run(self, loop_response: ResponsesLanguageModelStreamResponse) -> None:
+        raise NotImplementedError("Subclasses must implement this method.")
+
+    def apply_postprocessing_to_response(
+        self, loop_response: ResponsesLanguageModelStreamResponse
+    ) -> bool:
+        raise NotImplementedError(
+            "Subclasses must implement this method to apply post-processing to the response."
+        )
+
+    async def remove_from_text(self, text: str) -> str:
         raise NotImplementedError(
             "Subclasses must implement this method to remove post-processing from the message."
         )
@@ -59,12 +83,16 @@ class PostprocessorManager:
     ):
         self._logger = logger
         self._chat_service = chat_service
-        self._postprocessors: list[Postprocessor] = []
+        self._postprocessors: list[Postprocessor | ResponsesApiPostprocessor] = []
 
-    def add_postprocessor(self, postprocessor: Postprocessor):
+    def add_postprocessor(
+        self, postprocessor: Postprocessor | ResponsesApiPostprocessor
+    ):
         self._postprocessors.append(postprocessor)
 
-    def get_postprocessors(self, name: str) -> list[Postprocessor]:
+    def get_postprocessors(
+        self, name: str
+    ) -> list[Postprocessor | ResponsesApiPostprocessor]:
         return self._postprocessors
 
     async def run_postprocessors(
@@ -75,25 +103,36 @@ class PostprocessorManager:
             logger=self._logger,
         )
 
+        if isinstance(loop_response, ResponsesLanguageModelStreamResponse):
+            postprocessors = self._postprocessors
+        else:
+            postprocessors = [
+                postprocessor
+                for postprocessor in self._postprocessors
+                if isinstance(postprocessor, Postprocessor)
+            ]
+
         tasks = [
             task_executor.execute_async(
                 self.execute_postprocessors,
                 loop_response=loop_response,
                 postprocessor_instance=postprocessor,
             )
-            for postprocessor in self._postprocessors
+            for postprocessor in postprocessors
         ]
         postprocessor_results = await asyncio.gather(*tasks)
 
-        for i, result in enumerate(postprocessor_results):
+        for postprocessor, result in zip(postprocessors, postprocessor_results):
             if not result.success:
                 self._logger.warning(
-                    f"Postprocessor {self._postprocessors[i].get_name()} failed to run."
+                    "Postprocessor %s failed to run.",
+                    postprocessor.get_name(),
+                    exc_info=result.exception,
                 )
 
         modification_results = [
-            postprocessor.apply_postprocessing_to_response(loop_response)
-            for postprocessor in self._postprocessors
+            postprocessor.apply_postprocessing_to_response(loop_response)  # type: ignore
+            for postprocessor in postprocessors
         ]
 
         has_been_modified = any(modification_results)
@@ -108,9 +147,9 @@ class PostprocessorManager:
     async def execute_postprocessors(
         self,
         loop_response: LanguageModelStreamResponse,
-        postprocessor_instance: Postprocessor,
+        postprocessor_instance: Postprocessor | ResponsesApiPostprocessor,
     ) -> None:
-        await postprocessor_instance.run(loop_response)
+        await postprocessor_instance.run(loop_response)  # type: ignore
 
     async def remove_from_text(
         self,

unique_toolkit/agentic/responses_api/__init__.py

@@ -0,0 +1,19 @@
+from unique_toolkit.agentic.responses_api.postprocessors.code_display import (
+    ShowExecutedCodePostprocessor,
+    ShowExecutedCodePostprocessorConfig,
+)
+from unique_toolkit.agentic.responses_api.postprocessors.generated_files import (
+    DisplayCodeInterpreterFilesPostProcessor,
+    DisplayCodeInterpreterFilesPostProcessorConfig,
+)
+from unique_toolkit.agentic.responses_api.stream_handler import (
+    ResponsesStreamingHandler,
+)
+
+__all__ = [
+    "ShowExecutedCodePostprocessor",
+    "ShowExecutedCodePostprocessorConfig",
+    "DisplayCodeInterpreterFilesPostProcessorConfig",
+    "DisplayCodeInterpreterFilesPostProcessor",
+    "ResponsesStreamingHandler",
+]

unique_toolkit/agentic/responses_api/postprocessors/code_display.py

@@ -0,0 +1,63 @@
+import logging
+import re
+from typing import override
+
+from pydantic import BaseModel, Field
+
+from unique_toolkit.agentic.postprocessor.postprocessor_manager import (
+    ResponsesApiPostprocessor,
+)
+from unique_toolkit.agentic.tools.config import get_configuration_dict
+from unique_toolkit.language_model.schemas import ResponsesLanguageModelStreamResponse
+
+_TEMPLATE = """
+<details><summary>Code Interpreter Call</summary>    
+
+```python
+{code}
+```  
+
+</details>    
+</br>
+
+""".lstrip()
+
+logger = logging.getLogger(__name__)
+
+
+class ShowExecutedCodePostprocessorConfig(BaseModel):
+    model_config = get_configuration_dict()
+    remove_from_history: bool = Field(
+        default=False,
+        description="If set, the code interpreter call will be removed from the history on subsequent calls to the assistant.",
+    )
+
+
+class ShowExecutedCodePostprocessor(ResponsesApiPostprocessor):
+    def __init__(self, config: ShowExecutedCodePostprocessorConfig):
+        super().__init__(self.__class__.__name__)
+        self._config = config
+
+    @override
+    async def run(self, loop_response: ResponsesLanguageModelStreamResponse) -> None:
+        return None
+
+    @override
+    def apply_postprocessing_to_response(
+        self, loop_response: ResponsesLanguageModelStreamResponse
+    ) -> bool:
+        prepended_text = ""
+        for output in loop_response.code_interpreter_calls:
+            prepended_text += _TEMPLATE.format(code=output.code)
+
+        loop_response.message.text = prepended_text + loop_response.message.text
+
+        return prepended_text != ""
+
+    @override
+    async def remove_from_text(self, text) -> str:
+        if not self._config.remove_from_history:
+            return text
+        # Remove code interpreter blocks using regex
+        pattern = r"<details><summary>Code Interpreter Call</summary>.*?</details>"
+        return re.sub(pattern, "", text, flags=re.DOTALL)

unique_toolkit/agentic/responses_api/postprocessors/generated_files.py

@@ -0,0 +1,145 @@
+import logging
+import re
+from mimetypes import guess_type
+from typing import override
+
+from openai import AsyncOpenAI
+from pydantic import BaseModel
+from unique_sdk import Content
+
+from unique_toolkit.agentic.postprocessor.postprocessor_manager import (
+    ResponsesApiPostprocessor,
+)
+from unique_toolkit.agentic.tools.config import get_configuration_dict
+from unique_toolkit.content.schemas import ContentReference
+from unique_toolkit.content.service import ContentService
+from unique_toolkit.language_model.schemas import ResponsesLanguageModelStreamResponse
+
+logger = logging.getLogger(__name__)
+
+
+class DisplayCodeInterpreterFilesPostProcessorConfig(BaseModel):
+    model_config = get_configuration_dict()
+    upload_scope_id: str
+
+
+class DisplayCodeInterpreterFilesPostProcessor(
+    ResponsesApiPostprocessor,
+):
+    def __init__(
+        self,
+        client: AsyncOpenAI,
+        content_service: ContentService,
+        config: DisplayCodeInterpreterFilesPostProcessorConfig,
+    ) -> None:
+        super().__init__(self.__class__.__name__)
+        self._content_service = content_service
+        self._config = config
+        self._client = client
+        self._content_map = {}
+
+    @override
+    async def run(self, loop_response: ResponsesLanguageModelStreamResponse) -> None:
+        logger.info("Fetching and adding code interpreter files to the response")
+
+        container_files = loop_response.container_files
+        logger.info("Found %s container files", len(container_files))
+
+        self._content_map = {}
+        for container_file in container_files:
+            logger.info("Fetching file content for %s", container_file.filename)
+            file_content = await self._client.containers.files.content.retrieve(
+                container_id=container_file.container_id, file_id=container_file.file_id
+            )
+
+            logger.info(
+                "Uploading file content for %s to knowledge base",
+                container_file.filename,
+            )
+            content = self._content_service.upload_content_from_bytes(
+                content=file_content.content,
+                content_name=container_file.filename,
+                skip_ingestion=True,
+                mime_type=guess_type(container_file.filename)[0] or "text/plain",
+                scope_id=self._config.upload_scope_id,
+            )
+            self._content_map[container_file.filename] = content
+
+    @override
+    def apply_postprocessing_to_response(
+        self, loop_response: ResponsesLanguageModelStreamResponse
+    ) -> bool:
+        ref_number = _get_next_ref_number(loop_response.message.references)
+        changed = False
+        # images
+        for filename, content in self._content_map.items():
+            # Images
+            loop_response.message.text, replaced = _replace_container_image_citation(
+                text=loop_response.message.text, filename=filename, content=content
+            )
+            changed |= replaced
+
+            # Files
+            loop_response.message.text, replaced = _replace_container_file_citation(
+                text=loop_response.message.text,
+                filename=filename,
+                ref_number=ref_number,
+            )
+            changed |= replaced
+            if replaced:
+                loop_response.message.references.append(
+                    ContentReference(
+                        sequence_number=ref_number,
+                        source_id=content.id,
+                        source="node-ingestion-chunks",
+                        url=f"unique://content/{content.id}",
+                        name=filename,
+                    )
+                )
+                ref_number += 1
+        return changed
+
+    @override
+    async def remove_from_text(self, text) -> str:
+        return text
+
+
+def _get_next_ref_number(references: list[ContentReference]) -> int:
+    max_ref_number = 0
+    for ref in references:
+        max_ref_number = max(max_ref_number, ref.sequence_number)
+    return max_ref_number + 1
+
+
+def _replace_container_image_citation(
+    text: str, filename: str, content: Content
+) -> tuple[str, bool]:
+    image_markdown = rf"!\[.*?\]\(sandbox:/mnt/data/{re.escape(filename)}\)"
+
+    if not re.search(image_markdown, text):
+        logger.info("No image markdown found for %s", filename)
+        return text, False
+
+    logger.info("Displaying image %s", filename)
+    return re.sub(
+        image_markdown,
+        f"![image](unique://content/{content.id})",
+        text,
+    ), True
+
+
+def _replace_container_file_citation(
+    text: str, filename: str, ref_number: int
+) -> tuple[str, bool]:
+    file_markdown = rf"\[.*?\]\(sandbox:/mnt/data/{re.escape(filename)}\)"
+
+    if not re.search(file_markdown, text):
+        logger.info("No file markdown found for %s", filename)
+        return text, False
+
+    logger.info("Displaying file %s", filename)
+    return re.sub(
+        file_markdown,
+        f"<sup>{ref_number}</sup>",
+        text,
+    ), True

unique_toolkit/agentic/responses_api/stream_handler.py

@@ -0,0 +1,15 @@
+from unique_toolkit.protocols.support import ResponsesSupportCompleteWithReferences
+from unique_toolkit.services.chat_service import ChatService
+
+
+class ResponsesStreamingHandler(ResponsesSupportCompleteWithReferences):
+    def __init__(self, chat_service: ChatService):
+        self._chat_service = chat_service
+
+    def complete_with_references(self, *args, **kwargs):
+        return self._chat_service.complete_responses_with_references(*args, **kwargs)
+
+    async def complete_with_references_async(self, *args, **kwargs):
+        return await self._chat_service.complete_responses_with_references_async(
+            *args, **kwargs
+        )

unique_toolkit/agentic/tools/factory.py

@@ -11,6 +11,10 @@ class ToolFactory:
     tool_map: dict[str, type[Tool]] = {}
     tool_config_map: dict[str, Callable] = {}
 
+    @classmethod
+    def register_tool_config(cls, tool_name: str, tool_config: type[BaseToolConfig]):
+        cls.tool_config_map[tool_name] = tool_config
+
     @classmethod
     def register_tool(
         cls,