rindo-convert — the Rindo converter agent (KB2)

Vision-grounded conversion of hard formats (text-layer PDF, scanned PDF, PPTX) into reviewable Rindo documents. Invoked by rindo-runner through the command-template contract; the result is always a REV-8 pending draft a human approves — the agent can never publish.

The rendered page is the only ground truth. Machine extraction (Docling for PDFs, python-pptx for decks) is a text donor the model may copy characters from — never a structure authority. A deterministic repair pass (ported from the Rindo worker's extraction pipeline, with drift tests) runs on every page regardless of model quality. DOCX / XLSX / CSV / HTML / MD / TXT are declined politely: their machine representation loses ~nothing a render carries.

Operator documentation lives in the Rindo ops runbook §4.7 (register the agent, mint the runner token, designate converter_agent_id, duration + cost guidance). This README is the package-local quickstart.

Install (on the runner host)

rindo-convert is Apache-2.0 (LICENSE beside this file) — like rindo-runner, not part of the proprietary Software. It is published on PyPI:

uv tool install rindo-convert                # base install — scanned-PDF + PPTX arms work
uv tool install 'rindo-convert[docling]'     # + the Docling scaffold for text-layer PDFs (~5 GB)
# from a source checkout instead: cd agents/converter && uv sync [--extra docling]

Host prerequisites:

• PPTX arm: LibreOffice (soffice) and CJK fonts covering the deck's script (fonts-noto-cjk; verify fc-match :lang=ja resolves to a JP face — the render is the ground truth, so a substituted face degrades silently). The tool refuses to run the PPTX arm without a JA-capable font.
• PDF arms: nothing — pypdfium2 ships wheels; poppler is not needed.
• An Anthropic API key (ANTHROPIC_API_KEY, or an ant auth login profile).

Wire it to the runner

# ~/.config/rindo-runner/config.toml
server_url = "https://rindo.example.com"
token      = "rndr_..."
command    = "/opt/rindo-convert/run.sh {payload_file}"
poll_timeout = 60

#!/usr/bin/env bash
# /opt/rindo-convert/run.sh   (chmod 700 — it holds the API key)
set -euo pipefail
export ANTHROPIC_API_KEY="sk-ant-..."
export RINDO_CONVERT_MODEL="claude-opus-5"
exec /opt/rindo-convert/.venv/bin/rindo-convert "$1"

The runner injects RINDO_SERVER_URL / RINDO_MCP_URL / RINDO_RUNNER_TOKEN / RINDO_JOB_ID; model and engine knobs ride the ambient environment (the wrapper). One job at a time per runner token.

Knobs (RINDO_CONVERT_*)

Exit codes (the runner maps non-zero → job failed)

The classified reason is always the final RESULT: line of the output tail (agent_jobs.result.summary_md on the server), after the usage/cost summary.

Development

uv run pytest -q                      # offline: no network, no key, no docling, no soffice
uv run ruff check . && uv run ruff format --check .

Ported backend symbols (postpass.py, ooxmlguard.py, the router constants) are byte-copies with drift tests: tests/test_ported_drift.py reads the backend sources by relative path and AST-compares. When it fails, re-sync the copy, re-record the sha, and re-run the postpass goldens. The bench harness (measurements M1/M2, the judging protocol) lives in bench/ and writes only outside the repo.