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

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

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

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

{unique_sdk-2026.28.0.dev3 → unique_sdk-2026.28.0.dev5}/unique_sdk/cli/cli.py

@@ -376,11 +376,26 @@ def download(ctx: click.Context, name_or_id: str, local_dest: str | None) -> Non
     default=None,
     help="Page numbers to cite: '3-7' or '1,3,5'. Omit for whole-file.",
 )
+@click.option(
+    "--read-method",
+    "-m",
+    "read_method",
+    required=True,
+    help=(
+        "How you read the cited source: 'text' (page/document text, e.g. "
+        "pdftotext, PyMuPDF, MarkItDown), 'vision' (page rendered as an image "
+        "and read visually), or 'indexed' (read via the platform index with "
+        "unique-cli read). Common tool names (pdftotext, fitz, ocr, ...) are "
+        "accepted and normalized. Use separate cite calls when different pages "
+        "were read by different methods."
+    ),
+)
 @click.pass_context
 def cite(
     ctx: click.Context,
     name_or_id: str,
     pages: str | None,
+    read_method: str,
 ) -> None:
     """Declare page citations for a file.
 
@@ -388,14 +403,18 @@ def cite(
     Registers [filesourceN] markers for pages you referenced in your answer.
     Does NOT read or extract the file — use your own tools for that.
     NAME_OR_ID can be a file path, current-directory file name, or content ID.
+    --read-method is mandatory: it records how you read the page(s).
+    --pages is optional; omit it to cite the whole file (e.g. non-paginated
+    formats).
 
     \b
     Examples:
-      unique-cli cite report.pdf --pages 3,5,7
-      unique-cli cite /Reports/Q1/report.pdf --pages 3,5,7
-      unique-cli cite cont_abc123 --pages 1-4
+      unique-cli cite report.pdf --pages 3,5,7 --read-method text
+      unique-cli cite /Reports/Q1/report.pdf --pages 3,5,7 --read-method vision
+      unique-cli cite cont_abc123 --pages 1-4 --read-method indexed
+      unique-cli cite notes.docx --read-method text
     """
-    click.echo(cmd_cite_file(LazyState.get(ctx), name_or_id, pages))
+    click.echo(cmd_cite_file(LazyState.get(ctx), name_or_id, pages, read_method))
 
 
 @main.command(name="read")

{unique_sdk-2026.28.0.dev3 → unique_sdk-2026.28.0.dev5}/unique_sdk/cli/commands/cite_file.py

@@ -23,6 +23,74 @@ _CHAT_FILES_MANIFEST = Path(".unique") / "chat-files.json"
 
 _MAX_PAGES_PER_CALL = 500
 
+# File extensions with no inherent pagination. Passing ``--pages`` for these is
+# meaningless — the whole file is the citeable unit. PDFs and PPTX (slides) are
+# paginated; unknown/other extensions (and bare content IDs) are left untouched
+# so we only emit the targeted error when we can detect the format confidently.
+_NON_PAGINATED_SUFFIXES = frozenset(
+    {
+        ".xlsx",
+        ".xls",
+        ".csv",
+        ".txt",
+        ".md",
+        ".html",
+        ".htm",
+        ".png",
+        ".jpg",
+        ".jpeg",
+        ".gif",
+        ".webp",
+        ".bmp",
+        ".tiff",
+        ".tif",
+    }
+)
+
+
+def _is_non_paginated(filename: str) -> bool:
+    """True when ``filename`` has a known extension that carries no page numbers."""
+    return Path(filename).suffix.lower() in _NON_PAGINATED_SUFFIXES
+
+
+# Canonical reading-method values declared via ``--read-method``. They record
+# the *representation* of the source the agent actually read so the runner can
+# reconstruct the matching ground truth for a hallucination check:
+# - ``text``    — page/document text (e.g. pdftotext, PyMuPDF get_text,
+#                 MarkItDown conversion).
+# - ``vision``  — the page/slide rendered as an image and read with vision.
+# - ``indexed`` — content read through the platform index (unique-cli
+#                 read/search), i.e. existing chunks.
+READ_METHODS = ("text", "vision", "indexed")
+
+# Convenience aliases accepted from the agent and normalized to canonical values.
+_READ_METHOD_ALIASES = {
+    "pdftotext": "text",
+    "pymupdf": "text",
+    "fitz": "text",
+    "mupdf": "text",
+    "pdfminer": "text",
+    "markitdown": "text",
+    "image": "vision",
+    "ocr": "vision",
+    "render": "vision",
+    "read": "indexed",
+    "search": "indexed",
+}
+
+
+def _normalize_read_method(read_method: str | None) -> str | None:
+    """Normalize a ``--read-method`` value to a canonical one, or None if invalid.
+
+    Case-insensitive, with a small alias map. Returns None for missing or
+    unrecognized values so callers can fail closed with a clear message.
+    """
+    if not read_method or not read_method.strip():
+        return None
+    candidate = read_method.strip().lower()
+    candidate = _READ_METHOD_ALIASES.get(candidate, candidate)
+    return candidate if candidate in READ_METHODS else None
+
 
 def _parse_pages(pages: str | None) -> list[int]:
     """Parse '3-7' or '1,3,5' into a list of 1-based page numbers.
@@ -91,17 +159,35 @@ def cmd_cite_file(
     state: ShellState,
     name_or_id: str,
     pages: str | None,
+    read_method: 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.
+    markers for the agent to use inline. ``read_method`` records how the cited
+    page text was read (one of :data:`READ_METHODS`); it is mandatory and
+    validated here as defense in depth for callers that bypass the CLI layer.
     """
+    canonical_method = _normalize_read_method(read_method)
+    if canonical_method is None:
+        return (
+            f"{CITE_ERROR_PREFIX} --read-method is required and must be one of: "
+            f"{', '.join(READ_METHODS)}. Report the method that produced the "
+            "text you actually used."
+        )
+
     try:
         content_id, filename = _resolve_content_id_with_manifest(state, name_or_id)
     except Exception as exc:
         return f"{CITE_ERROR_PREFIX} {exc}"
 
+    if pages and pages.strip() and _is_non_paginated(filename):
+        suffix = Path(filename).suffix.lower()
+        return (
+            f"{CITE_ERROR_PREFIX} {filename} is non-paginated ({suffix} files "
+            "have no pages) — omit --pages to cite the whole file."
+        )
+
     page_list = _parse_pages(pages)
     if not page_list:
         return f"{CITE_ERROR_PREFIX} invalid --pages value"
@@ -114,20 +200,38 @@ def cmd_cite_file(
         ):
             existing = _read_turn_refs_manifest(refs_log_path)
 
-            existing_keys: dict[tuple[str, int], int] = {}
+            # Track the source number and the read method already recorded for
+            # each (contentId, page) so we can dedup and flag method conflicts.
+            existing_keys: dict[tuple[str, int], tuple[int, str]] = {}
             for entry in existing:
                 key = (entry.get("contentId", ""), entry.get("page", 0))
-                existing_keys[key] = entry.get("sourceNumber", 0)
+                existing_keys[key] = (
+                    entry.get("sourceNumber", 0),
+                    entry.get("readMethod", ""),
+                )
 
-            next_source_number = max(existing_keys.values()) + 1 if existing_keys else 1
+            next_source_number = (
+                max(sn for sn, _ in 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]
+                    sn, prior_method = existing_keys[key]
+                    # A page is grounded by a single representation. If the agent
+                    # re-cites it with a different method, keep the first and say
+                    # so explicitly rather than silently dropping the new method.
+                    if prior_method and prior_method != canonical_method:
+                        note = (
+                            f"already declared with --read-method "
+                            f"{prior_method}; keeping it (one read-method per "
+                            "page — issue a separate cite for a different page)"
+                        )
+                    else:
+                        note = "already declared"
                     output_lines.append(
-                        f"[filesource{sn}] -> {filename} page {page} (already declared)"
+                        f"[filesource{sn}] -> {filename} page {page} ({note})"
                     )
                     continue
 
@@ -136,12 +240,13 @@ def cmd_cite_file(
                     "contentId": content_id,
                     "filename": filename,
                     "page": page,
+                    "readMethod": canonical_method,
                 }
                 _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
+                existing_keys[key] = (next_source_number, canonical_method)
                 next_source_number += 1
 
     except UnsafeRefsLogPathError as exc:

{unique_sdk-2026.28.0.dev3 → unique_sdk-2026.28.0.dev5}/unique_sdk/cli/shell.py

@@ -62,7 +62,7 @@ OVERVIEW_HELP = textwrap.dedent("""\
       download <name|path|id> [dest] Download a file to local machine
       rm <name|path|id>         Delete a file
       mv <old|path|id> <new>    Rename a file
-      cite <name|path|id> [--pages] Declare page citations for a file
+      cite <name|path|id> [--pages] --read-method METHOD  Declare page citations
 
     Search:
       search <query> [options]  Combined search (vector + full-text)
@@ -443,20 +443,31 @@ class UniqueShell(cmd.Cmd):
     def do_cite(self, arg: str) -> None:
         """Declare page citations for a file.
 
-        Usage: cite <name|path|content_id> [--pages RANGE]
+        Usage: cite <name|path|content_id> [--pages RANGE] --read-method METHOD
+
+        --read-method is mandatory (one of: text, vision, indexed). --pages is
+        optional; omit it to cite the whole file.
 
         Examples:
-          /Reports> cite report.pdf --pages 3,5,7
-          /Reports> cite /Reports/Q1/report.pdf --pages 3,5,7
-          /Reports> cite cont_abc123 --pages 1-4
+          /Reports> cite report.pdf --pages 3,5,7 --read-method text
+          /Reports> cite /Reports/Q1/report.pdf --pages 3,5,7 --read-method vision
+          /Reports> cite cont_abc123 --pages 1-4 --read-method indexed
+          /Reports> cite notes.docx --read-method text
         """
-        from unique_sdk.cli.commands.cite_file import cmd_cite_file
+        from unique_sdk.cli.commands.cite_file import (
+            READ_METHODS,
+            cmd_cite_file,
+        )
 
+        usage = (
+            "Usage: cite <name|path|content_id> [--pages RANGE] --read-method METHOD"
+        )
         parts = shlex.split(arg)
         if not parts:
-            self._print("Usage: cite <name|path|content_id> [--pages RANGE]")
+            self._print(usage)
             return
         pages: str | None = None
+        read_method: str | None = None
         positional: list[str] = []
         index = 0
         while index < len(parts):
@@ -467,13 +478,27 @@ class UniqueShell(cmd.Cmd):
                     return
                 pages = parts[index + 1]
                 index += 2
+            elif token in ("--read-method", "-m"):
+                if index + 1 >= len(parts):
+                    self._print(
+                        "cite: --read-method requires a value (one of: "
+                        f"{', '.join(READ_METHODS)})"
+                    )
+                    return
+                read_method = parts[index + 1]
+                index += 2
             else:
                 positional.append(token)
                 index += 1
         if not positional:
-            self._print("Usage: cite <name|path|content_id> [--pages RANGE]")
+            self._print(usage)
+            return
+        if read_method is None:
+            self._print(
+                f"cite: --read-method is required (one of: {', '.join(READ_METHODS)})"
+            )
             return
-        self._print(cmd_cite_file(self.state, positional[0], pages))
+        self._print(cmd_cite_file(self.state, positional[0], pages, read_method))
 
     def _parse_int(self, raw: str, flag: str) -> tuple[int | None, bool]:
         """Parse an int option value, returning (value, ok). Prints on failure."""

{unique_sdk-2026.28.0.dev3 → unique_sdk-2026.28.0.dev5}/unique_sdk/cli/skills/unique-cli-file-management/SKILL.md

@@ -73,9 +73,11 @@ unique-cli read cont_abc123
 unique-cli read cont_abc123 --page 12
 unique-cli read cont_abc123 --from-page 5 --to-page 9
 
-# Declare page citations after reading a file
-unique-cli cite report.pdf --pages 3,5,7
-unique-cli cite cont_abc123 --pages 1-4
+# Declare page citations after reading a file (--read-method is mandatory)
+unique-cli cite report.pdf --pages 3,5,7 --read-method text
+unique-cli cite cont_abc123 --pages 1-4 --read-method vision
+# Non-paginated files (Excel, CSV, txt): omit --pages to cite the whole file
+unique-cli cite data.xlsx --read-method text
 
 # Delete a file
 unique-cli rm report.pdf
@@ -203,26 +205,60 @@ can attribute text to pages.
 
 ## Citing File Pages
 
-After reading **any** file and using its content in your answer, declare citations:
+After reading **any** file (PDF, Office, text, etc.) and using its content in your
+answer, declare citations. `cite` works on **any** file type, not just PDFs.
+`--read-method` is **mandatory**: it records how you actually read the cited page(s).
 
 ```bash
-unique-cli cite report.pdf --pages 3,5
-unique-cli cite cont_abc123 --pages 1-4
+unique-cli cite report.pdf --pages 3,5 --read-method text
+unique-cli cite cont_abc123 --pages 1-4 --read-method vision
+unique-cli cite data.xlsx --read-method text          # non-paginated: omit --pages
 ```
 
 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.
-
+**`--pages` is optional.** Omit it to cite the **whole file**. Paginated formats
+(PDF, PPTX) take page/slide numbers; **non-paginated formats (Excel `.xlsx`/`.xls`,
+CSV, `.txt`, HTML, images) have no pages — always omit `--pages`** and cite the
+whole file.
+
+**Choosing `--read-method`** (declare the *representation* of the source you actually read):
+
+- `text` → you used **extracted text** (`pdftotext`, PyMuPDF / `fitz` `page.get_text()`, MarkItDown, or any text extraction).
+- `vision` → you read a **rendered image** of the page/slide (e.g. `get_pixmap()`) with your vision capability.
+- `indexed` → you relied on **`unique-cli read`** output (the platform's indexed chunks).
+
+| Value | When to use |
+|-------|-------------|
+| `text` | You read the page/document as extracted text and used that text. |
+| `vision` | You rendered the page to an image and read it with your vision capability. |
+| `indexed` | You read the content via `unique-cli read` (indexed chunks). |
+
+**MANDATORY verification before EVERY `unique-cli cite` call — NO EXCEPTIONS.**
+Pick the row matching the file you read; verify the cited content really is where
+you claim before calling `cite`:
+
+- **PDF** — `pdfinfo file.pdf | grep Pages` for the total physical page count, then
+  for **each** page run `pdftotext -f N -l N file.pdf -` and confirm the content is
+  on that physical page. Page numbers are **physical PDF positions** (1-based);
+  NEVER use printed page numbers from headers/footers — they often differ.
+- **PPTX** — the page number is the **slide number** (1-based). Verify against the
+  slide you actually read.
+- **DOCX** — use the rendered page from your text extraction; if there is no
+  reliable page boundary, cite the **whole file** (omit `--pages`).
+- **Non-paginated (XLSX/CSV/TXT/HTML/images)** — there are no pages. Do **NOT**
+  pass `--pages`; cite the whole file and verify the content exists in it.
+
+Then determine `--read-method`: report the representation you actually read. In a
+fallback chain (e.g. text extraction returned nothing → render + read visually),
+report `text` if you used extracted text or `vision` if you read a rendered image.
+Only after verifying, call `unique-cli cite` with the verified page numbers (if any)
+and `--read-method`.
+
+- **One method per `cite` call.** If different pages were read with different methods, issue separate `cite` calls — one per method.
 - 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`.
+- Do NOT use `cite` for content from `unique-cli search` or `unique-cli web-search` — those are referenced automatically.
 
 ## Error Handling