docs/inference.md

# Inference guide

Abjad 0.2 is a fused MLX-VLM checkpoint. The published model already contains the final LoRA weights, so no
adapter is required for normal inference.

## PDF or image

From the project directory:

```bash
.venv/bin/python mlx_ocr_pipeline.py INPUT \
  -o outputs/result.txt \
  --model /path/to/Abjad_0.2 \
  --no-adapter \
  --preserve-digit-shapes
```

For a single-column scanned page, `--regions` can improve reading order by processing horizontal strips:

```bash
.venv/bin/python mlx_ocr_pipeline.py INPUT.pdf \
  -o outputs/result.txt \
  --model /path/to/Abjad_0.2 \
  --no-adapter \
  --regions \
  --preserve-digit-shapes
```

Useful options:

| Option | Purpose |
| --- | --- |
| `--pages 1 2 3` | Process selected one-based PDF pages |
| `--resume` | Continue a stopped PDF job |
| `--max-tokens 4096` | Increase the output budget for dense pages |
| `--max-image-pixels 1500000` | Cap rendered image size to control memory |
| `--preserve-digit-shapes` | Keep Arabic-Indic digits as printed |
| `--regions` | Try horizontal strips for single-column scans |

The pipeline reports repetition and length problems as review signals. It does not silently invent missing text.
Watermarks, stamps, and signatures are excluded by the default OCR instruction unless they are part of the
document text. A visual review is still required for legal or archival documents.

## PDF to Word

```bash
.venv/bin/python abjad_convert.py INPUT.pdf OUTPUT.docx --trained
```

Use the layout-aware option for pages with tables or complex blocks:

```bash
.venv/bin/python abjad_convert.py INPUT.pdf OUTPUT.docx --layout --trained
```

## Adapter checkpoints

Historical adapters remain under `adapters/` for reproducibility. They are not needed when using the fused
`Abjad_0.2` directory. If testing an adapter explicitly, pass its directory with `--adapter` and do not add
`--no-adapter`.