apache / apache/maka

feat(runtime): preflight native PDF inputs against provider document constraints

Open
#3,284 1 comment 0 reactions 0 assignees View on GitHub
enhancement help wanted
Dominant language
TypeScript
Stars
5.4k
Forks
502
Avg merge
1d 2h
Merged PRs (30d)
715

Description

## Problem

#3164 adds the first provider-native PDF materialization path with provider/wire gating and raw-binary budgets. That slice intentionally does not parse PDF structure before dispatch.

The remaining local boundary is deterministic document validation. A canonical Attachment may declare `application/pdf` while the provider still rejects it because it is encrypted, password-protected, malformed, or over a provider-specific page limit. Anthropic currently requires a standard unencrypted PDF and limits the total pages in one request; OpenAI requires a real PDF MIME/type and applies file/request limits.

## Desired outcome

Before raw PDF bytes enter a verified provider request, Maka performs bounded, deterministic validation for the constraints it can establish locally. Rejected inputs remain durable attachments but degrade to a short provider-visible explanation; their bytes never enter the model request.

## Proposed scope

1. Introduce a bounded PDF metadata inspection boundary owned below `AiSdkBackend`. It should report at least:
- whether the bytes are structurally a PDF;
- whether the document is encrypted or password-protected;
- page count when it can be determined safely;
- a typed validation failure without extracted document text.
2. Preserve the storage-sniffed MIME through `AttachmentByteReader` (or an equivalent authority) so declared metadata cannot relabel another binary type as a PDF.
3. Carry provider-specific document constraints in the explicit PDF input contract rather than scattering model/provider conditionals through materialization.
4. Apply Anthropic's current standard-PDF, encryption, and request-page requirements using the resolved context window.
5. Cache inspection by immutable Artifact identity/content so current Turn, replay, steering, compaction replacement, and provider steps do not repeatedly parse the same durable occurrence.
6. Keep inspection bounded in CPU, memory, recursion, and malformed-object handling.

## Acceptance criteria

- A valid unencrypted PDF under the applicable limits still materializes through the #3164 native path.
- An encrypted/password-protected PDF is not sent and produces a bounded explanation.
- A binary whose declared metadata says PDF but whose sniffed content is not PDF is not sent.
- An Anthropic request exceeding the applicable total page limit is not sent.
- Inspection failures do not copy PDF bytes or extracted text into transcripts, RuntimeEvents, logs, diagnostics, or telemetry.
- Current Turn and durable replay make the same validation decision for the same immutable Artifact.
- Focused malformed/encrypted/page-boundary tests run without external provider credentials.

## Non-goals

- OCR, PDF text extraction, rendering, repair, or decryption.
- Uploading documents to a third-party Files API.
- Retrying a provider request after a remote PDF rejection; track that separately.
- Expanding native PDF support to unverified compatible providers.

## References

- Parent delivery: #3164
- Anthropic PDF requirements: https://platform.claude.com/docs/en/build-with-claude/pdf-support
- OpenAI file inputs: https://developers.openai.com/api/docs/guides/file-inputs

Disclosure: this issue was drafted with OpenAI Codex assistance and reviewed and approved by the human contributor.

Contributor guide

Open the contributing guide

Research direction

Start by reading parent issue #3164 and the proposed AiSdkBackend and AttachmentByteReader boundaries. Trace how canonical Attachments become verified provider requests, then define the bounded inspection and explicit provider-constraint contract. Done means valid PDFs still use the native path, rejected PDFs never enter requests, decisions are cached by immutable Artifact identity, and focused malformed, encrypted, and page-boundary tests pass without credentials.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
ai, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.