pro-ledin-healthos

Recognize an external family medical archive (PDFs, scans, photos) into tracked Obsidian Markdown that mirrors the source folder structure one-to-one. OCR is delegated to the pro-ledin-ocr package, imported as a library. HealthOS never interprets medical content — it only transcribes and mirrors.

• Import name: pro.ledin.healthos
• Console script: healthos
• PyPI: pro-ledin-healthos

Install

pip install pro-ledin-healthos             # pulls in pro-ledin-ocr and OpenAI-compatible vision support
pip install "pro-ledin-healthos[easyocr]" # + EasyOCR
pip install "pro-ledin-healthos[paddle]"  # + PaddleOCR
pip install "pro-ledin-healthos[paddle-vl]" # + PaddleOCR-VL parser client

System binaries poppler and tesseract are required for the local OCR path.

Configure

Set the AGENT_HEALTH_* environment variables (see skills/healthos/SKILL.md for the full list):

export AGENT_HEALTH_SOURCE_DIR=/absolute/path/to/source   # ':'-separated for many
export AGENT_HEALTH_TARGET_DIR=/path/to/vault/03-areas/health
export AGENT_HEALTH_CACHE_DIR=~/Library/Caches/healthos
export AGENT_HEALTH_OCR_ENGINE=vision
export AGENT_HEALTH_CACHE_IGNORE_PROFILE=healthos_version  # optional; default
# vision engine also needs:
export AGENT_HEALTH_VISION_API_URL=http://127.0.0.1:1234/v1
export AGENT_HEALTH_VISION_API_KEY=token
export AGENT_HEALTH_VISION_MODEL=model-name

# Local structured OCR on Apple Silicon:
export AGENT_HEALTH_OCR_ENGINE=paddleocr-vl-mlx
export AGENT_HEALTH_PADDLE_VL_SERVER_URL=http://127.0.0.1:8111/
export AGENT_HEALTH_PADDLE_VL_MODEL=PaddlePaddle/PaddleOCR-VL-1.6

Never store real credentials in tracked files.

vision sends medical document images to the configured external endpoint. Use it only with explicit user consent and an endpoint whose access, retention, training, and deletion policies are acceptable for protected health information. Leave AGENT_HEALTH_VISION_API_URL unset only when intentionally using OpenAI's default endpoint.

For paddleocr-vl-mlx, first validate direct PaddleOCRVL inference, then start the VLM-only backend with mlx_vlm.server --host 127.0.0.1 --port 8111. HealthOS uses the full PaddleOCR-VL layout pipeline and rejects non-loopback service URLs. Shared preflight also verifies that configured loopback port is reachable.

Upgrade from 0.6

• Replace healthos index --check with healthos check.
• Normal cache hits no longer overwrite existing output files.
• Use --force-ocr to refresh OCR and --force-overwrite to permit replacing an existing output. Both are required to re-OCR a manually changed output.
• HealthOS writes <cache>/manifest.json to track generated outputs safely.

Run

healthos doctor                        # validate config and OCR dependencies
healthos index                         # recognize misses; preserve existing files
healthos index --dry-run               # preview index actions
healthos index --force-ocr             # refresh OCR where overwrite is safe
healthos index --force-overwrite       # restore existing output from cache
healthos index --force-ocr --force-overwrite
healthos index --single-file scans/report.pdf
healthos index --quiet                   # suppress live OCR progress
healthos check                         # verify source/cache/output/manifest state
healthos prune --dry-run               # preview orphan cleanup
healthos prune                         # remove orphan cache and generated output

Every command runs the same preflight before inspecting documents, reading the cache, invoking OCR, or writing files. Missing dependencies identify the engine, component, HealthOS/OCR extra or system binary, and Python environment. Because PDF is a supported source type, preflight also requires either Poppler (pdftoppm and pdftotext) or PyMuPDF. HealthOS never installs packages automatically.

EasyOCR and PaddleOCR may download models on first use. HealthOS enables live OCR progress so model loading and page processing do not appear hung.

Cache hits with existing matching output are skipped. Changed output is treated as a user edit and preserved. --force-ocr alone does not overwrite it; --force-overwrite is explicit permission to replace existing output.

The cache profile hashes OCR-affecting settings. healthos_version remains in profile metadata but is ignored by default. Override the ignored fields with AGENT_HEALTH_CACHE_IGNORE_PROFILE or --ignore-profile.

HealthOS always imports the installed pro-ledin-ocr package.

Development

Local dev resolves pro-ledin-ocr from a sibling ../ocr checkout via [tool.uv.sources] in pyproject.toml:

uv run --extra dev pytest
uv build

To test against the published pro-ledin-ocr from PyPI instead (as CI does), add --no-sources:

uv run --no-sources --extra dev pytest
uv build --no-sources

OCR benchmark

The benchmark is configured externally; it does not contain machine-specific paths or a built-in model list. Start from scripts/ocr-profile-benchmark.example.json, adjust source_dir, tools, services, credentials, and targets, then run:

export OMLX_API_KEY=your-omlx-key
export LITELLM_API_KEY=your-litellm-key
python scripts/ocr-profile-benchmark.py --config path/to/ocr-profile-benchmark.json

Relative paths in the configuration are resolved relative to the configuration file. Every run stores its resolved configuration in run-config.json, so an existing run can be resumed without the original config file:

python scripts/ocr-profile-benchmark.py --resume path/to/run

License

MIT