unique_toolkit 1.35.4__py3-none-any.whl → 1.36.0__py3-none-any.whl

unique_toolkit/_common/referencing.py

@@ -15,7 +15,7 @@ def _iter_ref_numbers(text: str) -> Generator[int, None, None]:
 
 
 @functools.cache
-def _get_detection_pattern_for_ref(ref_number: int) -> re.Pattern[str]:
+def get_detection_pattern_for_ref(ref_number: int) -> re.Pattern[str]:
     return re.compile(rf"<sup>\s*{ref_number}\s*</sup>")
 
 
@@ -35,11 +35,11 @@ def replace_ref_number(text: str, ref_number: int, replacement: int | str) -> st
     if isinstance(replacement, int):
         replacement = get_reference_pattern(replacement)
 
-    return _get_detection_pattern_for_ref(ref_number).sub(replacement, text)
+    return get_detection_pattern_for_ref(ref_number).sub(replacement, text)
 
 
 def remove_ref_number(text: str, ref_number: int) -> str:
-    return _get_detection_pattern_for_ref(ref_number).sub("", text)
+    return get_detection_pattern_for_ref(ref_number).sub("", text)
 
 
 def remove_all_refs(text: str) -> str:

unique_toolkit/agentic/tools/a2a/postprocessing/config.py

@@ -65,7 +65,7 @@ class SubAgentDisplayConfig(BaseModel):
     )
     force_include_references: bool = Field(
         default=False,
-        description="If set, the sub agent references will be added to the main agent response references even in not mentioned in the main agent response text.",
+        description="If set, the sub agent references will be added to the main agent response references even if not mentioned in the main agent response text.",
     )
 
     answer_substrings_config: list[SubAgentAnswerSubstringConfig] = Field(

unique_toolkit/agentic/tools/a2a/prompts.py

@@ -37,6 +37,8 @@ References: <sup><name>SubAgentName 4</name>2</sup><sup><name>SubAgentName 4</na
 
 6. Fact repetition: If you reuse a fact from SubAgentName, you MUST reference it again inline with the correct format.
 
+7. You can ONLY use references if they are present in the subagent response! You must NOT create any references!
+
 Reminder:
 Inline = directly next to the fact, inside the same sentence or bullet.
 """.strip()

unique_toolkit/agentic/tools/a2a/tool/config.py

@@ -13,6 +13,7 @@ class SubAgentSystemReminderType(StrEnum):
     FIXED = "fixed"
     REGEXP = "regexp"
     REFERENCE = "reference"
+    NO_REFERENCE = "no_reference"
 
 
 T = TypeVar("T", bound=SubAgentSystemReminderType)
@@ -31,12 +32,24 @@ The reminder to add to the tool response. The reminder can be a Jinja template a
 """.strip()
 
 
+class NoReferenceSystemReminderConfig(SystemReminderConfig):
+    """A system reminder that is only added if the sub agent response does not contain any references."""
+
+    type: Literal[SubAgentSystemReminderType.NO_REFERENCE] = (
+        SubAgentSystemReminderType.NO_REFERENCE
+    )
+    reminder: str = Field(
+        default="Do NOT create any references from this sub agent in your response! The sub agent response does not contain any references.",
+        description=_SYSTEM_REMINDER_FIELD_DESCRIPTION,
+    )
+
+
 class ReferenceSystemReminderConfig(SystemReminderConfig):
     type: Literal[SubAgentSystemReminderType.REFERENCE] = (
         SubAgentSystemReminderType.REFERENCE
     )
     reminder: str = Field(
-        default="Rememeber to properly reference EACH fact from sub agent {{ display_name }}'s response with the correct format INLINE.",
+        default="Rememeber to properly reference EACH fact from sub agent {{ display_name }}'s response with the correct format INLINE. You MUST COPY THE REFERENCE AS PRESENT IN THE SUBAGENT RESPONSE.",
         description=_SYSTEM_REMINDER_FIELD_DESCRIPTION,
     )
 
@@ -69,6 +82,13 @@ class RegExpDetectedSystemReminderConfig(SystemReminderConfig):
     )
 
 
+SystemReminderConfigType = (
+    FixedSystemReminderConfig
+    | RegExpDetectedSystemReminderConfig
+    | ReferenceSystemReminderConfig
+    | NoReferenceSystemReminderConfig
+)
+
 DEFAULT_PARAM_DESCRIPTION_SUB_AGENT_USER_MESSAGE = """
 This is the message that will be sent to the sub-agent.
 """.strip()
@@ -147,9 +167,7 @@ class SubAgentToolConfig(BaseToolConfig):
 
     system_reminders_config: list[
         Annotated[
-            FixedSystemReminderConfig
-            | RegExpDetectedSystemReminderConfig
-            | ReferenceSystemReminderConfig,
+            SystemReminderConfigType,
             Field(discriminator="type"),
         ]
     ] = Field(

unique_toolkit/agentic/tools/a2a/tool/service.py

@@ -12,7 +12,7 @@ from unique_sdk.utils.chat_in_space import send_message_and_wait_for_completion
 
 from unique_toolkit._common.referencing import (
     get_all_ref_numbers,
-    remove_all_refs,
+    get_detection_pattern_for_ref,
     replace_ref_number,
 )
 from unique_toolkit._common.utils.jinja.render import render_template
@@ -29,6 +29,7 @@ from unique_toolkit.agentic.tools.a2a.tool.config import (
     RegExpDetectedSystemReminderConfig,
     SubAgentSystemReminderType,
     SubAgentToolConfig,
+    SystemReminderConfigType,
 )
 from unique_toolkit.agentic.tools.factory import ToolFactory
 from unique_toolkit.agentic.tools.schemas import ToolCallResponse
@@ -201,15 +202,39 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
             if response["text"] is None:
                 raise ValueError("No response returned from sub agent")
 
+            has_refs = False
+            content = ""
+            content_chunks = None
             if self.config.returns_content_chunks:
-                content = ""
                 content_chunks = _ContentChunkList.validate_json(response["text"])
             else:
-                content = self._prepare_response_references(
+                has_refs = self.config.use_sub_agent_references and _response_has_refs(
+                    response
+                )
+                content = response["text"]
+                if has_refs:
+                    refs = response["references"]
+                    assert refs is not None  # Checked in _response_has_refs
+                    content = _prepare_sub_agent_response_refs(
+                        response=content,
+                        name=self.name,
+                        sequence_number=sequence_number,
+                        refs=refs,
+                    )
+                    content = _remove_extra_refs(content, refs=refs)
+                else:
+                    content = _remove_extra_refs(content, refs=[])
+
+            system_reminders = []
+            if not self.config.returns_content_chunks:
+                system_reminders = _get_sub_agent_system_reminders(
                     response=response["text"],
+                    configs=self.config.system_reminders_config,
+                    name=self.name,
+                    display_name=self.display_name(),
                     sequence_number=sequence_number,
+                    has_refs=has_refs,
                 )
-                content_chunks = None
 
             await self._notify_progress(
                 tool_call=tool_call,
@@ -223,58 +248,11 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
                 content=_format_response(
                     tool_name=self.name,
                     text=content,
-                    system_reminders=self._get_system_reminders(response),
+                    system_reminders=system_reminders,
                 ),
                 content_chunks=content_chunks,
             )
 
-    def _get_system_reminders(self, message: unique_sdk.Space.Message) -> list[str]:
-        reminders = []
-        for reminder_config in self.config.system_reminders_config:
-            if reminder_config.type == SubAgentSystemReminderType.FIXED:
-                reminders.append(
-                    render_template(
-                        reminder_config.reminder,
-                        display_name=self.display_name(),
-                        tool_name=self.name,
-                    )
-                )
-            elif (
-                reminder_config.type == SubAgentSystemReminderType.REFERENCE
-                and self.config.use_sub_agent_references
-                and message["references"] is not None
-                and len(message["references"]) > 0
-            ):
-                reminders.append(
-                    render_template(
-                        reminder_config.reminder,
-                        display_name=self.display_name(),
-                        tool_name=self.name,
-                    )
-                )
-            elif (
-                reminder_config.type == SubAgentSystemReminderType.REGEXP
-                and message["text"] is not None
-            ):
-                reminder_config = cast(
-                    RegExpDetectedSystemReminderConfig, reminder_config
-                )
-                text_matches = [
-                    match.group(0)
-                    for match in reminder_config.regexp.finditer(message["text"])
-                ]
-                if len(text_matches) > 0:
-                    reminders.append(
-                        render_template(
-                            reminder_config.reminder,
-                            display_name=self.display_name(),
-                            tool_name=self.name,
-                            text_matches=text_matches,
-                        )
-                    )
-
-        return reminders
-
     async def _get_chat_id(self) -> str | None:
         if not self.config.reuse_chat:
             return None
@@ -290,23 +268,6 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
 
         return None
 
-    def _prepare_response_references(self, response: str, sequence_number: int) -> str:
-        if not self.config.use_sub_agent_references:
-            # Remove all references from the response
-            response = remove_all_refs(response)
-            return response
-
-        for ref_number in get_all_ref_numbers(response):
-            reference = self.get_sub_agent_reference_format(
-                name=self.name,
-                sequence_number=sequence_number,
-                reference_number=ref_number,
-            )
-            response = replace_ref_number(
-                text=response, ref_number=ref_number, replacement=reference
-            )
-        return response
-
     async def _save_chat_id(self, chat_id: str) -> None:
         if not self.config.reuse_chat:
             return
@@ -390,4 +351,93 @@ def _format_response(tool_name: str, text: str, system_reminders: list[str]) ->
     return json.dumps(response, indent=2)
 
 
+def _response_has_refs(response: unique_sdk.Space.Message) -> bool:
+    if (
+        response["text"] is None
+        or response["references"] is None
+        or len(response["references"]) == 0
+    ):
+        return False
+
+    for ref in response["references"]:
+        if (
+            re.search(
+                get_detection_pattern_for_ref(ref["sequenceNumber"]), response["text"]
+            )
+            is not None
+        ):
+            return True
+
+    return False
+
+
+def _remove_extra_refs(response: str, refs: list[unique_sdk.Space.Reference]) -> str:
+    text_ref_numbers = set(get_all_ref_numbers(response))
+    extra_ref_numbers = text_ref_numbers - set(ref["sequenceNumber"] for ref in refs)
+
+    for ref_num in extra_ref_numbers:
+        response = get_detection_pattern_for_ref(ref_num).sub("", response)
+
+    return response
+
+
+def _prepare_sub_agent_response_refs(
+    response: str,
+    name: str,
+    sequence_number: int,
+    refs: list[unique_sdk.Space.Reference],
+) -> str:
+    for ref in refs:
+        ref_number = ref["sequenceNumber"]
+        reference = SubAgentTool.get_sub_agent_reference_format(
+            name=name, sequence_number=sequence_number, reference_number=ref_number
+        )
+        response = replace_ref_number(
+            text=response, ref_number=ref_number, replacement=reference
+        )
+
+    return response
+
+
+def _get_sub_agent_system_reminders(
+    response: str,
+    configs: list[SystemReminderConfigType],
+    name: str,
+    display_name: str,
+    sequence_number: int,
+    has_refs: bool,
+) -> list[str]:
+    reminders = []
+
+    for reminder_config in configs:
+        render_kwargs = {}
+        render_kwargs["display_name"] = display_name
+        render_kwargs["tool_name"] = name
+        template = None
+
+        if reminder_config.type == SubAgentSystemReminderType.FIXED:
+            template = reminder_config.reminder
+        elif (
+            reminder_config.type == SubAgentSystemReminderType.REFERENCE and has_refs
+        ) or (
+            reminder_config.type == SubAgentSystemReminderType.NO_REFERENCE
+            and not has_refs
+        ):
+            render_kwargs["tool_name"] = f"{name} {sequence_number}"
+            template = reminder_config.reminder
+        elif reminder_config.type == SubAgentSystemReminderType.REGEXP:
+            reminder_config = cast(RegExpDetectedSystemReminderConfig, reminder_config)
+            text_matches = [
+                match.group(0) for match in reminder_config.regexp.finditer(response)
+            ]
+            if len(text_matches) > 0:
+                template = reminder_config.reminder
+                render_kwargs["text_matches"] = text_matches
+
+        if template is not None:
+            reminders.append(render_template(template, **render_kwargs))
+
+    return reminders
+
+
 ToolFactory.register_tool(SubAgentTool, SubAgentToolConfig)

unique_toolkit/agentic/tools/a2a/tool/test/test_service_utils.py

@@ -0,0 +1,829 @@
+"""
+Unit tests for utility functions in service.py for SubAgentTool.
+"""
+
+import json
+import re
+from typing import Any
+
+import pytest
+
+from unique_toolkit.agentic.tools.a2a.tool.config import (
+    FixedSystemReminderConfig,
+    NoReferenceSystemReminderConfig,
+    ReferenceSystemReminderConfig,
+    RegExpDetectedSystemReminderConfig,
+)
+from unique_toolkit.agentic.tools.a2a.tool.service import (
+    _format_response,
+    _get_sub_agent_system_reminders,
+    _prepare_sub_agent_response_refs,
+    _remove_extra_refs,
+    _response_has_refs,
+)
+
+# Fixtures
+
+
+@pytest.fixture
+def base_message_response() -> dict[str, Any]:
+    """Base message response fixture mimicking unique_sdk.Space.Message."""
+    return {
+        "text": "Some response text",
+        "references": None,
+        "chatId": "chat-123",
+        "assessment": None,
+    }
+
+
+@pytest.fixture
+def message_with_refs() -> dict[str, Any]:
+    """Message response with references that appear in text."""
+    return {
+        "text": "This is the answer <sup>1</sup> and also <sup>2</sup>",
+        "references": [
+            {"sequenceNumber": 1, "name": "Doc 1", "url": "http://example.com/1"},
+            {"sequenceNumber": 2, "name": "Doc 2", "url": "http://example.com/2"},
+        ],
+        "chatId": "chat-123",
+        "assessment": None,
+    }
+
+
+@pytest.fixture
+def refs_list() -> list[dict[str, Any]]:
+    """List of reference objects mimicking unique_sdk.Space.Reference."""
+    return [
+        {"sequenceNumber": 1, "name": "Doc 1", "url": "http://example.com/1"},
+        {"sequenceNumber": 2, "name": "Doc 2", "url": "http://example.com/2"},
+    ]
+
+
+# Tests for _format_response
+
+
+@pytest.mark.ai
+def test_format_response__returns_text__when_no_system_reminders() -> None:
+    """
+    Purpose: Verify _format_response returns plain text when system_reminders is empty.
+    Why this matters: Avoids unnecessary JSON wrapping for simple responses.
+    Setup summary: Empty system_reminders list, assert text returned unchanged.
+    """
+    # Arrange
+    tool_name = "TestTool"
+    text = "This is the response text"
+    system_reminders: list[str] = []
+
+    # Act
+    result = _format_response(tool_name, text, system_reminders)
+
+    # Assert
+    assert result == text
+
+
+@pytest.mark.ai
+def test_format_response__returns_json__when_system_reminders_present() -> None:
+    """
+    Purpose: Verify _format_response returns JSON with reminders when reminders present.
+    Why this matters: Ensures system reminders are properly included for LLM context.
+    Setup summary: Provide system reminders, assert JSON structure with reminders key.
+    """
+    # Arrange
+    tool_name = "TestTool"
+    text = "This is the response"
+    system_reminders = ["Remember to cite sources", "Be concise"]
+
+    # Act
+    result = _format_response(tool_name, text, system_reminders)
+
+    # Assert
+    parsed = json.loads(result)
+    assert "TestTool response" in parsed
+    assert parsed["TestTool response"] == text
+    assert "SYSTEM_REMINDERS" in parsed
+    assert parsed["SYSTEM_REMINDERS"] == system_reminders
+
+
+@pytest.mark.ai
+def test_format_response__uses_tool_name_in_key__correctly() -> None:
+    """
+    Purpose: Verify the response key includes the tool name.
+    Why this matters: Allows LLM to identify which tool the response belongs to.
+    Setup summary: Use specific tool name, verify it appears in JSON key.
+    """
+    # Arrange
+    tool_name = "MySpecialAgent"
+    text = "Response content"
+    system_reminders = ["Reminder 1"]
+
+    # Act
+    result = _format_response(tool_name, text, system_reminders)
+
+    # Assert
+    parsed = json.loads(result)
+    assert "MySpecialAgent response" in parsed
+
+
+@pytest.mark.ai
+def test_format_response__preserves_special_characters__in_text() -> None:
+    """
+    Purpose: Verify special characters in text are preserved in JSON output.
+    Why this matters: Ensures markdown, code, and special chars don't break formatting.
+    Setup summary: Text with special JSON chars, verify they're properly escaped.
+    """
+    # Arrange
+    tool_name = "TestTool"
+    text = 'Text with "quotes" and newlines\nand tabs\t'
+    system_reminders = ["Reminder"]
+
+    # Act
+    result = _format_response(tool_name, text, system_reminders)
+
+    # Assert
+    parsed = json.loads(result)
+    assert parsed["TestTool response"] == text
+
+
+# Tests for _response_has_refs
+
+
+@pytest.mark.ai
+def test_response_has_refs__returns_false__when_text_is_none() -> None:
+    """
+    Purpose: Verify _response_has_refs returns False when text is None.
+    Why this matters: Handles edge case of empty/null responses gracefully.
+    Setup summary: Response with None text, assert False returned.
+    """
+    # Arrange
+    response = {"text": None, "references": [{"sequenceNumber": 1}]}
+
+    # Act
+    result = _response_has_refs(response)
+
+    # Assert
+    assert result is False
+
+
+@pytest.mark.ai
+def test_response_has_refs__returns_false__when_references_is_none() -> None:
+    """
+    Purpose: Verify _response_has_refs returns False when references is None.
+    Why this matters: Handles missing references attribute gracefully.
+    Setup summary: Response with None references, assert False returned.
+    """
+    # Arrange
+    response = {"text": "Some text <sup>1</sup>", "references": None}
+
+    # Act
+    result = _response_has_refs(response)
+
+    # Assert
+    assert result is False
+
+
+@pytest.mark.ai
+def test_response_has_refs__returns_false__when_references_empty() -> None:
+    """
+    Purpose: Verify _response_has_refs returns False when references list is empty.
+    Why this matters: Distinguishes between missing and empty reference lists.
+    Setup summary: Response with empty references list, assert False returned.
+    """
+    # Arrange
+    response = {"text": "Some text <sup>1</sup>", "references": []}
+
+    # Act
+    result = _response_has_refs(response)
+
+    # Assert
+    assert result is False
+
+
+@pytest.mark.ai
+def test_response_has_refs__returns_true__when_ref_found_in_text(
+    message_with_refs: dict[str, Any],
+) -> None:
+    """
+    Purpose: Verify _response_has_refs returns True when reference appears in text.
+    Why this matters: Core functionality for detecting valid references.
+    Setup summary: Response with refs that appear in text, assert True returned.
+    """
+    # Act
+    result = _response_has_refs(message_with_refs)
+
+    # Assert
+    assert result is True
+
+
+@pytest.mark.ai
+def test_response_has_refs__returns_false__when_refs_not_in_text() -> None:
+    """
+    Purpose: Verify _response_has_refs returns False when references don't appear in text.
+    Why this matters: Ensures we only process actually-used references.
+    Setup summary: Response with refs that don't match text, assert False returned.
+    """
+    # Arrange
+    response = {
+        "text": "Text without any sup tags",
+        "references": [{"sequenceNumber": 1}, {"sequenceNumber": 2}],
+    }
+
+    # Act
+    result = _response_has_refs(response)
+
+    # Assert
+    assert result is False
+
+
+@pytest.mark.ai
+def test_response_has_refs__handles_whitespace_in_refs__correctly() -> None:
+    """
+    Purpose: Verify _response_has_refs handles whitespace inside sup tags.
+    Why this matters: Reference patterns may have varying whitespace.
+    Setup summary: Text with whitespace in sup tags, assert still detected.
+    """
+    # Arrange
+    response = {
+        "text": "Text with <sup> 1 </sup> reference",
+        "references": [{"sequenceNumber": 1}],
+    }
+
+    # Act
+    result = _response_has_refs(response)
+
+    # Assert
+    assert result is True
+
+
+@pytest.mark.ai
+def test_response_has_refs__returns_true__when_at_least_one_ref_matches() -> None:
+    """
+    Purpose: Verify returns True if any reference matches, not necessarily all.
+    Why this matters: Partial reference usage is still valid.
+    Setup summary: Multiple refs where only one appears in text, assert True.
+    """
+    # Arrange
+    response = {
+        "text": "Only first ref <sup>1</sup> is used",
+        "references": [
+            {"sequenceNumber": 1},
+            {"sequenceNumber": 2},
+            {"sequenceNumber": 3},
+        ],
+    }
+
+    # Act
+    result = _response_has_refs(response)
+
+    # Assert
+    assert result is True
+
+
+# Tests for _remove_extra_refs
+
+
+@pytest.mark.ai
+def test_remove_extra_refs__returns_unchanged__when_no_refs_in_text() -> None:
+    """
+    Purpose: Verify _remove_extra_refs returns text unchanged when no refs present.
+    Why this matters: Avoids unnecessary string manipulation.
+    Setup summary: Plain text without refs, assert unchanged.
+    """
+    # Arrange
+    response = "This is plain text without references"
+    refs: list[dict[str, Any]] = []
+
+    # Act
+    result = _remove_extra_refs(response, refs)
+
+    # Assert
+    assert result == response
+
+
+@pytest.mark.ai
+def test_remove_extra_refs__removes_orphan_refs__not_in_refs_list() -> None:
+    """
+    Purpose: Verify _remove_extra_refs removes refs that aren't in the refs list.
+    Why this matters: Cleans up invalid/orphan reference markers.
+    Setup summary: Text with refs not in refs list, verify they're removed.
+    """
+    # Arrange
+    response = "Text with <sup>1</sup> and <sup>2</sup> and <sup>3</sup>"
+    refs = [{"sequenceNumber": 1}]  # Only ref 1 is valid
+
+    # Act
+    result = _remove_extra_refs(response, refs)
+
+    # Assert
+    assert "<sup>1</sup>" in result
+    assert "<sup>2</sup>" not in result
+    assert "<sup>3</sup>" not in result
+
+
+@pytest.mark.ai
+def test_remove_extra_refs__preserves_valid_refs__in_text(
+    refs_list: list[dict[str, Any]],
+) -> None:
+    """
+    Purpose: Verify _remove_extra_refs preserves refs that are in the refs list.
+    Why this matters: Ensures valid references remain intact.
+    Setup summary: Text with valid refs, verify all preserved.
+    """
+    # Arrange
+    response = "First <sup>1</sup> and second <sup>2</sup>"
+
+    # Act
+    result = _remove_extra_refs(response, refs_list)
+
+    # Assert
+    assert result == response
+
+
+@pytest.mark.ai
+def test_remove_extra_refs__removes_all_refs__when_refs_list_empty() -> None:
+    """
+    Purpose: Verify all refs removed when refs list is empty.
+    Why this matters: Cleans up all references when none are valid.
+    Setup summary: Text with refs, empty refs list, verify all removed.
+    """
+    # Arrange
+    response = "Has <sup>1</sup> and <sup>2</sup>"
+    refs: list[dict[str, Any]] = []
+
+    # Act
+    result = _remove_extra_refs(response, refs)
+
+    # Assert
+    assert "<sup>" not in result
+    assert result == "Has  and "
+
+
+@pytest.mark.ai
+def test_remove_extra_refs__handles_multiple_occurrences__of_same_ref() -> None:
+    """
+    Purpose: Verify removes all occurrences of an orphan ref.
+    Why this matters: Ensures complete cleanup of invalid refs.
+    Setup summary: Text with repeated orphan ref, verify all instances removed.
+    """
+    # Arrange
+    response = "First <sup>3</sup> middle <sup>3</sup> end <sup>3</sup>"
+    refs = [{"sequenceNumber": 1}]  # Ref 3 is orphan
+
+    # Act
+    result = _remove_extra_refs(response, refs)
+
+    # Assert
+    assert "<sup>3</sup>" not in result
+    assert result == "First  middle  end "
+
+
+# Tests for _prepare_sub_agent_response_refs
+
+
+@pytest.mark.ai
+def test_prepare_sub_agent_response_refs__replaces_ref_format__correctly() -> None:
+    """
+    Purpose: Verify refs are replaced with sub-agent format.
+    Why this matters: Core functionality for sub-agent reference attribution.
+    Setup summary: Text with standard refs, verify replaced with named format.
+    """
+    # Arrange
+    response = "Check this <sup>1</sup> reference"
+    name = "ResearchAgent"
+    sequence_number = 1
+    refs = [{"sequenceNumber": 1}]
+
+    # Act
+    result = _prepare_sub_agent_response_refs(response, name, sequence_number, refs)
+
+    # Assert
+    assert "<sup>1</sup>" not in result
+    assert "<sup><name>ResearchAgent 1</name>1</sup>" in result
+
+
+@pytest.mark.ai
+def test_prepare_sub_agent_response_refs__handles_multiple_refs__correctly() -> None:
+    """
+    Purpose: Verify multiple refs are all properly formatted.
+    Why this matters: Ensures batch processing of references works.
+    Setup summary: Text with multiple refs, verify all replaced correctly.
+    """
+    # Arrange
+    response = "First <sup>1</sup> and second <sup>2</sup>"
+    name = "TestAgent"
+    sequence_number = 3
+    refs = [{"sequenceNumber": 1}, {"sequenceNumber": 2}]
+
+    # Act
+    result = _prepare_sub_agent_response_refs(response, name, sequence_number, refs)
+
+    # Assert
+    assert "<sup><name>TestAgent 3</name>1</sup>" in result
+    assert "<sup><name>TestAgent 3</name>2</sup>" in result
+
+
+@pytest.mark.ai
+def test_prepare_sub_agent_response_refs__preserves_text__around_refs() -> None:
+    """
+    Purpose: Verify surrounding text is preserved when refs are replaced.
+    Why this matters: Ensures reference replacement doesn't corrupt text.
+    Setup summary: Text with refs, verify non-ref content unchanged.
+    """
+    # Arrange
+    response = "Start text <sup>1</sup> middle text <sup>2</sup> end text"
+    name = "Agent"
+    sequence_number = 1
+    refs = [{"sequenceNumber": 1}, {"sequenceNumber": 2}]
+
+    # Act
+    result = _prepare_sub_agent_response_refs(response, name, sequence_number, refs)
+
+    # Assert
+    assert "Start text" in result
+    assert "middle text" in result
+    assert "end text" in result
+
+
+@pytest.mark.ai
+def test_prepare_sub_agent_response_refs__returns_unchanged__when_no_refs() -> None:
+    """
+    Purpose: Verify text unchanged when refs list is empty.
+    Why this matters: Handles edge case of no references gracefully.
+    Setup summary: Empty refs list, verify text unchanged.
+    """
+    # Arrange
+    response = "Text without any references"
+    name = "Agent"
+    sequence_number = 1
+    refs: list[dict[str, Any]] = []
+
+    # Act
+    result = _prepare_sub_agent_response_refs(response, name, sequence_number, refs)
+
+    # Assert
+    assert result == response
+
+
+@pytest.mark.ai
+def test_prepare_sub_agent_response_refs__uses_correct_sequence_number__in_format() -> (
+    None
+):
+    """
+    Purpose: Verify the sequence number is correctly used in the formatted reference.
+    Why this matters: Sequence number identifies the sub-agent call instance.
+    Setup summary: Specific sequence number, verify it appears in output format.
+    """
+    # Arrange
+    response = "Ref <sup>1</sup>"
+    name = "MyAgent"
+    sequence_number = 42
+    refs = [{"sequenceNumber": 1}]
+
+    # Act
+    result = _prepare_sub_agent_response_refs(response, name, sequence_number, refs)
+
+    # Assert
+    assert "<name>MyAgent 42</name>" in result
+
+
+# Tests for _get_sub_agent_system_reminders
+
+
+@pytest.mark.ai
+def test_get_sub_agent_system_reminders__returns_empty__when_no_configs() -> None:
+    """
+    Purpose: Verify returns empty list when no reminder configs provided.
+    Why this matters: Handles no-config case gracefully.
+    Setup summary: Empty configs list, assert empty result.
+    """
+    # Arrange
+    response = "Some response"
+    configs: list[Any] = []
+    name = "TestAgent"
+    display_name = "Test Agent"
+    sequence_number = 1
+    has_refs = False
+
+    # Act
+    result = _get_sub_agent_system_reminders(
+        response, configs, name, display_name, sequence_number, has_refs
+    )
+
+    # Assert
+    assert result == []
+
+
+@pytest.mark.ai
+def test_get_sub_agent_system_reminders__adds_fixed_reminder__always() -> None:
+    """
+    Purpose: Verify FIXED type reminders are always added.
+    Why this matters: FIXED reminders should appear regardless of response content.
+    Setup summary: FIXED config, verify reminder added.
+    """
+    # Arrange
+    response = "Any response"
+    configs = [FixedSystemReminderConfig(reminder="Always show this reminder")]
+    name = "TestAgent"
+    display_name = "Test Agent"
+    sequence_number = 1
+    has_refs = False
+
+    # Act
+    result = _get_sub_agent_system_reminders(
+        response, configs, name, display_name, sequence_number, has_refs
+    )
+
+    # Assert
+    assert len(result) == 1
+    assert "Always show this reminder" in result[0]
+
+
+@pytest.mark.ai
+def test_get_sub_agent_system_reminders__adds_reference_reminder__when_has_refs() -> (
+    None
+):
+    """
+    Purpose: Verify REFERENCE type reminder added when has_refs is True.
+    Why this matters: Reference reminders help LLM cite sources correctly.
+    Setup summary: REFERENCE config with has_refs=True, verify reminder added.
+    """
+    # Arrange
+    response = "Response with refs"
+    configs = [ReferenceSystemReminderConfig()]
+    name = "TestAgent"
+    display_name = "Test Agent"
+    sequence_number = 1
+    has_refs = True
+
+    # Act
+    result = _get_sub_agent_system_reminders(
+        response, configs, name, display_name, sequence_number, has_refs
+    )
+
+    # Assert
+    assert len(result) == 1
+    assert "Test Agent" in result[0]  # display_name should be rendered
+
+
+@pytest.mark.ai
+def test_get_sub_agent_system_reminders__skips_reference_reminder__when_no_refs() -> (
+    None
+):
+    """
+    Purpose: Verify REFERENCE reminder skipped when has_refs is False.
+    Why this matters: Avoids irrelevant reminders about citations.
+    Setup summary: REFERENCE config with has_refs=False, verify not added.
+    """
+    # Arrange
+    response = "Response without refs"
+    configs = [ReferenceSystemReminderConfig()]
+    name = "TestAgent"
+    display_name = "Test Agent"
+    sequence_number = 1
+    has_refs = False
+
+    # Act
+    result = _get_sub_agent_system_reminders(
+        response, configs, name, display_name, sequence_number, has_refs
+    )
+
+    # Assert
+    assert result == []
+
+
+@pytest.mark.ai
+def test_get_sub_agent_system_reminders__adds_no_reference_reminder__when_no_refs() -> (
+    None
+):
+    """
+    Purpose: Verify NO_REFERENCE reminder added when has_refs is False.
+    Why this matters: Warns LLM not to fabricate citations.
+    Setup summary: NO_REFERENCE config with has_refs=False, verify added.
+    """
+    # Arrange
+    response = "Response without refs"
+    configs = [NoReferenceSystemReminderConfig()]
+    name = "TestAgent"
+    display_name = "Test Agent"
+    sequence_number = 1
+    has_refs = False
+
+    # Act
+    result = _get_sub_agent_system_reminders(
+        response, configs, name, display_name, sequence_number, has_refs
+    )
+
+    # Assert
+    assert len(result) == 1
+    assert "NOT" in result[0]  # Default reminder contains "Do NOT"
+
+
+@pytest.mark.ai
+def test_get_sub_agent_system_reminders__skips_no_reference_reminder__when_has_refs() -> (
+    None
+):
+    """
+    Purpose: Verify NO_REFERENCE reminder skipped when has_refs is True.
+    Why this matters: Avoids contradictory instructions when refs exist.
+    Setup summary: NO_REFERENCE config with has_refs=True, verify not added.
+    """
+    # Arrange
+    response = "Response with refs"
+    configs = [NoReferenceSystemReminderConfig()]
+    name = "TestAgent"
+    display_name = "Test Agent"
+    sequence_number = 1
+    has_refs = True
+
+    # Act
+    result = _get_sub_agent_system_reminders(
+        response, configs, name, display_name, sequence_number, has_refs
+    )
+
+    # Assert
+    assert result == []
+
+
+@pytest.mark.ai
+def test_get_sub_agent_system_reminders__adds_regexp_reminder__when_pattern_matches() -> (
+    None
+):
+    """
+    Purpose: Verify REGEXP reminder added when pattern matches response.
+    Why this matters: Enables conditional reminders based on response content.
+    Setup summary: REGEXP config matching response, verify reminder added.
+    """
+    # Arrange
+    response = "This response contains IMPORTANT_KEYWORD here"
+    configs = [
+        RegExpDetectedSystemReminderConfig(
+            regexp=re.compile(r"IMPORTANT_KEYWORD"),
+            reminder="Found keyword: {{ text_matches }}",
+        )
+    ]
+    name = "TestAgent"
+    display_name = "Test Agent"
+    sequence_number = 1
+    has_refs = False
+
+    # Act
+    result = _get_sub_agent_system_reminders(
+        response, configs, name, display_name, sequence_number, has_refs
+    )
+
+    # Assert
+    assert len(result) == 1
+    assert "IMPORTANT_KEYWORD" in result[0]
+
+
+@pytest.mark.ai
+def test_get_sub_agent_system_reminders__skips_regexp_reminder__when_no_match() -> None:
+    """
+    Purpose: Verify REGEXP reminder skipped when pattern doesn't match.
+    Why this matters: Avoids irrelevant conditional reminders.
+    Setup summary: REGEXP config not matching response, verify not added.
+    """
+    # Arrange
+    response = "This response has no special keywords"
+    configs = [
+        RegExpDetectedSystemReminderConfig(
+            regexp=re.compile(r"NONEXISTENT_PATTERN"),
+            reminder="Should not appear",
+        )
+    ]
+    name = "TestAgent"
+    display_name = "Test Agent"
+    sequence_number = 1
+    has_refs = False
+
+    # Act
+    result = _get_sub_agent_system_reminders(
+        response, configs, name, display_name, sequence_number, has_refs
+    )
+
+    # Assert
+    assert result == []
+
+
+@pytest.mark.ai
+def test_get_sub_agent_system_reminders__renders_jinja_template__correctly() -> None:
+    """
+    Purpose: Verify Jinja templates in reminders are correctly rendered.
+    Why this matters: Templates allow dynamic reminder content.
+    Setup summary: FIXED config with template placeholders, verify rendered.
+    """
+    # Arrange
+    response = "Some response"
+    configs = [
+        FixedSystemReminderConfig(
+            reminder="Tool {{ tool_name }} ({{ display_name }}) says hello"
+        )
+    ]
+    name = "MyTool"
+    display_name = "My Special Tool"
+    sequence_number = 1
+    has_refs = False
+
+    # Act
+    result = _get_sub_agent_system_reminders(
+        response, configs, name, display_name, sequence_number, has_refs
+    )
+
+    # Assert
+    assert len(result) == 1
+    assert "Tool MyTool (My Special Tool) says hello" in result[0]
+
+
+@pytest.mark.ai
+def test_get_sub_agent_system_reminders__includes_sequence_in_tool_name__for_ref_types() -> (
+    None
+):
+    """
+    Purpose: Verify REFERENCE/NO_REFERENCE types include sequence number in tool_name.
+    Why this matters: Helps identify which sub-agent call produced the response.
+    Setup summary: REFERENCE config, verify tool_name includes sequence number.
+    """
+    # Arrange
+    response = "Response"
+    configs = [ReferenceSystemReminderConfig(reminder="Cite {{ tool_name }} correctly")]
+    name = "Agent"
+    display_name = "Agent"
+    sequence_number = 5
+    has_refs = True
+
+    # Act
+    result = _get_sub_agent_system_reminders(
+        response, configs, name, display_name, sequence_number, has_refs
+    )
+
+    # Assert
+    assert len(result) == 1
+    assert "Agent 5" in result[0]
+
+
+@pytest.mark.ai
+def test_get_sub_agent_system_reminders__handles_multiple_configs__correctly() -> None:
+    """
+    Purpose: Verify multiple configs are processed and applicable ones added.
+    Why this matters: Supports complex reminder configurations.
+    Setup summary: Multiple config types, verify correct ones added.
+    """
+    # Arrange
+    response = "Response with SPECIAL text"
+    configs = [
+        FixedSystemReminderConfig(reminder="Fixed reminder"),
+        NoReferenceSystemReminderConfig(),  # Should be added (has_refs=False)
+        ReferenceSystemReminderConfig(),  # Should NOT be added (has_refs=False)
+        RegExpDetectedSystemReminderConfig(
+            regexp=re.compile(r"SPECIAL"),
+            reminder="Found special",
+        ),
+    ]
+    name = "TestAgent"
+    display_name = "Test Agent"
+    sequence_number = 1
+    has_refs = False
+
+    # Act
+    result = _get_sub_agent_system_reminders(
+        response, configs, name, display_name, sequence_number, has_refs
+    )
+
+    # Assert
+    assert len(result) == 3
+    assert any("Fixed reminder" in r for r in result)
+    assert any("NOT" in r for r in result)  # NO_REFERENCE default
+    assert any("Found special" in r for r in result)
+
+
+@pytest.mark.ai
+def test_get_sub_agent_system_reminders__captures_all_regexp_matches__in_text_matches() -> (
+    None
+):
+    """
+    Purpose: Verify all regexp matches are captured in text_matches variable.
+    Why this matters: Allows templates to reference all matched content.
+    Setup summary: Response with multiple pattern matches, verify all captured.
+    """
+    # Arrange
+    response = "Found CODE123 and CODE456 and CODE789"
+    configs = [
+        RegExpDetectedSystemReminderConfig(
+            regexp=re.compile(r"CODE\d+"),
+            reminder="Codes found: {{ text_matches | join(', ') }}",
+        )
+    ]
+    name = "TestAgent"
+    display_name = "Test Agent"
+    sequence_number = 1
+    has_refs = False
+
+    # Act
+    result = _get_sub_agent_system_reminders(
+        response, configs, name, display_name, sequence_number, has_refs
+    )
+
+    # Assert
+    assert len(result) == 1
+    assert "CODE123" in result[0]
+    assert "CODE456" in result[0]
+    assert "CODE789" in result[0]

{unique_toolkit-1.35.4.dist-info → unique_toolkit-1.36.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: unique_toolkit
-Version: 1.35.4
+Version: 1.36.0
 Summary: 
 License: Proprietary
 Author: Cedric Klinkert
@@ -121,6 +121,9 @@ All notable changes to this project will be documented in this file.
 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.36.0] - 2025-12-11
+- Add support for a sub agent tool system reminder when no references are present in the sub agent response.
+
 ## [1.35.4] - 2025-12-10
 - Fix a potential stacktrace leak
 

{unique_toolkit-1.35.4.dist-info → unique_toolkit-1.36.0.dist-info}/RECORD

@@ -22,7 +22,7 @@ unique_toolkit/_common/experimental/endpoint_requestor.py,sha256=YnDr8wASAEjZjLA
 unique_toolkit/_common/feature_flags/schema.py,sha256=X32VqH4VMK7bhEfSd8Wbddl8FVs7Gh7ucuIEbmqc4Kw,268
 unique_toolkit/_common/pydantic/rjsf_tags.py,sha256=T3AZIF8wny3fFov66s258nEl1GqfKevFouTtG6k9PqU,31219
 unique_toolkit/_common/pydantic_helpers.py,sha256=Yg1CHD603wVrqvinHiyh3stjIK3MjuexUe9aQQUfmXs,5406
-unique_toolkit/_common/referencing.py,sha256=kEWkzMaz6DMCpkxsQD7AY4YWl15KendqbK_WkASfhaw,1499
+unique_toolkit/_common/referencing.py,sha256=UY7-9nJLcRqlHUNytfJZPVkdpjvy5wIps_7P33_qgA0,1496
 unique_toolkit/_common/string_utilities.py,sha256=hiNyGCNISm2HuEGWYgu01dB2YJGN_NfHI345X7rRu80,4347
 unique_toolkit/_common/tests/test_referencing.py,sha256=WYKGkO3OXPYyTL8f6fVE9pqKuFowUHja5CUCTpWzRJQ,16206
 unique_toolkit/_common/tests/test_string_utilities.py,sha256=J2HYZ1fniOfJWI149wlooVrT7ot4qe5bhehGh9B7FN8,15641
@@ -93,20 +93,21 @@ unique_toolkit/agentic/tools/a2a/manager.py,sha256=pk06UUXKQdIUY-PyykYiItubBjmIy
 unique_toolkit/agentic/tools/a2a/postprocessing/__init__.py,sha256=aVtUBPN7kDrqA6Bze34AbqQpcBBqpvfyJG-xF65w7R0,659
 unique_toolkit/agentic/tools/a2a/postprocessing/_display_utils.py,sha256=eL_5bkud6aPCKGER705ZQkNttrUZEs-zco83SfbffDQ,7107
 unique_toolkit/agentic/tools/a2a/postprocessing/_ref_utils.py,sha256=tfH3Bhx67uQtH3fYoUr2Zp45HVw7hV_N-5F_qRwiOas,2727
-unique_toolkit/agentic/tools/a2a/postprocessing/config.py,sha256=nYH1otBrVGHq1Y2i1KII3pb1IVE0efwmOwhOLLsv1qU,2841
+unique_toolkit/agentic/tools/a2a/postprocessing/config.py,sha256=bmdi5CbtpSWe33fUY-VDRu0PdYI6ZB9fFqCY1cUQz30,2841
 unique_toolkit/agentic/tools/a2a/postprocessing/display.py,sha256=e8R92XJHwyVI8UxVqCG_cTzensHSfGOIfDe1nfGcDoE,9058
 unique_toolkit/agentic/tools/a2a/postprocessing/references.py,sha256=DGiv8WXMjIwumI7tlpWRgV8wSxnE282ryxEf03fgck8,3465
 unique_toolkit/agentic/tools/a2a/postprocessing/test/test_display.py,sha256=pP7fjvCm4aamtizs4viZSwsrw4Vb4kMxwDPEEx8GI98,14676
 unique_toolkit/agentic/tools/a2a/postprocessing/test/test_display_utils.py,sha256=5d67L4msesDENsNhgeoDTH6pjw_Z4FUUC1lRM9j4PlI,63608
 unique_toolkit/agentic/tools/a2a/postprocessing/test/test_ref_utils.py,sha256=u-eNrHjsRFcu4TmzkD5XfFrxvaIToB42YGyXZ-RpsR0,17830
-unique_toolkit/agentic/tools/a2a/prompts.py,sha256=0ILHL_RAcT04gFm2d470j4Gho7PoJXdCJy-bkZgf_wk,2401
+unique_toolkit/agentic/tools/a2a/prompts.py,sha256=Qm4yGs2kVm1rUtO-qntDf87q_euG7ed1cp9yf81demQ,2515
 unique_toolkit/agentic/tools/a2a/response_watcher/__init__.py,sha256=fS8Lq49DZo5spMcP8QGTMWwSg80rYSr2pTfYDbssGYs,184
 unique_toolkit/agentic/tools/a2a/response_watcher/service.py,sha256=Tlzd7Tvk0X8a9Jyi4qHWuAx0PffAnt6BGBbQ4QWAZus,2485
 unique_toolkit/agentic/tools/a2a/tool/__init__.py,sha256=JIJKZBTLTA39OWhxoUd6uairxmqINur1Ex6iXDk9ef8,197
 unique_toolkit/agentic/tools/a2a/tool/_memory.py,sha256=w8bxjokrqHQZgApd55b5rHXF-DpgJwaKTg4CvLBLamc,1034
 unique_toolkit/agentic/tools/a2a/tool/_schema.py,sha256=wMwyunViTnxaURvenkATEvyfXn5LvLaP0HxbYqdZGls,158
-unique_toolkit/agentic/tools/a2a/tool/config.py,sha256=zK9onAMYlYrPc0MCz0gBocd22jm0H5ar1ihNJ7CyjJU,5780
-unique_toolkit/agentic/tools/a2a/tool/service.py,sha256=OJx1zc1roPgt4aa1fDw4XTF9VOCCF72dhEJaNMEMOSU,13865
+unique_toolkit/agentic/tools/a2a/tool/config.py,sha256=k-YRhy7ELVLj7WP-BIDxlPYL8WK2kQll87U7wTtCrUk,6480
+unique_toolkit/agentic/tools/a2a/tool/service.py,sha256=XC5bHZfKlUTvbvUrjYpCdKFrCFqZP53CznGBUT_m6Uo,15152
+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=x32Dp1Z8cVW5i-XzXbaMwX2KHPcNGmqEU-FB4AV9ZGo,1909
 unique_toolkit/agentic/tools/config.py,sha256=71PSq8LoR80irk2iJfy_AgXOPi4Nh3luW5z5cDvY8i0,3920
 unique_toolkit/agentic/tools/factory.py,sha256=A1Aliwx037UAk9ADiDsg0zjCWWnvzV_PxwJNoPTvW6c,1434
@@ -208,7 +209,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.35.4.dist-info/LICENSE,sha256=GlN8wHNdh53xwOPg44URnwag6TEolCjoq3YD_KrWgss,193
-unique_toolkit-1.35.4.dist-info/METADATA,sha256=dcIwAZ7cJvDVgC11zc7DC29MqbTIkYZFjUI1C_vbLes,46044
-unique_toolkit-1.35.4.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-unique_toolkit-1.35.4.dist-info/RECORD,,
+unique_toolkit-1.36.0.dist-info/LICENSE,sha256=GlN8wHNdh53xwOPg44URnwag6TEolCjoq3YD_KrWgss,193
+unique_toolkit-1.36.0.dist-info/METADATA,sha256=b-BMlh-JACksT29xq0D-VY8p3OZo-wXrrwJgn6Ronf0,46179
+unique_toolkit-1.36.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+unique_toolkit-1.36.0.dist-info/RECORD,,