moonshotnote-ocr

Files (31)

• SKILL.md
• openai.yaml · agents/
• doctor.py · scripts/
• ocr_image.py · scripts/
• __init__.py · scripts/ocr_pipeline/
• __init__.py · scripts/ocr_pipeline/classifiers/
• page_type.py · scripts/ocr_pipeline/classifiers/
• __init__.py · scripts/ocr_pipeline/engines/
• paddle.py · scripts/ocr_pipeline/engines/
• pdf_inspector.py · scripts/ocr_pipeline/engines/
• pp_structure.py · scripts/ocr_pipeline/engines/
• surya.py · scripts/ocr_pipeline/engines/
• models.py · scripts/ocr_pipeline/
• output.py · scripts/ocr_pipeline/
• __init__.py · scripts/ocr_pipeline/postprocess/
• columns.py · scripts/ocr_pipeline/postprocess/
• paragraphs.py · scripts/ocr_pipeline/postprocess/
• tables.py · scripts/ocr_pipeline/postprocess/
• router.py · scripts/ocr_pipeline/
• utils.py · scripts/ocr_pipeline/
• requirements-pdf.txt · scripts/
• requirements-structure.txt · scripts/
• requirements-surya.txt · scripts/
• requirements.txt · scripts/
• review_low_confidence.py · scripts/
• setup.ps1 · scripts/
• setup.sh · scripts/
• test_canonical_schema.py · tests/
• test_page_type.py · tests/
• test_pdf_inspector.py · tests/
• test_review_compatibility.py · tests/

SKILL.md (first lines)

# moonshotnote-ocr

Use this skill to extract reliable OCR and text content from PDF documents, image files, and scanned page images.

## Engine Choice

- Use `pdf-inspector` (Firecrawl) first for PDF document inputs. It rapidly classifies PDFs (`text_based`, `scanned`, `image_based`, `mixed`) and directly extracts structured Markdown for native text PDFs in milliseconds (0ms OCR compute cost).
- When a PDF is `scanned` or `image_based` (or for scanned pages in `mixed` PDFs), selective routing automatically directs scanned pages to PaddleOCR, PP-StructureV3, or Surya.
- Use PaddleOCR first for normal screenshots, UI captures, receipts, signs, mobile captures, Korean text, and mixed Korean-English text.
- Use `--page-mode auto` for ebook captures so PaddleOCR boxes can classify `plain-text`, `table`, `multi-column`, `layout`, or `unknown`.
- Use optional PP-StructureV3 only when `doctor.py` reports `optional_capabilities.pp_structure.available=true`; it is intended for table/layout parsing and may be unavailable on a local runtime.
- Use Surya when the input is a document page where layout, reading order, section headers, formulas, or markdown reconstruction matter.
- Use `--engine paddle` when the task must avoid Surya runtime use.

## Output Policy

Default output is intentionally minimal:

- plain text: `<stem>.<engine>.txt`

When `--out` is not provided, save under the source location: `<input-dir>/ocr-output/<requested-engine>/`.

Use optional evidence outputs only when needed:

- `--json`: write `<stem>.<engine>.json` with boxes, confidence, warnings, and low-confidence lines
- `--md`: write `<stem>.<engine>.md` for human review
- `--summary`: write `batch_summary.json` for batch audit
- `--all`: write txt, json, md, and batch summary

Preserve original text. Do not translate Korean unless the user asks for translation. Mark unreadable or suspicious text as `[unclear]` rather than inventing content.

Structured JSON fields are additive. Existing consumers can keep reading `engine`, `input`, `text`, `items`, `warnings`, and `low_confidence`. New outputs may also include `requested_engine`, `fallback_used`, `fallback_reason`, `page_type`, `page_type_confidence`, `runtime_metadata`, and `structured`.

## Low-confidence Review

Do not treat a low-confidence count as a final result by itself.

When OCR output has `[unclear]`, low-confidence lines, suspicious mixed Korean/English text, table noise, code noise, or visible OCR artifacts:

1. Generate evidence outputs with `--json` or `--all`.
2. Build a review pack:

```powershell
$ocrPython = "$HOME\.moonshot-relay\runtimes\moonshotnote-ocr-py312\Scripts\python.exe"
& $ocrPython scripts/review_low_confidence.py C:\path\to\ocr-output\paddle --threshold 0.75
```

3. Inspect the generated crop images/contact sheets against the original page images.
4. Update `low_confidence_manifest.json` item statuses:
   - `accepted`: OCR text is good enough
   - `corrected`: `review_text` contains the corrected text
   - `unreadable`: source image is not legible enough to recover
   - `ignored`: non-content chrome, page number, watermark, decoration, or irrelevant table artifact
5. Do not close the task while any item remains `needs_review` unless the user explicitly accepts that risk.

If there are many low-confidence items, prioritize content-bearing body text, headings, code, table labels, and commands first. Page numbers, viewer chrome, watermarks, tiny benchmark internals, and decorative glyphs can be marked `ignored` after visual confirmation.

## Commands

Run setup once on Windows:

```powershell
powershell -ExecutionPolicy Bypass -File scripts/setup.ps1
```

Default setup installs the PaddleOCR core runtime only. Install optional dependencies only when needed:

```powershell
powershell -ExecutionPolicy Bypass -File scripts/setup.ps1 -InstallPdf
powershell -ExecutionPolicy Bypass -File scripts/setup.ps1 -InstallStructure
powershell -ExecutionPolicy Bypass -File scripts/setup.ps1 -InstallSurya
powershell -ExecutionPolicy Bypass -File scripts/setup.ps1 -InstallAll
```

By default, setup creates a shared runtime at `%MOONSHOT_RELAY_HOME%\runtimes\moonshotnote-ocr-py312`, or `%USERPROFILE%\.moonshot-relay\runtimes\moonshotnote-ocr-py312` when `MOONSHOT_RELAY_HOME` is unset. Set `MOONSHOTNOTE_OCR_RUNTIME` or pass `-RuntimePath` only when a custom shared runtime location is required.

Run setup once on macOS Apple Silicon or Linux:

```bash
bash scripts/setup.sh
```

On macOS Apple Silicon, keep the default setup path for PaddleOCR first. Optional dependencies can be requested explicitly:

```bash
bash scripts/setup.sh --with-pdf
bash scripts/setup.sh --with-structure
bash scripts/setup.sh --with-surya
bash scripts/setup.sh --with-all
```

macOS Intel x86_64 is not supported by the pinned PaddlePaddle runtime.

Check the local runtime:

```powershell
$ocrPython = "$HOME\.moonshot-relay\runtimes\moonshotnote-ocr-py312\Scripts\python.exe"
& $ocrPython scripts/doctor.py
```

On macOS/Linux:

```bash
OCR_PYTHON="${MOONSHOT_RELAY_HOME:-$HOME/.moonshot-relay}/runtimes/moonshotnote-ocr-py312/bin/python"
"$OCR_PYTHON" scripts/doctor.py
```

Inspect and extract text from a PDF file using Firecrawl `pdf-inspector`:

```powershell
$ocrPython = "$HOME\.moonshot-relay\runtimes\moonshotnote-ocr-py312\Scripts\python.exe"
& $ocrPython scripts/ocr_image.py C:\path\to\document.pdf --engine pdf-inspector --json --md
```

OCR an image with PaddleOCR Korean mode:

```powershell
$ocrPython = "$HOME\.moonshot-relay\runtimes\moonshotnote-ocr-py312\Scripts\python.exe"
& $ocrPython scripts/ocr_image.py C:\path\to\screenshot.png --engine paddle --lang korean

From munlucky/moonshotnote-skills, MIT.

More from munlucky/moonshotnote-skills