Ghid operator pentru PDF

Ce face

Skill-ul pdf este pentru citire, creare, inspectare, randare si verificare de fisiere PDF atunci cand aspectul vizual conteaza. Un PDF nu este doar text extras: este o pagina compusa vizual, cu margini, fonturi, tabele, grafice, imagini, header-e, footer-e si numerotare.

Regula principala: pentru layout, verificarea reala este randarea in imagini PNG si inspectarea lor. Text extraction poate confirma continutul, dar nu poate garanta ca pagina arata corect.

Pentru lucru cu PDF-uri, fluxul foloseste Poppler, mai ales pdftoppm si pdfinfo, plus unelte Python precum reportlab, pdfplumber si pypdf. reportlab este pentru generare de PDF-uri. pdfplumber si pypdf sunt pentru extragere de text si verificari rapide. Randarea cu Poppler ramane verificarea principala pentru fidelitate vizuala.

Vezi si All guides pentru restul ghidurilor.

Când îmi folosește

Foloseste acest skill cand trebuie citit, revizuit sau validat un PDF unde conteaza felul in care arata pagina: formulare, rapoarte, facturi, documente cu tabele, grafice, layout-uri dense sau materiale care urmeaza sa fie livrate mai departe.

Este util si cand trebuie creat un PDF programatic, cu formatare stabila si predictibila. Un PDF generat nu trebuie considerat gata doar pentru ca fisierul exista sau textul poate fi extras. Trebuie randat si verificat vizual.

Este potrivit pentru verificarea finala inainte de livrare: aliniere, spatiere, lizibilitate, margini, ierarhie de sectiuni, header-e, footer-e, numerotare si tranzitii intre pagini. Tabelele, graficele si imaginile trebuie sa fie clare, aliniate si etichetate corect.

Cum îl invoc / declanșez

Nu exista o comanda universala de chat sau CLI definita de sursa publica a skill-ului. Numele skill-ului este pdf, iar declansarea depinde de runtime si de mecanismul local de skill routing.

In practica, il declansezi printr-o cerere explicita despre un PDF unde conteaza citirea, generarea, randarea sau verificarea vizuala. Exemple sigure:

„Verifica acest PDF si spune-mi daca layout-ul este curat.”

„Creeaza un PDF din continutul acesta si verifica randarea.”

„Extrage textul din PDF, dar verifica si daca tabelele arata corect.”

Daca routing-ul automat de skill-uri este activ, astfel de cereri ar trebui sa activeze pdf. Daca nu, operatorul trebuie sa invoce mecanismul disponibil in runtime-ul folosit. Nu presupune ca un anumit alias, plugin extern sau comanda locala exista daca nu a fost configurata.

Exemplu practic

Ai un raport care trebuie livrat ca PDF. Fluxul corect este:

1. Generezi PDF-ul cu reportlab, daca documentul este creat de la zero.
2. Faci verificari rapide de text cu pdfplumber sau pypdf, fara sa tratezi asta ca verificare de layout.
3. Randezi paginile in PNG cu Poppler:

pdftoppm -png "$INPUT_PDF" "$OUTPUT_PREFIX"

4. Inspectezi imaginile rezultate pentru defecte: text taiat, elemente suprapuse, tabele rupte, glyph-uri ilizibile, patrate negre, margini inconsistente, grafice neclare sau etichete lipsa.
5. Dupa fiecare modificare semnificativa, repeti randarea si verificarea.

PDF-ul poate fi livrat doar dupa ce ultima inspectie PNG nu mai arata defecte vizuale sau de formatare.

Output / unde aterizează

Pentru fisiere intermediare, conventia este tmp/pdfs/. Pastreaza-le organizate si sterge-le cand nu mai sunt necesare.

Pentru artifacte finale, cand se lucreaza intr-un repo care foloseste aceasta conventie, output-ul final merge in output/pdf/.

Numele fisierelor trebuie sa fie stabile si descriptive, mai ales cand exista mai multe versiuni randate sau comparatii intre iteratii.

Limite / gotchas

Text extraction nu garanteaza layout corect. Un PDF poate avea continut extras perfect si totusi sa arate prost in randarea reala.

Dependintele pot lipsi. Runtime-ul principal este asteptat sa includa reportlab, pdfplumber, pypdf, pdftoppm si pdfinfo, dar disponibilitatea lor nu este garantata in orice mediu.

Pentru pachete Python:

uv pip install reportlab pdfplumber pypdf

Daca uv nu este disponibil:

python3 -m pip install reportlab pdfplumber pypdf

Pentru Poppler pe macOS:

brew install poppler

Pentru Ubuntu/Debian:

sudo apt-get install -y poppler-utils

Daca o dependinta lipseste, se instaleaza doar ce este necesar. Daca instalarea nu este posibila in mediul curent, raspunsul corect este sa spui clar ce lipseste si cum se poate instala local. Nu livra un PDF ca „verificat” fara randare si inspectie vizuala.

Nu exista variabile de mediu obligatorii. Citatiile si referintele trebuie sa fie lizibile pentru oameni; nu lasa token-uri de tool, placeholder-e sau siruri interne in documentul final.