offagent 0.10.0__py3-none-any.whl

offagent/interfaces/__init__.py

@@ -0,0 +1 @@
+"""Interface adapters."""

offagent/interfaces/cli.py

@@ -0,0 +1,438 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+from offagent.app.progress import NullProgressReporter
+from offagent.app.services import (
+    AppServices,
+)
+from offagent.config import load_config
+from offagent.errors import (
+    InvalidArgumentsError,
+    PolicyRefusedError,
+    StaleLocatorError,
+    TargetNotEditableError,
+    TargetNotFoundError,
+)
+from offagent.interfaces.cli_output import (
+    emit_output,
+    render_doctor_report,
+    render_document,
+    render_documents,
+    render_index_summary,
+    render_item,
+    render_items,
+    render_patch_result,
+    render_search_hits,
+    render_text_result,
+)
+
+try:
+    import typer
+except ModuleNotFoundError:  # pragma: no cover - covered indirectly by doctor
+    typer = None
+
+if typer is not None:
+    CONFIG_OPTION = typer.Option(
+        "--config",
+        help="Optional path to an office-agent TOML configuration file.",
+        dir_okay=False,
+        resolve_path=False,
+    )
+else:  # pragma: no cover - exercised only when typer is unavailable
+    CONFIG_OPTION = None
+
+if typer is not None:
+    JSON_OPTION = typer.Option(
+        "--json",
+        help="Emit machine-readable JSON with no extra text.",
+    )
+    QUIET_OPTION = typer.Option(
+        "--quiet",
+        help="Suppress successful command output.",
+    )
+else:  # pragma: no cover - exercised only when typer is unavailable
+    JSON_OPTION = None
+    QUIET_OPTION = None
+
+
+def main() -> None:
+    if typer is None:
+        raise SystemExit(
+            "Typer is required to run the office-agent CLI. Install project dependencies first."
+        )
+
+    build_app()(prog_name="office-agent")
+
+
+def build_app():
+    if typer is None:
+        raise RuntimeError("Typer is unavailable.")
+
+    app = typer.Typer(help="Local-first Office document tooling.")
+
+    @app.callback()
+    def main_callback() -> None:
+        """Root command group for office-agent."""
+
+    @app.command()
+    def doctor(
+        config: Annotated[Path | None, CONFIG_OPTION] = None,
+        as_json: Annotated[bool, JSON_OPTION] = False,
+        quiet: Annotated[bool, QUIET_OPTION] = False,
+    ) -> None:
+        settings = load_config(config)
+        services = AppServices(settings)
+        report = _run_command(
+            lambda: services.run_doctor(), as_json=as_json, quiet=quiet
+        )
+        emit_output(
+            report,
+            as_json=as_json,
+            quiet=quiet,
+            human_renderer=render_doctor_report,
+            echo=typer.echo,
+        )
+        raise typer.Exit(code=0 if report.ok else 1)
+
+    @app.command("index")
+    def index_command(
+        path: Path,
+        with_embeddings: Annotated[bool, typer.Option("--with-embeddings")] = False,
+        config: Annotated[Path | None, CONFIG_OPTION] = None,
+        as_json: Annotated[bool, JSON_OPTION] = False,
+        quiet: Annotated[bool, QUIET_OPTION] = False,
+    ) -> None:
+        services = AppServices(load_config(config))
+
+        def runner() -> None:
+            with _build_index_reporter(as_json=as_json, quiet=quiet) as reporter:
+                summary = services.index_path(
+                    path,
+                    with_embeddings=with_embeddings,
+                    reporter=reporter,
+                )
+            emit_output(
+                {
+                    "path": path.resolve(),
+                    "summary": summary,
+                },
+                as_json=as_json,
+                quiet=quiet,
+                human_renderer=render_index_summary,
+                echo=typer.echo,
+            )
+
+        _run_command(
+            runner,
+            as_json=as_json,
+            quiet=quiet,
+        )
+
+    @app.command("reindex")
+    def reindex_command(
+        path: Path,
+        with_embeddings: Annotated[bool, typer.Option("--with-embeddings")] = False,
+        config: Annotated[Path | None, CONFIG_OPTION] = None,
+        as_json: Annotated[bool, JSON_OPTION] = False,
+        quiet: Annotated[bool, QUIET_OPTION] = False,
+    ) -> None:
+        services = AppServices(load_config(config))
+
+        def runner() -> None:
+            with _build_index_reporter(as_json=as_json, quiet=quiet) as reporter:
+                summary = services.reindex_path(
+                    path,
+                    with_embeddings=with_embeddings,
+                    reporter=reporter,
+                )
+            emit_output(
+                {
+                    "path": path.resolve(),
+                    "summary": summary,
+                },
+                as_json=as_json,
+                quiet=quiet,
+                human_renderer=render_index_summary,
+                echo=typer.echo,
+            )
+
+        _run_command(
+            runner,
+            as_json=as_json,
+            quiet=quiet,
+        )
+
+    @app.command()
+    def search(
+        query: str,
+        file_type: Annotated[str | None, typer.Option("--type")] = None,
+        doc: Annotated[Path | None, typer.Option("--doc")] = None,
+        mode: Annotated[str, typer.Option("--mode")] = "keyword",
+        config: Annotated[Path | None, CONFIG_OPTION] = None,
+        as_json: Annotated[bool, JSON_OPTION] = False,
+        quiet: Annotated[bool, QUIET_OPTION] = False,
+    ) -> None:
+        services = AppServices(load_config(config))
+
+        def runner() -> None:
+            hits = services.search_corpus(
+                query,
+                file_type=file_type,
+                document_path=doc,
+                mode=mode,
+            )
+            emit_output(
+                {"hits": hits},
+                as_json=as_json,
+                quiet=quiet,
+                human_renderer=lambda payload: render_search_hits(payload["hits"]),
+                echo=typer.echo,
+            )
+
+        _run_command(runner, as_json=as_json, quiet=quiet)
+
+    @app.command()
+    def locate(
+        doc: Annotated[Path, typer.Option("--doc")],
+        paragraph: Annotated[int | None, typer.Option("--paragraph")] = None,
+        slide: Annotated[int | None, typer.Option("--slide")] = None,
+        shape: Annotated[int | None, typer.Option("--shape")] = None,
+        sheet: Annotated[str | None, typer.Option("--sheet")] = None,
+        cell: Annotated[str | None, typer.Option("--cell")] = None,
+        config: Annotated[Path | None, CONFIG_OPTION] = None,
+        as_json: Annotated[bool, JSON_OPTION] = False,
+        quiet: Annotated[bool, QUIET_OPTION] = False,
+    ) -> None:
+        services = AppServices(load_config(config))
+
+        def runner() -> None:
+            items = services.locate_items(
+                doc,
+                paragraph_index=paragraph,
+                slide_number=slide,
+                shape_id=shape,
+                sheet_name=sheet,
+                cell_coordinate=cell,
+            )
+            emit_output(
+                {"items": items},
+                as_json=as_json,
+                quiet=quiet,
+                human_renderer=lambda payload: render_items(payload["items"]),
+                echo=typer.echo,
+            )
+
+        _run_command(runner, as_json=as_json, quiet=quiet)
+
+    @app.command()
+    def read(
+        doc: Annotated[Path, typer.Option("--doc")],
+        item: Annotated[str, typer.Option("--item")],
+        config: Annotated[Path | None, CONFIG_OPTION] = None,
+        as_json: Annotated[bool, JSON_OPTION] = False,
+        quiet: Annotated[bool, QUIET_OPTION] = False,
+    ) -> None:
+        services = AppServices(load_config(config))
+        _run_command(
+            lambda: emit_output(
+                {
+                    "document_path": doc.resolve(),
+                    "item_id": item,
+                    "text": services.read_item(doc, item),
+                },
+                as_json=as_json,
+                quiet=quiet,
+                human_renderer=render_text_result,
+                echo=typer.echo,
+            ),
+            as_json=as_json,
+            quiet=quiet,
+        )
+
+    @app.command()
+    def replace(
+        doc: Annotated[Path, typer.Option("--doc")],
+        item: Annotated[str, typer.Option("--item")],
+        text: Annotated[str, typer.Option("--text")],
+        output_mode: Annotated[str, typer.Option("--output-mode")] = "versioned",
+        config: Annotated[Path | None, CONFIG_OPTION] = None,
+        as_json: Annotated[bool, JSON_OPTION] = False,
+        quiet: Annotated[bool, QUIET_OPTION] = False,
+    ) -> None:
+        services = AppServices(load_config(config))
+        _run_command(
+            lambda: emit_output(
+                services.replace_item_text(doc, item, text, output_mode=output_mode),
+                as_json=as_json,
+                quiet=quiet,
+                human_renderer=render_patch_result,
+                echo=typer.echo,
+            ),
+            as_json=as_json,
+            quiet=quiet,
+        )
+
+    @app.command()
+    def append(
+        doc: Annotated[Path, typer.Option("--doc")],
+        item: Annotated[str, typer.Option("--item")],
+        text: Annotated[str, typer.Option("--text")],
+        output_mode: Annotated[str, typer.Option("--output-mode")] = "versioned",
+        config: Annotated[Path | None, CONFIG_OPTION] = None,
+        as_json: Annotated[bool, JSON_OPTION] = False,
+        quiet: Annotated[bool, QUIET_OPTION] = False,
+    ) -> None:
+        services = AppServices(load_config(config))
+        _run_command(
+            lambda: emit_output(
+                services.append_item_text(doc, item, text, output_mode=output_mode),
+                as_json=as_json,
+                quiet=quiet,
+                human_renderer=render_patch_result,
+                echo=typer.echo,
+            ),
+            as_json=as_json,
+            quiet=quiet,
+        )
+
+    @app.command("write-cell")
+    def write_cell(
+        doc: Annotated[Path, typer.Option("--doc")],
+        sheet: Annotated[str, typer.Option("--sheet")],
+        cell: Annotated[str, typer.Option("--cell")],
+        value: Annotated[str, typer.Option("--value")],
+        output_mode: Annotated[str, typer.Option("--output-mode")] = "versioned",
+        config: Annotated[Path | None, CONFIG_OPTION] = None,
+        as_json: Annotated[bool, JSON_OPTION] = False,
+        quiet: Annotated[bool, QUIET_OPTION] = False,
+    ) -> None:
+        services = AppServices(load_config(config))
+        _run_command(
+            lambda: emit_output(
+                services.write_cell_value(
+                    doc, sheet, cell, value, output_mode=output_mode
+                ),
+                as_json=as_json,
+                quiet=quiet,
+                human_renderer=render_patch_result,
+                echo=typer.echo,
+            ),
+            as_json=as_json,
+            quiet=quiet,
+        )
+
+    @app.command("list")
+    def list_command(
+        config: Annotated[Path | None, CONFIG_OPTION] = None,
+        as_json: Annotated[bool, JSON_OPTION] = False,
+        quiet: Annotated[bool, QUIET_OPTION] = False,
+    ) -> None:
+        services = AppServices(load_config(config))
+        _run_command(
+            lambda: emit_output(
+                {"documents": services.list_documents()},
+                as_json=as_json,
+                quiet=quiet,
+                human_renderer=lambda payload: render_documents(payload["documents"]),
+                echo=typer.echo,
+            ),
+            as_json=as_json,
+            quiet=quiet,
+        )
+
+    @app.command()
+    def show(
+        doc: Annotated[Path, typer.Option("--doc")],
+        item: Annotated[str | None, typer.Option("--item")] = None,
+        config: Annotated[Path | None, CONFIG_OPTION] = None,
+        as_json: Annotated[bool, JSON_OPTION] = False,
+        quiet: Annotated[bool, QUIET_OPTION] = False,
+    ) -> None:
+        services = AppServices(load_config(config))
+
+        def runner() -> None:
+            if item is None:
+                emit_output(
+                    services.show_document(doc),
+                    as_json=as_json,
+                    quiet=quiet,
+                    human_renderer=render_document,
+                    echo=typer.echo,
+                )
+                return
+            emit_output(
+                services.show_item(doc, item),
+                as_json=as_json,
+                quiet=quiet,
+                human_renderer=render_item,
+                echo=typer.echo,
+            )
+
+        _run_command(runner, as_json=as_json, quiet=quiet)
+
+    @app.command()
+    def mcp(
+        config: Annotated[Path | None, CONFIG_OPTION] = None,
+    ) -> None:
+        settings = load_config(config)
+
+        def runner() -> None:
+            from offagent.interfaces.mcp import run_mcp_server
+
+            run_mcp_server(settings)
+
+        _run_command(runner)
+
+    return app
+
+
+def _run_command(callback, *, as_json: bool = False, quiet: bool = False):
+    if typer is None:
+        raise RuntimeError("Typer is unavailable.")
+
+    try:
+        _validate_output_flags(as_json, quiet)
+        return callback()
+    except InvalidArgumentsError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=2) from exc
+    except (FileNotFoundError, TargetNotFoundError, StaleLocatorError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=3) from exc
+    except TargetNotEditableError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=4) from exc
+    except PolicyRefusedError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=5) from exc
+    except RuntimeError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+
+
+def _validate_output_flags(as_json: bool, quiet: bool) -> None:
+    if as_json and quiet:
+        raise InvalidArgumentsError("Choose either --json or --quiet, not both.")
+
+
+def _build_index_reporter(*, as_json: bool, quiet: bool):
+    if quiet or as_json or not _stderr_supports_live_progress():
+        return NullProgressReporter()
+    return _rich_progress_reporter_class()()
+
+
+def _stderr_supports_live_progress() -> bool:
+    return sys.stderr.isatty()
+
+
+def _rich_progress_reporter_class():
+    try:
+        from offagent.interfaces.cli_progress import RichProgressReporter
+    except ModuleNotFoundError as exc:
+        raise RuntimeError(
+            "Rich is required to render indexing progress. Install project dependencies first."
+        ) from exc
+    return RichProgressReporter

offagent/interfaces/cli_output.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, is_dataclass
+from pathlib import Path
+from typing import Any, Callable, Sequence
+
+from offagent.app.services import DoctorReport, IndexSummary, PatchResult
+from offagent.domain.models import DocumentRef, ItemRef, SearchHit
+
+
+def emit_output(
+    payload: Any,
+    *,
+    as_json: bool,
+    quiet: bool,
+    human_renderer: Callable[[Any], str],
+    echo: Callable[[str], None],
+) -> None:
+    if quiet:
+        return
+    if as_json:
+        echo(json.dumps(to_jsonable(payload), indent=2, sort_keys=True))
+        return
+    echo(human_renderer(payload))
+
+
+def to_jsonable(value: Any) -> Any:
+    if isinstance(value, DoctorReport):
+        return {"ok": value.ok, "checks": to_jsonable(value.checks)}
+    if is_dataclass(value):
+        return to_jsonable(asdict(value))
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, dict):
+        return {key: to_jsonable(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [to_jsonable(item) for item in value]
+    return value
+
+
+def render_doctor_report(report: DoctorReport) -> str:
+    lines = ["Doctor Report"]
+    for check in report.checks:
+        status = "PASS" if check.ok else "FAIL"
+        lines.append(f"[{status}] {check.name}: {check.detail}")
+    lines.append("All checks passed." if report.ok else "One or more checks failed.")
+    return "\n".join(lines)
+
+
+def render_index_summary(payload: dict[str, Any]) -> str:
+    path = payload["path"]
+    summary: IndexSummary = payload["summary"]
+    return (
+        f"path={path}\tfiles_scanned={summary.files_scanned}\tfiles_indexed={summary.files_indexed}"
+        f"\tfiles_skipped={summary.files_skipped}"
+    )
+
+
+def render_search_hits(hits: Sequence[SearchHit]) -> str:
+    if not hits:
+        return "No matches found."
+    lines: list[str] = []
+    for hit in hits:
+        mode = f"\tmode={hit.match_mode}" if hit.match_mode is not None else ""
+        lines.append(
+            f"{hit.item_id}\tscore={hit.score:.3f}{mode}\tdoc={hit.display_name or hit.document_path}"
+        )
+        if hit.scores:
+            score_parts = ", ".join(
+                f"{name}={value:.3f}" for name, value in sorted(hit.scores.items())
+            )
+            lines.append(f"scores: {score_parts}")
+        if hit.metadata:
+            metadata_parts = ", ".join(
+                f"{name}={value}" for name, value in sorted(hit.metadata.items())
+            )
+            lines.append(f"metadata: {metadata_parts}")
+        lines.append(hit.preview)
+    return "\n".join(lines)
+
+
+def render_items(items: Sequence[ItemRef]) -> str:
+    if not items:
+        return "No items found."
+    return "\n".join(
+        f"{item.item_id}\t{item.locator}\t{item.preview}" for item in items
+    )
+
+
+def render_patch_result(result: PatchResult) -> str:
+    return f"{result.item.item_id}\tupdated\t{result.output_path}"
+
+
+def render_documents(documents: Sequence[DocumentRef]) -> str:
+    if not documents:
+        return "No indexed documents."
+    return "\n".join(
+        (
+            f"{document.document_id}\ttype={document.file_type}\titems={document.item_count or 0}"
+            f"\tpath={document.path}"
+        )
+        for document in documents
+    )
+
+
+def render_document(document: DocumentRef) -> str:
+    lines = [
+        f"document_id: {document.document_id}",
+        f"path: {document.path}",
+        f"file_type: {document.file_type}",
+        f"display_name: {document.display_name}",
+        f"modified_time: {document.modified_time}",
+        f"item_count: {document.item_count or 0}",
+    ]
+    if document.content_hash is not None:
+        lines.append(f"content_hash: {document.content_hash}")
+    return "\n".join(lines)
+
+
+def render_item(item: ItemRef) -> str:
+    lines = [
+        f"document_id: {item.document_id}",
+        f"item_id: {item.item_id}",
+        f"item_type: {item.item_type}",
+        f"locator: {item.locator}",
+        f"preview: {item.preview}",
+    ]
+    if item.content_text is not None:
+        lines.append(f"content_text: {item.content_text}")
+    if item.metadata:
+        lines.append("metadata:")
+        for key, value in sorted(item.metadata.items()):
+            lines.append(f"  {key}: {value}")
+    return "\n".join(lines)
+
+
+def render_text_result(payload: dict[str, Any]) -> str:
+    return str(payload["text"])

offagent/interfaces/cli_progress.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+
+
+class RichProgressReporter:
+    """Rich-based progress reporter for index and reindex commands."""
+
+    def __init__(
+        self, *, console: Console | None = None, transient: bool = True
+    ) -> None:
+        self._progress = Progress(
+            SpinnerColumn(),
+            TextColumn("{task.description}"),
+            BarColumn(bar_width=24),
+            MofNCompleteColumn(),
+            TimeElapsedColumn(),
+            console=console or Console(stderr=True),
+            transient=transient,
+        )
+        self._file_task_id: int | None = None
+        self._embed_task_id: int | None = None
+        self._current_file_index = 0
+
+    def __enter__(self) -> "RichProgressReporter":
+        self._progress.__enter__()
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self._progress.__exit__(*args)
+
+    def on_index_start(self, total_files: int) -> None:
+        self._file_task_id = self._progress.add_task(
+            "Indexing", total=total_files, completed=0
+        )
+
+    def on_file_start(self, path: Path, index: int, total: int) -> None:
+        self._current_file_index = index
+        self._hide_embedding_task()
+        if self._file_task_id is None:
+            self._file_task_id = self._progress.add_task(
+                f"Indexing {path.name}",
+                total=total,
+                completed=max(index - 1, 0),
+            )
+            return
+        self._progress.update(
+            self._file_task_id,
+            description=f"Indexing {path.name}",
+            total=total,
+            completed=max(index - 1, 0),
+            visible=True,
+        )
+
+    def on_embedding_start(self, path: Path, item_count: int) -> None:
+        if item_count <= 0:
+            self._hide_embedding_task()
+            return
+        description = f"Embedding {item_count} items"
+        if self._embed_task_id is None:
+            self._embed_task_id = self._progress.add_task(
+                description, total=item_count, completed=0
+            )
+            return
+        self._progress.update(
+            self._embed_task_id,
+            description=description,
+            total=item_count,
+            completed=0,
+            visible=True,
+        )
+
+    def on_embedding_item(self, done: int, total: int) -> None:
+        if self._embed_task_id is None:
+            self._embed_task_id = self._progress.add_task(
+                f"Embedding {total} items",
+                total=total,
+                completed=done,
+            )
+            return
+        self._progress.update(
+            self._embed_task_id,
+            description=f"Embedding {total} items",
+            total=total,
+            completed=done,
+            visible=True,
+        )
+
+    def on_file_done(self, path: Path, items_indexed: int) -> None:
+        if self._file_task_id is not None:
+            self._progress.update(
+                self._file_task_id,
+                description=f"Indexing {path.name}",
+                completed=self._current_file_index,
+            )
+        self._hide_embedding_task()
+
+    def on_index_done(self, files_indexed: int, files_skipped: int) -> None:
+        self._hide_embedding_task()
+        if self._file_task_id is not None:
+            self._progress.update(
+                self._file_task_id,
+                description="Indexing complete",
+                completed=files_indexed + files_skipped,
+            )
+
+    def _hide_embedding_task(self) -> None:
+        if self._embed_task_id is None:
+            return
+        self._progress.update(self._embed_task_id, visible=False)