unique-sdk 2026.30.0.dev3__tar.gz → 2026.30.0.dev5__tar.gz

{unique_sdk-2026.30.0.dev3 → unique_sdk-2026.30.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.30.0.dev3
+Version: 2026.30.0.dev5
 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.30.0.dev3 → unique_sdk-2026.30.0.dev5}/pyproject.toml

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

{unique_sdk-2026.30.0.dev3 → unique_sdk-2026.30.0.dev5}/unique_sdk/cli/commands/mcp.py

@@ -45,6 +45,13 @@ _MCP_OUTPUT_TEXT_CHAR_LIMIT = 200_000
 _MCP_REFS_LOG_RELATIVE_PATH = Path(".unique") / "mcp-refs.jsonl"
 _MCP_REFS_LOCK_FILENAME = "mcp-refs.lock"
 _MCP_SNIPPET_CHAR_LIMIT = 300
+# Writer-side cap on the per-item ``text`` recorded in the refs manifest — the
+# cited item's underlying text, consumed by the runner's hallucination check to
+# ground each ``[mcpsourceN]`` citation on what was actually retrieved
+# (UN-22762). Half the flat-output cap (``_MCP_OUTPUT_TEXT_CHAR_LIMIT``): one
+# cited item (a page, an issue record) rarely exceeds it, and the eval side
+# bounds the combined cited-text payload separately.
+_MCP_REF_TEXT_CHAR_LIMIT = 100_000
 
 # Keys an MCP tool's JSON result commonly uses for a record's human title.
 _TITLE_KEYS = ("title", "name", "displayName", "subject", "summary", "key")
@@ -247,6 +254,7 @@ def _titles_from_json(text: str) -> list[dict[str, Any]]:
                     "title": title,
                     "snippet": None,
                     "details": _details_from_json(entry),
+                    "text": _record_text(entry),
                 }
             )
     return items
@@ -350,6 +358,31 @@ def _first_text_title(response: Any, max_chars: int) -> str | None:
     return None
 
 
+def _all_text_blocks(response: Any) -> str | None:
+    """Concatenation of every text block — the underlying text of a single-item
+    result (e.g. a fetched document) recorded as that item's ground truth."""
+    texts: list[str] = []
+    for block in getattr(response, "content", None) or []:
+        if not isinstance(block, dict) or block.get("type") != "text":
+            continue
+        text = block.get("text")
+        if isinstance(text, str) and text.strip():
+            texts.append(text)
+    return "\n\n".join(texts) or None
+
+
+def _record_text(record: Any) -> str | None:
+    """A record's underlying text for citation grounding: the record itself
+    when it is a plain string, else the serialized record — which carries the
+    titled field plus all metadata the agent may cite."""
+    if isinstance(record, str):
+        return record or None
+    try:
+        return json.dumps(record, ensure_ascii=False, default=str)
+    except (TypeError, ValueError):
+        return None
+
+
 def _extract_with_reference_mapping(
     response: Any, mapping: dict[str, Any]
 ) -> list[dict[str, Any]]:
@@ -409,6 +442,7 @@ def _extract_with_reference_mapping(
                 "title": title,
                 "snippet": None,
                 "details": str(details).strip() if details else None,
+                "text": _record_text(record),
             }
         )
     if items:
@@ -421,7 +455,14 @@ def _extract_with_reference_mapping(
     if not records and title_from_text:
         title = _first_text_title(response, title_max_chars)
         if title:
-            return [{"title": title, "snippet": None, "details": None}]
+            return [
+                {
+                    "title": title,
+                    "snippet": None,
+                    "details": None,
+                    "text": _all_text_blocks(response),
+                }
+            ]
     return items
 
 
@@ -431,8 +472,9 @@ def _extract_mcp_citation_items(
     tool_name: str,
     server_name: str | None,
     reference_mapping: dict[str, Any] | None = None,
+    fallback_text: str | None = None,
 ) -> list[dict[str, Any]]:
-    """Context for what the tool retrieved: ``{title, snippet}`` per item.
+    """Context for what the tool retrieved: ``{title, snippet, text}`` per item.
 
     An optional admin ``reference_mapping`` is applied first (deterministic
     destructuring of a list result); when it yields nothing we fall back to the
@@ -441,6 +483,12 @@ def _extract_mcp_citation_items(
     JSON-in-text). No URLs are extracted — the chip is display-only. Falls back
     to a single title-less item (the runner names it after the tool) when the
     result carries no recognizable title.
+
+    ``text`` is the item's underlying retrieved text (the serialized record, a
+    fetched document body, or — for the title-less fallback — ``fallback_text``,
+    the whole formatted output). The runner grounds the hallucination check for
+    each cited ``[mcpsourceN]`` on it. A ``resource_link`` carries no body, so
+    its ``text`` is the link description only.
     """
     if reference_mapping:
         mapped = _extract_with_reference_mapping(response, reference_mapping)
@@ -457,7 +505,11 @@ def _extract_mcp_citation_items(
             name = (block.get("name") or "").strip()
             if name:
                 items.append(
-                    {"title": name, "snippet": _snippet(block.get("description"))}
+                    {
+                        "title": name,
+                        "snippet": _snippet(block.get("description")),
+                        "text": block.get("description") or None,
+                    }
                 )
 
     if not items:
@@ -467,7 +519,7 @@ def _extract_mcp_citation_items(
 
     if not items:
         # No recognizable title — one chip named after the tool itself.
-        items.append({"title": None, "snippet": None})
+        items.append({"title": None, "snippet": None, "text": fallback_text})
 
     return items
 
@@ -489,6 +541,16 @@ def _item_dedup_key(tool_name: str, item: dict[str, Any]) -> str:
     return f"tool:{tool_name}"
 
 
+def _ref_text(item: dict[str, Any]) -> str | None:
+    """The item's underlying text for the manifest, capped at
+    ``_MCP_REF_TEXT_CHAR_LIMIT`` (single write-side cap shared by all
+    extraction modes)."""
+    text = item.get("text")
+    if not isinstance(text, str) or not text:
+        return None
+    return text[:_MCP_REF_TEXT_CHAR_LIMIT]
+
+
 def _annotate_mcp_results_for_citations(
     response: Any,
     *,
@@ -496,6 +558,7 @@ def _annotate_mcp_results_for_citations(
     server_name: str | None,
     refs_log_path: Path | None = None,
     reference_mapping: dict[str, Any] | None = None,
+    fallback_text: str | None = None,
 ) -> list[tuple[int, dict[str, Any]]]:
     """Assign per-turn ``[mcpsourceN]`` numbers to each retrieved item and append
     the refs manifest. Returns ``[(sourceNumber, item)]`` for the Sources block.
@@ -512,6 +575,7 @@ def _annotate_mcp_results_for_citations(
             tool_name=tool_name,
             server_name=server_name,
             reference_mapping=reference_mapping,
+            fallback_text=fallback_text,
         )
         with _locked_turn_refs_manifest(
             refs_log_path, lock_filename=_MCP_REFS_LOCK_FILENAME
@@ -542,6 +606,7 @@ def _annotate_mcp_results_for_citations(
                         "title": item.get("title"),
                         "snippet": item.get("snippet"),
                         "details": item.get("details"),
+                        "text": _ref_text(item),
                     }
                     try:
                         _append_turn_refs_manifest_entry(refs_log_path, manifest_entry)
@@ -563,13 +628,26 @@ def _annotate_mcp_results_for_citations(
                     if stored is not None and new_details and not stored.get("details"):
                         stored["details"] = new_details
                         needs_rewrite = True
+                    # ``text`` upgrades to the longer capture: the common turn
+                    # is a search (small per-record JSON) followed by a full
+                    # fetch of the same titled item — the later, richer text is
+                    # the better ground truth for the hallucination check.
+                    new_text = _ref_text(item)
+                    if stored is not None and new_text:
+                        stored_text = stored.get("text")
+                        stored_len = (
+                            len(stored_text) if isinstance(stored_text, str) else 0
+                        )
+                        if len(new_text) > stored_len:
+                            stored["text"] = new_text
+                            needs_rewrite = True
                 annotated.append((source_number, item))
             if needs_rewrite:
                 try:
                     _rewrite_turn_refs_manifest(refs_log_path, entries)
                 except (UnsafeRefsLogPathError, OSError) as exc:
                     _LOGGER.warning(
-                        "mcp: failed to backfill refs manifest details: %s", exc
+                        "mcp: failed to backfill refs manifest enrichment: %s", exc
                     )
     except (UnsafeRefsLogPathError, OSError) as exc:
         _LOGGER.warning("mcp: failed to append refs manifest: %s", exc)
@@ -656,7 +734,10 @@ def record_mcp_citations(
     - ``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.
+      tool result, recorded as the hallucination groundedness context. It also
+      serves as the per-item ``text`` of the title-less fallback chip, so a
+      cited ``[mcpsourceN]`` without extractable records still grounds on the
+      whole output.
 
     Best-effort and never raises: the underlying manifest writers swallow their
     own errors, and ``_annotate_mcp_results_for_citations`` owns the per-turn
@@ -675,6 +756,7 @@ def record_mcp_citations(
         server_name=server_name,
         refs_log_path=unique_dir / _MCP_REFS_LOG_RELATIVE_PATH.name,
         reference_mapping=reference_mapping,
+        fallback_text=formatted_text,
     )
     return _citation_sources_block(annotated)
 

{unique_sdk-2026.30.0.dev3 → unique_sdk-2026.30.0.dev5}/unique_sdk/cli/skills/unique-cli-search/SKILL.md

@@ -7,10 +7,7 @@ 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, 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`.
+  of a document when its content ID is already known.
   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,
@@ -95,43 +92,10 @@ 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.30.0.dev5/unique_sdk/cli/skills/unique-cli-uploaded-search/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: unique-cli-uploaded-search
+description: >-
+  Search the documents uploaded for the CURRENT task/row (e.g. an Agentic
+  Table row's attached files) via the `unique-cli uploaded-search "<query>"`
+  command, with the same per-turn citation tracking as `unique-cli search`
+  so cited facts render as `<sup>N</sup>` footnotes and clickable reference
+  chips on the Unique platform. ALWAYS use this skill when the user refers to
+  documents they uploaded/attached to this task, or when you need facts from
+  the task's own attached files. These uploaded files are scoped to the chat,
+  NOT to a knowledge-base folder, so they will NEVER appear in
+  `unique-cli search` results no matter the folder or metadata filters. Use
+  `unique-cli search` for the knowledge base and this command for the task's
+  uploaded documents; the two are complementary and citation numbering is
+  shared across them within a turn.
+---
+
+# Unique CLI -- Uploaded Document Search
+
+Documents **uploaded for the current task** (for example an Agentic Table
+row's attached files) are **not** part of the knowledge-base folder scope.
+They are scoped to the chat, so they will **never** appear in
+`unique-cli search` results — no folder or metadata filter can surface them.
+Use `unique-cli uploaded-search` to retrieve them.
+
+## Basic Usage
+
+```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
+```
+
+There is **no** `--folder`/`--metadata` for `uploaded-search` — the set of
+uploaded documents is fixed by what was attached to the task.
+
+If no documents were uploaded for this task, the command reports that and you
+should fall back to `unique-cli search` for the knowledge base.
+
+## When to use which command
+
+| 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>"` |
+
+## Output Format
+
+Each result is rendered as a `<sourceN>...</sourceN>` block, identical to
+`unique-cli search`. `N` is **1-based** and **shared with `unique-cli search`
+within the same turn** — both commands append to the same per-turn citation
+manifest, so numbering stays continuous across them (a `search` call that
+emitted `<source1>`–`<source3>` is followed by an `uploaded-search` call whose
+first result is `<source4>`).
+
+```
+Found 1 result(s):
+
+<source1>
+<|document|>investment-mandate.pdf</|document|>
+<|page|>2</|page|>
+<|info|>cont_abc123</|info|>
+...the mandate targets EMEA equities with a 5% cap per issuer...
+</source1>
+```
+
+## Citation Rules
+
+Cite a fact from `uploaded-search` results with `[sourceN]`, **exactly** as you
+would for `unique-cli search` — the two share the same namespace and manifest.
+The Unique platform converts each `[sourceN]` marker in your final answer into a
+`<sup>N</sup>` footnote and a clickable reference chip.
+
+```
+The uploaded mandate caps single-issuer exposure at 5% [source1].
+```
+
+**Rules** (enforced by the platform's reference post-processor):
+
+1. **`[sourceN]` is for KB and uploaded-document results.** Web results from
+   `unique-cli web-search` use `[websourceN]` — never mix the two namespaces.
+2. Only cite numbers you saw in the **current** turn's `search` /
+   `uploaded-search` output. Numbers from previous turns are stale and will be
+   silently dropped.
+3. Write `source` in singular form with the number in digits: `[source1]`,
+   `[source2]` — not `[Source 1]` or `[source one]`.
+4. Prefer citing each fact with a single, most-relevant source.
+5. Do not invent source numbers for remembered or inferred facts.
+
+## Command Reference
+
+```
+unique-cli uploaded-search <query> [--limit <N>]
+```
+
+| Option | Short | Default | Description |
+|--------|-------|---------|-------------|
+| `--limit` | `-l` | 200 | Max results |
+
+## Prerequisites
+
+Requires these environment variables:
+
+```bash
+UNIQUE_USER_ID    # User ID (required)
+UNIQUE_COMPANY_ID # Company ID (required)
+UNIQUE_API_KEY    # API key — optional on localhost / secured cluster
+UNIQUE_APP_ID     # App ID — optional on localhost / secured cluster
+```
+
+Install: `pip install unique-sdk`

{unique_sdk-2026.30.0.dev3 → unique_sdk-2026.30.0.dev5}/unique_sdk/cli/state.py

@@ -263,6 +263,14 @@ class ShellState:
         """Return True if *content_id* is in the current workspace scope.
 
         Precedence (UN-21780):
+        0. Per-row uploaded documents (``.unique-uploaded.json``) surfaced by
+           ``unique-cli uploaded-search`` are task inputs that live *outside* the
+           KB scope boundary by design, so neither the metadata filter nor the
+           static ``scopeIds`` path below would admit them. Exempt them for
+           non-destructive access so the agent can ``read``/``ls``/``cite`` a doc
+           it just found via uploaded-search — mirroring the chat-file exemption.
+           Mutating ops (``rm``/``mv``) pass ``allow_chat_files=False`` and stay
+           denied, so an uploaded input can't be deleted or renamed this way.
         1. A per-message UniqueQL ``metaDataFilter`` (e.g. an Agentic Table
            column's ``scope_rules``) is the authority for this turn and
            *replaces* the static ``scopeIds`` for content access. Files the
@@ -275,6 +283,8 @@ class ShellState:
            ``is_folder_target_within_workspace``).
         3. With neither configured, everything is in scope.
         """
+        if allow_chat_files and content_id in self.uploaded_search_content_ids:
+            return True
         if self.workspace_metadata_filter is not None:
             if allow_chat_files and content_id in self._chat_file_content_ids():
                 return True