chunksmith-cli 0.4.0__py3-none-any.whl

chunksmith_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Interactive CLI: ChunkSmith PDF (pageindex), multimodal (Unstructured JSON + PDF), or saved JSON view."""
+
+__all__: list[str] = []

chunksmith_cli/__main__.py

@@ -0,0 +1,41 @@
+"""ChunkSmith interactive CLI — ``python -m chunksmith_cli`` or ``chunksmith``."""
+
+from __future__ import annotations
+
+import sys
+
+
+def main() -> int:
+    if len(sys.argv) > 1 and sys.argv[1] in ("--version", "-V"):
+        from chunksmith_cli.theme import VERSION
+
+        print(f"chunksmith-cli {VERSION}")
+        return 0
+
+    from chunksmith_cli.branding import ensure_utf8_stdio
+    from chunksmith_cli.theme import make_console
+    from chunksmith_cli.wizard import run_interactive
+
+    ensure_utf8_stdio()
+    console = make_console()
+
+    try:
+        return run_interactive(console)
+    except KeyboardInterrupt:
+        console.print("\n[dim]Interrupted. Goodbye.[/dim]")
+        return 130
+
+
+def __version__() -> str:
+    from chunksmith_cli.theme import VERSION as v
+
+    return v
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1 and sys.argv[1] in ("--version", "-V"):
+        from chunksmith_cli.theme import VERSION
+
+        print(f"chunksmith-cli {VERSION}")
+        raise SystemExit(0)
+    raise SystemExit(main())

chunksmith_cli/agent/__init__.py

@@ -0,0 +1 @@
+"""LangChain agent over saved ChunkSmith indexes."""

chunksmith_cli/agent/agent_display.py

@@ -0,0 +1,160 @@
+"""Render tables and figures from agent events in the terminal."""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from html import unescape
+from pathlib import Path
+from typing import Any
+
+from rich.align import Align
+from rich.console import Console
+from rich.markup import escape
+from rich.panel import Panel
+
+from chunksmith_cli.config import open_images_in_viewer, show_images_in_terminal, show_tables_in_terminal
+
+try:
+    from rich.image import Image as RichImage
+except ImportError:  # pragma: no cover
+    RichImage = None  # type: ignore[misc, assignment]
+
+
+def html_table_preview(html: str, *, max_len: int = 2400) -> str:
+    """Plain-text preview of HTML table content for terminal display."""
+    text = re.sub(r"<br\s*/?>", "\n", html or "", flags=re.IGNORECASE)
+    text = re.sub(r"</t[rdh]>", "\t", text, flags=re.IGNORECASE)
+    text = re.sub(r"<[^>]+>", "", text)
+    text = unescape(text)
+    text = re.sub(r"[ \t\f\v]+", " ", text)
+    text = re.sub(r" *\n *", "\n", text)
+    text = re.sub(r"\n{3,}", "\n\n", text).strip()
+    if len(text) > max_len:
+        return text[:max_len] + "\n…"
+    return text or "(empty table)"
+
+
+def print_table(console: Console, payload: dict[str, Any]) -> None:
+    nid = payload.get("node_id")
+    pg = payload.get("page_number")
+    preview = html_table_preview(str(payload.get("html") or ""))
+    title = f"[bold yellow]Table[/bold yellow] · node {escape(str(nid or '?'))} · page {escape(str(pg or '?'))}"
+    console.print(Panel(escape(preview), title=title, border_style="yellow"))
+
+
+def _open_image_file(path: Path) -> bool:
+    """Open image in the system default viewer (Windows/macOS/Linux)."""
+    if not path.is_file():
+        return False
+    try:
+        if sys.platform == "win32":
+            os.startfile(str(path))  # noqa: S606
+        elif sys.platform == "darwin":
+            os.system(f'open "{path}"')  # noqa: S605
+        else:
+            os.system(f'xdg-open "{path}"')  # noqa: S605
+        return True
+    except OSError:
+        return False
+
+
+def print_figure(console: Console, payload: dict[str, Any]) -> None:
+    path = payload.get("path")
+    pg = payload.get("page_number")
+    nid = payload.get("node_id")
+    caption = f"node {nid} · page {pg}"
+    path_str = str(path or "").strip()
+    file_path = Path(path_str) if path_str else None
+    rendered_inline = False
+
+    if file_path and file_path.is_file() and RichImage is not None:
+        try:
+            img = RichImage.from_file(str(file_path), width=min(72, max(40, console.width - 4)))
+            console.print(
+                Panel(
+                    Align.center(img),
+                    title=f"[bold cyan]Figure[/bold cyan] · {escape(caption)}",
+                    border_style="cyan",
+                )
+            )
+            rendered_inline = True
+        except Exception:
+            rendered_inline = False
+
+    if rendered_inline:
+        console.print(f"[dim]{escape(path_str)}[/dim]\n")
+        if open_images_in_viewer():
+            _open_image_file(file_path)
+        return
+
+    hint = "[dim]Inline image preview is not supported in this terminal (common on Windows PowerShell).[/dim]\n"
+    if file_path and file_path.is_file():
+        if sys.platform == "win32":
+            hint += f'[dim]Open manually:[/dim] start "" {escape(path_str)}\n'
+        if open_images_in_viewer():
+            if _open_image_file(file_path):
+                hint += "[green]Opened in your default image viewer.[/green]\n"
+        elif sys.platform == "win32":
+            hint += (
+                "[dim]Tip: set[/dim] [bold]CHUNKSMITH_CLI_OPEN_IMAGES=1[/bold] "
+                "[dim]to auto-open figures in Photos.[/dim]\n"
+            )
+    else:
+        hint += "[yellow]Image file not found on disk.[/yellow]\n"
+
+    console.print(
+        Panel(
+            f"{hint}\n[bold]{escape(path_str or '(no image path)')}[/bold]",
+            title=f"[bold cyan]Figure file[/bold cyan] · {escape(caption)}",
+            border_style="cyan",
+        )
+    )
+    console.print()
+
+
+def print_tables_summary(console: Console, count: int) -> None:
+    if count:
+        console.print(f"[dim]Tables in context:[/dim] {count}\n")
+
+
+def print_figures_summary(console: Console, count: int) -> None:
+    if count:
+        console.print(f"[dim]Figures in context:[/dim] {count}\n")
+
+
+def print_media_mentions(console: Console, payload: dict[str, Any]) -> None:
+    hint = str(payload.get("hint") or "").strip()
+    if hint:
+        console.print(Panel(escape(hint), title="[bold yellow]Media[/bold yellow]", border_style="yellow"))
+
+    figures = payload.get("figures") or []
+    if figures and show_images_in_terminal():
+        lines = [
+            f"• [dim]node {escape(str(f.get('node_id') or '?'))}[/dim] — {escape(str(f.get('caption') or ''))}"
+            for f in figures[:12]
+        ]
+        console.print(
+            Panel(
+                "\n".join(lines),
+                title="[bold cyan]Figures mentioned in text[/bold cyan]",
+                border_style="cyan",
+            )
+        )
+
+    tables = payload.get("tables") or []
+    if tables and show_tables_in_terminal():
+        lines = [
+            f"• [dim]node {escape(str(t.get('node_id') or '?'))}[/dim] — {escape(str(t.get('caption') or ''))}"
+            for t in tables[:12]
+        ]
+        console.print(
+            Panel(
+                "\n".join(lines),
+                title="[bold yellow]Tables mentioned in text[/bold yellow]",
+                border_style="yellow",
+            )
+        )
+    if figures or tables:
+        console.print()

chunksmith_cli/agent/agent_session.py

@@ -0,0 +1,294 @@
+"""Agent CLI session state and actions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+from rich.console import Console
+from rich.markup import escape
+from rich.prompt import Confirm, Prompt
+
+from chunksmith_cli.agent_stream import handle_agent_event
+from chunksmith_cli.menu import prompt_menu
+from chunksmith_cli.menus import AGENT_MENU
+from chunksmith_cli.paths import (
+    default_project_logs_dir,
+    ensure_cli_storage,
+    resolve_agent_index_input,
+)
+
+
+def _index_media_counts(doc_index: Any) -> tuple[int, int]:
+    from chunksmith_agent.index_context import index_media_counts
+
+    return index_media_counts(doc_index)
+
+
+def _media_loaded_line(doc_index: Any) -> str:
+    """Counts shown on the main Loaded / Ready line."""
+    n_tables, n_images = _index_media_counts(doc_index)
+    if n_tables or n_images:
+        return (
+            f"[dim]·[/dim] [bold cyan]{n_tables}[/bold cyan] tables loaded "
+            f"[dim]·[/dim] [bold cyan]{n_images}[/bold cyan] figures loaded"
+        )
+    return "[dim]· 0 tables · 0 figures (text-only index)[/dim]"
+
+
+def _print_index_media_hint(console: Console, doc_index: Any) -> None:
+    from rich.panel import Panel
+
+    from chunksmith_agent.index_context import index_media_inventory
+
+    n_tables, n_images = _index_media_counts(doc_index)
+    table_lines, figure_lines = index_media_inventory(doc_index)
+    extra_tables = max(0, n_tables - len(table_lines))
+    extra_figures = max(0, n_images - len(figure_lines))
+
+    if n_tables or n_images:
+        body_parts = [
+            f"[bold yellow]Tables loaded:[/bold yellow]  [bold]{n_tables}[/bold]",
+        ]
+        if table_lines:
+            body_parts.append("\n".join(escape(line) for line in table_lines))
+            if extra_tables:
+                body_parts.append(f"[dim]… and {extra_tables} more table(s)[/dim]")
+        else:
+            body_parts.append("[dim](none)[/dim]")
+
+        body_parts.append(f"\n[bold cyan]Figures loaded:[/bold cyan] [bold]{n_images}[/bold]")
+        if figure_lines:
+            body_parts.append("\n".join(escape(line) for line in figure_lines))
+            if extra_figures:
+                body_parts.append(f"[dim]… and {extra_figures} more figure(s)[/dim]")
+        else:
+            body_parts.append("[dim](none)[/dim]")
+
+        body_parts.append(
+            "\n[dim]In chat, tables/figures show after search (sections in Sources, up to 3 each). "
+            "Windows PowerShell often shows [bold]paths only[/bold], not inline pictures — set "
+            "[bold]CHUNKSMITH_CLI_OPEN_IMAGES=1[/bold] to open PNGs in Photos.[/dim]"
+        )
+        console.print(
+            Panel(
+                "\n".join(body_parts),
+                title="[bold green]Loaded from JSON[/bold green]",
+                border_style="green",
+            )
+        )
+        console.print()
+        return
+    console.print(
+        Panel(
+            "[bold]Tables loaded:[/bold]  0\n"
+            "[bold]Figures loaded:[/bold] 0\n\n"
+            "[dim]This JSON has outline/text only. For tables and images, index with "
+            "load a [bold]*_canonical_bundle.json[/bold] or use [bold]chunking → Multimodal index[/bold].[/dim]",
+            title="[bold yellow]Text-only index[/bold yellow]",
+            border_style="yellow",
+        )
+    )
+    console.print()
+
+
+@dataclass
+class AgentCliState:
+    agent: Any | None = None
+    loaded_name: str | None = None
+
+    @property
+    def is_ready(self) -> bool:
+        return self.agent is not None
+
+    def status_line(self) -> str:
+        if not self.is_ready:
+            return "[dim]No document loaded yet — pick option 1 to open a saved index.[/dim]"
+        n = len(self.agent.index.media_by_node)
+        media = _media_loaded_line(self.agent.index)
+        return (
+            f"[green]Ready:[/green] [bold]{escape(self.loaded_name or 'index')}[/bold] [dim]({n} nodes)[/dim] {media}"
+        )
+
+
+def _find_saved_indexes(storage: Path) -> list[dict[str, str]]:
+    rows: list[dict[str, str]] = []
+    seen: set[str] = set()
+
+    def _add(*, stem: str, pageindex: str, canonical: str, source: str) -> None:
+        if stem in seen:
+            return
+        seen.add(stem)
+        rows.append(
+            {
+                "stem": stem,
+                "pageindex": pageindex,
+                "canonical": canonical,
+                "source": source,
+            }
+        )
+
+    for p in sorted(storage.glob("*_pageindex.json"), reverse=True):
+        stem = p.name.replace("_pageindex.json", "")
+        cb = storage / f"{stem}_canonical_bundle.json"
+        _add(
+            stem=stem,
+            pageindex=str(p),
+            canonical=str(cb) if cb.is_file() else "",
+            source="cli/data",
+        )
+
+    logs = default_project_logs_dir()
+    if logs is not None:
+        json_dir = logs / "json"
+        if json_dir.is_dir():
+            for cb in sorted(json_dir.glob("*_canonical_bundle.json"), reverse=True):
+                stem = cb.name.replace("_canonical_bundle.json", "")
+                pi = json_dir / f"{stem}_pageindex.json"
+                _add(
+                    stem=stem,
+                    pageindex=str(pi) if pi.is_file() else "",
+                    canonical=str(cb),
+                    source="logs",
+                )
+    return rows
+
+
+def _load_saved(console: Console, state: AgentCliState, storage: Path) -> None:
+    from chunksmith_agent import ChunkSmithAgent
+    from chunksmith_agent.index_builder import build_document_index_from_saved
+
+    rows = _find_saved_indexes(storage)
+    logs_hint = ""
+    logs = default_project_logs_dir()
+    if logs is not None:
+        logs_hint = f"\n  [cyan]{logs}[/cyan]  [dim](artifact folder → newest bundle + images)[/dim]"
+    console.print(
+        f"\n[bold]Load saved index[/bold]\n"
+        f"[dim]Enter a path, artifact folder, or stem. Examples:[/dim]\n"
+        f"  [cyan]{storage / 'mydoc_20260517T120000Z_pageindex.json'}[/cyan]\n"
+        f"  [cyan]logs[/cyan] or [cyan]logs/json/mydoc_*_canonical_bundle.json[/cyan]"
+        f"{logs_hint}\n"
+        f"  [cyan]mydoc_20260517T120000Z[/cyan]\n"
+        f"[dim]Empty line = pick from list · quotes and ~ supported[/dim]\n"
+    )
+    if rows:
+        console.print("[dim]Recent indexes:[/dim]")
+        for i, r in enumerate(rows[:8], start=1):
+            tag = f" [dim]({r['source']})[/dim]" if r.get("source") else ""
+            console.print(f"  [cyan]{i:>2}[/]  {escape(r['stem'])}{tag}")
+
+    while True:
+        raw = Prompt.ask(
+            "[bold]Index path or stem[/bold]",
+            default="",
+            show_default=False,
+        ).strip()
+
+        if not raw and rows:
+            pick = Prompt.ask("[bold]Or pick number[/bold]", default="1")
+            try:
+                row = rows[int(pick) - 1]
+            except (ValueError, IndexError):
+                console.print("[red]Invalid number.[/red]")
+                continue
+            resolved_pageindex = Path(row["pageindex"])
+            resolved_canonical = Path(row["canonical"]) if row["canonical"] else None
+            label = row["stem"]
+            break
+
+        if not raw:
+            console.print("[dim]Cancelled.[/dim]")
+            return
+
+        resolved = resolve_agent_index_input(raw, storage=storage)
+        if resolved is None:
+            console.print(
+                "[yellow]Could not find a valid index at that path.[/yellow]\n"
+                "[dim]Use an artifact folder (``logs`` with ``json/`` + ``image/``), a "
+                "``*_canonical_bundle.json``, ``*_pageindex.json``, or a stem.[/dim]\n"
+            )
+            continue
+
+        resolved_pageindex = resolved.pageindex_path
+        resolved_canonical = resolved.canonical_bundle_path
+        label = resolved.label
+        break
+
+    try:
+        doc_index = build_document_index_from_saved(
+            pageindex_path=resolved_pageindex,
+            canonical_bundle_path=resolved_canonical,
+            artifact_root=resolved.artifact_root,
+        )
+    except Exception as e:
+        console.print(f"[bold red]Load failed:[/bold red] {e}")
+        return
+
+    state.agent = ChunkSmithAgent(doc_index)
+    state.agent.reset_conversation()
+    state.loaded_name = label
+    console.print(f"\n[bold green]Loaded.[/bold green] {state.status_line()}\n")
+    _print_index_media_hint(console, doc_index)
+    if Confirm.ask("[bold]Start chatting now?[/bold]", default=True):
+        _chat_loop(console, state)
+
+
+def _chat_loop(console: Console, state: AgentCliState) -> None:
+    if not state.is_ready:
+        console.print("[yellow]Load a document first (option 1 — open saved index).[/yellow]")
+        return
+
+    console.print(
+        f"\n[dim]Chatting about[/dim] [bold]{escape(state.loaded_name or 'document')}[/bold]. "
+        "[dim]Type[/dim] [bold]exit[/bold] [dim]to return to the agent menu.[/dim]\n"
+    )
+    while True:
+        q = Prompt.ask("[bold #00b4a6]You[/]").strip()
+        if not q:
+            continue
+        if q.lower() in ("exit", "quit", "q", "back"):
+            console.print("[dim]Back to agent menu.[/dim]\n")
+            break
+        console.print()
+        for _ in state.agent.ask_events(
+            q,
+            event_sink=lambda n, p: handle_agent_event(console, n, p),
+            emit_image_events=True,
+            emit_table_events=True,
+        ):
+            pass
+        console.print()
+
+
+_AGENT_ACTIONS: dict[str, Callable[[Console, AgentCliState, Path], None]] = {
+    "1": lambda c, s, st: _load_saved(c, s, st),
+    "2": lambda c, s, st: _chat_loop(c, s),
+}
+
+
+def run_agent_session(console: Console) -> int:
+    state = AgentCliState()
+    storage = ensure_cli_storage()
+
+    while True:
+        console.print()
+        console.print(state.status_line())
+        choice = prompt_menu(
+            console,
+            title="ChunkSmith Agent",
+            options=AGENT_MENU,
+            prompt="What next",
+            default_key="2" if state.is_ready else "1",
+            allow_back=True,
+            hint="Option 2 (chat) needs a loaded index — use option 1 first.",
+        )
+        if choice == "exit":
+            return 0
+        if choice == "back":
+            return 0
+
+        action = _AGENT_ACTIONS.get(choice)
+        if action:
+            action(console, state, storage)

chunksmith_cli/agent/agent_stream.py

@@ -0,0 +1,152 @@
+"""Render ChunkSmith agent events in the terminal (search, thinking, answer)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.markup import escape
+from rich.panel import Panel
+from rich.rule import Rule
+
+from chunksmith_cli.agent_display import (
+    print_figure,
+    print_figures_summary,
+    print_media_mentions,
+    print_table,
+    print_tables_summary,
+)
+from chunksmith_cli.config import show_images_in_terminal, show_tables_in_terminal
+from chunksmith_cli.theme import TEAL
+
+_streamed_thinking = False
+_thinking_header_printed = False
+
+
+def _reset_agent_stream_state() -> None:
+    global _streamed_thinking, _thinking_header_printed
+    _streamed_thinking = False
+    _thinking_header_printed = False
+
+
+def handle_agent_event(console: Console, name: str, payload: dict[str, Any]) -> None:
+    """Print one agent event."""
+    global _streamed_thinking, _thinking_header_printed
+
+    if name == "agent:connected":
+        _reset_agent_stream_state()
+        console.print(Rule("[bold]ChunkSmith Agent[/bold]", style=TEAL))
+        return
+
+    if name == "agent:search_start":
+        q = escape(str(payload.get("query", "")))
+        if payload.get("reused"):
+            hint = escape(str(payload.get("hint") or "Using the same sections as your last question."))
+            console.print(
+                Panel(
+                    f"{q}\n\n[dim]{hint}[/dim]",
+                    title="[bold cyan]Your question[/bold cyan]",
+                    border_style="cyan",
+                )
+            )
+            return
+        console.print(
+            Panel(
+                q,
+                title="[bold cyan]Your question[/bold cyan]",
+                border_style="cyan",
+            )
+        )
+        return
+
+    if name == "agent:thinking":
+        if _streamed_thinking:
+            console.print()
+            _thinking_header_printed = False
+            return
+        text = str(payload.get("text") or "").strip()
+        phase = escape(str(payload.get("phase", "selection")))
+        if text:
+            console.print(
+                Panel(
+                    escape(text),
+                    title=f"[bold magenta]Reasoning — {phase}[/bold magenta]",
+                    border_style="magenta",
+                )
+            )
+        return
+
+    if name == "agent:thinking_token":
+        ch = payload.get("chunk") or ""
+        if not ch:
+            return
+        if not _thinking_header_printed:
+            console.print("\n[bold magenta]Reasoning[/bold magenta]")
+            _thinking_header_printed = True
+        _streamed_thinking = True
+        console.print(f"[magenta]{escape(str(ch))}[/magenta]", end="", highlight=False)
+        return
+
+    if name == "agent:search_complete":
+        if payload.get("reused"):
+            console.print("[dim]No new section search (follow-up / similar question).[/dim]\n")
+            return
+        sources = payload.get("sources") or []
+        nids = payload.get("node_ids") or []
+        lines = [
+            f"• {escape(str(s))} [dim](node {escape(str(nids[i]) if i < len(nids) else '?')})[/dim]"
+            for i, s in enumerate(sources[:12])
+        ]
+        if len(sources) > 12:
+            lines.append(f"[dim]… and {len(sources) - 12} more[/dim]")
+        console.print(
+            Panel(
+                "\n".join(lines) if lines else "[dim]No sections matched.[/dim]",
+                title=f"[bold green]Sources[/bold green] · {payload.get('chunks_count', 0)} sections",
+                border_style="green",
+            )
+        )
+        console.print()
+        return
+
+    if name == "agent:tables_found":
+        if show_tables_in_terminal():
+            print_tables_summary(console, int(payload.get("count") or 0))
+        return
+
+    if name == "agent:table":
+        if show_tables_in_terminal():
+            print_table(console, payload)
+        return
+
+    if name == "agent:images_found":
+        if show_images_in_terminal():
+            print_figures_summary(console, int(payload.get("count") or 0))
+        return
+
+    if name == "agent:image":
+        if show_images_in_terminal():
+            print_figure(console, payload)
+        return
+
+    if name == "agent:media_mentions":
+        print_media_mentions(console, payload)
+        return
+
+    if name == "agent:response_start":
+        console.print(Rule("[bold]Answer[/bold]", style="blue"))
+        return
+
+    if name == "agent:token":
+        ch = payload.get("content") or ""
+        if ch:
+            console.print(str(ch), end="", highlight=False)
+        return
+
+    if name == "agent:complete":
+        console.print()
+        return
+
+    if name == "agent:end":
+        console.print(Rule(style="dim"))
+        return

chunksmith_cli/agent/agent_wizard.py

@@ -0,0 +1,5 @@
+"""Backward-compatible entry; implementation lives in ``agent_session``."""
+
+from chunksmith_cli.agent_session import run_agent_session
+
+__all__ = ["run_agent_session"]

chunksmith_cli/agent_display.py

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

chunksmith_cli/agent_session.py

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

chunksmith_cli/agent_stream.py

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

chunksmith_cli/agent_wizard.py

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