agent-pdf-workspace 0.1.1__py3-none-any.whl

agent_pdf_workspace/__init__.py

@@ -0,0 +1,48 @@
+"""Offline, agent-oriented PDF exploration workspaces."""
+
+from importlib.metadata import version
+
+__version__ = version("agent-pdf-workspace")
+
+from .config import IngestConfig
+from .models import (
+    AuditRegion,
+    Diagnostic,
+    ExtractionMethod,
+    PageRecord,
+    PageVisualAudit,
+    SearchHit,
+    TableRecord,
+    TextBlock,
+    VerificationResult,
+    VisualDescription,
+    VisualOccurrence,
+    VisualTask,
+    VisualTaskStatus,
+    VisualTaskType,
+    WorkspaceManifest,
+    WorkspaceStatus,
+)
+from .workspace import Workspace
+
+__all__ = [
+    "AuditRegion",
+    "Diagnostic",
+    "ExtractionMethod",
+    "IngestConfig",
+    "PageRecord",
+    "PageVisualAudit",
+    "SearchHit",
+    "TableRecord",
+    "TextBlock",
+    "VerificationResult",
+    "VisualDescription",
+    "VisualOccurrence",
+    "VisualTask",
+    "VisualTaskStatus",
+    "VisualTaskType",
+    "Workspace",
+    "WorkspaceManifest",
+    "WorkspaceStatus",
+    "__version__",
+]

agent_pdf_workspace/_io.py

@@ -0,0 +1,97 @@
+"""Small, deterministic filesystem helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import tempfile
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def sha256_file(path: Path, chunk_size: int = 1024 * 1024) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        while chunk := handle.read(chunk_size):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def atomic_write_bytes(path: Path, data: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    atomic_write_bytes(path, text.encode("utf-8"))
+
+
+def atomic_copy(source: Path, destination: Path) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f".{destination.name}.", dir=destination.parent
+    )
+    temporary = Path(temporary_name)
+    try:
+        with source.open("rb") as input_handle, os.fdopen(descriptor, "wb") as output_handle:
+            shutil.copyfileobj(input_handle, output_handle, length=1024 * 1024)
+            output_handle.flush()
+            os.fsync(output_handle.fileno())
+        os.replace(temporary, destination)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def write_json(path: Path, value: Any) -> None:
+    if hasattr(value, "model_dump"):
+        value = value.model_dump(mode="json")
+    payload = json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+    atomic_write_text(path, payload)
+
+
+def markdown_document(frontmatter: Mapping[str, Any], body: str) -> str:
+    yaml_text = yaml.safe_dump(
+        dict(frontmatter), allow_unicode=True, sort_keys=False, default_flow_style=False
+    ).strip()
+    return f"---\n{yaml_text}\n---\n\n{body.rstrip()}\n"
+
+
+def canonical_paths(root: Path) -> Iterable[Path]:
+    excluded_files = {
+        "manifest-sha256.txt",
+        "log.md",
+        ".pdfws.lock",
+    }
+    for path in sorted(root.rglob("*")):
+        if not path.is_file():
+            continue
+        relative = path.relative_to(root).as_posix()
+        if relative in excluded_files or relative.startswith("cache/"):
+            continue
+        yield path
+
+
+def write_integrity_manifest(root: Path) -> None:
+    lines = [
+        f"{sha256_file(path)}  {path.relative_to(root).as_posix()}"
+        for path in canonical_paths(root)
+    ]
+    atomic_write_text(root / "manifest-sha256.txt", "\n".join(lines) + "\n")

agent_pdf_workspace/assets/opencode/agent_pdf_workspace.ts

@@ -0,0 +1,237 @@
+import { tool } from "@opencode-ai/plugin"
+import { unlink } from "node:fs/promises"
+import path from "path"
+
+async function runPdfws(args: string[]): Promise<string> {
+  const process = Bun.spawnSync(["pdfws", ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  const stdout = process.stdout.toString().trim()
+  if (process.exitCode !== 0) {
+    const stderr = process.stderr.toString().trim()
+    throw new Error(stderr || `pdfws exited with status ${process.exitCode}`)
+  }
+  return stdout
+}
+
+async function withJsonInput(
+  payload: Record<string, unknown>,
+  invoke: (inputPath: string) => Promise<string>,
+): Promise<string> {
+  const temporaryDirectory = Bun.env.TMPDIR || Bun.env.TEMP || Bun.env.TMP || "."
+  const inputPath = path.join(
+    temporaryDirectory,
+    `agent-pdf-workspace-${crypto.randomUUID()}.json`,
+  )
+  await Bun.write(inputPath, JSON.stringify(payload))
+  try {
+    return await invoke(inputPath)
+  } finally {
+    await unlink(inputPath).catch(() => undefined)
+  }
+}
+
+export const inspect = tool({
+  description: "Inspect a local agent-pdf-workspace without loading the full PDF.",
+  args: {
+    workspace: tool.schema.string().describe("Path to the existing PDF workspace"),
+  },
+  async execute(args) {
+    return runPdfws(["inspect", args.workspace, "--json"])
+  },
+})
+
+export const search = tool({
+  description: "Search a local PDF workspace and return page-grounded hits and snippets.",
+  args: {
+    workspace: tool.schema.string().describe("Path to the existing PDF workspace"),
+    query: tool.schema.string().describe("Text or expression to find"),
+    mode: tool.schema.enum(["fts", "exact", "regex"]).default("fts"),
+    limit: tool.schema.number().int().min(1).max(100).default(20),
+  },
+  async execute(args) {
+    return runPdfws([
+      "search",
+      args.workspace,
+      args.query,
+      "--mode",
+      args.mode,
+      "--limit",
+      String(args.limit),
+      "--json",
+    ])
+  },
+})
+
+export const read_page = tool({
+  description: "Read one page from a local PDF workspace with bounded output.",
+  args: {
+    workspace: tool.schema.string().describe("Path to the existing PDF workspace"),
+    page: tool.schema.number().int().min(1).describe("One-based page number"),
+    max_chars: tool.schema.number().int().min(1).max(100000).default(20000),
+    cursor: tool.schema.string().optional().describe("Continuation cursor from a prior read"),
+  },
+  async execute(args) {
+    const command = [
+      "read",
+      args.workspace,
+      "--page",
+      String(args.page),
+      "--max-chars",
+      String(args.max_chars),
+      "--json",
+    ]
+    if (args.cursor) command.push("--cursor", args.cursor)
+    return runPdfws(command)
+  },
+})
+
+export const render_region = tool({
+  description: "Render a bounded PDF page region for visual interpretation by the calling agent.",
+  args: {
+    workspace: tool.schema.string().describe("Path to the existing PDF workspace"),
+    page: tool.schema.number().int().min(1).describe("One-based page number"),
+    bbox: tool.schema
+      .array(tool.schema.number())
+      .length(4)
+      .describe("Page-coordinate bounding box [x0, y0, x1, y1]"),
+    dpi: tool.schema.number().int().min(72).max(600).default(200),
+  },
+  async execute(args) {
+    return runPdfws([
+      "render",
+      args.workspace,
+      "--page",
+      String(args.page),
+      "--bbox",
+      args.bbox.join(","),
+      "--dpi",
+      String(args.dpi),
+      "--json",
+    ])
+  },
+})
+
+export const visuals_next = tool({
+  description: "Return the next pending visual-description or page-audit task.",
+  args: {
+    workspace: tool.schema.string().describe("Path to the existing PDF workspace"),
+  },
+  async execute(args) {
+    const result = await runPdfws(["visuals", "next", args.workspace, "--json"])
+    const task = JSON.parse(result)
+    if (task?.asset_path) {
+      task.asset_path_absolute = path.resolve(args.workspace, task.asset_path)
+    }
+    return JSON.stringify(task)
+  },
+})
+
+export const visuals_submit = tool({
+  description: "Persist a visual description. For charts, use a Markdown table with one row per data point and explicit labels, values, and units. Never recompute verified values during a formatting-only replacement.",
+  args: {
+    workspace: tool.schema.string().describe("Path to the existing PDF workspace"),
+    task_id: tool.schema.string(),
+    visual_id: tool.schema.string(),
+    crop_sha256: tool.schema.string(),
+    kind: tool.schema.string(),
+    decorative: tool.schema.boolean(),
+    short_description: tool.schema.string().max(1000),
+    long_description: tool.schema.string().max(20000).optional(),
+    text_in_visual: tool.schema.string().max(20000).optional().describe("Visible text or data. For charts, provide a Markdown table and preserve exact label/value associations, signs, decimals, and units."),
+    model_id: tool.schema.string().max(200).optional(),
+    replace: tool.schema.boolean().default(false).describe("Replace a submitted description only after rechecking the unchanged crop and existing JSON."),
+  },
+  async execute(args) {
+    const payload = {
+      visual_id: args.visual_id,
+      crop_sha256: args.crop_sha256,
+      kind: args.kind,
+      decorative: args.decorative,
+      short_description: args.short_description,
+      long_description: args.long_description,
+      text_in_visual: args.text_in_visual,
+      agent_id: "opencode",
+      model_id: args.model_id,
+    }
+    return withJsonInput(payload, (inputPath) => {
+      const command = [
+        "visuals",
+        "submit",
+        args.workspace,
+        "--task-id",
+        args.task_id,
+        "--input",
+        inputPath,
+      ]
+      if (args.replace) command.push("--replace")
+      command.push("--json")
+      return runPdfws(command)
+    })
+  },
+})
+
+export const visuals_audit = tool({
+  description: "Persist a visual page audit and queue any missed regions.",
+  args: {
+    workspace: tool.schema.string().describe("Path to the existing PDF workspace"),
+    task_id: tool.schema.string(),
+    page: tool.schema.number().int().min(1),
+    regions: tool.schema
+      .array(
+        tool.schema.object({
+          bbox: tool.schema.array(tool.schema.number()).length(4),
+          kind: tool.schema.string().default("unknown"),
+          short_description: tool.schema.string().max(1000).optional(),
+        }),
+      )
+      .max(100)
+      .default([]),
+    notes: tool.schema.string().max(10000).optional(),
+    model_id: tool.schema.string().max(200).optional(),
+  },
+  async execute(args) {
+    const payload = {
+      task_id: args.task_id,
+      page: args.page,
+      regions: args.regions,
+      notes: args.notes,
+      agent_id: "opencode",
+      model_id: args.model_id,
+    }
+    return withJsonInput(payload, (inputPath) =>
+      runPdfws([
+        "visuals",
+        "audit",
+        args.workspace,
+        "--task-id",
+        args.task_id,
+        "--input",
+        inputPath,
+        "--json",
+      ]),
+    )
+  },
+})
+
+export const visuals_skip = tool({
+  description: "Resolve a visual task as skipped with an explicit reason.",
+  args: {
+    workspace: tool.schema.string().describe("Path to the existing PDF workspace"),
+    task_id: tool.schema.string(),
+    reason: tool.schema.string().min(1).max(1000),
+  },
+  async execute(args) {
+    return runPdfws([
+      "visuals",
+      "skip",
+      args.workspace,
+      "--task-id",
+      args.task_id,
+      "--reason",
+      args.reason,
+      "--json",
+    ])
+  },
+})

agent_pdf_workspace/cli.py

@@ -0,0 +1,322 @@
+"""Typer command-line interface for agents and humans."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from importlib.resources import as_file, files
+from pathlib import Path
+from typing import Annotated, Any, Never
+
+import typer
+
+from agent_pdf_workspace import __version__
+from agent_pdf_workspace.errors import InputValidationError, PdfWorkspaceError
+from agent_pdf_workspace.models import PageVisualAudit, VisualDescription, WorkspaceStatus
+from agent_pdf_workspace.opencode import discover_opencode_config_dir, install_opencode
+from agent_pdf_workspace.workspace import Workspace
+
+app = typer.Typer(
+    no_args_is_help=True,
+    invoke_without_command=True,
+    help="Create and explore offline PDF workspaces.",
+)
+visuals_app = typer.Typer(no_args_is_help=True, help="Manage agent visual tasks.")
+skill_app = typer.Typer(no_args_is_help=True, help="Export the bundled agent skill.")
+opencode_app = typer.Typer(no_args_is_help=True, help="Install the OpenCode skill and tools.")
+app.add_typer(visuals_app, name="visuals")
+app.add_typer(skill_app, name="skill")
+app.add_typer(opencode_app, name="opencode")
+
+
+def _jsonable(value: Any) -> Any:
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json")
+    if isinstance(value, list):
+        return [_jsonable(item) for item in value]
+    return value
+
+
+def _emit(value: Any, json_output: bool) -> None:
+    payload = _jsonable(value)
+    if json_output:
+        typer.echo(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+    elif isinstance(payload, str):
+        typer.echo(payload)
+    else:
+        typer.echo(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True))
+
+
+def _abort(error: Exception) -> Never:
+    typer.echo(str(error), err=True)
+    code = error.exit_code if isinstance(error, PdfWorkspaceError) else 2
+    raise typer.Exit(code=code)
+
+
+def _open(target: Path, *, password: str | None = None) -> Workspace:
+    try:
+        return Workspace.open(target, password=password)
+    except (PdfWorkspaceError, ValueError, OSError) as error:
+        _abort(error)
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(False, "--version", help="Show the package version and exit."),
+) -> None:
+    if version:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.command()
+def ingest(
+    source: Annotated[Path, typer.Argument(exists=False, dir_okay=False)],
+    target: Annotated[Path, typer.Option("--target", file_okay=False)],
+    ocr: str = typer.Option("auto", "--ocr"),
+    language: str = typer.Option("eng", "--language"),
+    workers: int = typer.Option(4, "--workers", min=1, max=4),
+    password_stdin: bool = typer.Option(False, "--password-stdin"),
+    force: bool = typer.Option(False, "--force"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Convert one local PDF into a persistent workspace."""
+
+    password = sys.stdin.readline().rstrip("\r\n") if password_stdin else None
+    try:
+        workspace = Workspace.ingest(
+            source,
+            target,
+            ocr=ocr,
+            ocr_languages=tuple(item for item in language.split("+") if item),
+            workers=workers,
+            password=password,
+            force=force,
+        )
+        _emit(workspace.inspect(), json_output)
+    except (PdfWorkspaceError, ValueError, OSError) as error:
+        _abort(error)
+
+
+@app.command("inspect")
+def inspect_command(
+    target: Path,
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    workspace = _open(target)
+    _emit(workspace.inspect(), json_output)
+    if workspace.manifest.status in {
+        WorkspaceStatus.BUILDING,
+        WorkspaceStatus.PARTIAL,
+        WorkspaceStatus.FAILED,
+    }:
+        raise typer.Exit(code=3)
+
+
+@app.command()
+def search(
+    target: Path,
+    query: str,
+    mode: str = typer.Option("fts", "--mode"),
+    limit: int = typer.Option(20, "--limit", min=1, max=100),
+    cursor: str | None = typer.Option(None, "--cursor"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    try:
+        _emit(
+            _open(target).search(query, mode=mode, limit=limit, cursor=cursor),
+            json_output,
+        )
+    except (PdfWorkspaceError, ValueError, OSError) as error:
+        _abort(error)
+
+
+@app.command("read")
+def read_command(
+    target: Path,
+    page: int = typer.Option(..., "--page", min=1),
+    max_chars: int = typer.Option(20_000, "--max-chars", min=1, max=100_000),
+    cursor: str | None = typer.Option(None, "--cursor"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    try:
+        _emit(
+            _open(target).read_page(page, max_chars=max_chars, cursor=cursor),
+            json_output,
+        )
+    except (PdfWorkspaceError, ValueError, OSError) as error:
+        _abort(error)
+
+
+def _bbox(value: str) -> tuple[float, float, float, float]:
+    try:
+        parts = tuple(float(item) for item in value.split(","))
+    except ValueError as error:
+        raise InputValidationError("bbox must contain four comma-separated numbers") from error
+    if len(parts) != 4:
+        raise InputValidationError("bbox must contain four comma-separated numbers")
+    return (parts[0], parts[1], parts[2], parts[3])
+
+
+@app.command()
+def render(
+    target: Path,
+    page: int = typer.Option(..., "--page", min=1),
+    bbox: str = typer.Option(..., "--bbox"),
+    dpi: int = typer.Option(200, "--dpi", min=72, max=600),
+    password_stdin: bool = typer.Option(False, "--password-stdin"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    try:
+        password = sys.stdin.readline().rstrip("\r\n") if password_stdin else None
+        path = _open(target, password=password).render_region(page, _bbox(bbox), dpi=dpi)
+        _emit({"path": str(path)}, json_output)
+    except (PdfWorkspaceError, ValueError, OSError) as error:
+        _abort(error)
+
+
+@app.command()
+def verify(
+    target: Path,
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    try:
+        result = _open(target).verify()
+        _emit(result, json_output)
+        if not result.valid:
+            raise typer.Exit(code=5)
+    except typer.Exit:
+        raise
+    except (PdfWorkspaceError, ValueError, OSError) as error:
+        _abort(error)
+
+
+@visuals_app.command("list")
+def visuals_list(
+    target: Path,
+    status: str = typer.Option("pending", "--status"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    try:
+        tasks = _open(target).list_visual_tasks(None if status == "all" else status)
+        _emit(tasks, json_output)
+    except (PdfWorkspaceError, ValueError, OSError) as error:
+        _abort(error)
+
+
+@visuals_app.command("next")
+def visuals_next(
+    target: Path,
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    try:
+        tasks = _open(target).list_visual_tasks("pending")
+        if not tasks:
+            tasks = _open(target).list_visual_tasks("stale")
+        _emit(tasks[0] if tasks else None, json_output)
+    except (PdfWorkspaceError, ValueError, OSError) as error:
+        _abort(error)
+
+
+@visuals_app.command("submit")
+def visuals_submit(
+    target: Path,
+    task_id: Annotated[str, typer.Option("--task-id")],
+    input_path: Annotated[Path, typer.Option("--input", exists=True, dir_okay=False)],
+    replace: bool = typer.Option(False, "--replace"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    try:
+        description = VisualDescription.model_validate_json(input_path.read_text(encoding="utf-8"))
+        task = _open(target).submit_visual_description(task_id, description, replace=replace)
+        _emit(task, json_output)
+    except (PdfWorkspaceError, ValueError, OSError) as error:
+        _abort(error)
+
+
+@visuals_app.command("skip")
+def visuals_skip(
+    target: Path,
+    task_id: Annotated[str, typer.Option("--task-id")],
+    reason: Annotated[str, typer.Option("--reason")],
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    try:
+        task = _open(target).skip_visual_task(task_id, reason=reason)
+        _emit(task, json_output)
+    except (PdfWorkspaceError, ValueError, OSError) as error:
+        _abort(error)
+
+
+@visuals_app.command("audit")
+def visuals_audit(
+    target: Path,
+    task_id: Annotated[str, typer.Option("--task-id")],
+    input_path: Annotated[Path, typer.Option("--input", exists=True, dir_okay=False)],
+    password_stdin: bool = typer.Option(False, "--password-stdin"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    try:
+        audit = PageVisualAudit.model_validate_json(input_path.read_text(encoding="utf-8"))
+        password = sys.stdin.readline().rstrip("\r\n") if password_stdin else None
+        task = _open(target, password=password).submit_page_audit(task_id, audit)
+        _emit(task, json_output)
+    except (PdfWorkspaceError, ValueError, OSError) as error:
+        _abort(error)
+
+
+@skill_app.command("export")
+def skill_export(
+    target: Path,
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    try:
+        if target.exists() and target.is_symlink():
+            raise InputValidationError("skill export target must not be a symbolic link")
+        target.mkdir(parents=True, exist_ok=True)
+        destination = target / "agent-pdf-workspace"
+        if destination.exists():
+            raise InputValidationError(f"skill destination already exists: {destination}")
+        resource = files("agent_pdf_workspace").joinpath("skill/agent-pdf-workspace")
+        with as_file(resource) as source:
+            shutil.copytree(source, destination)
+        _emit({"path": str(destination.resolve())}, json_output)
+    except (PdfWorkspaceError, ValueError, OSError) as error:
+        _abort(error)
+
+
+@opencode_app.command("path")
+def opencode_path(
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Report the effective OpenCode config directory."""
+
+    try:
+        location = discover_opencode_config_dir()
+        _emit({"config_dir": str(location.path), "source": location.source}, json_output)
+    except (PdfWorkspaceError, ValueError, OSError) as error:
+        _abort(error)
+
+
+@opencode_app.command("install")
+def opencode_install(
+    config_dir: Annotated[Path | None, typer.Option("--config-dir", file_okay=False)] = None,
+    force: bool = typer.Option(False, "--force"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Install the bundled skill and native tools into OpenCode."""
+
+    try:
+        target = config_dir or discover_opencode_config_dir().path
+        result = install_opencode(target, force=force)
+        _emit(
+            {
+                "config_dir": str(result.config_dir),
+                "skill_path": str(result.skill_path),
+                "tool_path": str(result.tool_path),
+            },
+            json_output,
+        )
+    except (PdfWorkspaceError, ValueError, OSError) as error:
+        _abort(error)