unique_toolkit 2026.22.0.dev13__tar.gz → 2026.24.0__tar.gz

{unique_toolkit-2026.22.0.dev13 → unique_toolkit-2026.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 2026.22.0.dev13
+Version: 2026.24.0
 Summary: 
 Author: Cedric Klinkert, Martin Fadler, Sadique Sheik, Fabian Schläpfer, Pascal Hauri, Ejiroghene Oki-Peter, Rami Azouz, Ricardo Visini, Sanzio Monti
 Author-email: Cedric Klinkert <cedric.klinkert@unique.ch>, Martin Fadler <martin.fadler@unique.ch>, Sadique Sheik <sadique@unique.ch>, Fabian Schläpfer <fabian@unique.ch>, Pascal Hauri <pascal@unique.ch>, Ejiroghene Oki-Peter <oki-peter.ejiroghene@unique.ai>, Rami Azouz <rami.ext@unique.ch>, Ricardo Visini <ricardo.visini@unique.ch>, Sanzio Monti <sanzio.monti@unique.ai>
@@ -16,7 +16,7 @@ Requires-Dist: sseclient>=0.0.27,<0.0.28
 Requires-Dist: openai>=1.105.0,<3
 Requires-Dist: platformdirs>=4.0.0,<5
 Requires-Dist: pillow>=12.1.1
-Requires-Dist: unique-sdk>=2026.22.0.dev3,<2026.22.0rc0
+Requires-Dist: unique-sdk>=2026.24.0
 Requires-Dist: jambo>=0.1.2,<0.2
 Requires-Dist: jinja2>=3.1.6,<4
 Requires-Dist: docxtpl>=0.20.1,<0.21
@@ -31,6 +31,7 @@ Requires-Dist: deepdiff>=8.6.1,<9
 Requires-Dist: pypandoc>=1.16.2,<2
 Requires-Dist: tenacity>=9.1.4
 Requires-Dist: pydantic-core>=2.41.5
+Requires-Dist: cachetools>=5.0,<6
 Requires-Dist: fastapi>=0.121.0,<0.122 ; extra == 'fastapi'
 Requires-Dist: starlette>=0.49.1 ; extra == 'fastapi'
 Requires-Dist: uvicorn>=0.37.0,<0.38 ; extra == 'fastapi'

{unique_toolkit-2026.22.0.dev13 → unique_toolkit-2026.24.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "2026.22.0.dev13"
+version = "2026.24.0"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12"
@@ -28,7 +28,7 @@ dependencies = [
     "openai>=1.105.0,<3",
     "platformdirs>=4.0.0,<5",
     "pillow>=12.1.1",
-    "unique-sdk>=2026.22.0.dev3,<2026.22.0rc0",
+    "unique-sdk>=2026.24.0",
     "jambo>=0.1.2,<0.2",
     "jinja2>=3.1.6,<4",
     "docxtpl>=0.20.1,<0.21",
@@ -43,6 +43,7 @@ dependencies = [
     "pypandoc>=1.16.2,<2",
     "tenacity>=9.1.4",
     "pydantic-core>=2.41.5",
+    "cachetools>=5.0,<6",
 ]
 
 [project.optional-dependencies]
@@ -60,7 +61,6 @@ fastapi = [
 monitoring = [
     "prometheus_client>=0.24.1,<1",
 ]
-
 [build-system]
 requires = ["uv_build>=0.8.14,<0.9.0"]
 build-backend = "uv_build"
@@ -69,13 +69,15 @@ build-backend = "uv_build"
 module-root = ""
 
 [dependency-groups]
-dev = []
+dev = [
+    "types-cachetools>=5.0,<6",
+]
 
 [tool.uv]
 exclude-newer = "2 weeks"
 constraint-dependencies = [
     "starlette>=0.49.1",
-    "lxml>=5.0.0",
+    "lxml>=6.1.0",
 ]
 
 [tool.uv.exclude-newer-package]

unique_toolkit-2026.24.0/unique_toolkit/__init__.py

@@ -0,0 +1,149 @@
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from unique_toolkit.chat import ChatService as ChatService
+    from unique_toolkit.content import ContentService as ContentService
+    from unique_toolkit.data_extraction import (
+        StructuredOutputDataExtractor as StructuredOutputDataExtractor,
+    )
+    from unique_toolkit.data_extraction import (
+        StructuredOutputDataExtractorConfig as StructuredOutputDataExtractorConfig,
+    )
+    from unique_toolkit.embedding import EmbeddingService as EmbeddingService
+    from unique_toolkit.framework_utilities.openai.client import (
+        get_async_openai_client as get_async_openai_client,
+    )
+    from unique_toolkit.framework_utilities.openai.client import (
+        get_openai_client as get_openai_client,
+    )
+    from unique_toolkit.language_model import (
+        LanguageModelMessages as LanguageModelMessages,
+    )
+    from unique_toolkit.language_model import LanguageModelName as LanguageModelName
+    from unique_toolkit.language_model import (
+        LanguageModelService as LanguageModelService,
+    )
+    from unique_toolkit.language_model import (
+        LanguageModelToolDescription as LanguageModelToolDescription,
+    )
+    from unique_toolkit.services.knowledge_base import (
+        KnowledgeBaseService as KnowledgeBaseService,
+    )
+    from unique_toolkit.short_term_memory import (
+        ShortTermMemoryService as ShortTermMemoryService,
+    )
+
+_EXPORTS: dict[str, tuple[str, str]] = {
+    "ChatService": ("unique_toolkit.chat", "ChatService"),
+    "ContentService": ("unique_toolkit.content", "ContentService"),
+    "EmbeddingService": ("unique_toolkit.embedding", "EmbeddingService"),
+    "get_openai_client": (
+        "unique_toolkit.framework_utilities.openai.client",
+        "get_openai_client",
+    ),
+    "get_async_openai_client": (
+        "unique_toolkit.framework_utilities.openai.client",
+        "get_async_openai_client",
+    ),
+    "KnowledgeBaseService": (
+        "unique_toolkit.services.knowledge_base",
+        "KnowledgeBaseService",
+    ),
+    "LanguageModelMessages": (
+        "unique_toolkit.language_model",
+        "LanguageModelMessages",
+    ),
+    "LanguageModelName": ("unique_toolkit.language_model", "LanguageModelName"),
+    "LanguageModelService": ("unique_toolkit.language_model", "LanguageModelService"),
+    "LanguageModelToolDescription": (
+        "unique_toolkit.language_model",
+        "LanguageModelToolDescription",
+    ),
+    "ShortTermMemoryService": (
+        "unique_toolkit.short_term_memory",
+        "ShortTermMemoryService",
+    ),
+    "StructuredOutputDataExtractor": (
+        "unique_toolkit.data_extraction",
+        "StructuredOutputDataExtractor",
+    ),
+    "StructuredOutputDataExtractorConfig": (
+        "unique_toolkit.data_extraction",
+        "StructuredOutputDataExtractorConfig",
+    ),
+}
+
+# Conditionally import config_checker (requires pydantic-settings)
+_CONFIG_CHECKER_AVAILABLE: bool = False
+try:
+    from unique_toolkit._common.config_checker import (
+        ConfigDiffer,  # noqa: F401, I001
+        ConfigEntry,  # noqa: F401, I001
+        ConfigExporter,  # noqa: F401, I001
+        ConfigRegistry,  # noqa: F401, I001
+        ConfigValidator,  # noqa: F401, I001
+        DefaultChangeReport,  # noqa: F401, I001
+        ExportManifest,  # noqa: F401, I001
+        ValidationReport,  # noqa: F401, I001
+        register_config,  # noqa: F401, I001
+    )
+
+    _CONFIG_CHECKER_AVAILABLE = True  # pyright: ignore[reportConstantRedefinition]
+except ImportError:
+    pass
+
+# Conditionally import langchain utilities if langchain is installed
+_LANGCHAIN_AVAILABLE: bool = False
+try:
+    from unique_toolkit.framework_utilities.langchain.client import get_langchain_client  # noqa: F401, I001
+
+    _LANGCHAIN_AVAILABLE = True  # pyright: ignore[reportConstantRedefinition]
+except ImportError:
+    pass
+
+# You can add other classes you frequently use here as well
+
+__all__ = [
+    "ChatService",
+    "ContentService",
+    "EmbeddingService",
+    "get_openai_client",
+    "get_async_openai_client",
+    "KnowledgeBaseService",
+    "LanguageModelMessages",
+    "LanguageModelName",
+    "LanguageModelService",
+    "LanguageModelToolDescription",
+    "ShortTermMemoryService",
+    "StructuredOutputDataExtractor",
+    "StructuredOutputDataExtractorConfig",
+]
+
+# Add config_checker exports if available
+if _CONFIG_CHECKER_AVAILABLE:
+    __all__.extend(
+        [
+            "ConfigDiffer",
+            "ConfigEntry",
+            "ConfigExporter",
+            "ConfigRegistry",
+            "ConfigValidator",
+            "DefaultChangeReport",
+            "ExportManifest",
+            "ValidationReport",
+            "register_config",
+        ]
+    )
+# Add langchain-specific exports if available
+if _LANGCHAIN_AVAILABLE:
+    __all__.append("get_langchain_client")
+
+
+def __getattr__(name: str) -> Any:
+    export = _EXPORTS.get(name)
+    if export is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module_name, attribute_name = export
+    return getattr(import_module(module_name), attribute_name)

{unique_toolkit-2026.22.0.dev13 → unique_toolkit-2026.24.0}/unique_toolkit/_common/metadata_filter_scope.py

@@ -8,6 +8,8 @@ from typing import Any
 from unique_toolkit.content.smart_rules import (
     Operator,
     Statement,
+    UniqueQL,
+    uniqueql_to_dict,
 )
 
 _UQL_AND = "and"
@@ -29,16 +31,17 @@ def build_folder_id_in_clause(scope_ids: list[str]) -> dict[str, Any]:
 
 def merge_scope_clause_into_metadata_filter(
     scope_clause: Mapping[str, Any],
-    metadata_filter: dict[str, Any] | None,
+    metadata_filter: UniqueQL | Mapping[str, Any] | None,
 ) -> dict[str, Any]:
     """AND-merge *scope_clause* with *metadata_filter*, flattening a top-level ``and``."""
     scope_dict = dict(scope_clause)
-    if not metadata_filter:
+    metadata_dict = uniqueql_to_dict(metadata_filter)
+    if not metadata_dict:
         return scope_dict
-    inner_and = metadata_filter.get(_UQL_AND)
+    inner_and = metadata_dict.get(_UQL_AND)
     if isinstance(inner_and, list):
         return {_UQL_AND: [scope_dict, *inner_and]}
-    return {_UQL_AND: [scope_dict, dict(metadata_filter)]}
+    return {_UQL_AND: [scope_dict, metadata_dict]}
 
 
 __all__ = [

{unique_toolkit-2026.22.0.dev13 → unique_toolkit-2026.24.0}/unique_toolkit/_common/pydantic/rjsf_tags.py

@@ -974,7 +974,12 @@ def ui_schema_for_model(
             node["items"] = item_node
 
         # Dict -> additionalProperties (value side)
-        elif origin is dict:
+        # Skip when the node already carries a ui:widget (fully-specified
+        # widget) or an anyOf (fully-specified type branching): walking the
+        # dict value type in those cases adds a spurious "additionalProperties"
+        # node that confuses RJSF renderers.  Presentation-only meta such as
+        # ui:expandable or ui:title does NOT prevent the walk.
+        elif origin is dict and "ui:widget" not in node and "anyOf" not in node:
             _key_t, val_t = get_args(base) or (Any, Any)
             val_base, val_meta = _walk_annotated_chain(val_t)
             val_base = _unwrap_optional(val_base)

unique_toolkit-2026.24.0/unique_toolkit/agentic/tools/a2a/config.py

@@ -0,0 +1,41 @@
+import logging
+from typing import Self
+
+from pydantic import Field, model_validator
+
+from unique_toolkit.agentic.tools.a2a.evaluation import SubAgentEvaluationConfig
+from unique_toolkit.agentic.tools.a2a.postprocessing import (
+    SubAgentDisplayConfig,
+    SubAgentResponseDisplayMode,
+)
+from unique_toolkit.agentic.tools.a2a.tool import SubAgentToolConfig
+
+_LOGGER = logging.getLogger(__name__)
+
+
+# SubAgentToolConfig with display and evaluation configs
+class ExtendedSubAgentToolConfig(SubAgentToolConfig):
+    response_display_config: SubAgentDisplayConfig = Field(
+        default_factory=SubAgentDisplayConfig,
+        description="Configuration for how to display the sub-agent response.",
+    )
+    evaluation_config: SubAgentEvaluationConfig = Field(
+        default_factory=SubAgentEvaluationConfig,
+        description="Configuration for handling assessments of the sub-agent response.",
+    )
+
+    @model_validator(mode="after")
+    def _ensure_response_display_config_off_when_sub_agent_response_passthrough(
+        self,
+    ) -> Self:
+        if (
+            self.passthrough_config.enabled
+            and self.response_display_config.mode != SubAgentResponseDisplayMode.HIDDEN
+        ):
+            _LOGGER.warning(
+                "SubAgent (assistant_id=%r): `passthrough_config.enabled=True` but `response_display_config.mode` is not HIDDEN. "
+                "Overriding `response_display_config.mode` to HIDDEN.",
+                self.assistant_id,
+            )
+            self.response_display_config.mode = SubAgentResponseDisplayMode.HIDDEN
+        return self

unique_toolkit-2026.24.0/unique_toolkit/agentic/tools/a2a/tool/__init__.py

@@ -0,0 +1,7 @@
+from unique_toolkit.agentic.tools.a2a.tool.config import (
+    SubAgentPassthroughConfig,
+    SubAgentToolConfig,
+)
+from unique_toolkit.agentic.tools.a2a.tool.service import SubAgentTool
+
+__all__ = ["SubAgentPassthroughConfig", "SubAgentTool", "SubAgentToolConfig"]

{unique_toolkit-2026.22.0.dev13 → unique_toolkit-2026.24.0}/unique_toolkit/agentic/tools/a2a/tool/config.py

@@ -1,8 +1,9 @@
+import logging
 import re
 from enum import StrEnum
-from typing import Annotated, Generic, Literal, TypeVar
+from typing import Annotated, Generic, Literal, Self, TypeVar
 
-from pydantic import Field, field_validator
+from pydantic import Field, field_validator, model_validator
 from pydantic.main import BaseModel
 
 from unique_toolkit._common.pydantic.rjsf_tags import RJSFMetaTag
@@ -26,6 +27,9 @@ class SystemReminderConfig(BaseModel, Generic[T]):
     type: T
 
 
+_LOGGER = logging.getLogger(__name__)
+
+
 _SYSTEM_REMINDER_FIELD_DESCRIPTION = """
 The reminder to add to the tool response. The reminder can be a Jinja template and can contain the following placeholders:
 - {{ display_name }}: The display name of the sub agent.
@@ -103,6 +107,19 @@ This is the message that will be sent to the sub-agent.
 """.strip()
 
 
+class SubAgentPassthroughConfig(BaseModel):
+    model_config = get_configuration_dict()
+
+    enabled: bool = Field(
+        default=False,
+        description="If set, this sub agent's response will be directly displayed to the user once the agent is called, ending the orchestrator loop.",
+    )
+    include_assessments: bool = Field(
+        default=True,
+        description="If set, this sub agent's assessments will be added to the main agent response.",
+    )
+
+
 class SubAgentToolConfig(BaseToolConfig):
     model_config = get_configuration_dict()
 
@@ -171,10 +188,12 @@ class SubAgentToolConfig(BaseToolConfig):
     poll_interval: Annotated[float, RJSFMetaTag.NumberWidget.updown()] = Field(
         default=1.0,
         description="Time interval in seconds between polling attempts when waiting for sub-agent response.",
+        gt=0,
     )
     max_wait: Annotated[float, RJSFMetaTag.NumberWidget.updown()] = Field(
         default=120.0,
         description="Maximum time in seconds to wait for the sub-agent response before timing out.",
+        gt=0,
     )
     stop_condition: Literal["stoppedStreamingAt", "completedAt"] = Field(
         default="completedAt",
@@ -197,6 +216,11 @@ class SubAgentToolConfig(BaseToolConfig):
         default=False,
         description="If set, the sub-agent response will be interpreted as a list of content chunks.",
     )
+    passthrough_config: SubAgentPassthroughConfig = Field(
+        default_factory=SubAgentPassthroughConfig,
+        description="Configuration for streaming the sub-agent response directly back to the user.",
+        title="Direct Streaming Configuration (Experimental)",
+    )
 
     system_reminders_config: list[
         Annotated[
@@ -207,3 +231,28 @@ class SubAgentToolConfig(BaseToolConfig):
         default=[],
         description="Configuration for the system reminders to add to the tool response.",
     )
+
+    @model_validator(mode="after")
+    def _ensure_response_passthrough_and_returns_content_chunks_mutually_exclusive(
+        self,
+    ) -> Self:
+        if self.passthrough_config.enabled and self.returns_content_chunks:
+            raise ValueError(
+                f"SubAgent (assistant_id={self.assistant_id!r}): "
+                "`passthrough_config.enabled` and `returns_content_chunks` are mutually exclusive."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _ensure_use_sub_agent_references_off_when_tool_response_passthrough(
+        self,
+    ) -> Self:
+        if self.passthrough_config.enabled and self.use_sub_agent_references:
+            _LOGGER.warning(
+                "SubAgent (assistant_id=%r): `passthrough_config.enabled=True` and `use_sub_agent_references=True`. "
+                "`use_sub_agent_references` will be overridden to False.",
+                self.assistant_id,
+            )
+            self.use_sub_agent_references = False
+
+        return self

{unique_toolkit-2026.22.0.dev13 → unique_toolkit-2026.24.0}/unique_toolkit/agentic/tools/a2a/tool/service.py

@@ -11,6 +11,7 @@ from pydantic import Field, TypeAdapter, create_model
 from unique_sdk.api_resources._space import Space
 from unique_sdk.utils.chat_in_space import send_message_and_wait_for_completion
 
+from unique_toolkit._common.execution import SafeTaskExecutor
 from unique_toolkit._common.referencing import (
     get_all_ref_numbers,
     get_detection_pattern_for_ref,
@@ -41,9 +42,15 @@ from unique_toolkit.agentic.tools.tool_progress_reporter import (
     ToolProgressReporter,
 )
 from unique_toolkit.app import ChatEvent
-from unique_toolkit.chat.schemas import MessageLog, MessageLogStatus
+from unique_toolkit.chat.schemas import (
+    ChatMessageAssessmentLabel,
+    ChatMessageAssessmentStatus,
+    ChatMessageAssessmentType,
+    MessageLog,
+    MessageLogStatus,
+)
 from unique_toolkit.chat.service import ChatService
-from unique_toolkit.content import ContentChunk
+from unique_toolkit.content import ContentChunk, ContentReference
 from unique_toolkit.language_model import (
     LanguageModelFunction,
     LanguageModelToolDescription,
@@ -146,6 +153,10 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
     def tool_format_information_for_user_prompt(self) -> str:
         return self.config.tool_format_information_for_user_prompt
 
+    @override
+    def takes_control(self) -> bool:
+        return self.config.passthrough_config.enabled
+
     @override
     def evaluation_check_list(self) -> list[EvaluationMetricName]:
         return [EvaluationMetricName.SUB_AGENT] if self._should_run_evaluation else []
@@ -215,6 +226,7 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
                 self._should_run_evaluation |= (
                     response["assessment"] is not None
                     and len(response["assessment"]) > 0
+                    and not self.config.passthrough_config.enabled
                 )  # Run evaluation if any sub agent returned an assessment
 
                 self._notify_watcher(response, sequence_number, timestamp)
@@ -273,6 +285,9 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
                     active_message_log=active_message_log,
                 )
 
+                if self.config.passthrough_config.enabled:
+                    await self._display_sub_agent_response(response)
+
                 return ToolCallResponse(
                     id=tool_call.id,
                     name=tool_call.name,
@@ -303,6 +318,68 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
             )
             raise e
 
+    async def _display_sub_agent_response(self, response: Space.Message) -> None:
+        await self._publish_sub_agent_response(response, set_completed_at=True)
+
+        if self.config.passthrough_config.include_assessments:
+            await self._forward_sub_agent_assessments(response["assessment"] or [])
+
+    async def _publish_sub_agent_response(
+        self,
+        response: Space.Message,
+        *,
+        set_completed_at: bool,
+    ) -> None:
+        await self._chat_service.modify_assistant_message_async(
+            content=response["text"],
+            original_content=response["originalText"],
+            references=[
+                ContentReference.from_sdk_reference(ref)
+                for ref in response["references"] or []
+            ],
+            set_completed_at=set_completed_at,
+        )
+
+    async def _publish_sub_agent_response_update(
+        self,
+        response: Space.Message,
+    ) -> None:
+        try:
+            await self._publish_sub_agent_response(response, set_completed_at=False)
+        except Exception:
+            logger.warning(
+                "Failed to publish streaming sub agent passthrough update",
+                exc_info=True,
+            )
+
+    async def _forward_sub_agent_assessments(
+        self,
+        assessments: list[unique_sdk.Space.Assessment],
+    ) -> None:
+        async def _create_one_assessment(
+            assessment: unique_sdk.Space.Assessment,
+        ) -> None:
+            await self._chat_service.create_message_assessment_async(
+                assistant_message_id=self._chat_service._assistant_message_id,
+                status=ChatMessageAssessmentStatus(assessment["status"]),
+                type=ChatMessageAssessmentType(assessment["type"]),
+                title=assessment["title"],
+                explanation=assessment["explanation"],
+                label=ChatMessageAssessmentLabel(assessment["label"]),
+                is_visible=assessment["isVisible"],
+            )
+
+        if not assessments:
+            return
+
+        task_executor = SafeTaskExecutor(logger=logger)
+        await asyncio.gather(
+            *(
+                task_executor.execute_async(_create_one_assessment, a)
+                for a in assessments
+            ),
+        )
+
     async def _get_chat_id(self) -> str | None:
         if not self.config.reuse_chat:
             return None
@@ -388,6 +465,12 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
         active_message_log: MessageLog | None = None,
     ) -> unique_sdk.Space.Message:
         try:
+            on_message_update = (
+                self._publish_sub_agent_response_update
+                if self.config.passthrough_config.enabled
+                else None
+            )
+
             return await send_message_and_wait_for_completion(
                 user_id=self._user_id,
                 assistant_id=self.config.assistant_id,
@@ -403,6 +486,7 @@ class SubAgentTool(Tool[SubAgentToolConfig]):
                     parentChatId=self._event.payload.chat_id,
                     parentAssistantId=self.config.assistant_id,
                 ),
+                on_message_update=on_message_update,
             )
         except TimeoutError as e:
             await self._notify_progress(

{unique_toolkit-2026.22.0.dev13 → unique_toolkit-2026.24.0}/unique_toolkit/agentic/tools/openai_builtin/code_interpreter/config.py

@@ -147,6 +147,7 @@ HTML files — CRITICAL rules:
     - The main content container MUST have a bounded, measurable height. For charts/dashboards either (a) give the chart container an explicit pixel height (e.g. `height: 500px`) or (b) use `aspect-ratio` together with a `width` so height is derived. Do NOT leave the top-level container with no intrinsic height.
     - Do NOT use `position: fixed` or `position: absolute` on top-level layout elements — they remove the element from the flow and the iframe cannot measure it.
     - Plotly users — CRITICAL: Plotly's `fig.write_html(...)` / `fig.to_html(...)` defaults emit a `<div class="plotly-graph-div" style="height:100%; width:100%;">` with no wrapper height (iframe collapse) **and** inline the entire Plotly JS bundle (~3MB), which often fails KB upload. You MUST pass `include_plotlyjs="cdn"`, `full_html=True`, and `default_height` (and `default_width` when relevant). Example: `fig.write_html(path, full_html=True, include_plotlyjs="cdn", default_height="600px")`. If you hand-write the wrapper HTML around a Plotly div, wrap the `plotly-graph-div` in a container with an explicit pixel height and never leave the graph div at `height:100%`.
+    - Plotly header overlap — CRITICAL: When a chart combines a horizontal legend positioned above the axes (`legend.y > 1`), range-selector buttons (`rangeselector`), and subplot title annotations, all three compete for the same top region and will overlap unless you reserve enough space. Rules: (1) set `fig.update_layout(margin=dict(t=150))` (or more) whenever any two of those elements coexist; (2) place a horizontal legend at `y=1.15` or higher (not `y=1.0`–`1.05`) so it clears the range-selector row; (3) for annotation-based subplot titles use `y` values ≥ 0.05 above the legend's `y` value; (4) if a chart also has range-sliders at the bottom, add sufficient bottom margin (`margin.b ≥ 80`) to avoid clipping the slider. Never rely on Plotly's default top margin of 80 px when the header contains more than a single title.
     - Single-chart HTML files — always add an outer wrapper with an explicit `height` (e.g. `<div style="height:600px">…chart…</div>`) so the document has a non-zero intrinsic height, even if the chart library defaults to percentage sizing.
   - Apply clean, readable typography: prefer system fonts (`-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif`) and sufficient contrast (WCAG AA minimum).
   - Use semantic HTML elements (`<table>` for tabular data, `<button>` for actions, `<h1>`–`<h6>` for headings, `alt` attributes on `<img>` tags). Avoid using `<div>` for everything.
@@ -160,6 +161,7 @@ Handling User Queries:
 - Whenever the user query requires using the python tool, you must always think first about the steps required.
 - CRITICAL: If any step generates a plot or visualization as a PNG, use **matplotlib** — that code block MUST include `plt.savefig('/mnt/data/<filename>.png', bbox_inches='tight')` and `plt.close()` as the final lines. Code that only calls `plt.show()` without saving will NOT display the image to the user.
 - CRITICAL: NEVER reference a `sandbox:/mnt/data/<filename>` link unless you have already executed code in this response that saved that exact file. Referencing a file that was not created by executed code will result in a broken link.
+  - Self-check before writing any sandbox link: look back at the code blocks you executed in this response. Is there a block that explicitly saves this exact filename to `/mnt/data/`? If not, execute the code first — then reference the file.
 - CRITICAL: The sandbox has NO internet access. NEVER use `requests`, `httpx`, `urllib`, or any other HTTP library to fetch data from the web — these calls will always fail. If the user's query requires live web data (e.g. market prices, news, APIs), you MUST retrieve it using the web search tool first and then pass the result into the code interpreter.
 - CRITICAL: For Excel files (`.xls`, `.xlsx`) and CSV files uploaded to the chat, ALWAYS use this tool to read and process them (e.g. `pandas.read_excel`, `pandas.read_csv`, `openpyxl`). Do NOT rely on the chat's text content or prior ingestion for spreadsheet data — the raw file contents are only accessible via code execution from `/mnt/data/<filename>`.
 - For calculation, retrieval, or exploratory-analysis answers, return the result concisely in the chat as markdown (key numbers inline, short tables where useful). Do NOT produce a separate artifact file (HTML, PDF, etc.) unless the user explicitly asked for a downloadable output or the request clearly calls for a dashboard/report.

{unique_toolkit-2026.22.0.dev13 → unique_toolkit-2026.24.0}/unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/generated_files.py

@@ -620,13 +620,16 @@ class DisplayCodeInterpreterFilesPostProcessor(
                 self._log.info("Fence injection modified the message text")
 
         _warn_missing_content_ids(loop_response.message.text or "", self._content_map)
+        ci_ran = bool(loop_response.code_interpreter_calls)
         loop_response.message.text, dangling_replaced = _replace_dangling_sandbox_links(
-            loop_response.message.text
+            loop_response.message.text, ci_ran=ci_ran
         )
         changed |= dangling_replaced
         if dangling_replaced:
             self._log.warning(
-                "apply_postprocessing found and replaced dangling sandbox links"
+                "apply_postprocessing found and replaced dangling sandbox links "
+                "(ci_ran=%s)",
+                ci_ran,
             )
 
         apply_ms = (time.monotonic() - apply_t0) * 1000
@@ -1254,7 +1257,9 @@ _SANDBOX_MARKDOWN_LINK_RE = re.compile(r"!?\[.*?\]\(sandbox:/mnt/data/\S+?\)")
 _SANDBOX_FILENAME_RE = re.compile(r"sandbox:/mnt/data/([^)\s]+)")
 
 
-def _replace_dangling_sandbox_links(text: str) -> tuple[str, bool]:
+def _replace_dangling_sandbox_links(
+    text: str, *, ci_ran: bool = True
+) -> tuple[str, bool]:
     """Replace any remaining sandbox:/mnt/data/ markdown links with a per-file notice.
 
     A dangling link means either the LLM hallucinated a file reference (the sandbox
@@ -1263,6 +1268,12 @@ def _replace_dangling_sandbox_links(text: str) -> tuple[str, bool]:
     cases the user would see a broken link; this function replaces each such link with
     an actionable message that names the specific file, and logs a warning so the
     incident is visible in production logs.
+
+    Args:
+        text: The message text to scan for dangling sandbox links.
+        ci_ran: Whether the code interpreter was called at all this turn.  When
+            ``False`` the LLM emitted a sandbox link without invoking the tool
+            (hallucination); a more accurate message is shown to the user.
     """
     if not _SANDBOX_MARKDOWN_LINK_RE.search(text):
         return text, False
@@ -1271,11 +1282,17 @@ def _replace_dangling_sandbox_links(text: str) -> tuple[str, bool]:
         filename_match = _SANDBOX_FILENAME_RE.search(m.group())
         filename = filename_match.group(1) if filename_match else "the file"
         logger.warning(
-            "Dangling sandbox link found in final text: '%s'. "
-            "The file was either never uploaded or the link format did not match "
+            "Dangling sandbox link found in final text: '%s'. ci_ran=%s. "
+            "The file was either never generated or the link format did not match "
             "the expected pattern — replacing with per-file notice.",
             m.group(),
+            ci_ran,
         )
+        if not ci_ran:
+            return (
+                f"⚠️ The file *{filename}* was not generated. "
+                "Please ask me to create it."
+            )
         return f"⚠️ The file *{filename}* could not be retrieved. You can ask me to regenerate it."
 
     return _SANDBOX_MARKDOWN_LINK_RE.sub(_replacement, text), True