unique-sdk 2026.28.0.dev12__tar.gz → 2026.28.0.dev14__tar.gz

{unique_sdk-2026.28.0.dev12 → unique_sdk-2026.28.0.dev14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.28.0.dev12
+Version: 2026.28.0.dev14
 Summary: 
 Author: Martin Fadler, Konstantin Krauss, Andreas Hauri
 Author-email: Martin Fadler <martin.fadler@unique.ch>, Konstantin Krauss <konstantin@unique.ch>, Andreas Hauri <andreas@unique.ch>

{unique_sdk-2026.28.0.dev12 → unique_sdk-2026.28.0.dev14}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_sdk"
-version = "2026.28.0.dev12"
+version = "2026.28.0.dev14"
 description = ""
 readme = "README.md"
 license = { text = "MIT" }

{unique_sdk-2026.28.0.dev12 → unique_sdk-2026.28.0.dev14}/unique_sdk/cli/cli.py

@@ -53,10 +53,14 @@ from unique_sdk.cli.commands.scheduled_tasks import (
 )
 from unique_sdk.cli.commands.search import (
     cmd_search,
+    cmd_uploaded_search,
 )
 from unique_sdk.cli.commands.search import (
     is_error_output as _is_search_error_output,
 )
+from unique_sdk.cli.commands.search import (
+    is_uploaded_search_error_output as _is_uploaded_search_error_output,
+)
 from unique_sdk.cli.commands.subagent import cmd_subagent
 from unique_sdk.cli.commands.subagent import (
     is_error_output as _is_subagent_error_output,
@@ -739,6 +743,43 @@ def search(
         ctx.exit(1)
 
 
+@main.command(name="uploaded-search")
+@click.argument("query")
+@click.option(
+    "--limit",
+    "-l",
+    default=200,
+    show_default=True,
+    help="Maximum number of results to return.",
+)
+@click.pass_context
+def uploaded_search(
+    ctx: click.Context,
+    query: str,
+    limit: int,
+) -> None:
+    """Search the documents uploaded for this task (not the knowledge base).
+
+    \b
+    QUERY is the search text. This searches only the files attached to this
+    row/task (e.g. an Agentic Table row's uploaded documents), which are NOT
+    part of the knowledge-base folder scope and therefore never appear in
+    `unique-cli search`. Results are ranked the same way and cite as
+    `[sourceN]`, with numbering continuous across `search` and
+    `uploaded-search` within a turn.
+
+    \b
+    Examples:
+      unique-cli uploaded-search "target asset classes"
+      unique-cli uploaded-search "fee structure" --limit 50
+    """
+    state = LazyState.get(ctx)
+    output = cmd_uploaded_search(state, query, limit=limit)
+    click.echo(output)
+    if _is_uploaded_search_error_output(output):
+        ctx.exit(1)
+
+
 @main.command()
 @click.argument("payload", required=False, default=None)
 @click.option(

{unique_sdk-2026.28.0.dev12 → unique_sdk-2026.28.0.dev14}/unique_sdk/cli/commands/files.py

@@ -358,7 +358,7 @@ def cmd_upload(
         ).get("folderPath", scope_id)
         return f"Uploaded: {display_name} ({content_id}) to {folder_path}"
 
-    except (ValueError, unique_sdk.APIError, OSError) as e:
+    except (ValueError, unique_sdk.UniqueError, OSError) as e:
         return f"upload: {e}"
 
 
@@ -384,7 +384,7 @@ def cmd_versions(
         )
         data = result.get("data", [])
         return f"Versions for {display_name} ({content_id}):\n{_format_content_versions(data)}"
-    except (ValueError, unique_sdk.APIError) as e:
+    except (ValueError, unique_sdk.UniqueError) as e:
         return f"versions: {e}"
 
 
@@ -414,7 +414,7 @@ def cmd_restore_version(state: ShellState, content_version_id: str) -> str:
         title = result.get("title") or result.get("key") or result.get("id", "?")
         content_id = result.get("id", "?")
         return f"Restored: {title} ({content_id}) from version {content_version_id}"
-    except (ValueError, unique_sdk.APIError) as e:
+    except (ValueError, unique_sdk.UniqueError) as e:
         return f"restore-version: {e}"
 
 
@@ -449,7 +449,7 @@ def cmd_download(
         shutil.move(str(downloaded_path), str(final_dest))
         return f"Downloaded: {display_name} -> {final_dest}"
 
-    except (ValueError, unique_sdk.APIError, OSError) as e:
+    except (ValueError, unique_sdk.UniqueError, OSError) as e:
         return f"download: {e}"
 
 
@@ -468,7 +468,7 @@ def cmd_rm(state: ShellState, name_or_id: str) -> str:
             contentId=content_id,
         )
         return f"Deleted: {display_name} ({content_id})"
-    except (ValueError, unique_sdk.APIError) as e:
+    except (ValueError, unique_sdk.UniqueError) as e:
         return f"rm: {e}"
 
 
@@ -488,7 +488,7 @@ def cmd_mv_file(state: ShellState, old_name: str, new_name: str) -> str:
             title=new_name,
         )
         return f"Renamed: {display_name} -> {result.get('title', new_name)}\n{format_content_info(result)}"
-    except (ValueError, unique_sdk.APIError) as e:
+    except (ValueError, unique_sdk.UniqueError) as e:
         return f"mv: {e}"
 
 

{unique_sdk-2026.28.0.dev12 → unique_sdk-2026.28.0.dev14}/unique_sdk/cli/commands/folders.py

@@ -70,7 +70,7 @@ def cmd_mkdir(state: ShellState, name: str) -> str:
             last = created[-1]
             return f"Created: {full_path} ({last['id']})"
         return f"Created: {full_path}"
-    except (ValueError, unique_sdk.APIError) as e:
+    except (ValueError, unique_sdk.UniqueError) as e:
         return f"mkdir: {e}"
 
 
@@ -108,7 +108,7 @@ def cmd_rmdir(state: ShellState, target: str, recursive: bool = False) -> str:
                 recursive=recursive,
             )
             return f"Deleted folder: {target}"
-    except (ValueError, unique_sdk.APIError) as e:
+    except (ValueError, unique_sdk.UniqueError) as e:
         return f"rmdir: {e}"
 
 
@@ -145,5 +145,5 @@ def cmd_mvdir(state: ShellState, old_name: str, new_name: str) -> str:
                 name=new_name,
             )
         return f"Renamed folder -> {result.get('name', new_name)}\n{format_folder_info(result)}"
-    except (ValueError, unique_sdk.APIError) as e:
+    except (ValueError, unique_sdk.UniqueError) as e:
         return f"mvdir: {e}"

{unique_sdk-2026.28.0.dev12 → unique_sdk-2026.28.0.dev14}/unique_sdk/cli/commands/mcp.py

@@ -337,16 +337,25 @@ def _citation_footer(annotated: list[tuple[int, dict[str, Any]]]) -> str:
 
 
 def _append_mcp_output_manifest(
-    name: str, text: str, *, server_name: str | None = None
+    name: str,
+    text: str,
+    *,
+    server_name: str | None = None,
+    output_path: Path | None = None,
 ) -> None:
     """Best-effort append of one MCP tool result to the per-turn manifest.
 
     Never raises: a manifest failure must not change what the agent sees as
     the tool result. The groundedness check simply does not fire for this
     call when the write fails.
+
+    ``output_path`` is the full path of the ``mcp-output.jsonl`` manifest. It
+    defaults to ``Path.cwd() / .unique / mcp-output.jsonl`` so the CLI flow
+    (where cwd is the agent workspace) is unchanged; callers that run outside
+    the workspace cwd (e.g. the in-process tools-mode proxy) pass it explicitly.
     """
     try:
-        refs_log_path = Path.cwd() / _MCP_OUTPUT_LOG_RELATIVE_PATH
+        refs_log_path = output_path or (Path.cwd() / _MCP_OUTPUT_LOG_RELATIVE_PATH)
         _append_turn_refs_manifest_entry(
             refs_log_path,
             {
@@ -359,6 +368,47 @@ def _append_mcp_output_manifest(
         _LOGGER.warning("mcp: failed to append output manifest: %s", exc)
 
 
+def record_mcp_citations(
+    response: Any,
+    *,
+    tool_name: str,
+    server_name: str | None,
+    unique_dir: Path,
+    formatted_text: str,
+) -> str:
+    """Write both per-turn MCP manifests under ``unique_dir`` and return the
+    ``[mcpsourceN]`` citation footer for the agent.
+
+    Shared by the ``unique-cli mcp`` skills flow (``cmd_mcp``) and the
+    in-process tools-mode proxy in assistants-core, so both write identical
+    manifests and footers. ``unique_dir`` is the workspace ``.unique`` directory
+    (its filenames are joined directly here — do not pass the workspace root).
+
+    - ``response`` is the raw ``unique_sdk.MCP`` result, used for citation
+      extraction (titles from ``resource_link`` names / JSON bodies).
+    - ``formatted_text`` is the source text the model actually saw for this
+      tool result, recorded as the hallucination groundedness context.
+
+    Best-effort and never raises: the underlying manifest writers swallow their
+    own errors, and ``_annotate_mcp_results_for_citations`` owns the per-turn
+    file lock — this function must stay lock-free to avoid a same-process flock
+    self-deadlock.
+    """
+    _append_mcp_output_manifest(
+        tool_name,
+        formatted_text,
+        server_name=server_name,
+        output_path=unique_dir / _MCP_OUTPUT_LOG_RELATIVE_PATH.name,
+    )
+    annotated = _annotate_mcp_results_for_citations(
+        response,
+        tool_name=tool_name,
+        server_name=server_name,
+        refs_log_path=unique_dir / _MCP_REFS_LOG_RELATIVE_PATH.name,
+    )
+    return _citation_footer(annotated)
+
+
 def _read_payload(
     payload: str | None,
     file: str | None,
@@ -440,8 +490,11 @@ def cmd_mcp(
         formatted = f"mcp: formatter error ({fmt_exc}); raw response:\n{fallback}"
 
     server_name = _server_name_from_tool(name) or getattr(response, "mcpServerId", None)
-    _append_mcp_output_manifest(name, formatted, server_name=server_name)
-    annotated = _annotate_mcp_results_for_citations(
-        response, tool_name=name, server_name=server_name
+    footer = record_mcp_citations(
+        response,
+        tool_name=name,
+        server_name=server_name,
+        unique_dir=Path.cwd() / ".unique",
+        formatted_text=formatted,
     )
-    return formatted + _citation_footer(annotated)
+    return formatted + footer

{unique_sdk-2026.28.0.dev12 → unique_sdk-2026.28.0.dev14}/unique_sdk/cli/commands/navigation.py

@@ -19,7 +19,7 @@ def cmd_cd(state: ShellState, target: str) -> str:
     try:
         new_path = state.cd(target)
         return new_path
-    except (ValueError, unique_sdk.APIError) as e:
+    except (ValueError, unique_sdk.UniqueError) as e:
         return f"cd: {e}"
 
 
@@ -65,7 +65,7 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
                             scopeId=sid,
                         )
                     )
-                except unique_sdk.APIError:
+                except unique_sdk.UniqueError:
                     pass
             scoped_files: list[Any] = []
             for cid in content_ids:
@@ -86,7 +86,7 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
                     items = info.get("contentInfo", [])
                     if items:
                         scoped_files.append(items[0])
-                except unique_sdk.APIError:
+                except unique_sdk.UniqueError:
                     pass
             output = format_ls(scoped_folders, scoped_files)
             summary = (
@@ -107,7 +107,7 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
                         scopeId=ws_id,
                     )
                     folders.append(info)
-                except unique_sdk.APIError:
+                except unique_sdk.UniqueError:
                     pass
             output = format_ls(folders, [])
             summary = f"\n{len(folders)} folder(s), 0 file(s)"
@@ -161,5 +161,5 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
         summary = f"\n{total_folders} folder(s), {total_files} file(s)"
         return output + summary
 
-    except (ValueError, unique_sdk.APIError) as e:
+    except (ValueError, unique_sdk.UniqueError) as e:
         return f"ls: {e}"

{unique_sdk-2026.28.0.dev12 → unique_sdk-2026.28.0.dev14}/unique_sdk/cli/commands/read.py

@@ -110,7 +110,7 @@ def cmd_read(
             company_id=state.config.company_id,
             where={"id": {"equals": cont_id}},
         )
-    except unique_sdk.APIError as e:
+    except unique_sdk.UniqueError as e:
         return f"{READ_ERROR_PREFIX} {e}"
 
     if not results:

{unique_sdk-2026.28.0.dev12 → unique_sdk-2026.28.0.dev14}/unique_sdk/cli/commands/search.py

@@ -30,6 +30,7 @@ from unique_sdk.cli.state import ShellState
 DEFAULT_LIMIT = 200
 
 SEARCH_ERROR_PREFIX = "search:"
+UPLOADED_SEARCH_ERROR_PREFIX = "uploaded-search:"
 
 _REFS_LOG_RELATIVE_PATH = Path(".unique") / "kb-search-refs.jsonl"
 _LOCK_FILENAME = "kb-search-refs.lock"
@@ -272,7 +273,7 @@ def cmd_search(
             **search_params,
         )
 
-    except (ValueError, unique_sdk.APIError) as e:
+    except (ValueError, unique_sdk.UniqueError) as e:
         return f"{SEARCH_ERROR_PREFIX} {e}"
 
     log_path = refs_log_path or (Path.cwd() / _REFS_LOG_RELATIVE_PATH)
@@ -282,6 +283,69 @@ def cmd_search(
         return f"{SEARCH_ERROR_PREFIX} {exc}"
 
 
+def cmd_uploaded_search(
+    state: ShellState,
+    query: str,
+    limit: int = DEFAULT_LIMIT,
+    *,
+    refs_log_path: Path | None = None,
+) -> str:
+    """Search this task's per-row **uploaded** documents.
+
+    Uploaded files (e.g. an Agentic Table row's attached documents) live
+    outside the knowledge-base folder scopes, so the scope-bound
+    ``unique-cli search`` cannot return them. This mirrors the platform's
+    UploadedSearch tool: a chat-scoped ``Search.create`` (``chatOnly=True``)
+    over the owning chat and the selected content ids, both written by the
+    Swappable Intelligence runner to ``.unique-uploaded.json``. See UN-21780.
+
+    Results share the same per-turn ``<sourceN>`` manifest as
+    ``unique-cli search`` (``_format_results_with_citations`` appends under the
+    same lock), so ``[sourceN]`` citation numbering stays continuous across
+    both commands within a turn.
+
+    Args:
+        state: Shell state carrying user/company credentials and the uploaded
+            document scope loaded from ``.unique-uploaded.json``.
+        query: Search string.
+        limit: Maximum number of results.
+        refs_log_path: Override the per-turn citation manifest path — for
+            tests; production callers leave this ``None``.
+    """
+    if not state.uploaded_search_available:
+        return (
+            f"{UPLOADED_SEARCH_ERROR_PREFIX} no uploaded documents are "
+            "available for this task. Use `unique-cli search` for the "
+            "knowledge base."
+        )
+
+    try:
+        search_params: dict[str, Any] = {
+            "searchString": query,
+            "searchType": "COMBINED",
+            "chatOnly": True,
+            "limit": limit,
+        }
+        if state.uploaded_search_chat_id:
+            search_params["chatId"] = state.uploaded_search_chat_id
+        if state.uploaded_search_content_ids:
+            search_params["contentIds"] = state.uploaded_search_content_ids
+
+        results = unique_sdk.Search.create(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            **search_params,
+        )
+    except (ValueError, unique_sdk.UniqueError) as e:
+        return f"{UPLOADED_SEARCH_ERROR_PREFIX} {e}"
+
+    log_path = refs_log_path or (Path.cwd() / _REFS_LOG_RELATIVE_PATH)
+    try:
+        return _format_results_with_citations(results, refs_log_path=log_path)
+    except UnsafeRefsLogPathError as exc:
+        return f"{UPLOADED_SEARCH_ERROR_PREFIX} {exc}"
+
+
 def is_error_output(output: str) -> bool:
     """Return ``True`` when ``output`` is a CLI error message.
 
@@ -290,3 +354,8 @@ def is_error_output(output: str) -> bool:
     exit code without changing the existing string-returning contract.
     """
     return output.startswith(SEARCH_ERROR_PREFIX)
+
+
+def is_uploaded_search_error_output(output: str) -> bool:
+    """Return ``True`` when ``output`` is an ``uploaded-search`` error message."""
+    return output.startswith(UPLOADED_SEARCH_ERROR_PREFIX)

{unique_sdk-2026.28.0.dev12 → unique_sdk-2026.28.0.dev14}/unique_sdk/cli/skills/unique-cli-search/SKILL.md

@@ -7,7 +7,10 @@ description: >-
   platform. Use whenever the user asks to find, search, or query documents
   or content on Unique, including filtering by folder or metadata.
   Also covers `unique-cli read <cont_id>` for reading the full indexed text
-  of a document when its content ID is already known.
+  of a document when its content ID is already known, and
+  `unique-cli uploaded-search "<query>"` for searching documents uploaded for
+  the current task/row, which are NOT in the knowledge-base scope and never
+  appear in `unique-cli search`.
   NOTE: This search uses combined vector + full-text indexing. Excel
   (.xlsx/.xls), CSV (.csv), and image files are NOT full-text indexed,
   so they will not appear in search results. To locate these file types,
@@ -64,6 +67,9 @@ When no `--folder` is given:
 - If the task defines a scope (a per-message scope filter): that scope is the
   search boundary, regardless of the current directory. `cd`/cwd does **not**
   narrow further — only an explicit `--folder` ANDs an additional constraint.
+  **You do not need `--folder` here** — just run `unique-cli search "<query>"`.
+  Passing a folder *path* that isn't navigable to your user errors with
+  `Folder ... not found`; only narrow within the scope via a `scope_` id.
 - Otherwise, in interactive mode: searches within the current directory
 - Otherwise, at root `/`: searches the entire knowledge base
 
@@ -89,10 +95,43 @@ unique-cli search "audit" -m department=Legal -m year=2025
 unique-cli search "regulatory" -f /Legal -m year=2025 -l 50
 ```
 
+## Searching Uploaded Documents (`uploaded-search`)
+
+Documents **uploaded for the current task** (e.g. an Agentic Table row's
+attached files) are **not** part of the knowledge-base folder scope. They will
+**never** appear in `unique-cli search` results, no matter the folder or
+metadata filters — uploaded files are scoped to the chat, not to a KB folder.
+Use `uploaded-search` to retrieve them:
+
+```bash
+# Search the documents uploaded for this row/task
+unique-cli uploaded-search "target asset classes and investment strategy"
+
+# Limit results
+unique-cli uploaded-search "fee structure" --limit 50
+```
+
+When to use which:
+
+| You want to search… | Command |
+|---------------------|---------|
+| The knowledge base (folders the task scope grants) | `unique-cli search "<query>"` |
+| Documents uploaded for **this** row/task | `unique-cli uploaded-search "<query>"` |
+
+`uploaded-search` returns the same `<sourceN>...</sourceN>` blocks as `search`
+and shares the **same per-turn citation manifest**, so `[sourceN]` numbering is
+continuous across both commands within a turn — cite an uploaded-document fact
+exactly the same way (`[sourceN]`). If no documents were uploaded for the task,
+the command reports that and you should fall back to `unique-cli search`.
+
+> **Note:** there is no `--folder`/`--metadata` for `uploaded-search` — the set
+> of uploaded documents is fixed by what was attached to the task.
+
 ## Command Reference
 
 ```
 unique-cli search <query> [--folder <path|scope_id>] [--metadata <key=value>]... [--limit <N>]
+unique-cli uploaded-search <query> [--limit <N>]
 ```
 
 | Option | Short | Default | Description |

{unique_sdk-2026.28.0.dev12 → unique_sdk-2026.28.0.dev14}/unique_sdk/cli/state.py

@@ -12,6 +12,7 @@ from unique_sdk.cli.config import Config
 from unique_sdk.cli.metadata_filter import MetadataFilter
 
 _SEARCH_CONFIG_FILENAME = ".unique-search.json"
+_UPLOADED_CONFIG_FILENAME = ".unique-uploaded.json"
 _CHAT_FILES_MANIFEST_PATH = Path(".unique") / "chat-files.json"
 
 
@@ -27,6 +28,38 @@ def _load_search_config() -> dict[str, Any]:
     return data if isinstance(data, dict) else {}
 
 
+def _load_uploaded_config() -> dict[str, Any]:
+    """Load ``.unique-uploaded.json`` from the cwd, or ``{}`` when absent/invalid.
+
+    Written by the Swappable Intelligence runner when the task carries per-row
+    uploaded documents (an Agentic Table row's ``selectedUploadedFiles``). It
+    holds the chat that owns those uploads and their content ids so
+    ``unique-cli uploaded-search`` can reach them: uploaded files live outside
+    the knowledge-base folder scopes, so the scope-bound ``unique-cli search``
+    structurally cannot return them. See UN-21780.
+    """
+    config_path = Path.cwd() / _UPLOADED_CONFIG_FILENAME
+    if not config_path.is_file():
+        return {}
+    try:
+        data = json.loads(config_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _load_uploaded_content_ids(data: dict[str, Any]) -> list[str]:
+    content_ids = data.get("contentIds")
+    if isinstance(content_ids, list) and all(isinstance(c, str) for c in content_ids):
+        return content_ids
+    return []
+
+
+def _load_uploaded_chat_id(data: dict[str, Any]) -> str | None:
+    chat_id = data.get("chatId")
+    return chat_id if isinstance(chat_id, str) and chat_id else None
+
+
 def _load_workspace_scope_ids(data: dict[str, Any]) -> list[str]:
     scope_ids = data.get("scopeIds")
     if isinstance(scope_ids, list) and all(isinstance(s, str) for s in scope_ids):
@@ -100,6 +133,35 @@ class ShellState:
         self._workspace_metadata_filter: dict[str, Any] | None = None
         self._metadata_filter: MetadataFilter | None = None
         self.workspace_metadata_filter = _load_workspace_metadata_filter(_search_config)
+        # Per-row uploaded documents reachable via ``unique-cli uploaded-search``.
+        # Loaded from ``.unique-uploaded.json`` (written by the runner). The chat
+        # id is the chat that *owns* the uploads — for a subagent this is the
+        # parent chat — and is required for the chat-scoped uploaded search.
+        # See UN-21780.
+        _uploaded_config = _load_uploaded_config()
+        self.uploaded_search_chat_id: str | None = _load_uploaded_chat_id(
+            _uploaded_config
+        )
+        self.uploaded_search_content_ids: list[str] = _load_uploaded_content_ids(
+            _uploaded_config
+        )
+
+    @property
+    def uploaded_search_available(self) -> bool:
+        """True when this task has per-row uploaded documents to search.
+
+        Requires *both* a non-empty selected content-id set and the owning
+        chat id. The owning chat id alone is not enough: ``cmd_uploaded_search``
+        would then issue a ``chatOnly`` ``Search.create`` with no ``contentIds``
+        filter, silently widening scope from the row's selected files to *every*
+        upload in the chat. That degenerate state arises when the runner wrote
+        a ``.unique-uploaded.json`` whose ``contentIds`` were absent or
+        malformed (e.g. mixed types, rejected wholesale by
+        ``_load_uploaded_content_ids``) while the ``chatId`` still parsed — so
+        we treat it as "no uploaded scope" rather than "all chat uploads".
+        See UN-21780.
+        """
+        return bool(self.uploaded_search_content_ids and self.uploaded_search_chat_id)
 
     @property
     def workspace_metadata_filter(self) -> dict[str, Any] | None: