osrforge.pages
The shared interleaved text-plus-image request-part builder.
Including the text layer is load-bearing, not a nicety: in the recorded capability probes, an images-only survey request produced one dungeon, three areas, and one monster name, while the text-plus-image request over the same module's pages produced the full index. Per-page interleaving is the pinned arrangement — the shape every successful extraction probe used. Every page-consuming request — survey, content, and the stat-block pass — builds its parts only through this function.
This lives in its own module because Workdir's charter is layout plus
run.json I/O, providers/ is the vendor seam, and both stages need it — a
one-function module matches house scale (versioning.py).
clamp_pages
Normalize a model-supplied page list: drop out-of-range references, deduplicate, sort.
Models hallucinate page references; anything outside 1..page_count is dropped. Lives here — not in a stage module — because both extraction stages normalize page lists and no stage module imports another.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pages
|
Iterable[int]
|
The page numbers as the model gave them. |
required |
page_count
|
int
|
The source's page count. |
required |
Returns:
| Type | Description |
|---|---|
tuple[int, ...]
|
The in-range pages, deduplicated and ascending. |
page_request_parts
page_request_parts(workdir: Workdir, page_numbers: Sequence[int]) -> tuple[TextPart | ImagePart, ...]
Build the ordered request parts for a sequence of pages.
For each page, in the given order: a TextPart of "[page N]\n" plus the
page's extracted text, immediately followed by the page's ImagePart. The
[page N] marker is emitted even when the text layer is empty (the
scanned-module path) — the markers define the page-number space: printed
page numbers visible in the images differ from PDF page numbers, so every
prompt states that source_pages/map_pages refer to these markers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workdir
|
Workdir
|
The workdir holding |
required |
page_numbers
|
Sequence[int]
|
The 1-based page numbers, in request order. |
required |
Returns:
| Type | Description |
|---|---|
tuple[TextPart | ImagePart, ...]
|
The interleaved text and image parts. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If a page's render or text file is missing (misuse: preprocess didn't run, or a bad page number). |