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

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

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

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

{unique_sdk-2026.26.0.dev5 → unique_sdk-2026.26.0.dev7}/unique_sdk/cli/cli.py

@@ -20,6 +20,10 @@ from unique_sdk.cli.commands.files import cmd_download, cmd_mv_file, cmd_rm, cmd
 from unique_sdk.cli.commands.folders import cmd_mkdir, cmd_mvdir, cmd_rmdir
 from unique_sdk.cli.commands.mcp import cmd_mcp
 from unique_sdk.cli.commands.navigation import cmd_cd, cmd_ls, cmd_pwd
+from unique_sdk.cli.commands.read import cmd_read
+from unique_sdk.cli.commands.read import (
+    is_error_output as _is_read_error_output,
+)
 from unique_sdk.cli.commands.scheduled_tasks import (
     cmd_schedule_create,
     cmd_schedule_delete,
@@ -329,6 +333,32 @@ def cite(
     click.echo(cmd_cite_file(LazyState.get(ctx), name_or_id, pages))
 
 
+@main.command(name="read")
+@click.argument("cont_id")
+@click.pass_context
+def read_cmd(ctx: click.Context, cont_id: str) -> None:
+    """Read all indexed text chunks for a known content ID.
+
+    \b
+    CONT_ID must be a content ID (cont_...) obtained from a prior `ls` or
+    `search` result. Retrieves every indexed chunk directly from the database
+    — no vector search, no query string needed.
+
+    \b
+    Use `search` when you need to find documents by topic or keyword.
+    Use `read` when you already know the content ID and want the full text.
+
+    \b
+    Examples:
+      unique-cli read cont_abc123
+    """
+    output = cmd_read(LazyState.get(ctx), cont_id)
+    if _is_read_error_output(output):
+        click.echo(output, err=True)
+        raise SystemExit(1)
+    click.echo(output)
+
+
 @main.command()
 @click.argument("name_or_id")
 @click.pass_context

unique_sdk-2026.26.0.dev7/unique_sdk/cli/commands/read.py

@@ -0,0 +1,93 @@
+"""Read command: retrieve all indexed text chunks for a known content ID.
+
+Calls ``Content.search(where={"id": {"equals": cont_id}})`` — a direct
+Postgres lookup that returns every indexed chunk for the document in one
+request, no vector search involved.
+
+Use this when you already know the ``cont_*`` ID (e.g. from a prior ``ls``
+or ``unique-cli search`` result) and want to read the full document text.
+For discovery or query-based retrieval use ``unique-cli search`` instead.
+"""
+
+from __future__ import annotations
+
+import unique_sdk
+from unique_sdk.cli.state import ShellState
+
+READ_ERROR_PREFIX = "read:"
+
+
+def cmd_read(state: ShellState, cont_id: str) -> str:
+    """Return all indexed text chunks for *cont_id* as plain text.
+
+    Args:
+        state: Shell state carrying user/company credentials.
+        cont_id: A content ID (``cont_...``) to retrieve.
+
+    Returns:
+        A formatted string of chunks, or an error message prefixed with
+        ``read:``.
+    """
+    if not cont_id.startswith("cont_"):
+        return f"{READ_ERROR_PREFIX} expected a content ID starting with 'cont_', got: {cont_id!r}"
+
+    # Enforce the same .unique-search.json workspace boundary as search/ls/rm.
+    # Content.search has no scopeIds param, so we guard by owner scope before
+    # the point-lookup — matching rm/mv, not search's API-level scopeIds filter.
+    if not state.is_content_within_workspace(cont_id):
+        return f"{READ_ERROR_PREFIX} permission denied (outside workspace scope)"
+
+    try:
+        results = unique_sdk.Content.search(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            where={"id": {"equals": cont_id}},
+        )
+    except unique_sdk.APIError as e:
+        return f"{READ_ERROR_PREFIX} {e}"
+
+    if not results:
+        return f"{READ_ERROR_PREFIX} no content found for ID: {cont_id}"
+
+    content = results[0]
+    title = getattr(content, "title", None) or getattr(content, "key", None) or cont_id
+    chunks = getattr(content, "chunks", None) or []
+
+    if not chunks:
+        return (
+            f"Content: {title} ({cont_id})\n"
+            "No indexed chunks found — the document may still be ingesting or ingestion failed."
+        )
+
+    sorted_chunks = sorted(chunks, key=lambda c: c.get("order") or 0)
+
+    lines: list[str] = [
+        f"Content: {title} ({cont_id}) — {len(sorted_chunks)} chunk(s)\n"
+    ]
+    for chunk in sorted_chunks:
+        text = (chunk.get("text") or "").strip()
+        if not text:
+            continue
+        start = chunk.get("startPage")
+        end = chunk.get("endPage")
+        if start is not None or end is not None:
+            page_start = start if start is not None else end
+            page_end = end if end is not None else start
+            if page_start is not None and page_end is not None:
+                page_ref = (
+                    f"[p.{page_start}]"
+                    if page_start == page_end
+                    else f"[p.{page_start}-{page_end}]"
+                )
+                lines.append(f"{page_ref} {text}")
+            else:
+                lines.append(text)
+        else:
+            lines.append(text)
+
+    return "\n\n".join(lines)
+
+
+def is_error_output(output: str) -> bool:
+    """Return ``True`` when *output* is an error message from ``cmd_read``."""
+    return output.startswith(READ_ERROR_PREFIX)

{unique_sdk-2026.26.0.dev5 → unique_sdk-2026.26.0.dev7}/unique_sdk/cli/shell.py

@@ -59,6 +59,7 @@ OVERVIEW_HELP = textwrap.dedent("""\
         --folder <path|id>        Restrict to a folder
         --metadata <key=value>    Filter by metadata (repeatable)
         --limit <N>               Max results (default: 200)
+      read <cont_id>            Read all indexed text chunks for a content ID
 
     MCP:
       mcp [options] <json>      Call an MCP server tool
@@ -394,6 +395,28 @@ class UniqueShell(cmd.Cmd):
             return
         self._print(cmd_cite_file(self.state, positional[0], pages))
 
+    def do_read(self, arg: str) -> None:
+        """Read all indexed text chunks for a known content ID.
+
+        Usage: read <cont_id>
+
+        Retrieves every indexed chunk for the document directly from the
+        database — no vector search, no query string needed.
+
+        Use `search` to find documents by topic; use `read` once you have
+        the content ID and want the full text.
+
+        Examples:
+          /Reports> read cont_abc123
+        """
+        from unique_sdk.cli.commands.read import cmd_read
+
+        parts = shlex.split(arg)
+        if not parts:
+            self._print("Usage: read <cont_id>")
+            return
+        self._print(cmd_read(self.state, parts[0]))
+
     def do_rm(self, arg: str) -> None:
         """Delete a file.
 

{unique_sdk-2026.26.0.dev5 → unique_sdk-2026.26.0.dev7}/unique_sdk/cli/skills/unique-cli-search/SKILL.md

@@ -6,6 +6,8 @@ description: >-
   as clickable reference chips and `<sup>N</sup>` footnotes on the Unique
   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.
   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,
@@ -13,7 +15,20 @@ description: >-
   `unique-cli ls` to find them by name).
 ---
 
-# Unique CLI -- Knowledge Base Search
+# Unique CLI -- Knowledge Base Search & Document Read
+
+## `search` vs `read` — which command to use
+
+| Situation | Command |
+|-----------|---------|
+| You have a **query or topic** and want to find relevant chunks across documents | `unique-cli search "<query>"` |
+| You already have a **`cont_*` ID** and want the **full indexed text** of that document | `unique-cli read <cont_id>` |
+
+**What "full indexed text" means:** the platform has already ingested the document — OCR for scanned pages, extracted text from PDFs and Office files, and image descriptions from figures/charts. `read` returns that pre-processed text directly; you do **not** need to download the file or run OCR yourself. If `read` returns no chunks after ingestion should be complete, download the file with `unique-cli download` and inspect it directly — ingestion occasionally fails and the raw file must be checked.
+
+Use `read` after a `ls` or `search` surfaces a content ID and you need to go deeper into that specific document — it retrieves every chunk directly from the database with no query needed. Use `search` for discovery.
+
+---
 
 Search the Unique knowledge base using combined vector + full-text search via the `unique-cli search` command. Every invocation wraps each result in a `<sourceN>...</sourceN>` block and records a per-turn citation manifest at `.unique/kb-search-refs.jsonl`, so any fact you cite as `[sourceN]` is rendered with a footnote and a clickable reference chip in the chat UI.
 
@@ -131,6 +146,32 @@ unique-cli search "Q4 earnings" \
   --limit 100
 ```
 
+## Reading a Document by ID (`read`)
+
+When you already know a `cont_*` ID, use `read` to retrieve every indexed chunk in one call:
+
+```bash
+unique-cli read cont_abc123
+```
+
+Output:
+
+```
+Content: annual-report.pdf (cont_abc123) — 42 chunk(s)
+
+[p.1] The company was founded in 1998 with a focus on...
+
+[p.2-3] Revenue grew 15% year over year, driven by...
+
+[p.4] Key risks include supply chain disruptions...
+```
+
+Each paragraph is one ingested chunk (OCR, extracted text, image descriptions) prefixed with its page range when available. No further file parsing or OCR is required on your side.
+
+**When chunks are empty:** if the document was just uploaded and ingestion hasn't finished, `read` returns a message saying so — retry after a short wait. If chunks stay empty after a reasonable wait, download the file (`unique-cli download <cont_id>`) and inspect it yourself; some files are not ingested correctly and must be read directly.
+
+**`read` does not produce `[sourceN]` citations.** It is for reading and understanding document content. If you need to cite specific facts in your answer, run `unique-cli search "<relevant query>"` against the same document's folder to generate proper `[sourceN]` references.
+
 ## Prerequisites
 
 Requires these environment variables: