chunksmith-cli 0.4.0__py3-none-any.whl

chunksmith_cli/branding.py

@@ -0,0 +1,6 @@
+"""Backward-compatible import path. Prefer `cli.core.branding`."""
+
+import importlib
+
+_mod = importlib.import_module("chunksmith_cli.core.branding")
+globals().update({k: v for k, v in _mod.__dict__.items() if not k.startswith("__")})

chunksmith_cli/config.py

@@ -0,0 +1,6 @@
+"""Backward-compatible import path. Prefer `cli.core.config`."""
+
+import importlib
+
+_mod = importlib.import_module("chunksmith_cli.core.config")
+globals().update({k: v for k, v in _mod.__dict__.items() if not k.startswith("__")})

chunksmith_cli/core/__init__.py

@@ -0,0 +1,21 @@
+"""Shared CLI infrastructure: paths, theme, menus, catalogs."""
+
+from chunksmith_cli.core.paths import (
+    cli_archive_stamp,
+    cli_data_dir,
+    cli_json_storage_dir,
+    cli_runs_dir,
+    ensure_cli_storage,
+    normalize_path_string,
+    resolve_pdf_candidate,
+)
+
+__all__ = [
+    "cli_archive_stamp",
+    "cli_data_dir",
+    "cli_json_storage_dir",
+    "cli_runs_dir",
+    "ensure_cli_storage",
+    "normalize_path_string",
+    "resolve_pdf_candidate",
+]

chunksmith_cli/core/artifact_layout.py

@@ -0,0 +1,60 @@
+"""Artifact folder layout for multi-indexing CLI runs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+ARTIFACT_SUBDIR_JSON = "json"
+ARTIFACT_SUBDIR_IMAGE = "image"
+ARTIFACT_SUBDIR_PICKLE = "pickle"
+ARTIFACT_SUBDIR_TEXT = "text"
+
+
+@dataclass(frozen=True)
+class ArtifactLayout:
+    root: Path
+    pdf_stem: str
+    json_dir: Path
+    image_dir: Path
+    pickle_dir: Path
+    text_dir: Path
+
+    def pickle_path(self, *, stamp: str) -> Path:
+        return self.pickle_dir / f"{self.pdf_stem}_{stamp}.pkl"
+
+    def unstructured_json_path(self, *, stamp: str) -> Path:
+        return self.json_dir / f"{self.pdf_stem}_{stamp}_unstructured_elements.json"
+
+    def pageindex_json_path(self, *, stamp: str) -> Path:
+        return self.json_dir / f"{self.pdf_stem}_{stamp}_pageindex.json"
+
+    def multi_index_json_path(self, *, stamp: str) -> Path:
+        return self.json_dir / f"{self.pdf_stem}_{stamp}_multi_index.json"
+
+    def canonical_bundle_json_path(self, *, stamp: str) -> Path:
+        return self.json_dir / f"{self.pdf_stem}_{stamp}_canonical_bundle.json"
+
+    def coded_text_path(self, *, stamp: str) -> Path:
+        return self.text_dir / f"{self.pdf_stem}_{stamp}_title_coded_formate.txt"
+
+    def compressed_tree_text_path(self, *, stamp: str) -> Path:
+        return self.text_dir / f"{self.pdf_stem}_{stamp}_compressed_tree.txt"
+
+
+def ensure_artifact_layout(artifact_root: Path, pdf_stem: str) -> ArtifactLayout:
+    root = artifact_root.resolve()
+    json_dir = root / ARTIFACT_SUBDIR_JSON
+    image_dir = root / ARTIFACT_SUBDIR_IMAGE
+    pickle_dir = root / ARTIFACT_SUBDIR_PICKLE
+    text_dir = root / ARTIFACT_SUBDIR_TEXT
+    for d in (json_dir, image_dir, pickle_dir, text_dir):
+        d.mkdir(parents=True, exist_ok=True)
+    return ArtifactLayout(
+        root=root,
+        pdf_stem=pdf_stem,
+        json_dir=json_dir,
+        image_dir=image_dir,
+        pickle_dir=pickle_dir,
+        text_dir=text_dir,
+    )

chunksmith_cli/core/branding.py

@@ -0,0 +1,137 @@
+"""ChunkSmith CLI welcome banner (ASCII wordmark, no inline images)."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from rich import box
+from rich.align import Align
+from rich.console import Console, Group, RenderableType
+from rich.panel import Panel
+from rich.text import Text
+
+from chunksmith_cli.theme import MUTED, NAVY, NAVY_LIGHT, TEAL, TEAL_BRIGHT, VERSION
+
+_LOGO_PNG = Path(__file__).resolve().parent.parent / "assets" / "chunksmith_logo.png"
+_TAGLINE = "Multimodal RAG · document chunking · outline indexing"
+
+
+def logo_png_path() -> Path:
+    return _LOGO_PNG
+
+
+_WORD_GAP = "   "
+
+# Block glyphs: CHUNK (navy) + gap + SMITH (teal)
+_CHUNK_BLOCK = [
+    " ####  #    # #    # #    # #   # ",
+    "#      #    # #    # ##   # #  #  ",
+    "#      ###### #    # # #  # ###   ",
+    "#      #    # #    # #  # # #  #  ",
+    " ####  #    #  ####  #    # #   # ",
+]
+_SMITH_BLOCK = [
+    " ####  #    # ###### ###### #    # ",
+    "#      ##  ##   ##     ##   #    # ",
+    " ####  # ## #   ##     ##   ###### ",
+    "     # #    #   ##     ##   #    # ",
+    " ####  #    # ######   ##   #    # ",
+]
+_CHUNKSMITH_BLOCK = [c + _WORD_GAP + s for c, s in zip(_CHUNK_BLOCK, _SMITH_BLOCK, strict=True)]
+_CHUNK_PART_LEN = len(_CHUNK_BLOCK[0]) + len(_WORD_GAP)
+
+
+def ensure_utf8_stdio() -> None:
+    """Use UTF-8 on Windows Terminal so block glyphs render cleanly."""
+    if sys.platform != "win32":
+        return
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if not callable(reconfigure):
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+
+def _console_supports_unicode(console: Console) -> bool:
+    enc = getattr(console.file, "encoding", None) or "utf-8"
+    try:
+        for ch in "█":
+            ch.encode(enc)
+        return True
+    except (UnicodeEncodeError, LookupError):
+        return False
+
+
+def _logo_art(console: Console) -> Text:
+    """Block letters: CHUNK · SMITH (two-tone)."""
+    use_blocks = _console_supports_unicode(console)
+    out = Text()
+    for i, row in enumerate(_CHUNKSMITH_BLOCK):
+        line = row.replace("#", "█") if use_blocks else row
+        chunk_part = line[:_CHUNK_PART_LEN]
+        smith_part = line[_CHUNK_PART_LEN:]
+        if i:
+            out.append("\n")
+        out.append(chunk_part, style=f"bold {NAVY_LIGHT if i % 2 else NAVY}")
+        out.append(smith_part, style=f"bold {TEAL if i % 2 else TEAL_BRIGHT}")
+    return out
+
+
+def _brand_stack(*, subtitle: str | None, console: Console) -> RenderableType:
+    lines: list[RenderableType] = [
+        Align.center(_logo_art(console)),
+        Text(""),
+        Align.center(Text(_TAGLINE, style=f"bold {NAVY_LIGHT}")),
+        Text(""),
+        Align.center(Text(f"v{VERSION}", style=f"dim {MUTED}")),
+    ]
+    if subtitle:
+        lines.append(Align.center(Text(subtitle, style=f"italic {MUTED}")))
+    return Group(*lines)
+
+
+def print_chunksmith_banner(console: Console, *, subtitle: str | None = None) -> None:
+    """Welcome panel — ASCII wordmark only (no terminal inline images)."""
+    console.print()
+    console.print(
+        Panel(
+            _brand_stack(subtitle=subtitle, console=console),
+            border_style=TEAL,
+            box=box.ROUNDED,
+            padding=(1, 2),
+            subtitle="[dim]Interactive CLI[/dim]",
+            subtitle_align="center",
+        )
+    )
+    console.print()
+
+
+def print_session_hint(console: Console) -> None:
+    console.print(
+        Panel(
+            "[dim]Choose a mode from the menu. Type [bold red]exit[/bold red] to quit · "
+            "[bold cyan]back[/bold cyan] where shown to return.[/dim]",
+            border_style=NAVY_LIGHT,
+            box=box.SIMPLE,
+            padding=(0, 1),
+        )
+    )
+    console.print()
+
+
+def print_root_menu(console: Console) -> None:
+    from chunksmith_cli.menu import render_menu_table
+    from chunksmith_cli.menus import ROOT_MENU
+
+    render_menu_table(console, title="Start here", options=ROOT_MENU)
+
+
+def print_main_menu(console: Console) -> None:
+    from chunksmith_cli.menu import render_menu_table
+    from chunksmith_cli.menus import CHUNKING_MENU
+
+    render_menu_table(console, title="Chunking", options=CHUNKING_MENU)

chunksmith_cli/core/config.py

@@ -0,0 +1,32 @@
+"""CLI display and behavior (environment overrides)."""
+
+from __future__ import annotations
+
+import os
+
+
+def _env_truthy(name: str, *, default: bool = False) -> bool:
+    raw = os.environ.get(name, "")
+    if not str(raw).strip():
+        return default
+    return str(raw).strip().lower() in ("1", "true", "yes", "on")
+
+
+def show_images_in_terminal() -> bool:
+    """Show figure previews in agent chat (set CHUNKSMITH_CLI_SHOW_IMAGES=0 to disable)."""
+    return _env_truthy("CHUNKSMITH_CLI_SHOW_IMAGES", default=True)
+
+
+def open_images_in_viewer() -> bool:
+    """Open each figure file in the OS default viewer (Windows: Photos). CHUNKSMITH_CLI_OPEN_IMAGES=1."""
+    return _env_truthy("CHUNKSMITH_CLI_OPEN_IMAGES", default=False)
+
+
+def show_tables_in_terminal() -> bool:
+    """Allow table panels in chat (set CHUNKSMITH_CLI_SHOW_TABLES=0 to disable)."""
+    return _env_truthy("CHUNKSMITH_CLI_SHOW_TABLES", default=True)
+
+
+def show_verbose_pipeline_events() -> bool:
+    """Print low-level pipeline event names during indexing runs."""
+    return _env_truthy("CHUNKSMITH_CLI_VERBOSE_EVENTS", default=False)

chunksmith_cli/core/media_preview.py

@@ -0,0 +1,72 @@
+"""Optional PNG export for ``media_by_node`` images (CLI terminals rarely render raw bitmaps inline)."""
+
+from __future__ import annotations
+
+import base64
+import re
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+from rich.markup import escape
+from rich.panel import Panel
+
+
+def export_media_images_to_folder(
+    media_by_node: dict[str, Any],
+    dest_dir: Path,
+    *,
+    max_files: int = 8,
+) -> list[Path]:
+    """
+    Decode ``image_base64`` payloads from ``media_by_node`` values and write ``nodeId__img__*.png`` files.
+
+    Returns paths written (may be fewer than ``max_files`` if decoding fails).
+    """
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    safe_node = re.compile(r"[^a-zA-Z0-9_-]+")
+
+    for node_id, blob in media_by_node.items():
+        if len(written) >= max_files:
+            break
+        if not isinstance(blob, dict):
+            continue
+        nid = str(node_id)
+        slug = safe_node.sub("_", nid)[:40]
+        for i, img in enumerate(blob.get("images") or []):
+            if len(written) >= max_files:
+                break
+            if not isinstance(img, dict):
+                continue
+            b64 = img.get("image_base64")
+            if not isinstance(b64, str) or not b64.strip():
+                continue
+            try:
+                raw = base64.b64decode(b64, validate=False)
+            except Exception:
+                continue
+            pnum = img.get("page_number", 0)
+            out = dest_dir / f"{slug}__p{pnum}__img{i}.png"
+            try:
+                out.write_bytes(raw)
+                written.append(out)
+            except OSError:
+                continue
+    return written
+
+
+def offer_image_export_panel(console: Console, media_by_node: dict[str, Any], dest_dir: Path) -> None:
+    """Print a short panel listing exported paths (call after ``export_media_images_to_folder``)."""
+    if not dest_dir.is_dir():
+        return
+    lines = "\n".join(f"- {escape(str(p))}" for p in sorted(dest_dir.glob("*.png"))[:20])
+    if lines.strip():
+        console.print(
+            Panel(
+                lines,
+                title="[bold]Image previews (PNG on disk)[/bold]",
+                border_style="yellow",
+                expand=False,
+            )
+        )

chunksmith_cli/core/menu.py

@@ -0,0 +1,110 @@
+"""Friendly menus: one table + one prompt loop (no scattered if/else)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+from rich import box
+from rich.console import Console
+from rich.prompt import Prompt
+from rich.table import Table
+
+from chunksmith_cli.theme import NAVY, TEAL, TEAL_BRIGHT, MUTED
+
+_EXIT_KEYS = frozenset({"exit", "quit", "q"})
+
+
+@dataclass(frozen=True)
+class MenuOption:
+    key: str
+    title: str
+    detail: str = ""
+    aliases: tuple[str, ...] = ()
+
+    def matches(self, raw: str) -> bool:
+        s = (raw or "").strip().lower()
+        return s == self.key.lower() or s in self.aliases
+
+
+def is_exit(raw: str) -> bool:
+    return (raw or "").strip().lower() in _EXIT_KEYS
+
+
+def render_menu_table(
+    console: Console,
+    *,
+    title: str,
+    options: Sequence[MenuOption],
+    allow_back: bool = False,
+    hint: str | None = None,
+) -> None:
+    """Print menu table only (no prompt)."""
+    table = Table(
+        title=f"[bold]{title}[/bold]",
+        box=box.ROUNDED,
+        border_style=TEAL,
+        padding=(0, 1),
+        show_header=True,
+        header_style=f"bold {NAVY}",
+    )
+    table.add_column("", style=f"bold {TEAL_BRIGHT}", width=10, justify="center")
+    table.add_column("What", style="bold white", min_width=22)
+    table.add_column("Description", style=MUTED)
+    for opt in options:
+        table.add_row(opt.key, opt.title, opt.detail)
+    if allow_back:
+        table.add_row("back", "Go back", "Previous menu")
+    console.print(table)
+    if hint:
+        console.print(f"[dim]{hint}[/dim]")
+    labels = ", ".join(f"[cyan]{o.key}[/cyan]" for o in options)
+    if allow_back:
+        labels += ", [cyan]back[/cyan]"
+    labels += ", [bold red]exit[/bold red]"
+    console.print(f"[dim]Pick:[/dim] {labels}\n")
+
+
+def prompt_menu(
+    console: Console,
+    *,
+    title: str,
+    options: Sequence[MenuOption],
+    prompt: str = "Choice",
+    default_key: str | None = None,
+    allow_back: bool = False,
+    hint: str | None = None,
+) -> str:
+    """
+    Show a menu table and read until the input is valid.
+
+    Returns an option ``key``, ``"exit"``, or ``"back"`` (when ``allow_back``).
+    """
+    default_key = default_key or options[0].key
+    valid = {o.key for o in options}
+    render_menu_table(console, title=title, options=options, allow_back=allow_back, hint=hint)
+
+    while True:
+        raw = Prompt.ask(f"[bold #00b4a6]{prompt}[/]", default=default_key, show_default=True)
+        if is_exit(raw):
+            return "exit"
+        if allow_back and (raw or "").strip().lower() == "back":
+            return "back"
+        for opt in options:
+            if opt.matches(raw):
+                return opt.key
+        console.print(f"[yellow]Not recognized.[/yellow] Try: {', '.join(sorted(valid))} or exit.")
+
+
+def confirm_continue_session(console: Console) -> bool:
+    """``True`` = return to main menu; ``False`` = quit CLI."""
+    console.print()
+    raw = Prompt.ask(
+        "[dim]Press[/dim] [bold]Enter[/bold] [dim]for main menu · type[/dim] [bold red]exit[/bold red] [dim]to quit[/dim]",
+        default="",
+        show_default=False,
+    )
+    if is_exit(raw):
+        console.print("[dim]Goodbye.[/dim]")
+        return False
+    return True

chunksmith_cli/core/menus.py

@@ -0,0 +1,55 @@
+"""Menu definitions for the interactive CLI."""
+
+from __future__ import annotations
+
+from chunksmith_cli.menu import MenuOption
+
+ROOT_MENU: tuple[MenuOption, ...] = (
+    MenuOption(
+        "chunking",
+        "Multi-indexing",
+        "Unstructured → group-by-title → coded markup → LLM outline → mapper",
+        aliases=("c", "index"),
+    ),
+    MenuOption(
+        "view",
+        "View saved runs",
+        "Inspect outline JSON from saved runs",
+        aliases=("v", "browse"),
+    ),
+    MenuOption(
+        "agent",
+        "Document Q&A",
+        "Load a saved index and chat (legacy multimodal bundles)",
+        aliases=("a", "chat"),
+    ),
+)
+
+CHUNKING_MENU: tuple[MenuOption, ...] = (
+    MenuOption(
+        "1",
+        "Multi-indexing",
+        "Partition → group → coded markup → LLM outline → mapper (JSON or TOON)",
+        aliases=("multi", "indexing"),
+    ),
+    MenuOption(
+        "2",
+        "PageIndexer",
+        "PDF parser + LLM outline (no Unstructured partition)",
+        aliases=("pageindex", "pi"),
+    ),
+)
+
+VIEW_MENU: tuple[MenuOption, ...] = (
+    MenuOption(
+        "1",
+        "View outlines",
+        "Section tree, summary, raw JSON (read-only)",
+        aliases=("outline", "json", "tree"),
+    ),
+)
+
+AGENT_MENU: tuple[MenuOption, ...] = (
+    MenuOption("1", "Open saved index", "Enter a path or stem from saved runs"),
+    MenuOption("2", "Chat", "Ask questions about the loaded document"),
+)

chunksmith_cli/core/panels.py

@@ -0,0 +1,24 @@
+"""Shared Rich panels for the CLI."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.markup import escape
+from rich.panel import Panel
+
+
+def print_extraction_warnings_panel(console: Console, warns: Any) -> None:
+    """If ``warns`` is a non-empty list, print the yellow quality panel (PDF or replay from JSON)."""
+    if not (isinstance(warns, list) and warns):
+        return
+    body = "\n".join(escape(str(x)) for x in warns)
+    console.print(
+        Panel(
+            body,
+            title="[bold yellow]PDF text quality (heuristic)[/bold yellow]",
+            subtitle="[dim]Does not replace OCR; flags suspicious pages (from run or stored JSON).[/dim]",
+            border_style="yellow",
+        )
+    )