unique_toolkit 1.4.2__tar.gz → 1.4.4__tar.gz

{unique_toolkit-1.4.2 → unique_toolkit-1.4.4}/CHANGELOG.md

@@ -5,6 +5,12 @@ 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.4.4] - 2025-09-30
+- Fix bugs with display of sub-agent answers and evaluations when multiple sub-agent from the same assistant run concurrently.
+
+## [1.4.3] - 2025-09-30
+- Fix bug with sub-agent post-processing reference numbers.
+
 ## [1.4.2] - 2025-09-30
 - Adding litellm models `litellm:anthropic-claude-sonnet-4-5` and `litellm:anthropic-claude-opus-4-1`
 

{unique_toolkit-1.4.2 → unique_toolkit-1.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: unique_toolkit
-Version: 1.4.2
+Version: 1.4.4
 Summary: 
 License: Proprietary
 Author: Cedric Klinkert
@@ -118,6 +118,12 @@ 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.4.4] - 2025-09-30
+- Fix bugs with display of sub-agent answers and evaluations when multiple sub-agent from the same assistant run concurrently.
+
+## [1.4.3] - 2025-09-30
+- Fix bug with sub-agent post-processing reference numbers.
+
 ## [1.4.2] - 2025-09-30
 - Adding litellm models `litellm:anthropic-claude-sonnet-4-5` and `litellm:anthropic-claude-opus-4-1`
 

{unique_toolkit-1.4.2 → unique_toolkit-1.4.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "unique_toolkit"
-version = "1.4.2"
+version = "1.4.4"
 description = ""
 authors = [
     "Cedric Klinkert <cedric.klinkert@unique.ch>",

{unique_toolkit-1.4.2 → unique_toolkit-1.4.4}/unique_toolkit/agentic/tools/a2a/config.py

@@ -9,6 +9,10 @@ DEFAULT_PARAM_DESCRIPTION_SUB_AGENT_USER_MESSAGE = """
 This is the message that will be sent to the sub-agent.
 """.strip()
 
+DEFAULT_FORMAT_INFORMATION_SUB_AGENT_SYSTEM_MESSAGE = """
+NEVER mention any references from sub-agent answers in your response.
+"""
+
 
 class ResponseDisplayMode(StrEnum):
     HIDDEN = "hidden"
@@ -40,7 +44,9 @@ class SubAgentToolConfig(BaseToolConfig):
     param_description_sub_agent_user_message: str = (
         DEFAULT_PARAM_DESCRIPTION_SUB_AGENT_USER_MESSAGE
     )
-    tool_format_information_for_system_prompt: str = ""
+    tool_format_information_for_system_prompt: str = (
+        DEFAULT_FORMAT_INFORMATION_SUB_AGENT_SYSTEM_MESSAGE
+    )
     tool_description_for_user_prompt: str = ""
     tool_format_information_for_user_prompt: str = ""
 

{unique_toolkit-1.4.2 → unique_toolkit-1.4.4}/unique_toolkit/agentic/tools/a2a/evaluation/config.py

@@ -15,6 +15,7 @@ Your task is to give a brief summary (1-10 sentences) of the received assessment
 1. You must NOT in ANY case state a fact that is not stated in the given assessments.
 2. You must focus first and foremost on the failing assessments, labeled `RED` below.
 3. You must mention each agent's name when summarizing its list of assessments.
+4. You must NOT use any markdown formatting in your response as this will FAIL to render in the chat frontend.
 """.strip()
 
 with open(Path(__file__).parent / "summarization_user_message.j2", "r") as file:

{unique_toolkit-1.4.2 → unique_toolkit-1.4.4}/unique_toolkit/agentic/tools/a2a/evaluation/evaluator.py

@@ -27,7 +27,7 @@ logger = logging.getLogger(__name__)
 
 
 class _SubAgentToolInfo(TypedDict):
-    assessment: list[unique_sdk.Space.Assessment] | None
+    assessments: list[list[unique_sdk.Space.Assessment]]
     display_name: str
 
 
@@ -53,7 +53,7 @@ class SubAgentsEvaluation(Evaluation):
             if sub_agent_tool.config.evaluation_config.display_evalution:
                 sub_agent_tool.subscribe(self)
                 self._assistant_id_to_tool_info[sub_agent_tool.config.assistant_id] = {
-                    "assessment": None,
+                    "assessments": [],
                     "display_name": sub_agent_tool.display_name(),
                 }
 
@@ -80,47 +80,53 @@ class SubAgentsEvaluation(Evaluation):
         label_comparison_dict[ChatMessageAssessmentLabel.RED] = 0
 
         for assistant_id, tool_info in self._assistant_id_to_tool_info.items():
-            assessments = tool_info["assessment"] or []
-            valid_assessments = []
-            for assessment in assessments:
-                if (
-                    assessment["label"] is None
-                    or assessment["label"] not in ChatMessageAssessmentLabel
-                ):
-                    logger.warning(
-                        "Unkown assistant label %s for assistant %s will be ignored",
-                        assessment["label"],
-                        assistant_id,
-                    )
-                    continue
-                if assessment["status"] != ChatMessageAssessmentStatus.DONE:
-                    logger.warning(
-                        "Assessment %s for assistant %s is not done (status: %s) will be ignored",
-                        assessment["label"],
-                        assistant_id,
+            sub_agent_assessments = tool_info["assessments"] or []
+            for i, assessments in enumerate(sub_agent_assessments, start=1):
+                valid_assessments = []
+                for assessment in assessments:
+                    if (
+                        assessment["label"] is None
+                        or assessment["label"] not in ChatMessageAssessmentLabel
+                    ):
+                        logger.warning(
+                            "Unkown assistant label %s for assistant %s will be ignored",
+                            assessment["label"],
+                            assistant_id,
+                        )
+                        continue
+                    if assessment["status"] != ChatMessageAssessmentStatus.DONE:
+                        logger.warning(
+                            "Assessment %s for assistant %s is not done (status: %s) will be ignored",
+                            assessment["label"],
+                            assistant_id,
+                        )
+                        continue
+                    valid_assessments.append(assessment)
+
+                if len(valid_assessments) == 0:
+                    logger.info(
+                        "No valid assessment found for assistant %s", assistant_id
                     )
                     continue
-                valid_assessments.append(assessment)
-
-            if len(valid_assessments) == 0:
-                logger.info("No valid assessment found for assistant %s", assistant_id)
-                continue
 
-            assessments = sorted(
-                valid_assessments, key=lambda x: label_comparison_dict[x["label"]]
-            )
-
-            for assessment in assessments:
-                value = min(
-                    value, assessment["label"], key=lambda x: label_comparison_dict[x]
+                assessments = sorted(
+                    valid_assessments, key=lambda x: label_comparison_dict[x["label"]]
                 )
 
-            sub_agents_display_data.append(
-                {
+                for assessment in assessments:
+                    value = min(
+                        value,
+                        assessment["label"],
+                        key=lambda x: label_comparison_dict[x],
+                    )
+                data = {
                     "name": tool_info["display_name"],
                     "assessments": assessments,
                 }
-            )
+                if len(sub_agent_assessments) > 1:
+                    data["name"] += f" {i}"
+
+                sub_agents_display_data.append(data)
 
         if len(sub_agents_display_data) == 0:
             logger.warning("No valid sub agent assessments found")
@@ -200,10 +206,10 @@ class SubAgentsEvaluation(Evaluation):
             )
             return
 
-        self._assistant_id_to_tool_info[sub_agent_assistant_id]["assessment"] = (
+        self._assistant_id_to_tool_info[sub_agent_assistant_id]["assessments"].append(
             response[
                 "assessment"
             ].copy()  # Shallow copy as we don't modify individual assessments
             if response["assessment"] is not None
-            else None
+            else []
         )

unique_toolkit-1.4.4/unique_toolkit/agentic/tools/a2a/postprocessing/postprocessor.py

@@ -0,0 +1,231 @@
+import logging
+import re
+from typing import TypedDict, override
+
+import unique_sdk
+
+from unique_toolkit.agentic.postprocessor.postprocessor_manager import Postprocessor
+from unique_toolkit.agentic.tools.a2a.config import (
+    ResponseDisplayMode,
+    SubAgentToolDisplayConfig,
+)
+from unique_toolkit.agentic.tools.a2a.postprocessing.display import (
+    build_sub_agent_answer_display,
+    remove_sub_agent_answer_from_text,
+)
+from unique_toolkit.agentic.tools.a2a.service import SubAgentTool
+from unique_toolkit.content.schemas import ContentReference
+from unique_toolkit.language_model.schemas import LanguageModelStreamResponse
+
+logger = logging.getLogger(__name__)
+
+SpaceMessage = unique_sdk.Space.Message
+
+
+class _SubAgentMessageInfo(TypedDict):
+    text: str | None
+    references: list[unique_sdk.Space.Reference]
+
+
+class _SubAgentToolInfo(TypedDict):
+    display_name: str
+    display_config: SubAgentToolDisplayConfig
+    responses: list[_SubAgentMessageInfo]
+
+
+class SubAgentResponsesPostprocessor(Postprocessor):
+    def __init__(
+        self,
+        user_id: str,
+        company_id: str,
+        agent_chat_id: str,
+        sub_agent_tools: list[SubAgentTool],
+    ):
+        super().__init__(name=self.__class__.__name__)
+
+        self._user_id = user_id
+        self._company_id = company_id
+
+        self._agent_chat_id = agent_chat_id
+
+        self._assistant_id_to_tool_info: dict[str, _SubAgentToolInfo] = {}
+
+        for sub_agent_tool in sub_agent_tools:
+            sub_agent_tool.subscribe(self)
+
+            self._assistant_id_to_tool_info[sub_agent_tool.config.assistant_id] = (
+                _SubAgentToolInfo(
+                    display_config=sub_agent_tool.config.response_display_config,
+                    display_name=sub_agent_tool.display_name(),
+                    responses=[],
+                )
+            )
+
+        self._sub_agent_message = None
+
+    @override
+    async def run(self, loop_response: LanguageModelStreamResponse) -> None:
+        self._sub_agent_message = await unique_sdk.Space.get_latest_message_async(
+            user_id=self._user_id,
+            company_id=self._company_id,
+            chat_id=self._agent_chat_id,
+        )
+
+    @override
+    def apply_postprocessing_to_response(
+        self, loop_response: LanguageModelStreamResponse
+    ) -> bool:
+        logger.info("Adding sub agent responses to the response")
+
+        # Get responses to display
+        displayed = {}
+        for assistant_id, tool_info in self._assistant_id_to_tool_info.items():
+            display_mode = tool_info["display_config"].mode
+
+            if len(tool_info["responses"]) == 0:
+                logger.warning(
+                    "No response from assistant %s",
+                    assistant_id,
+                )
+                continue
+
+            if display_mode != ResponseDisplayMode.HIDDEN:
+                displayed[assistant_id] = tool_info["responses"]
+
+        existing_refs = {
+            ref.source_id: ref.sequence_number
+            for ref in loop_response.message.references
+        }
+        _consolidate_references_in_place(displayed, existing_refs)
+
+        modified = len(displayed) > 0
+        for assistant_id, messages in reversed(displayed.items()):
+            for i in reversed(range(len(messages))):
+                message = messages[i]
+                tool_info = self._assistant_id_to_tool_info[assistant_id]
+                display_mode = tool_info["display_config"].mode
+                display_name = tool_info["display_name"]
+                if len(messages) > 1:
+                    display_name += f" {i + 1}"
+
+                loop_response.message.text = (
+                    build_sub_agent_answer_display(
+                        display_name=display_name,
+                        assistant_id=assistant_id,
+                        display_mode=display_mode,
+                        answer=message["text"],
+                    )
+                    + loop_response.message.text
+                )
+
+                assert self._sub_agent_message is not None
+
+                loop_response.message.references.extend(
+                    ContentReference(
+                        message_id=self._sub_agent_message["id"],
+                        source_id=ref["sourceId"],
+                        url=ref["url"],
+                        source=ref["source"],
+                        name=ref["name"],
+                        sequence_number=ref["sequenceNumber"],
+                    )
+                    for ref in message["references"]
+                )
+
+        return modified
+
+    @override
+    async def remove_from_text(self, text) -> str:
+        for assistant_id, tool_info in self._assistant_id_to_tool_info.items():
+            display_config = tool_info["display_config"]
+            if display_config.remove_from_history:
+                text = remove_sub_agent_answer_from_text(
+                    display_mode=display_config.mode,
+                    text=text,
+                    assistant_id=assistant_id,
+                )
+        return text
+
+    def notify_sub_agent_response(
+        self, sub_agent_assistant_id: str, response: SpaceMessage
+    ) -> None:
+        if sub_agent_assistant_id not in self._assistant_id_to_tool_info:
+            logger.warning(
+                "Unknown assistant id %s received, message will be ignored.",
+                sub_agent_assistant_id,
+            )
+            return
+
+        self._assistant_id_to_tool_info[sub_agent_assistant_id]["responses"].append(
+            {
+                "text": response["text"],
+                "references": [
+                    {
+                        "name": ref["name"],
+                        "url": ref["url"],
+                        "sequenceNumber": ref["sequenceNumber"],
+                        "originalIndex": [],
+                        "sourceId": ref["sourceId"],
+                        "source": ref["source"],
+                    }
+                    for ref in response["references"] or []
+                ],
+            }
+        )
+
+
+def _consolidate_references_in_place(
+    messages: dict[str, list[_SubAgentMessageInfo]], existing_refs: dict[str, int]
+) -> None:
+    start_index = max(existing_refs.values(), default=0) + 1
+
+    for assistant_id, assistant_messages in messages.items():
+        for message in assistant_messages:
+            references = message["references"]
+            if len(references) == 0 or message["text"] is None:
+                logger.info(
+                    "Message from assistant %s does not contain any references",
+                    assistant_id,
+                )
+                continue
+
+            references = list(sorted(references, key=lambda ref: ref["sequenceNumber"]))
+
+            ref_map = {}
+
+            message_new_refs = []
+            for reference in references:
+                source_id = reference["sourceId"]
+
+                if source_id not in existing_refs:
+                    message_new_refs.append(reference)
+                    existing_refs[source_id] = start_index
+                    start_index += 1
+
+                reference_num = existing_refs[source_id]
+                ref_map[reference["sequenceNumber"]] = reference_num
+                reference["sequenceNumber"] = reference_num
+
+            message["text"] = _replace_references_in_text(message["text"], ref_map)
+            message["references"] = message_new_refs
+
+
+def _replace_references_in_text_non_overlapping(
+    text: str, ref_map: dict[int, int]
+) -> str:
+    for orig, repl in ref_map.items():
+        text = re.sub(rf"<sup>{orig}</sup>", f"<sup>{repl}</sup>", text)
+    return text
+
+
+def _replace_references_in_text(text: str, ref_map: dict[int, int]) -> str:
+    # 2 phase replacement, since the map keys and values can overlap
+    max_ref = max(max(ref_map.keys(), default=0), max(ref_map.values(), default=0)) + 1
+    unique_refs = range(max_ref, max_ref + len(ref_map))
+
+    text = _replace_references_in_text_non_overlapping(
+        text, dict(zip(ref_map.keys(), unique_refs))
+    )
+    return _replace_references_in_text_non_overlapping(
+        text, dict(zip(unique_refs, ref_map.values()))
+    )

unique_toolkit-1.4.4/unique_toolkit/agentic/tools/a2a/postprocessing/test/test_postprocessor_reference_functions.py

@@ -0,0 +1,248 @@
+from unique_toolkit.agentic.tools.a2a.postprocessing.postprocessor import (
+    _replace_references_in_text,
+    _replace_references_in_text_non_overlapping,
+)
+
+
+class TestReplaceReferencesInTextNonOverlapping:
+    """Test cases for _replace_references_in_text_non_overlapping function."""
+
+    def test_single_reference_replacement(self):
+        """Test replacing a single reference."""
+        text = "This is a test<sup>1</sup> with one reference."
+        ref_map = {1: 5}
+        result = _replace_references_in_text_non_overlapping(text, ref_map)
+        expected = "This is a test<sup>5</sup> with one reference."
+        assert result == expected
+
+    def test_multiple_reference_replacements(self):
+        """Test replacing multiple references."""
+        text = "First<sup>1</sup> and second<sup>2</sup> and third<sup>3</sup>."
+        ref_map = {1: 10, 2: 20, 3: 30}
+        result = _replace_references_in_text_non_overlapping(text, ref_map)
+        expected = "First<sup>10</sup> and second<sup>20</sup> and third<sup>30</sup>."
+        assert result == expected
+
+    def test_no_references_in_text(self):
+        """Test with text that has no references."""
+        text = "This text has no references at all."
+        ref_map = {1: 5, 2: 10}
+        result = _replace_references_in_text_non_overlapping(text, ref_map)
+        assert result == text
+
+    def test_empty_ref_map(self):
+        """Test with empty reference map."""
+        text = "This text has<sup>1</sup> references but empty map."
+        ref_map = {}
+        result = _replace_references_in_text_non_overlapping(text, ref_map)
+        assert result == text
+
+    def test_empty_text(self):
+        """Test with empty text."""
+        text = ""
+        ref_map = {1: 5}
+        result = _replace_references_in_text_non_overlapping(text, ref_map)
+        assert result == ""
+
+    def test_reference_not_in_map(self):
+        """Test with references in text that are not in the map."""
+        text = "Reference<sup>1</sup> and<sup>2</sup> and<sup>3</sup>."
+        ref_map = {1: 10}  # Only maps reference 1
+        result = _replace_references_in_text_non_overlapping(text, ref_map)
+        expected = "Reference<sup>10</sup> and<sup>2</sup> and<sup>3</sup>."
+        assert result == expected
+
+    def test_duplicate_references_in_text(self):
+        """Test with duplicate references in text."""
+        text = "First<sup>1</sup> and second<sup>1</sup> occurrence."
+        ref_map = {1: 99}
+        result = _replace_references_in_text_non_overlapping(text, ref_map)
+        expected = "First<sup>99</sup> and second<sup>99</sup> occurrence."
+        assert result == expected
+
+    def test_adjacent_references(self):
+        """Test with adjacent references."""
+        text = "Adjacent<sup>1</sup><sup>2</sup> references."
+        ref_map = {1: 10, 2: 20}
+        result = _replace_references_in_text_non_overlapping(text, ref_map)
+        expected = "Adjacent<sup>10</sup><sup>20</sup> references."
+        assert result == expected
+
+    def test_references_with_multi_digit_numbers(self):
+        """Test with multi-digit reference numbers."""
+        text = "Reference<sup>123</sup> and<sup>456</sup>."
+        ref_map = {123: 789, 456: 101112}
+        result = _replace_references_in_text_non_overlapping(text, ref_map)
+        expected = "Reference<sup>789</sup> and<sup>101112</sup>."
+        assert result == expected
+
+    def test_references_at_text_boundaries(self):
+        """Test with references at the beginning and end of text."""
+        text = "<sup>1</sup>Start and end<sup>2</sup>"
+        ref_map = {1: 100, 2: 200}
+        result = _replace_references_in_text_non_overlapping(text, ref_map)
+        expected = "<sup>100</sup>Start and end<sup>200</sup>"
+        assert result == expected
+
+    def test_malformed_references_ignored(self):
+        """Test that malformed references are ignored."""
+        text = "Good<sup>1</sup> and bad<sup>abc</sup> and<sup></sup>."
+        ref_map = {1: 10}
+        result = _replace_references_in_text_non_overlapping(text, ref_map)
+        expected = "Good<sup>10</sup> and bad<sup>abc</sup> and<sup></sup>."
+        assert result == expected
+
+    def test_zero_reference_number(self):
+        """Test with zero as reference number."""
+        text = "Zero reference<sup>0</sup> here."
+        ref_map = {0: 100}
+        result = _replace_references_in_text_non_overlapping(text, ref_map)
+        expected = "Zero reference<sup>100</sup> here."
+        assert result == expected
+
+    def test_negative_reference_numbers(self):
+        """Test with negative reference numbers (edge case)."""
+        text = "Negative<sup>-1</sup> reference."
+        ref_map = {-1: 5}
+        result = _replace_references_in_text_non_overlapping(text, ref_map)
+        expected = "Negative<sup>5</sup> reference."
+        assert result == expected
+
+
+class TestReplaceReferencesInText:
+    """Test cases for _replace_references_in_text function."""
+
+    def test_non_overlapping_simple_case(self):
+        """Test simple non-overlapping case."""
+        text = "Reference<sup>1</sup> and<sup>2</sup>."
+        ref_map = {1: 10, 2: 20}
+        result = _replace_references_in_text(text, ref_map)
+        expected = "Reference<sup>10</sup> and<sup>20</sup>."
+        assert result == expected
+
+    def test_overlapping_references_case1(self):
+        """Test overlapping case where new reference numbers conflict with existing ones."""
+        text = "First<sup>1</sup> and second<sup>2</sup>."
+        ref_map = {1: 2, 2: 1}  # Swap references
+        result = _replace_references_in_text(text, ref_map)
+        expected = "First<sup>2</sup> and second<sup>1</sup>."
+        assert result == expected
+
+    def test_overlapping_references_case2(self):
+        """Test overlapping case with chain of replacements."""
+        text = "Refs<sup>1</sup><sup>2</sup><sup>3</sup>."
+        ref_map = {1: 2, 2: 3, 3: 1}  # Circular replacement
+        result = _replace_references_in_text(text, ref_map)
+        expected = "Refs<sup>2</sup><sup>3</sup><sup>1</sup>."
+        assert result == expected
+
+    def test_overlapping_with_higher_numbers(self):
+        """Test overlapping where replacement numbers are higher than originals."""
+        text = "Test<sup>1</sup> and<sup>2</sup>."
+        ref_map = {1: 3, 2: 1}  # 2 -> 1, but 1 -> 3
+        result = _replace_references_in_text(text, ref_map)
+        expected = "Test<sup>3</sup> and<sup>1</sup>."
+        assert result == expected
+
+    def test_complex_overlapping_scenario(self):
+        """Test complex overlapping scenario with multiple conflicts."""
+        text = "A<sup>1</sup>B<sup>2</sup>C<sup>3</sup>D<sup>4</sup>."
+        ref_map = {1: 4, 2: 1, 3: 2, 4: 3}  # Full rotation
+        result = _replace_references_in_text(text, ref_map)
+        expected = "A<sup>4</sup>B<sup>1</sup>C<sup>2</sup>D<sup>3</sup>."
+        assert result == expected
+
+    def test_empty_ref_map(self):
+        """Test with empty reference map."""
+        text = "Text with<sup>1</sup> references."
+        ref_map = {}
+        result = _replace_references_in_text(text, ref_map)
+        assert result == text
+
+    def test_empty_text(self):
+        """Test with empty text."""
+        text = ""
+        ref_map = {1: 2}
+        result = _replace_references_in_text(text, ref_map)
+        assert result == ""
+
+    def test_no_references_in_text(self):
+        """Test with text containing no references."""
+        text = "This text has no references."
+        ref_map = {1: 10, 2: 20}
+        result = _replace_references_in_text(text, ref_map)
+        assert result == text
+
+    def test_single_reference_no_overlap(self):
+        """Test single reference with no overlap potential."""
+        text = "Single<sup>5</sup> reference."
+        ref_map = {5: 100}
+        result = _replace_references_in_text(text, ref_map)
+        expected = "Single<sup>100</sup> reference."
+        assert result == expected
+
+    def test_partial_overlap(self):
+        """Test case where only some references have overlapping numbers."""
+        text = "Mix<sup>1</sup><sup>2</sup><sup>10</sup>."
+        ref_map = {1: 2, 2: 20, 10: 100}  # Only 1->2 creates potential overlap
+        result = _replace_references_in_text(text, ref_map)
+        expected = "Mix<sup>2</sup><sup>20</sup><sup>100</sup>."
+        assert result == expected
+
+    def test_self_mapping(self):
+        """Test case where a reference maps to itself."""
+        text = "Self<sup>1</sup> and other<sup>2</sup>."
+        ref_map = {1: 1, 2: 10}  # 1 maps to itself
+        result = _replace_references_in_text(text, ref_map)
+        expected = "Self<sup>1</sup> and other<sup>10</sup>."
+        assert result == expected
+
+    def test_duplicate_references_with_overlap(self):
+        """Test duplicate references in text with overlapping mappings."""
+        text = "Dup<sup>1</sup> and dup<sup>1</sup> and<sup>2</sup>."
+        ref_map = {1: 2, 2: 1}  # Swap
+        result = _replace_references_in_text(text, ref_map)
+        expected = "Dup<sup>2</sup> and dup<sup>2</sup> and<sup>1</sup>."
+        assert result == expected
+
+    def test_large_reference_numbers(self):
+        """Test with large reference numbers."""
+        text = "Large<sup>999</sup> and<sup>1000</sup>."
+        ref_map = {999: 1000, 1000: 999}  # Swap large numbers
+        result = _replace_references_in_text(text, ref_map)
+        expected = "Large<sup>1000</sup> and<sup>999</sup>."
+        assert result == expected
+
+    def test_zero_and_negative_with_overlap(self):
+        """Test zero and negative numbers with potential overlap."""
+        text = "Zero<sup>0</sup> and neg<sup>-1</sup> and pos<sup>1</sup>."
+        ref_map = {0: 1, -1: 0, 1: -1}  # Circular with zero and negative
+        result = _replace_references_in_text(text, ref_map)
+        expected = "Zero<sup>1</sup> and neg<sup>0</sup> and pos<sup>-1</sup>."
+        assert result == expected
+
+    def test_max_ref_calculation_edge_case(self):
+        """Test edge case for max_ref calculation with empty map."""
+        text = "Some<sup>1</sup> text."
+        ref_map = {}
+        result = _replace_references_in_text(text, ref_map)
+        assert result == text
+
+    def test_phase_separation_correctness(self):
+        """Test that the two-phase approach correctly handles complex overlaps."""
+        # This test ensures the intermediate unique references don't interfere
+        text = "Test<sup>1</sup><sup>2</sup><sup>3</sup><sup>4</sup><sup>5</sup>."
+        ref_map = {1: 5, 2: 4, 3: 3, 4: 2, 5: 1}  # Reverse order
+        result = _replace_references_in_text(text, ref_map)
+        expected = "Test<sup>5</sup><sup>4</sup><sup>3</sup><sup>2</sup><sup>1</sup>."
+        assert result == expected
+
+    def test_intermediate_collision_avoidance(self):
+        """Test that intermediate unique references don't collide with existing text."""
+        # Create a scenario where intermediate refs might collide
+        text = "Refs<sup>1</sup><sup>2</sup> and existing<sup>6</sup><sup>7</sup>."
+        ref_map = {1: 2, 2: 1}  # Simple swap
+        result = _replace_references_in_text(text, ref_map)
+        expected = "Refs<sup>2</sup><sup>1</sup> and existing<sup>6</sup><sup>7</sup>."
+        assert result == expected
+        # The existing <sup>6</sup> and <sup>7</sup> should remain unchanged