Add native document encoder

[nwaughachukwuma]

Summary

Adds two new document encoders and updates all documentation to reflect them.

• native encoder passes the raw document as an OpenAI-compatible base64 file part (the document analogue of the existing video native encoder),
• document_url passes it as a base64 document_url part — the native input shape accepted by the vlm.run gateway for models with native PDF document input support.

Both encoders don't initiate page extraction, rasterization, or text parsing, mirroring the design of the existing gemini-native document encoder.

How to test

$: uv run mm --profile gateway cat /path/to/document.pdf -p document-url --no-cache --model glm-ocr

# with streaming
$: uv run mm --profile gateway cat  /path/to/document.pdf -p document-url --no-cache --model glm-ocr --stream

# dots.mocr
$: uv run mm --profile gateway cat  /path/to/document.pdf -p document-url --no-cache --model dots.mocr --stream

# with paddle + method := ocr
$: uv run mm --profile gateway cat  /path/to/document.pdf -p document-url --no-cache --model pp-ocrv6 --stream --extra-body '{"method":"ocr"}'

Implements VLM-433

[gemini-code-assist]

Code Review

This pull request introduces two new document encoders, "document_url" and "native", to support direct base64-encoded document passthrough for gateway and OpenAI-compatible backends. It also registers these encoders, adds corresponding unit tests, and exposes an "--extra-body" option in the "cat" command. Feedback on the changes highlights that importing the private helper "_to_message" from "mm.encoders.image" in both new encoders introduces tight coupling, and suggests refactoring it into a shared module or constructing the message dictionary directly.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[spillai]

This is supposed to be input_file with file_url key: see https://developers.openai.com/api/docs/guides/file-inputs#file-urls

[nwaughachukwuma]

The shapes in the link you shared don't work with openrouter models. Here's what worked.

pdf_path = "path/to/your/document.pdf"
base64_pdf = encode_pdf_to_base64(pdf_path)
data_url = f"data:application/pdf;base64,{base64_pdf}"

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "file",
                "file": {
                    "filename": "document.pdf",
                    "file_data": data_url
                }
            },
        ]
    }
]

Refs:
- https://openrouter.ai/docs/guides/overview/multimodal/pdfs#using-base64-encoded-pdfs
- https://openrouter.ai/docs/guides/overview/multimodal/pdfs#using-pdf-urls

[spillai]

I think we need to introduce an pipelines/document/ocr.yaml pipeline, with an empty prompt, with an encode.strategy: document-url and then allow folks to override prompt if needed. By default glm-ocr, dots.mocr shouldn’t need prompts

encode.strategy_opts can have extra openai args like method, method_params etc. that’s specific to the gateway

[nwaughachukwuma]

I think we need to introduce an pipelines/document/ocr.yaml pipeline, with an empty prompt, with an encode.strategy: document-url and then allow folks to override prompt if needed. By default glm-ocr, dots.mocr shouldn’t need prompts

encode.strategy_opts can have extra openai args like method, method_params etc. that’s specific to the gateway

We can wire it at the encoder level without needing to write a new pipeline, which would warrant plumbing given pipelines are detected based on the file kind. encode.strategy_opts and --extra-body can continue to work the same way.

[nwaughachukwuma]

I think we need to introduce an pipelines/document/ocr.yaml pipeline, with an empty prompt, with an encode.strategy: document-url and then allow folks to override prompt if needed. By default glm-ocr, dots.mocr shouldn’t need prompts

encode.strategy_opts can have extra openai args like method, method_params etc. that’s specific to the gateway

Can we do this as a followup? Also, do you have additional reviews to bring this PR to a good place for merging?