PDF Table Preflight Router

A deterministic Apify Actor that inspects public PDF URLs and routes each document before a pipeline spends more on table extraction or OCR.

The Actor does not perform OCR, table extraction, LLM classification, vision-API calls, or manual document work. It only returns bounded routing evidence.

Input

{
  "pdfUrls": [
    "https://example.com/report.pdf"
  ],
  "maxPagesPerPdf": 50,
  "maxFileSizeMb": 20
}

• pdfUrls: required, 1–20 public absolute HTTP/HTTPS URLs.
• maxPagesPerPdf: optional integer, default 50, hard maximum 50.
• maxFileSizeMb: optional integer, default 20, hard maximum 20 MB.

No credentials, private files, OCR keys, AI keys, or paid API inputs are accepted.

Routing outcomes

Each inspected PDF receives exactly one route:

• NATIVE_TABLE_EXTRACTION — deterministic native text/vector/alignment evidence indicates a table candidate that should not require OCR first.
• MIXED_NATIVE_AND_OCR — the same PDF contains both native table-candidate pages and scan-like table-candidate pages.
• OCR_LIKELY_REQUIRED — table-like raster structure appears on image-dominant pages with little or no selectable text.
• NO_TABLE_CANDIDATE — no deterministic table candidate is detected within the inspected document.
• UNSUPPORTED_OR_ENCRYPTED — the PDF cannot be safely inspected because it is malformed, encrypted, or outside configured limits, or fetching/validation failed.

routeConfidence is a fixed deterministic heuristic confidence value. It is not a calibrated probability or ML score.

Evidence produced

The default dataset contains one diagnostic row per attempted URL. A completed inspected result includes:

• source/final URL, redirect chain, HTTP status and Content-Type;
• downloaded byte count;
• page count and pages inspected;
• encrypted state;
• selectable-text presence;
• textCoverage, defined as the fraction of inspected pages with at least 30 non-whitespace selectable characters;
• table-candidate page count;
• scan-likely page count;
• route, route confidence and stable reason codes;
• per-page text characters, approximate image-area ratio, table-candidate state, modality and geometry evidence;
• applied file/page limits;
• whether the custom pdf-preflight PPE event is eligible.

Complete schema-valid example (illustrative output shape; values are not a guarantee for future URLs or runs):

{
  "sourceUrl": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
  "finalUrl": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
  "httpStatus": 200,
  "contentType": "application/pdf; qs=0.001",
  "bytes": 13264,
  "pageCount": 1,
  "pagesInspected": 1,
  "encrypted": false,
  "selectableText": false,
  "textCoverage": 0,
  "tableCandidatePageCount": 0,
  "scannedLikelyPageCount": 0,
  "route": "NO_TABLE_CANDIDATE",
  "routeConfidence": 0.9,
  "reasonCodes": [
    "NO_TABLE_CANDIDATE"
  ],
  "pages": [
    {
      "page": 1,
      "textChars": 12,
      "imageAreaRatio": 0,
      "tableCandidate": false,
      "candidateCount": 0,
      "candidateConfidence": 0,
      "candidateModality": null,
      "scannedLikely": false,
      "geometry": {
        "horizontalRuleCount": 0,
        "verticalRuleCount": 0,
        "alignedRowCount": 0,
        "recurringColumnCount": 0,
        "denseNumericRowCount": 0,
        "recurringNumericColumnCount": 0,
        "rasterHorizontalLineCount": 0,
        "rasterVerticalLineCount": 0
      },
      "reasonCodes": []
    }
  ],
  "limitsApplied": {
    "maxPagesPerPdf": 50,
    "maxFileSizeMb": 20
  },
  "processingStatus": "completed",
  "paidEventEligible": true,
  "redirectChain": [
    "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
  ]
}

Deterministic table-candidate heuristics

The MVP intentionally uses several local signals instead of AI:

1. Selectable text — PyMuPDF extracts page text and word geometry.
2. Vector rule structure — repeated horizontal/vertical PDF drawing lines or rectangles provide ruled-table evidence.
3. Aligned columns — repeated x-position clusters across multiple short rows provide borderless-table evidence while rejecting paragraph-like rows with many words.
4. Dense numeric columns — wide rows with repeated numeric cell x-positions detect dense borderless statistical tables without relaxing the prose safeguard used by the short-row detector.
5. Image coverage — displayed image bounding boxes provide a coarse page-area ratio.
6. Raster grid structure — only on image-dominant, low-text pages, the page is rendered to 72-dpi grayscale and deterministic horizontal/vertical dark-pixel projections look for table-like grids. This is image processing, not OCR.

The Actor processes PDFs sequentially and rasterizes only scan-like pages. It does not retain full-page rasters after each page is inspected.

Stable reason codes

Document-level reason codes include, as applicable:

• FETCH_ERROR
• TIMEOUT
• HTTP_NON_2XX
• INVALID_URL
• PRIVATE_ADDRESS
• DNS_ERROR
• FILE_SIZE_LIMIT_EXCEEDED
• PAGE_LIMIT_EXCEEDED
• INVALID_PDF_MAGIC
• CONTENT_TYPE_MISMATCH
• PDF_PARSE_ERROR
• PDF_INSPECTION_ERROR
• PDF_ENCRYPTED
• SELECTABLE_TEXT_PRESENT
• IMAGE_DOMINANT_PAGES_PRESENT
• NATIVE_TABLE_CANDIDATE
• SCANNED_TABLE_CANDIDATE
• MIXED_TABLE_MODALITIES
• TABLE_GEOMETRY_DETECTED
• RASTER_TABLE_STRUCTURE_DETECTED
• OCR_NOT_REQUIRED
• OCR_LIKELY_REQUIRED
• NO_TABLE_CANDIDATE

Page-level reason codes include:

• SELECTABLE_TEXT_PAGE
• IMAGE_DOMINANT_LOW_TEXT
• ALIGNED_COLUMNS
• DENSE_NUMERIC_COLUMNS
• RULED_OR_DENSE_CELL_STRUCTURE
• RASTER_GRID_STRUCTURE
• TABLE_CANDIDATE

Limits and non-chargeable diagnostics

The custom paid event is emitted only for a PDF that:

1. was fetched successfully;
2. stayed within the configured byte/page limits;
3. was not encrypted;
4. was successfully inspected; and
5. produced one of the four usable routes: native, mixed, OCR-likely, or no-table.

Malformed, encrypted, oversized, over-page-limit, failed-download and other unsupported/error rows remain visible as structured diagnostics but do not intentionally trigger the custom pdf-preflight event.

The current verified Pay-per-Event composition has no paid apify-default-dataset-item event, so default-dataset rows do not receive a separate paid dataset-item event under the current configuration.

Pay per Event

Current verified pricing and billing composition:

• pdf-preflight — USD 0.01 per charge-eligible completed inspected PDF preflight and the primary custom event.
• apify-actor-start — USD 0.00005, a platform-managed one-time start event. The Actor source does not manually emit this event.
• apify-default-dataset-item — not present as a paid event in the current verified composition.
• User platform-usage pass-through — OFF; users are not separately charged the Actor's platform-usage costs under the current configuration.

The source binds pdf-preflight only to charge-eligible completed dataset rows:

await Actor.push_data(row, charged_event_name="pdf-preflight")

Unsupported/error diagnostic rows are pushed without the custom paid-result event.

Memory and cost guard

.actor/actor.json fixes:

• minimum memory: 256 MB;
• default memory: 256 MB;
• maximum memory: 256 MB.

The current local max-bound benchmark is recorded in LOCAL_MAX_BOUND_BENCHMARK.json. It is local evidence only and does not replace Apify-platform runtime measurements.

Public-network connection guard

Public URL safety is enforced twice: input/redirect validation rejects obvious non-public destinations, and the HTTP transport also resolves the hostname inside the TCP connection path, rejects any non-global DNS answer, and connects to the exact validated IP address rather than asking the operating system to resolve the hostname again. TLS SNI and certificate validation continue to use the original request hostname. This closes the earlier DNS-rebinding/TOCTOU gap for direct outbound connections. Proxy environment variables are disabled for this fetch client so they cannot bypass the destination guard.

Every new TCP connection, including connections created for redirect targets, passes through the same public-only network backend.

Validation notes

The deterministic routing logic is regression-tested against native-table, scanned/image-only, mixed, no-table, encrypted, and malformed PDF cases. Public regression controls include a U.S. Bureau of Labor Statistics statistical-table PDF and the W3C no-table dummy PDF. These cases are targeted regression controls, not a statistical estimate of accuracy on arbitrary real-world PDFs.

Explicit non-claims

This Actor does not:

• run OCR or return OCR text;
• extract tables, cells, CSV, Markdown, JSON content or invoice fields;
• call an LLM, multimodal model, computer-vision API or paid external API;
• determine semantic table correctness;
• guarantee Camelot/Tabula/pdfplumber extraction success;
• classify arbitrary embedded photos as tables unless deterministic grid evidence is present;
• support password entry for encrypted PDFs;
• accept private cloud-drive files or authenticated URLs;
• provide manual audits or document-processing services.