Oma Pdf

PDF Skill - PDF to Markdown Conversion

Scheduling

Goal

Convert PDF files into structured Markdown or another requested extraction format while preserving readable document structure for LLM context, RAG, or downstream review.

Intent signature

• User asks to convert, parse, read, extract, or transform a PDF.
• User needs PDF text, headings, lists, tables, or images prepared for AI consumption.
• User mentions "PDF to markdown", "parse PDF", "read this PDF", or equivalent wording.

When to use

• Converting PDF documents to Markdown for LLM context or RAG
• Extracting structured content such as tables, headings, lists, images, footnotes, or hyperlinks
• Preparing PDF data for AI consumption
• Checking whether a PDF has a text layer before choosing OCR

When NOT to use

• Generating or creating PDFs -> use document-generation tools
• Editing existing PDFs -> out of scope
• Reading an already-text file -> use direct file reading
• Processing HWP, HWPX, DOCX, XLSX, or slide decks -> use the matching document skill

Expected inputs

• input_path: PDF file or folder path
• output_dir: optional target directory
• format: optional output format, default markdown
• ocr_languages: optional OCR language list for scanned or image-based PDFs
• extraction_options: optional flags for tagged structure, image extraction, or hybrid conversion

Expected outputs

• Markdown, text, JSON, HTML, or combined extraction output
• Normalized Markdown when Markdown is produced
• A short report with output path, page count, and conversion issues

Dependencies

• uvx opendataloader-pdf for standard conversion
• uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid for OCR or hybrid conversion (the hybrid server is a console script of the [hybrid] extra, not a standalone package)
• uvx mdformat for Markdown normalization
• Local filesystem access to input and output paths
• Optional OCR runtime via the hybrid server

Control-flow features

• Branches on text-layer quality, tagged PDF availability, scan/OCR needs, and user-requested output format
• Calls external CLI tools through uvx
• Reads local files and writes local extraction outputs
• Uses a hybrid server only when OCR or complex extraction needs justify it

Structural Flow

Entry

1. Confirm that the input path exists and is a PDF file, PDF folder, or supported batch input. 2. Check file size and warn when the input is large enough to risk slow conversion or memory pressure. 3. Resolve output_dir and the expected output filename.

Scenes

1. PREPARE: Validate the input path, output target, and requested extraction options. 2. ACQUIRE: Assess whether the PDF has a readable text layer by extracting a text preview. 3. ACT: Convert using standard mode, tagged-structure mode, or hybrid OCR mode. 4. VERIFY: Run mdformat for Markdown output and inspect the result for readable structure. 5. FINALIZE: Report output path, page count, format, and any extraction quality issues.

Transitions

• If the preview text is readable, use standard conversion.
• If the PDF is tagged and standard output is garbled, retry with --use-struct-tree.
• If the PDF is scanned or image-based, start or reuse the hybrid OCR server and convert with hybrid mode.
• If conversion fails because the PDF is encrypted, stop and ask for the password or an unlocked copy.
• If conversion hits memory or size limits, process smaller page ranges or batches.

Failure and recovery

Exit

• Success: output file exists, Markdown is formatted when applicable, and extracted structure is readable.
• Partial success: output exists but quality issues are reported explicitly.
• Failure: no reliable output is produced and the blocking cause is reported.

Logical Operations

Actions

Tools and instruments

• opendataloader-pdf: primary PDF extraction CLI
• opendataloader-pdf-hybrid: hybrid OCR and complex extraction path
• mdformat: Markdown normalization
• Filesystem commands such as file, wc, or pdfinfo may be used for preflight when available

Canonical command path

uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}"
uvx mdformat "{output_path}"

For scanned/image-based PDFs, start OCR first and then convert through hybrid mode:

uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid --port 5002 --force-ocr --ocr-lang "{languages}"
uvx opendataloader-pdf --hybrid docling-fast "{input_path}" --format markdown --output-dir "{output_dir}"

Resource scope

Preconditions

• The input PDF path exists and is readable.
• The output location is writable or can be created.
• Required CLIs are available through uvx.
• OCR is only attempted when hybrid mode is available or can be started.

Effects and side effects

• Creates or overwrites extraction output depending on configuration and user intent.
• May start a local hybrid OCR server on the configured port.
• May consume significant CPU, memory, or time for large or scanned PDFs.
• Does not intentionally modify the source PDF.

Guardrails

1. Do not invent missing content when extraction is incomplete. 2. Always report garbled text, missing tables, OCR uncertainty, or partial extraction. 3. Prefer standard conversion first when the text layer is readable. 4. Use OCR only when the PDF is scanned, image-based, or standard extraction quality is insufficient. 5. Keep detailed command sequences in resources/execution-protocol.md rather than duplicating every variant here.

References

• Execution protocol: resources/execution-protocol.md
• Configuration: config/pdf-config.yaml
• Context loading: ../_shared/core/context-loading.md
• Quality principles: ../_shared/core/quality-principles.md

PDF Conversion - Execution Protocol

Step 0: Validate Input

1. Confirm the PDF file path exists 2. Check file size (wc -c or ls -lh); warn if >100MB 3. Determine output location:

• If user specified output path → use it
• If not specified → use the same directory as the input PDF

4. Determine output filename: {input_name}.md (same base name, .md extension)

Step 1: Assess PDF Type

Quick check to determine conversion strategy:

# Check if PDF has text layer (vs scanned image)
uvx opendataloader-pdf input.pdf --format text --output-dir /tmp/pdf-check/

• If output contains readable text → standard mode
• If output is empty or garbled → needs OCR (hybrid mode)

Step 2: Convert

Standard conversion

uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}"

If Tagged PDF (structured documents, official reports)

uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}" --use-struct-tree

If scanned/image-based PDF (requires hybrid server)

# Start hybrid server (if not already running).
# The server is a console script of the [hybrid] extra — bare `uvx opendataloader-pdf-hybrid` fails (no such PyPI package).
# First run downloads a large OCR stack (torch, easyocr, docling); warn the user before starting.
uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid --port 5002 --force-ocr --ocr-lang "{languages}"

# Convert
uvx opendataloader-pdf --hybrid docling-fast "{input_path}" --format markdown --output-dir "{output_dir}"

Step 3: Lint & Format

Run mdformat to normalize the converted Markdown:

uvx mdformat "{output_path}"

This auto-fixes:

• Inconsistent heading style
• Missing blank lines around blocks
• Trailing whitespace
• Unordered list marker normalization

Step 4: Verify

1. Read the generated Markdown file 2. Verify structure:

• Headings preserved (#, ##, etc.)
• Tables rendered correctly (pipe syntax)
• Lists maintained (bullets, numbered)
• No garbled or missing sections

3. If output directory is temporary, move the file to the target location 4. If the user needs the content in the conversation, read and present it

Step 5: Report

Tell the user:

• Output file path
• Page count processed
• Any issues encountered (missing tables, OCR quality, etc.)
• Suggest hybrid mode if standard conversion had quality issues

Error Recovery