# Architecture

Two models with a JSON file between them.

```text
page image ──> IndicDocLayout ──> layout JSON ──> IndicBlockOCR ──> page JSON + markdown
```

`IndicDocLayout` finds the blocks and orders them. `IndicBlockOCR` transcribes one block crop
per request. Everything between the two models (cropping, prompt selection, reassembly) is this
package.

## The call path

One page, top to bottom, with the file that owns each step.

```text
IndicDocParser.parse(image)                              idp_offline.py

  IndicDocLayout.detect(image)                           idp_offline.py
    _open                     image -> PIL RGB           idp_offline.py
    IndicDocLayoutBackend.detect                         idp_layout.py
      infer                   -> [y0,x0,y1,x1] at 0-1000 idp_model_infer.py
      convert + clamp_to_page -> pixel [x0,y0,x1,y1]     idp_layout.py, blocks.py
      clean_layout            drop duplicate boxes       idp_blocks.py
      _densify                order -> gap-free 0..n-1   idp_layout.py
    = PageResult, every block has text None              idp_types.py

  IndicBlockOCR.run(image, layout)                       idp_offline.py
    _as_page                  dict -> PageResult, validated
    is_transcribed            drop OCR_SKIP_LABELS       idp_contract.py
    resolve_nested_equations  drop nested equations      idp_blocks.py
    build_requests            -> [CropRequest]           idp_recognizer.py
      crop_for + area_clamp   block -> image             idp_crops.py
      prompt_for(block.type)  type  -> prompt            idp_contract.py
    backend.transcribe        [CropRequest] -> [str]     a recognizer backend
    match by order            texts -> blocks            idp_offline.py
    reconstruct               blocks -> markdown         idp_reconstruct.py
  = PageResult, every block has text
```

Blocks that were skipped are not deleted. They come back with `text: ""`.

## Files by role

**Contract and data.** The vocabulary everything else shares.

| file | holds |
| --- | --- |
| `idp_contract.py` | prompts, the label to type map, which labels are skipped |
| `idp_types.py` | `Block`, `PageResult`, and every tunable config |

**The layout model.** Torch lives here and nowhere else.

| file | holds |
| --- | --- |
| `idp_model_infer.py` | preprocessing and decode for one page |
| `idp_model_labels.py` | the 37 classes, pure Python |
| `idp_model_ppdoc.py` | the PP-DocLayoutV3 subclass |
| `idp_model_order_loss.py` | reading-order decode, training loss |

**Geometry and crops.** No model, no network.

| file | holds |
| --- | --- |
| `idp_blocks.py` | box math, `clean_layout`, nested-equation dedup |
| `idp_crops.py` | `crop_for` and `area_clamp` |

**Backends.** Two Protocols, five implementations, one per deployment.

| class | file | used by |
| --- | --- | --- |
| `IndicDocLayoutBackend` | `idp_layout.py` | the real detector |
| `JsonLayoutBackend` | `idp_layout.py` | replaying a layout file, no torch |
| `HfRecognizer` | `idp_recognizer.py` | plain transformers, the Hub package |


**Orchestration.**

| file | holds |
| --- | --- |
| `idp_offline.py` | `IndicDocLayout`, `IndicBlockOCR`, `IndicDocParser` |
| `idp_recognizer.py` | `CropRequest`, `build_requests`, the recognizer Protocol |
| `idp_reconstruct.py` | blocks to markdown, math and hyphen repair |

## Invariants

1. **Two box conventions.** The model emits `[y0, x0, y1, x1]` normalised to 0-1000. The
   pipeline uses pixel `[x0, y0, x1, y1]`. 
2. **`order` must be gap-free and 0-based.** Transcriptions are matched back to blocks by
   position, so a gap or a duplicate moves text onto the wrong block.
3. **The crop clamp is on area, not on a side.** Pinning a side explodes elongated crops. See
   `CropConfig` in `idp_types.py`.
4. **`type` selects the prompt.** A wrong `type` changes what the model was asked to do, not
   just how a block is labelled. Unrecognised labels are rejected for this reason.