unique-sdk 2026.44.0.dev5__tar.gz → 2026.44.0.dev7__tar.gz

{unique_sdk-2026.44.0.dev5 → unique_sdk-2026.44.0.dev7}/PKG-INFO

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

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

{unique_sdk-2026.44.0.dev5 → unique_sdk-2026.44.0.dev7}/unique_sdk/api_resources/_search.py

@@ -35,6 +35,8 @@ class Search(APIResource["Search"]):
         contentIds: NotRequired[list[str] | None]
         scoreThreshold: NotRequired[float | None]
         qdrantParams: NotRequired["Search.QdrantSearchParams | None"]
+        mergeStrategy: NotRequired[Literal["ZIP", "RRF", "DBSF"] | None]
+        includeScores: NotRequired[bool | None]
 
     id: str
     chunkId: str
@@ -48,6 +50,8 @@ class Search(APIResource["Search"]):
     startPage: int
     endPage: int
     metadata: dict[str, Any] | None
+    # Only present when the request sets includeScores.
+    score: float | None
 
     @classmethod
     def create(

{unique_sdk-2026.44.0.dev5 → unique_sdk-2026.44.0.dev7}/unique_sdk/cli/commands/files.py

@@ -38,6 +38,12 @@ _SUPPORTED_UPLOAD_MIME_TYPES = {
     ".md": "text/markdown",
 }
 
+# Bounds so one name resolve can never page through the whole knowledge base.
+_MAX_RESOLVE_MATCH_CANDIDATES = 100
+_MAX_RESOLVE_INFOS_PAGES = 10
+_RESOLVE_INFOS_PAGE_SIZE = 100
+_MAX_RESOLVE_INFOS_ENTRIES = _MAX_RESOLVE_INFOS_PAGES * _RESOLVE_INFOS_PAGE_SIZE
+
 
 def _normalize_unique_file_path(cwd: str, path: str) -> str:
     """Normalize a Unique file path without allowing traversal above root."""
@@ -79,6 +85,7 @@ def _resolve_content_id(
         return name_or_id, name_or_id
 
     lookup_name = name_or_id
+    folder_path = state.cwd
     scope_id = state.scope_id
     if "/" in name_or_id:
         unique_path = _normalize_unique_file_path(state.cwd, name_or_id)
@@ -124,16 +131,10 @@ def _resolve_content_id(
         if not scope_id:
             raise ValueError(f"folder not found: {folder_path}")
     elif scope_id is None:
-        # A bare file name with no folder context resolves via an *unparented*
-        # Content.get_infos scan across the whole knowledge base.
+        # Resolving a bare name at the root would page the whole knowledge base.
         if state.workspace_metadata_filter is not None:
-            # With a per-message filter active, a whole-KB filename scan would
-            # discover documents outside the task scope before the per-id gate
-            # runs — and the deny-vs-not-found distinction is an existence/title
-            # oracle across the task boundary. That is broader than the
-            # ls/read-at-root gating intent, so require a bounded context
-            # instead. The cont_ fast-path, an explicit in-scope path, or a
-            # ``cd`` into an in-scope folder all still work. See UN-21780.
+            # With a per-message filter active that is also a cross-scope
+            # existence/title oracle. See UN-21780.
             raise ValueError(
                 f"permission denied: {name_or_id} can't be resolved by name at "
                 f"the knowledge-base root while a task scope is active "
@@ -141,51 +142,180 @@ def _resolve_content_id(
                 "by content id, or 'cd' into an in-scope folder."
             )
         if not state.is_within_workspace():
-            # No per-message filter: defer to the static scopeIds boundary.
             raise ValueError("permission denied (outside workspace scope)")
+        raise ValueError(
+            f"{name_or_id} can't be resolved by name at the knowledge-base "
+            "root. Use 'unique-cli search', pass a content id (cont_...), "
+            "or 'cd' into a folder first."
+        )
+
+    return _resolve_content_id_in_folder(
+        state=state,
+        name_or_id=name_or_id,
+        lookup_name=lookup_name,
+        folder_path=folder_path,
+        scope_id=scope_id,
+        allow_chat_files=allow_chat_files,
+    )
+
+
+def _resolve_content_id_in_folder(
+    *,
+    state: ShellState,
+    name_or_id: str,
+    lookup_name: str,
+    folder_path: str,
+    scope_id: str,
+    allow_chat_files: bool,
+) -> tuple[str, str]:
+    """Resolve ``lookup_name`` inside one folder without paging the whole KB."""
+    match = _pick_match(
+        hits=_hits_by_file_path(
+            state=state,
+            folder_path=folder_path,
+            lookup_name=lookup_name,
+            scope_id=scope_id,
+        ),
+        lookup_name=lookup_name,
+    )
+    capped = False
+    if match is None:
+        hits, capped = _hits_by_search(
+            state=state, lookup_name=lookup_name, scope_id=scope_id
+        )
+        match = _pick_match(hits=hits, lookup_name=lookup_name)
+    if match is None:
+        if capped:
+            raise ValueError(
+                f"File not found in the first {_MAX_RESOLVE_INFOS_ENTRIES} "
+                f"entries of this folder: {name_or_id}. Use 'unique-cli "
+                "search' or pass a content id (cont_...)."
+            )
+        raise ValueError(f"File not found: {name_or_id}")
+
+    resolved_id, display_name = match
+    # Gate the *resolved* id too: resolving by file name or path must not
+    # bypass the per-message metadata-filter scope that the cont_ fast-path
+    # above enforces, and must honour the same read-only chat-file
+    # exemption (so rm/mv by name can't reach an out-of-scope attachment
+    # either). See UN-21780.
+    if not state.is_content_within_workspace(
+        resolved_id, allow_chat_files=allow_chat_files
+    ):
+        raise ValueError(
+            f"permission denied: {name_or_id} is outside your "
+            f"task scope ({state.scope_denial_hint()}). Use "
+            "'unique-cli search' or 'ls' within that scope "
+            "instead."
+        )
+    return resolved_id, display_name
+
+
+def _hits_by_file_path(
+    *, state: ShellState, folder_path: str, lookup_name: str, scope_id: str
+) -> Sequence[Any]:
+    # One indexed lookup that returns no chunks and also finds files whose
+    # ingestion failed.
+    try:
+        result = unique_sdk.Content.get_info(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            filePath=f"{folder_path.rstrip('/')}/{lookup_name}",
+        )
+    except unique_sdk.UniqueError:
+        return []
+    # A server that ignores filePath returns unrelated content.
+    return [
+        info
+        for info in result.get("contentInfo", [])
+        if info.get("ownerId") == scope_id
+    ]
+
+
+def _hits_by_search(
+    *, state: ShellState, lookup_name: str, scope_id: str
+) -> tuple[Sequence[Any], bool]:
+    """Return the hits, and whether the get_infos fallback hit its page cap."""
+    try:
+        hits = unique_sdk.Content.search(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            where={
+                "AND": [
+                    {"ownerId": {"equals": scope_id}},
+                    {
+                        "OR": [
+                            {"title": {"equals": lookup_name}},
+                            {"key": {"equals": lookup_name}},
+                        ]
+                    },
+                ]
+            },
+            includeFailedContent=True,
+        )
+    except unique_sdk.UniqueError:
+        return _resolve_content_id_via_infos_fallback(
+            state=state,
+            lookup_name=lookup_name,
+            scope_id=scope_id,
+        )
+    return hits, False
+
 
-    params: dict[str, Any] = {}
-    if scope_id:
-        params["parentId"] = scope_id
+def _pick_match(*, hits: Sequence[Any], lookup_name: str) -> tuple[str, str] | None:
+    for content in hits[:_MAX_RESOLVE_MATCH_CANDIDATES]:
+        info = _as_content_fields(content)
+        resolved_id = info.get("id")
+        if not isinstance(resolved_id, str) or not resolved_id:
+            continue
+        title = info.get("title") or ""
+        key = info.get("key") or ""
+        if lookup_name in {title, key}:
+            return resolved_id, title or key
+    return None
 
-    take = 100
+
+def _as_content_fields(content: Any) -> Mapping[str, Any]:
+    if isinstance(content, Mapping):
+        return content
+    return {
+        "id": getattr(content, "id", None),
+        "title": getattr(content, "title", None),
+        "key": getattr(content, "key", None),
+    }
+
+
+def _resolve_content_id_via_infos_fallback(
+    *,
+    state: ShellState,
+    lookup_name: str,
+    scope_id: str,
+) -> tuple[list[Mapping[str, Any]], bool]:
+    """Folder-scoped get_infos fallback with a hard page cap.
+
+    Returns the match (if any), and whether the cap stopped the scan early.
+    """
     skip = 0
-    while True:
+    for _ in range(_MAX_RESOLVE_INFOS_PAGES):
         result = unique_sdk.Content.get_infos(
             user_id=state.config.user_id,
             company_id=state.config.company_id,
+            parentId=scope_id,
             skip=skip,
-            take=take,
-            **params,
+            take=_RESOLVE_INFOS_PAGE_SIZE,
         )
         content_infos = result.get("contentInfos", [])
         if not content_infos:
-            break
-
+            return [], False
         for info in content_infos:
             title = info.get("title") or ""
             key = info.get("key") or ""
             if lookup_name in {title, key}:
-                resolved_id = info["id"]
-                # Gate the *resolved* id too: resolving by file name or path
-                # must not bypass the per-message metadata-filter scope that
-                # the cont_ fast-path above enforces, and must honour the same
-                # read-only chat-file exemption (so rm/mv by name can't reach
-                # an out-of-scope attachment either). See UN-21780.
-                if not state.is_content_within_workspace(
-                    resolved_id, allow_chat_files=allow_chat_files
-                ):
-                    raise ValueError(
-                        f"permission denied: {name_or_id} is outside your "
-                        f"task scope ({state.scope_denial_hint()}). Use "
-                        "'unique-cli search' or 'ls' within that scope "
-                        "instead."
-                    )
-                return resolved_id, title or key
-
+                return [info], False
+        if len(content_infos) < _RESOLVE_INFOS_PAGE_SIZE:
+            return [], False
         skip += len(content_infos)
-
-    raise ValueError(f"File not found: {name_or_id}")
+    return [], True
 
 
 def _detect_upload_mime_type(path: Path) -> str:

{unique_sdk-2026.44.0.dev5 → unique_sdk-2026.44.0.dev7}/unique_sdk/cli/skills/unique-cli-file-management/SKILL.md

@@ -99,6 +99,10 @@ unique-cli mv report.pdf "Annual Report 2025.pdf"
 | Content ID | `cont_abc123` | File directly by ID |
 | File path | `/Reports/Q1/report.pdf` | File in a folder |
 
+A bare file name such as `report.pdf` resolves in the current folder. At the
+root (`/`) a bare file name is an error: pass a full path, a content ID, or `cd`
+into the folder first.
+
 ## Upload Destination Resolution
 
 The `upload` command always enables immutable content versioning. It does not expose an unversioned upload mode. Its destination works like Linux `cp`: