Derive page rasterization requirements from embedding configuration

[jioffe502]

Problem

The ingestion API currently exposes three independently configurable settings that are not fully independent:

• embed_granularity: element or page
• embed_modality: text, image, or text_image
• extract_page_as_image: whether extraction produces a page raster

Granularity and modality are legitimate retrieval choices. Page rasterization is an execution prerequisite and output-retention concern. Requiring callers to coordinate all three permits contradictory configurations, silent missing embeddings, confusing QA expectations, and unnecessary page rendering.

Current examples show that the distinct product modes are real:

• Default ingestion uses element-level text embeddings.
• ViDoRe v3 benchmarks use page-level text_image embeddings with page images enabled.
• The fast-text profile explicitly disables page images.
• Published documentation includes page-level image embedding.

The ambiguity surfaced during RC verification of the page-collapse Arrow fix: a reproduction configured only embed_granularity="page" while its expected result required page-image embeddings. Because embed_modality remained at its text default, the requested behavior and acceptance criteria described different modes.

Proposed direction

Keep granularity and modality as explicit user choices, but make page rasterization a planner-owned requirement:

1. Compute whether the selected pipeline stages require a page raster.
2. Automatically enable page rasterization when image or text-image embedding requires it, unless an explicit contradictory setting should instead fail fast.
3. Reject configurations that request image input while disabling every stage capable of producing that input.
4. Avoid page rasterization for text-only ingestion when no extraction, OCR, captioning, storage, or embedding consumer needs it.
5. Expose the resolved plan so logs and test output show the effective granularity, modality, and raster requirement.

The exact compatibility policy for an explicitly supplied extract_page_as_image=False should be decided before implementation: either treat it as authoritative and raise a configuration error, or deprecate it as a pipeline-planning control and derive the value.

Acceptance criteria

• Page + text produces one text embedding row per page without requiring page-image embedding.
• Page + image and page + text_image always have valid page-image inputs or fail during configuration with an actionable error.
• Element modes preserve their existing per-type modality behavior.
• Fast-text ingestion does not render full-page images when no downstream stage requires them.
• Existing supported configurations remain compatible or receive a documented deprecation path.
• Planner/unit tests cover the valid configuration matrix and contradictory explicit settings.
• An integration test verifies resolved inputs and embeddings for text-page and image-page modes.
• Benchmarking reports page-render time and memory separately so any default change is evidence-based.

Non-goals

• Reworking the Arrow/pandas batch representation.
• Reopening the fixed collapse_content_to_page_rows() Arrow exception.
• Changing embedding model semantics or vector dimensions.

[jioffe502]

for future reference.