unique-sdk 2026.24.0.dev8__tar.gz → 2026.24.0.dev9__tar.gz

{unique_sdk-2026.24.0.dev8 → unique_sdk-2026.24.0.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.24.0.dev8
+Version: 2026.24.0.dev9
 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.24.0.dev8 → unique_sdk-2026.24.0.dev9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_sdk"
-version = "2026.24.0.dev8"
+version = "2026.24.0.dev9"
 description = ""
 readme = "README.md"
 license = { text = "MIT" }
@@ -77,6 +77,7 @@ reportUnusedCallResult = "none"
 reportUnannotatedClassAttribute = "none"
 reportImplicitOverride = "none"
 reportImplicitStringConcatenation = "none"
+reportPrivateUsage = "none"
 reportUnusedParameter = "none"
 reportImportCycles = "none"
 

{unique_sdk-2026.24.0.dev8 → unique_sdk-2026.24.0.dev9}/unique_sdk/_util.py

@@ -187,7 +187,7 @@ def convert_to_unique_object(
                 or (getattr(obj, "object") == "search_result")
             )
         ):
-            obj._retrieve_params = params  # pyright: ignore[reportPrivateUsage]
+            obj._retrieve_params = params
 
         return obj
     else:

{unique_sdk-2026.24.0.dev8 → unique_sdk-2026.24.0.dev9}/unique_sdk/cli/cli.py

@@ -7,6 +7,7 @@ from typing import Any
 import click
 
 from unique_sdk.cli import __version__
+from unique_sdk.cli.commands.cite_file import cmd_cite_file
 from unique_sdk.cli.commands.elicitation import (
     cmd_elicit_ask,
     cmd_elicit_create,
@@ -300,6 +301,34 @@ def download(ctx: click.Context, name_or_id: str, local_dest: str | None) -> Non
     click.echo(cmd_download(LazyState.get(ctx), name_or_id, local_dest))
 
 
+@main.command(name="cite")
+@click.argument("name_or_id")
+@click.option(
+    "--pages",
+    "-p",
+    default=None,
+    help="Page numbers to cite: '3-7' or '1,3,5'. Omit for whole-file.",
+)
+@click.pass_context
+def cite(
+    ctx: click.Context,
+    name_or_id: str,
+    pages: str | None,
+) -> None:
+    """Declare page citations for a file.
+
+    \b
+    Registers [filesourceN] markers for pages you referenced in your answer.
+    Does NOT read or extract the file — use your own tools for that.
+
+    \b
+    Examples:
+      unique-cli cite report.pdf --pages 3,5,7
+      unique-cli cite cont_abc123 --pages 1-4
+    """
+    click.echo(cmd_cite_file(LazyState.get(ctx), name_or_id, pages))
+
+
 @main.command()
 @click.argument("name_or_id")
 @click.pass_context

unique_sdk-2026.24.0.dev9/unique_sdk/cli/commands/cite_file.py

@@ -0,0 +1,150 @@
+"""Cite command: declare file page citations without extracting text."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from unique_sdk.cli.commands._citation_manifest import (
+    UnsafeRefsLogPathError,
+    _append_turn_refs_manifest_entry,
+    _locked_turn_refs_manifest,
+    _read_turn_refs_manifest,
+)
+from unique_sdk.cli.commands.files import _resolve_content_id
+from unique_sdk.cli.state import ShellState
+
+CITE_ERROR_PREFIX = "cite:"
+
+_FILE_REFS_LOG_RELATIVE_PATH = Path(".unique") / "file-refs.jsonl"
+_FILE_REFS_LOCK_FILENAME = "file-refs.lock"
+_CHAT_FILES_MANIFEST = Path(".unique") / "chat-files.json"
+
+
+_MAX_PAGES_PER_CALL = 500
+
+
+def _parse_pages(pages: str | None) -> list[int]:
+    """Parse '3-7' or '1,3,5' into a list of 1-based page numbers.
+
+    Returns [0] (whole-file) when pages is None or empty.
+    Returns [] on invalid input (triggers error in caller).
+    """
+    if not pages or not pages.strip():
+        return [0]
+    selected: list[int] = []
+    for part in pages.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        if "-" in part:
+            bounds = part.split("-", 1)
+            start_s, end_s = bounds[0].strip(), bounds[1].strip()
+            if not start_s.isdecimal() or not end_s.isdecimal():
+                return []
+            start, end = int(start_s), int(end_s)
+            if start < 1 or end < start or (end - start + 1) > _MAX_PAGES_PER_CALL:
+                return []
+            selected.extend(range(start, end + 1))
+        else:
+            if not part.isdecimal() or int(part) < 1:
+                return []
+            selected.append(int(part))
+    if not selected:
+        return []
+    if len(set(selected)) > _MAX_PAGES_PER_CALL:
+        return []
+    return sorted(set(selected))
+
+
+def _resolve_content_id_with_manifest(
+    state: ShellState, name_or_id: str
+) -> tuple[str, str]:
+    """Resolve a filename/content_id checking the chat-files manifest first.
+
+    Resolution order:
+    1. If name_or_id starts with "cont_", return it directly.
+    2. Check .unique/chat-files.json for a matching filename (exact or basename).
+    3. Fall back to KB resolution via _resolve_content_id.
+    """
+    if name_or_id.startswith("cont_"):
+        return name_or_id, name_or_id
+
+    manifest_path = Path.cwd() / _CHAT_FILES_MANIFEST
+    if manifest_path.is_file():
+        try:
+            manifest: dict[str, str] = json.loads(
+                manifest_path.read_text(encoding="utf-8")
+            )
+        except (json.JSONDecodeError, OSError):
+            manifest = {}
+
+        basename = Path(name_or_id).name
+        content_id = manifest.get(name_or_id) or manifest.get(basename)
+        if content_id:
+            return content_id, basename
+
+    return _resolve_content_id(state, name_or_id)
+
+
+def cmd_cite_file(
+    state: ShellState,
+    name_or_id: str,
+    pages: str | None,
+) -> str:
+    """Declare citations for a file's pages.
+
+    Writes entries to .unique/file-refs.jsonl and returns [filesourceN]
+    markers for the agent to use inline.
+    """
+    try:
+        content_id, filename = _resolve_content_id_with_manifest(state, name_or_id)
+    except Exception as exc:
+        return f"{CITE_ERROR_PREFIX} {exc}"
+
+    page_list = _parse_pages(pages)
+    if not page_list:
+        return f"{CITE_ERROR_PREFIX} invalid --pages value"
+
+    refs_log_path = Path.cwd() / _FILE_REFS_LOG_RELATIVE_PATH
+
+    try:
+        with _locked_turn_refs_manifest(
+            refs_log_path, lock_filename=_FILE_REFS_LOCK_FILENAME
+        ):
+            existing = _read_turn_refs_manifest(refs_log_path)
+
+            existing_keys: dict[tuple[str, int], int] = {}
+            for entry in existing:
+                key = (entry.get("contentId", ""), entry.get("page", 0))
+                existing_keys[key] = entry.get("sourceNumber", 0)
+
+            next_source_number = max(existing_keys.values()) + 1 if existing_keys else 1
+
+            output_lines: list[str] = []
+            for page in page_list:
+                key = (content_id, page)
+                if key in existing_keys:
+                    sn = existing_keys[key]
+                    output_lines.append(
+                        f"[filesource{sn}] -> {filename} page {page} (already declared)"
+                    )
+                    continue
+
+                entry = {
+                    "sourceNumber": next_source_number,
+                    "contentId": content_id,
+                    "filename": filename,
+                    "page": page,
+                }
+                _append_turn_refs_manifest_entry(refs_log_path, entry)
+                output_lines.append(
+                    f"[filesource{next_source_number}] -> {filename} page {page}"
+                )
+                existing_keys[key] = next_source_number
+                next_source_number += 1
+
+    except UnsafeRefsLogPathError as exc:
+        return f"{CITE_ERROR_PREFIX} {exc}"
+
+    return "\n".join(output_lines)

{unique_sdk-2026.24.0.dev8 → unique_sdk-2026.24.0.dev9}/unique_sdk/cli/shell.py

@@ -52,6 +52,7 @@ OVERVIEW_HELP = textwrap.dedent("""\
       download <name|id> [dest] Download a file to local machine
       rm <name|id>              Delete a file
       mv <old> <new>            Rename a file
+      cite <name|id> [--pages]  Declare page citations for a file
 
     Search:
       search <query> [options]  Combined search (vector + full-text)
@@ -359,6 +360,40 @@ class UniqueShell(cmd.Cmd):
         local_dest = parts[1] if len(parts) > 1 else None
         self._print(cmd_download(self.state, name_or_id, local_dest))
 
+    def do_cite(self, arg: str) -> None:
+        """Declare page citations for a file.
+
+        Usage: cite <name|content_id> [--pages RANGE]
+
+        Examples:
+          /Reports> cite report.pdf --pages 3,5,7
+          /Reports> cite cont_abc123 --pages 1-4
+        """
+        from unique_sdk.cli.commands.cite_file import cmd_cite_file
+
+        parts = shlex.split(arg)
+        if not parts:
+            self._print("Usage: cite <name|content_id> [--pages RANGE]")
+            return
+        pages: str | None = None
+        positional: list[str] = []
+        index = 0
+        while index < len(parts):
+            token = parts[index]
+            if token in ("--pages", "-p"):
+                if index + 1 >= len(parts):
+                    self._print("cite: --pages requires a value")
+                    return
+                pages = parts[index + 1]
+                index += 2
+            else:
+                positional.append(token)
+                index += 1
+        if not positional:
+            self._print("Usage: cite <name|content_id> [--pages RANGE]")
+            return
+        self._print(cmd_cite_file(self.state, positional[0], pages))
+
     def do_rm(self, arg: str) -> None:
         """Delete a file.
 

{unique_sdk-2026.24.0.dev8 → unique_sdk-2026.24.0.dev9}/unique_sdk/cli/skills/unique-cli-file-management/SKILL.md

@@ -59,6 +59,10 @@ unique-cli upload ./data.csv scope_abc123
 unique-cli download report.pdf ./local/
 unique-cli download cont_abc123 ~/Desktop/
 
+# Declare page citations after reading a file
+unique-cli cite report.pdf --pages 3,5,7
+unique-cli cite cont_abc123 --pages 1-4
+
 # Delete a file
 unique-cli rm report.pdf
 unique-cli rm cont_abc123
@@ -119,6 +123,29 @@ unique-cli mkdir "2025/Q1/Financials"
 unique-cli upload ./budget.xlsx /2025/Q1/Financials/
 ```
 
+## Citing File Pages
+
+After reading **any** file and using its content in your answer, declare citations:
+
+```bash
+unique-cli cite report.pdf --pages 3,5
+unique-cli cite cont_abc123 --pages 1-4
+```
+
+This registers `[filesourceN]` markers. Use them inline in your answer.
+The platform converts `[filesourceN]` into footnotes and clickable reference chips.
+
+**MANDATORY 3-step verification before EVERY `unique-cli cite` call — NO EXCEPTIONS:**
+
+1. `pdfinfo file.pdf | grep Pages` — get total physical page count.
+2. For **each** page you intend to cite, run `pdftotext -f N -l N file.pdf -` and confirm the content you are referencing is actually on that physical page. Do NOT skip this. Do NOT assume page numbers.
+3. Only after step 2 confirms a match, call `unique-cli cite` with the verified physical page numbers.
+
+Page numbers are **physical PDF positions** (1-based). NEVER use printed page numbers from headers/footers — they often differ from physical positions.
+
+- Numbers are **per-turn only**; do not reuse from prior turns.
+- Do NOT use `cite` for content from `unique-cli search` or `unique-cli web-search`.
+
 ## Error Handling
 
 - If env vars are missing, the CLI exits with a clear error listing the missing variables.