Metadata-Version: 2.5
Name: pro-ledin-healthos
Version: 0.7.6
Summary: Recognize a family medical archive into tracked Obsidian Markdown, delegating OCR to pro-ledin-ocr.
Project-URL: Homepage, https://github.com/ledin-pro/healthos
Project-URL: Repository, https://github.com/ledin-pro/healthos
Author: mxl
License-Expression: MIT
License-File: LICENSE
Keywords: healthos,markdown,medical,obsidian,ocr
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Requires-Dist: openai>=1.0
Requires-Dist: pro-ledin-ocr<0.8,>=0.7.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Provides-Extra: easyocr
Requires-Dist: pro-ledin-ocr[easyocr]<0.8,>=0.7.0; extra == 'easyocr'
Provides-Extra: paddle
Requires-Dist: pro-ledin-ocr[paddle]<0.8,>=0.7.0; extra == 'paddle'
Provides-Extra: paddle-vl
Requires-Dist: pro-ledin-ocr[paddle-vl]<0.8,>=0.7.0; extra == 'paddle-vl'
Description-Content-Type: text/markdown

# pro-ledin-healthos

[![skills.sh](https://skills.sh/b/ledin-pro/healthos)](https://skills.sh/ledin-pro/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`](https://github.com/ledin-pro/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

```bash
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):

```bash
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

```bash
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`:

```bash
uv run --extra dev pytest
uv build
```

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

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

## License

MIT
