unique_toolkit 1.53.3__tar.gz → 1.54.0__tar.gz

{unique_toolkit-1.53.3 → unique_toolkit-1.54.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 1.53.3
+Version: 1.54.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>

{unique_toolkit-1.53.3 → unique_toolkit-1.54.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "1.53.3"
+version = "1.54.0"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12"

{unique_toolkit-1.53.3 → unique_toolkit-1.54.0}/unique_toolkit/agentic/tools/openai_builtin/code_interpreter/config.py

@@ -41,6 +41,48 @@ Always use a line break between the title and the markdown!
 - Only the following file types are allowed to be uploaded to the platform, anything else will FAIL: PDF, DOCX, XLSX, PPTX, CSV, HTML, MD, TXT, PNG, JPG, JPEG.
 - You MUST always use this syntax, otherwise the files will not be displayed in the chat.
 
+# Displaying Dataframes/Tables:
+- Whenever asked to display a dataframe/table, it is CRITICAL to represent it faithfully as a markdown table in your response.
+
+Handling User Queries:
+- Whenever the user query requires using the python tool, you must always think first about the steps required.
+- Use the tool multiple times:
+    - You MUST NOT guess anything about the structure of the data / files uploaded. Rather, you MUST perform some data exploration first.
+        - Example: User uploads an excel files and asks a question about it. First Read the data, explore the columns, columns types, etc. Then use the tool to answer the user's query.
+        In this case, you can simply call the tool multiple times.
+        - REMEMBER that you can always read the content of text, csv files if needed. In this case, you MUST always limit the amount of data displayed.
+- If a tool step fails, you must recover as much as possible.
+- After exhausting all possible solutions without success, inform the user of what was tried and request clarification/help.
+""".strip()
+
+# Used when the code-execution fence feature flag (UN-17972) is enabled.
+# The frontend derives the artifact title from the filename itself, so the
+# LLM no longer needs to produce a markdown heading before the sandbox link.
+DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT_FENCE = """
+Use this tool to run python code, e.g to generate plots, process excel files, perform calculations, etc.
+
+Instructions:
+
+Uploaded and generated files:
+- All files uploaded to the chat are available at the path `/mnt/data/<filename>`.
+- All files generated through code MUST be saved in the `/mnt/data` folder.
+
+CRUCIAL Instructions for displaying images and files in the chat:
+- Once files are generated in the `/mnt/data` folder you MUST reference them in the chat using markdown syntax in order to display them in the chat.
+WHENEVER you reference a generated file, you MUST use the following format:
+```
+
+[*Generating your {Graph/Chart/File}…*](sandbox:/mnt/data/<filename>)
+
+```
+IMPORTANT: Do NOT append a leading `!` even when displaying an image.
+IMPORTANT: ALWAYS place a blank line before AND after each file reference link so it stands on its own paragraph. Never place a file reference inline within a sentence or as part of a list item.
+- Files are displayed as interactive components in the chat — images are shown inline, other files show the filename with an option to view the generating code and download the file.
+- Not using syntax above will FAIL to show files to the user.
+- YOU MUST use the syntax above to display files, otherwise the file will not be displayed in the chat.
+- Only the following file types are allowed to be uploaded to the platform, anything else will FAIL: PDF, DOCX, XLSX, PPTX, CSV, HTML, MD, TXT, PNG, JPG, JPEG.
+- You MUST always use this syntax, otherwise the files will not be displayed in the chat.
+
 
 # Displaying Dataframes/Tables:
 - Whenever asked to display a dataframe/table, it is CRITICAL to represent it faithfully as a markdown table in your response.

{unique_toolkit-1.53.3 → unique_toolkit-1.54.0}/unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/generated_files.py

@@ -194,10 +194,17 @@ class DisplayCodeInterpreterFilesPostProcessor(
 
             # Files (including HTML when feature flag is disabled)
             else:
+                fence_ff_on = (
+                    feature_flags.enable_code_execution_fence_un_17972.is_enabled(
+                        self._company_id
+                    )
+                )
                 loop_response.message.text, replaced = _replace_container_file_citation(
                     text=loop_response.message.text,
                     filename=filename,
                     content_id=content_id,
+                    ref_number=ref_number,
+                    use_content_link=fence_ff_on,
                 )
                 changed |= replaced
 
@@ -223,6 +230,7 @@ class DisplayCodeInterpreterFilesPostProcessor(
             self._company_id
         ):
             code_blocks = _build_code_blocks(loop_response, self._content_map)
+            _warn_unmatched_code_blocks(self._content_map, code_blocks)
             text_before = loop_response.message.text
             loop_response.message.text = _inject_code_execution_fences(
                 loop_response.message.text,
@@ -230,6 +238,12 @@ class DisplayCodeInterpreterFilesPostProcessor(
             )
             changed |= loop_response.message.text != text_before
 
+        _warn_missing_content_ids(loop_response.message.text, self._content_map)
+        loop_response.message.text, dangling_replaced = _replace_dangling_sandbox_links(
+            loop_response.message.text, self._config.file_download_failed_message
+        )
+        changed |= dangling_replaced
+
         return changed
 
     @override
@@ -395,6 +409,38 @@ def _inline_ref_pattern(file: CodeInterpreterFile) -> re.Pattern[str]:
     return re.compile(rf"\[{fname}\]\(unique://content/{cid}\)")
 
 
+_FENCE_BLOCK_START = re.compile(
+    r"^[^\n`]+?(````(?:imgWithSource|fileWithSource)\()",
+    re.MULTILINE,
+)
+
+# Matches two consecutive fence blocks and normalises the gap between them to
+# exactly one newline.  Two cases are handled:
+#   - same line: any non-newline, non-backtick content (e.g. " and ", ", ")
+#   - cross-line: 1 or 2 newlines optionally surrounded by horizontal whitespace
+#     (list-item linebreak, or blank-line paragraph gap)
+_CONSECUTIVE_FENCES_RE = re.compile(
+    r"(````(?:imgWithSource|fileWithSource)\([^\n]*\)````)"
+    r"(?:[^\n`]*|[ \t]*\n{1,2}[ \t]*)"
+    r"(?=````(?:imgWithSource|fileWithSource)\()"
+)
+
+
+def _ensure_fences_are_standalone(text: str) -> str:
+    """Strip any prefix text on the same line as a fence block.
+
+    The LLM sometimes puts file references inside list items or labels, e.g.:
+        - File: ````fileWithSource(...)````
+    After fence injection the label is left over. Strip it so the frontend
+    always receives the fence at the start of its own line, which is required
+    for correct parsing by the markdown renderer.
+
+    Only the prefix is removed; any trailing content after the closing `````
+    is preserved (it's unusual but not harmful).
+    """
+    return _FENCE_BLOCK_START.sub(r"\1", text)
+
+
 def _inject_code_execution_fences(
     text: str, code_blocks: list[CodeInterpreterBlock]
 ) -> str:
@@ -423,10 +469,20 @@ def _inject_code_execution_fences(
                 text = new_text
                 fence_id += 1
                 any_fence_injected = True
+            else:
+                logger.warning(
+                    "Fence injection skipped: no inline ref matched for '%s' "
+                    "(content_id=%s); fence discarded. "
+                    "The file was uploaded but will not appear in the message.",
+                    file.filename,
+                    file.content_id,
+                )
             # Remove duplicate refs (overwrite case)
             text = re.sub(pattern, "", text)
     if any_fence_injected:
         text = strip_executed_code_blocks(text)
+        text = _ensure_fences_are_standalone(text)
+        text = _CONSECUTIVE_FENCES_RE.sub(r"\1\n", text)
     return text
 
 
@@ -474,11 +530,90 @@ def _build_code_blocks(
         )
 
     # Step 3: build result preserving block execution order.
-    return [
-        CodeInterpreterBlock(code=calls[idx].code, files=list(files.values()))
-        for idx, files in sorted(block_file_map.items())
-        if calls[idx].code
-    ]
+    result: list[CodeInterpreterBlock] = []
+    for idx, files in sorted(block_file_map.items()):
+        code = calls[idx].code
+        if code is not None:
+            result.append(
+                CodeInterpreterBlock(code=code or "", files=list(files.values()))
+            )
+    return result
+
+
+def _warn_missing_content_ids(text: str, content_map: dict[str, str | None]) -> None:
+    """End-of-pipeline validation: warn for any uploaded file whose content_id is absent from text.
+
+    After all postprocessing stages have run every successfully uploaded file should
+    have its content_id referenced somewhere in the message text (either as a
+    unique://content/<id> link or embedded in a fence attribute).  A missing content_id
+    means the file was uploaded but the user will never see it.
+    """
+    for filename, content_id in content_map.items():
+        if content_id is None:
+            continue
+        if content_id not in text:
+            logger.info(
+                "End-of-pipeline check: content_id '%s' for file '%s' is not present "
+                "in the final message text — the file was uploaded but will not be "
+                "visible to the user.",
+                content_id,
+                filename,
+            )
+
+
+# Matches the full markdown link (including optional leading !) wrapping a sandbox URL,
+# so the entire `[label](sandbox://...)` token can be replaced rather than just the URL.
+_SANDBOX_MARKDOWN_LINK_RE = re.compile(r"!?\[.*?\]\(sandbox:/mnt/data/\S+?\)")
+
+
+def _replace_dangling_sandbox_links(text: str, error_message: str) -> tuple[str, bool]:
+    """Replace any remaining sandbox:/mnt/data/ markdown links with an error message.
+
+    A dangling link means either the LLM hallucinated a file reference (the sandbox
+    link appears in the text but no matching container file annotation was emitted by
+    OpenAI), or the link format did not match the expected regex in stage-1.  In both
+    cases the user would see a broken link; this function replaces each such link with
+    the configured error message and logs a warning so the incident is visible in logs.
+    """
+    matches = _SANDBOX_MARKDOWN_LINK_RE.findall(text)
+    if not matches:
+        return text, False
+    for match in matches:
+        logger.warning(
+            "Dangling sandbox link found in final text: '%s'. "
+            "The file was either never uploaded or the link format did not match "
+            "the expected pattern — replacing with error message.",
+            match,
+        )
+    return _SANDBOX_MARKDOWN_LINK_RE.sub(error_message, text), True
+
+
+def _warn_unmatched_code_blocks(
+    content_map: dict[str, str | None],
+    code_blocks: list[CodeInterpreterBlock],
+) -> None:
+    """Warn for files that were uploaded but could not be matched to any code block.
+
+    When the fence feature flag is on, every uploaded file should map to a code block
+    via its /mnt/data/<filename> path so it can receive a fence.  If a file is not
+    matched (e.g. the LLM used a variable for the output path rather than a literal
+    string) it falls back to a plain unique://content/ link with no code context.
+    The user can still download it, but the frontend artifact UI will not be shown.
+    """
+    fenced_filenames = {f.filename for block in code_blocks for f in block.files}
+    for filename, content_id in content_map.items():
+        if content_id is None:
+            continue
+        if filename not in fenced_filenames:
+            logger.warning(
+                "File '%s' (content_id=%s) could not be matched to any code block "
+                "(literal path '/mnt/data/%s' not found in executed code). "
+                "It will appear as a plain download link without code context — "
+                "consider re-running the query if the artifact UI is expected.",
+                filename,
+                content_id,
+                filename,
+            )
 
 
 def _get_next_ref_number(references: list[ContentReference]) -> int:
@@ -494,10 +629,14 @@ def _replace_container_file_error(
     image_markdown = rf"!?\[.*?\]\(sandbox:/mnt/data/{re.escape(filename)}\)"
 
     if not re.search(image_markdown, text):
-        logger.info("No image markdown found for %s", filename)
+        logger.warning(
+            "No sandbox link found for '%s'; file was uploaded but the LLM did not "
+            "reference it — it will not be displayed.",
+            filename,
+        )
         return text, False
 
-    logger.info("Displaying image %s", filename)
+    logger.info("Replacing failed download for '%s' with error message", filename)
     return re.sub(
         image_markdown,
         error_message,
@@ -511,10 +650,15 @@ def _replace_container_image_citation(
     image_markdown = rf"!?\[.*?\]\(sandbox:/mnt/data/{re.escape(filename)}\)"
 
     if not re.search(image_markdown, text):
-        logger.info("No image markdown found for %s", filename)
+        logger.warning(
+            "No sandbox link found for image '%s' (content_id=%s); "
+            "file was uploaded but the LLM did not reference it — it will not be displayed.",
+            filename,
+            content_id,
+        )
         return text, False
 
-    logger.info("Displaying image %s", filename)
+    logger.info("Inserting image citation for '%s'", filename)
     return re.sub(
         image_markdown,
         f"![image](unique://content/{content_id})",
@@ -528,10 +672,15 @@ def _replace_container_html_citation(
     html_markdown = rf"!?\[.*?\]\(sandbox:/mnt/data/{re.escape(filename)}\)"
 
     if not re.search(html_markdown, text):
-        logger.info("No HTML markdown found for %s", filename)
+        logger.warning(
+            "No sandbox link found for HTML file '%s' (content_id=%s); "
+            "file was uploaded but the LLM did not reference it — it will not be displayed.",
+            filename,
+            content_id,
+        )
         return text, False
 
-    logger.info("Displaying HTML %s", filename)
+    logger.info("Inserting HTML rendering block for '%s'", filename)
     html_rendering_block = f"""```HtmlRendering
 100%
 500px
@@ -547,17 +696,35 @@ unique://content/{content_id}
 
 
 def _replace_container_file_citation(
-    text: str, filename: str, content_id: str
+    text: str,
+    filename: str,
+    content_id: str,
+    ref_number: int,
+    use_content_link: bool,
 ) -> tuple[str, bool]:
+    """Replace a sandbox file link with either an inline content link or a superscript ref.
+
+    When the fence feature flag is on (use_content_link=True), the sandbox link is
+    replaced with [filename](unique://content/{id}) so the subsequent fence injection
+    step can locate and wrap it. When the flag is off (use_content_link=False), the
+    original pre-fence behaviour is restored: the link is replaced with <sup>N</sup>
+    and the file remains accessible via the references panel.
+    """
     file_markdown = rf"\[.*?\]\(sandbox:/mnt/data/{re.escape(filename)}\)"
 
     if not re.search(file_markdown, text):
-        logger.info("No file markdown found for %s", filename)
+        logger.warning(
+            "No sandbox link found for file '%s' (content_id=%s); "
+            "file was uploaded but the LLM did not reference it — it will not be displayed.",
+            filename,
+            content_id,
+        )
         return text, False
 
     logger.info("Displaying file %s", filename)
-    return re.sub(
-        file_markdown,
-        f"[{filename}](unique://content/{content_id})",
-        text,
-    ), True
+    replacement = (
+        f"[{filename}](unique://content/{content_id})"
+        if use_content_link
+        else f"<sup>{ref_number}</sup>"
+    )
+    return re.sub(file_markdown, replacement, text), True

{unique_toolkit-1.53.3 → unique_toolkit-1.54.0}/unique_toolkit/agentic/tools/openai_builtin/code_interpreter/service.py

@@ -5,6 +5,7 @@ from openai import AsyncOpenAI, BaseModel, NotFoundError
 from openai.types.responses.tool_param import CodeInterpreter
 
 from unique_toolkit import ContentService, ShortTermMemoryService
+from unique_toolkit.agentic.feature_flags.feature_flags import feature_flags
 from unique_toolkit.agentic.short_term_memory_manager.persistent_short_term_memory_manager import (
     PersistentShortMemoryManager,
 )
@@ -13,6 +14,8 @@ from unique_toolkit.agentic.tools.openai_builtin.base import (
     OpenAIBuiltInToolName,
 )
 from unique_toolkit.agentic.tools.openai_builtin.code_interpreter.config import (
+    DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT,
+    DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT_FENCE,
     OpenAICodeInterpreterConfig,
 )
 from unique_toolkit.agentic.tools.schemas import ToolPrompts
@@ -145,6 +148,7 @@ class OpenAICodeInterpreterTool(OpenAIBuiltInTool[CodeInterpreter]):
         self,
         config: OpenAICodeInterpreterConfig,
         container_id: str | None,
+        company_id: str = "",
         is_exclusive: bool = False,
     ) -> None:
         self._config = config
@@ -153,6 +157,7 @@ class OpenAICodeInterpreterTool(OpenAIBuiltInTool[CodeInterpreter]):
             raise ValueError("`container_id` required when not using `auto` containers")
 
         self._container_id = container_id
+        self._company_id = company_id
         self._is_exclusive = is_exclusive
 
     @property
@@ -196,7 +201,7 @@ class OpenAICodeInterpreterTool(OpenAIBuiltInTool[CodeInterpreter]):
     ) -> "OpenAICodeInterpreterTool":
         if config.use_auto_container:
             logger.info("Using `auto` container setting")
-            return cls(config=config, container_id=None)
+            return cls(config=config, container_id=None, company_id=company_id)
 
         memory_manager = _get_container_code_execution_short_term_memory_manager(
             company_id=company_id,
@@ -229,16 +234,36 @@ class OpenAICodeInterpreterTool(OpenAIBuiltInTool[CodeInterpreter]):
         assert memory.container_id is not None
 
         return OpenAICodeInterpreterTool(
-            config=config, container_id=memory.container_id, is_exclusive=is_exclusive
+            config=config,
+            container_id=memory.container_id,
+            company_id=company_id,
+            is_exclusive=is_exclusive,
         )
 
     @override
     def get_tool_prompts(self) -> ToolPrompts:
+        # When the fence feature flag is on the frontend derives the artifact title
+        # from the filename, so the LLM no longer needs to produce a markdown heading.
+        # We only substitute the fence-aware default when the operator has NOT
+        # customised the prompt — a custom value is always respected regardless of FF.
+        # When FF is off we always use the operator-configured prompt as-is.
+        fence_ff_on = feature_flags.enable_code_execution_fence_un_17972.is_enabled(
+            self._company_id
+        )
+        operator_customised = (
+            self._config.tool_description_for_system_prompt
+            != DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT
+        )
+        if fence_ff_on and not operator_customised:
+            system_prompt = DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT_FENCE
+        else:
+            system_prompt = self._config.tool_description_for_system_prompt
+
         return ToolPrompts(
             name="python",  # https://platform.openai.com/docs/guides/tools-code-interpreter
             display_name=self.DISPLAY_NAME,
             tool_description=self._config.tool_description,
-            tool_system_prompt=self._config.tool_description_for_system_prompt,
+            tool_system_prompt=system_prompt,
             tool_format_information_for_system_prompt="",
             tool_user_prompt=self._config.tool_description_for_user_prompt,
             tool_format_information_for_user_prompt="",