PDF Extract

PDF Extract – extrakce poznámek z knih v5.0 (script-backed)

Kdy použít

• Uživatel chce vytáhnout své ruční poznámky a zvýraznění z PDF knihy
• Trigger fráze: "extrahuj poznámky", "poznámky z PDF", "/pdf-extract", "vytáhni z knihy"

Vstup

• Cesta k PDF souboru (povinné)
• Volitelně: výstupní cesta, konkrétní rozsah stran

Kontext uživatele

• Uživatel anotuje digitálním perem na tabletu
• Typické anotace: čárky u textu, ohraničení pasáží, podtržení, sem tam ruční poznámka
• Tahy jsou vždy nepravidelné (nikdy dokonale rovné) – to je klíčový rozlišovací znak od tištěného obsahu
• Schémata a diagramy v knize mají být zachovány jako obrázky, NE převáděny na text

Architektura — AI dělá úsudek, skript mechaniku

Veškerá deterministická logika žije v ~/.claude/skills/pdf-extract/scripts/detect.py (JSON na stdout, progress na stderr). Detekční pravidla, prahy a draze zaplacené poučky z verzí v3–v4.1 (fill-only paths neviditelné v PNG, řazení merge_ranges dle y_min, margin=15, rozlišení ručního tahu od layoutu) jsou zapsané ve skriptu jako kód + komentáře — při úpravách logiky edituj skript, nepiš ad-hoc Python do session.

AI (tato session + subagenti) dělá jen to, co skript neumí: vizuální čtení ručního textu, interpretaci složitých stran, sestavení výstupu.

scan            → kategorizace stran: simple / marginal / complex
extract-simple  → strany s vestavěnými PDF anotacemi (highlight/underline/strikeout) → hotový markdown
extract-margins → zatržení na okrajích → hotový markdown (vektorová data, SPOLEHLIVĚJŠÍ než vizuální analýza)
render          → PNG + txt + hints pro složité strany (jediné, co jde na subagenty)
clip            → výřez schématu/obrázku do PNG (pro subagenty)

Dávkový režim (výchozí chování)

KRITICKÉ – MUSÍŠ DODRŽET:

• Výchozí: zpracuj prvních 50 stran, vytvoř výstupní .md soubor a ZASTAV SE
• Vypiš uživateli výsledky a ČEKEJ na jeho odpověď — NEPOKRAČUJ automaticky na strany 51+
• Pokud uživatel řekne "zpracuj celou knihu" / "pokračuj", pokračuj dalšími dávkami
• Při pokračování přidávej do existujícího .md, nemazej předchozí výsledky

Workflow

1. Závislosti

python3 ~/.claude/skills/pdf-extract/scripts/detect.py deps-check

Pokud "ok": false → python3 -m pip install --user --break-system-packages PyMuPDF Pillow numpy a znovu.

2. Scan (detekce + kategorizace)

python3 ~/.claude/skills/pdf-extract/scripts/detect.py scan "<pdf>" --start 1 --end 50

JSON vrátí metadata knihy a summary se stranami ve třech kategoriích:

• simple — pouze vestavěné PDF anotace (highlight/underline/strikeout) → krok 3a
• marginal — ruční kresby POUZE na okrajích → krok 3b (programaticky! fill-only tahy jsou v PNG neviditelné)
• complex — kresby v těle, ink anotace, barevné pixely, ruční text → krok 4 (subagenti)

Vypiš uživateli přehled: název/autor, kolik stran nalezeno, rozklad simple/marginal/complex. Skript sám filtruje layout vzory opakující se na >30 % stran (dekorace, rámečky).

3. Programatická extrakce (bez subagentů, extrémně levná)

# 3a — simple strany
python3 ~/.claude/skills/pdf-extract/scripts/detect.py extract-simple "<pdf>" --pages 12,15,23
# 3b — marginal strany
python3 ~/.claude/skills/pdf-extract/scripts/detect.py extract-margins "<pdf>" --pages 8,31

Oba vrací hotový markdown v JSON poli markdown — jde přímo do výstupního souboru.

4. Vizuální analýza složitých stran (subagenti)

NIKDY nečti PNG stran v hlavním kontextu — vždy deleguj.

python3 ~/.claude/skills/pdf-extract/scripts/detect.py render "<pdf>" --pages 5,9,14 --outdir temp_pages

Vytvoří page_NNNN.png (250 DPI), page_NNNN.txt (tištěný text) a page_NNNN_hints.txt (pozice detekovaných kreseb vč. hand_drawn příznaku — říká subagentovi KAM se dívat).

Rozděl složité strany do dávek po max 10–15 stranách, dávky spusť paralelně (2–3 subagenty). Model: sonnet default; opus pokud jde o hustý/špatně čitelný rukopis. Prompt pro každého subagenta:

Jsi expert na extrakci ručních poznámek z PDF knih.

Zpracuj strany: [seznam] | PNG+txt+hints: temp_pages/page_NNNN.*
Pro každou stranu: (1) přečti _hints.txt — pozice detekovaných kreseb,
(2) přečti PNG (Read tool), (3) přečti .txt pro kontext tištěného textu,
(4) identifikuj anotace dle tabulky, ZAMĚŘ SE na pozice z hints.

Typy: [RUKOU PSÁNO] ruční text · [ZATRŽENO] svislá čára na okraji ·
[ZVÝRAZNĚNO] highlight/rámeček · [PODTRŽENO] · [OBRÁZEK] označený obrázek ·
[SCHÉMA] diagram — VŽDY jako obrázek, NIKDY nepřevádět na text ·
[ŠIPKA] · [SYMBOL] hvězdička/vykřičník/otazník · [ZÁLOŽKA] celá strana

Rozlišení ruční vs. tištěné: uživatel píše digitálním perem na tabletu —
tahy jsou VŽDY nepravidelné. Dokonalá geometrie (tabulky, rámečky, dekorace)
= tištěný prvek, NEoznačuj jako anotaci. Při nejistotě zahrň s poznámkou [nejisté].

Schéma/obrázek extrahuj výřezem (souřadnice odhadni z PNG + hints):
python3 ~/.claude/skills/pdf-extract/scripts/detect.py clip "<pdf>" --page N \
  --rect x0,y0,x1,y1 --out "<nazev_knihy>_images/img_pageN_1.png"
V markdownu pak: ![popis](<nazev_knihy>_images/img_pageN_1.png)

VÝSTUP: pouze strukturovaný markdown per strana:
## Strana XX
### [TYP] emoji_barvy(jen u barevných: 🟢🟡🔴🔵🟠)
> text (zatržené pasáže = citace tištěného textu; ruční poznámky kurzívou)
---
Nečitelný text = [nečitelné]. NIKDY text nevymýšlej.

5. Programatická verifikace po subagentech

KRITICKÉ: Pro každou stranu, kde subagent nenašel nic (nebo hlásil „false positive"), zkontroluj scan JSON — pokud měla margin_drawings > 0, subagent se mýlil (fill-only tahy v PNG nevidí). Spusť na tyto strany:

python3 ~/.claude/skills/pdf-extract/scripts/detect.py extract-margins "<pdf>" --pages X,Y --min-items 10

a doplň výsledky do výstupu. Vektorová data z PDF jsou pro okrajová zatržení autoritativní.

6. Sestavení výstupního souboru

Sluč markdown z kroků 3a + 3b + 4 + 5, řazeno podle čísla strany.

• Název: Nazev_knihy (Autor).md (mezery v názvu knihy → podtržítka), do složky zdrojového PDF
• Hlavička: název, autor, datum extrakce, zdrojový soubor, počet anotovaných stran z celku
• NEMAZAT existující obsah — uživatel může mít vlastní poznámky nad extrakcí; doplňuj jen sekce za oddělovačem ---
• Černé anotace bez emoji (default), barevné s emoji

7. Úklid a shrnutí

rm -rf temp_pages/

Ponech {nazev_knihy}_images/. Vypiš: cestu k .md, cestu k obrázkům, počet stran/anotací, rozložení typů, nejčastěji anotovaná témata.

Pravidla kvality

Vždy: dávky (nedrž celé PDF v paměti) · přesný přepis ručních poznámek · [nečitelné] když nejde přečíst · dostatečně velký citovaný blok u zatržení · průběžně informuj o postupu · schémata vždy jako PNG.

Nikdy: nevynechávej nalezené anotace · nevymýšlej text · nemaž existující obsah · nečti PNG stran v hlavním kontextu · neoznačuj tištěné prvky jako anotace · nepřeváděj schémata na text.

Changelog

• 2026-07-02 (v5.0) — Konverze na script-backed: veškerá detekce a programatická extrakce přesunuta do scripts/detect.py (otestováno na syntetickém PDF: simple/marginal/complex kategorizace, layout filtr, párování textu, clip). SKILL.md už neobsahuje inline Python — konec re-implementace při každém běhu. Nový clip subcommand pro subagenty. Model subagentů: sonnet default (odstraněno mylné „opus má 1M kontext").
• v4.1 — Programatická extrakce marginálních stran (fill-only paths jsou v PNG neviditelné → vektorová data autoritativní), verifikace po subagentech, merge_ranges řazení dle y_min, margin=15.
• v3–v4 — is_hand_drawn heuristika (bezier/krátké segmenty/odchylka od osy), klasifikace pozice kreseb, dávkový režim 50 stran.