debug-pdf

> STOP. READ THIS ENTIRE SKILL.MD BEFORE CALLING ANY ENDPOINT. # Debug PDF Skill Automate the lifecycle of an extraction failure: **Failure -> Analysis -> Fixture -> Test** ## Why This Exists Extractors (Marker, Surya, Camelot) break on specific PDF patterns (scanned pages, TOC dots, cursed fonts, watermarks). Manually reproducing these bugs is slow. `/debug-pdf` fast-tracks this by: 1. Downloading the failed artifact 2. Identifying structural "traps" (TOC dots, watermarks, ligatures, etc.) 3. Generating minimal reproduction fixtures using `fixture-tricky` 4. Combining multiple failures into a single stress test PDF ## Quick Start ```bash # Analyze a single failed URL ./run.sh analyze "https://example.com/broken.pdf" # Process multiple failures in batch ./run.sh batch failed_urls.txt --output report.json # Combine all fixtures into one stress test PDF ./run.sh combine stress_test.pdf --max-pages 20 # List known failure patterns ./run.sh list-patterns # Check extraction fidelity (delegates to review-pdf) ./run.sh fidelity <pdf_path> <structural_json_path> # Check session status ./run.sh status ``` ## Commands ### analyze <url> Analyze a single PDF URL and optionally generate a reproduction fixture. ```bash ./run.sh analyze "https://example.com/broken.pdf" ./run.sh analyze "https://example.com/broken.pdf" --no-repro ./run.sh analyze "https://example.com/broken.pdf" --send-inbox ``` ### batch <url-file> Process multiple URLs from a file (one URL per line). ```bash # Create URL file echo "https://example.com/doc1.pdf" > failed.txt echo "https://example.com/doc2.pdf" >> failed.txt # Run batch analysis ./run.sh batch failed.txt --output analysis.json --send-inbox # With NDJSON streaming for real-time progress ./run.sh batch failed.txt --json-stream | tee results.jsonl ``` ### batch Options | Option | Default | Description | | ---------------------------------- | ------- | ------------------------------------------ | | `--file` | - | File containing URLs (one per line) | | `--output` | - | Output JSON report path | | `--send-inbox` | false | Send summary to agent inbox | | `--json-stream` | false | Output NDJSON per PDF (streaming progress) | | `--task-monitor/--no-task-monitor` | true | Enable/disable task-monitor integration | ### combine [output.pdf] Merge all generated fixtures into a single stress test PDF. ```bash ./run.sh combine stress_test.pdf --max-pages 15 ``` ### list-patterns Display all known failure patterns and their descriptions. ### status Show current debug session status and fixture count. ## Detected Patterns (27/30 = 90%) **Structural (4/4 detected):** - `scanned_no_ocr` - Scanned image PDF without text layer - `sparse_content_slides` - Slide deck with minimal text per page - `multi_column` - Complex multi-column layouts (via text block analysis) - `watermarks` - Text obscured by watermark overlays **Encoding (5/5 detected):** - `toc_noise` - Table of contents with dotted leaders - `metadata_artifacts` - Print metadata (Jkt/PO/Frm) in content - `invisible_chars` - Zero-width spaces, direction markers - `curly_quotes` - Windows-1252 encoded smart quotes - `ligatures` - fi/fl/ff ligature characters **Layout (4/4 detected):** - `footnotes_inline` - Footnotes merged into body text (via font size/position heuristics) - `split_tables` - Tables spanning multiple pages (flag only, no merging) - `header_footer_bleed` - Headers/footers mixed into content (via PyMuPDF4LLM Layout) - `diagram_heavy` - Many embedded diagrams/charts **Extraction Quality (6/6 detected):** - `symbol_fonts` - PUA characters from Microsoft Symbol/Wingdings (U+F000-U+F8FF) - `section_under_segmentation` - Too few sections relative to page count - `toc_leaders_in_headers` - Dotted leaders captured in section titles - `partial_sentence_headers` - Sentence fragments detected as section headers - `math_symbols_lost` - Mathematical symbols becoming '?' in extraction - `low_block_density` - Suspiciously few text blocks per page **Network (1/3 detected locally):** - `archive_org_wrap` - Wayback Machine URL wrapper (detected via URL pattern) - `auth_required` - Marketing platform cookie gates (network-level, not detectable locally) - `access_restricted` - Government/defense access controls (network-level, not detectable locally) ## Task-Monitor Integration debug-pdf integrates with the centralized task-monitor for live progress tracking: ```bash # Run batch analysis with task-monitor (enabled by default) ./run.sh batch failed_urls.txt # View progress in task-monitor TUI cd ~/.pi/skills/task-monitor uv run python monitor.py tui --filter debug-pdf # Or check state file directly cat /path/to/debug-pdf/debug_pdf_task_state.json | jq ``` State file schema: ```json { "completed": 25, "total": 50, "progress_pct": 50.0, "patterns": { "scanned_no_ocr": {"detected": 5}, "multi_column": {"detected": 8}, "toc_noise": {"detected": 3} }, "stats": { "download_success": 23, "download_failed": 2, "download_rate": 0.92, "fixtures_generated": 20, "total_pages": 450, "unique_patterns": 6 }, "failures": [...], "status": "running" } ``` ## NDJSON Streaming Output For long-running batch jobs, use `--json-stream` to output one JSON object per line: ```bash ./run.sh batch failed_urls.txt --json-stream | tee results.jsonl # Each line: # {"url": "https://...", "patterns": ["multi_column", "toc_noise"], "pages": 15, "success": true} ``` This enables: - Real-time progress monitoring via `tail -f results.jsonl | jq` - Integration with streaming parsers - Resume from partial runs ## Workflow Integration When `memory` or `extractor` agent reports failures: 1. Collect failed URLs in a text file 2. Run batch analysis: `./run.sh batch failed_urls.txt` 3. Review pattern distribution in output 4. Generate combined stress test: `./run.sh combine stress_test.pdf` 5. Add stress test to extractor's regression suite 6. New patterns get added to `fixture-tricky` for future testing ## Data Storage All data is stored in `~/.pi/debug-pdf/`: - `sessions/` - Individual analysis session JSON files - `fixtures/` - Generated reproduction PDFs - `last_analysis.json` - Quick reference to most recent analysis ## Dependencies - `pymupdf` (fitz) - PDF structure analysis - `pymupdf4llm` - ML-based layout detection for header/footer bleed - `httpx` - HTTP downloads with redirect handling - `typer` - CLI interface - `loguru` - Logging Sibling skills used: - `fetcher` - Robust URL downloading with Playwright support - `fixture-tricky` - Adversarial PDF generation - `extractor` - Verification of generated fixtures - `agent-inbox` - Cross-agent notifications ## Testing ```bash # Run test suite (24 tests) python -m pytest tests/test_debug_pdf.py -v # Generate test fixtures only python tests/test_debug_pdf.py ``` Test coverage includes: - URL validation (security hardening) - Wayback URL detection and extraction - Multi-column layout detection - Header/footer bleed detection - Split table detection - Footnote detection - Full PDF analysis integration ## Sanity Check ```bash ./sanity.sh ``` Verifies: - Python dependencies installed - Sibling skills available - Data directory accessible - CLI commands functional