PDFagendid/firecrawl/skill.mdown

Allpool on valmis `fire-pdf-agent-guide.md`, mille saad otse salvestada ja kasutada LuunaOS agentide õpetusfailina. [firecrawl](https://www.firecrawl.dev/blog/fire-pdf-launch)

***

```markdown
# Fire-PDF agenti juhend

See fail kirjeldab, kuidas agent peab Fire-PDF mootoriga töötama PDF-ide parsimisel, millal GPU kasutada, kuidas väljundit käsitleda ja kuidas seda siduda teiste agentidega LuunaOS-is.[page:1]

## 1. Mis on Fire-PDF

- Fire-PDF on Rustis kirjutatud PDF-parsimise mootor, mis konverteerib PDF-id struktureeritud markdowniks.[page:1]
- Kõik PDF-id (skännitud, tekstipõhised või segad) töödeldakse ühtse pipeline’i kaudu.[page:1]
- Tekstipõhised lehed ekstraktitakse natiivse tekstiväljavõttega ilma GPU-ta, skännitud ja pildirikkad lehed suunatakse neuronaalse layout-mudeli ja OCR-i kaudu.[page:1]
- Väljundis säilitatakse korrektne lugemisjärjekord, tabelid markdown-tabelitena, valemid LaTeX-ina ja mitme veeruga struktuur.[page:1]

## 2. Põhiomadused agentidele

Agent peab eeldama, et Fire-PDF:

- Kiirus: ca 3.5–5.7x kiirem kui eelmine parser, keskmiselt <400ms lehe kohta.[page:1]
- **GPU-optimeerimine**: ainult skännitud või pildirikkad lehed lähevad GPU pipeline’i; tekstilehed jäävad CPU-le.[page:1]
- **Layout-teadlik täpsus**:
  - Tabelid saavad kõrgema token-piirangu ja kuni 25 sekundit markdown-tabeli genereerimiseks.[page:1]
  - Valemid säilitatakse LaTeX-ina ja saavad valemispetsiifilised promptid.[page:1]
  - Tekstiregioonid töötatakse lühikese aja- ja token-eelarvega efektiivsuse nimel.[page:1]
  - Lugemisjärjekord ennustatakse neuronaalselt, vajadusel kasutatakse XY-cut fallback’i mitme veeruga layout’i jaoks.[page:1]

## 3. Fire-PDF pipeline – kuidas agent peab mõtlema

Fire-PDF pipeline koosneb viiest etapist.[page:1] Agent ei juhi detaile, aga peab mõistma etappe, et väljundit õigesti tõlgendada.

1. **Classify**
   - Rakendatakse `pdf-inspector` Rust teeki, mis skaneerib PDF sisekujundust (fonte, tekstikäske, pildikattuvust) millisekunditega.[page:1]
   - Iga leht märgitakse:
     - tekstipõhine (native extract, no GPU)
     - OCR-i vajav (skännitud/pildirikas)

2. **Render**
   - OCR-i vajavad lehed renderdatakse piltideks 200 DPI juures.[page:1]
   - Ülisuurte lehtede puhul tehakse automaatne cap või slicing (lehe tükeldamine).[page:1]

3. **Layout Detection**
   - Renderdatud pildid lähevad neuronaalse dokumendilayout-mudeli peale (GPU), mis tagastab:
     - bounding box’id
     - elementide tüübid (tabel, tekst, valem, pilt, header/footer)
     - lugemisjärjekorra.[page:1]

4. **Extraction**
   - Tekstipõhised lehed:
     - natiivne tekstiväljavõte, ilma GPU-ta.[page:1]
   - Skännitud/pildirikkad regioonid:
     - saadetakse GLM-OCR vision-language mudelile.[page:1]
     - kasutatakse regiooni-tüübi kaupa spetsiaalseid promte ja parameetreid (tabelid, valemid, tekst jne).[page:1]

5. **Assembly**
   - Kõik tulemused sorditakse lugemisjärjekorra järgi.[page:1]
   - Tabelid konverteeritakse markdown-tabeliteks.
   - Valemid jäävad LaTeX-i kujul.
   - Geomeetriline deduplikatsioon eemaldab kattuvad detektsioonid.[page:1]

## 4. Agentide käitumisreeglid Fire-PDF väljundiga

### 4.1 Üldine käitumine

- Eelda, et PDF on juba Fire-PDF läbi käinud, kui kasutad Firecrawl API /parse või muud dokumentide parsimise endpointi.[page:1]
- Ära ürita ise PDF-i käsitsi OCR-ida, kui Fire-PDF väljund olemas – kasuta antud markdowni, LaTeX-i ja tabeleid.
- Kui väljundis on nähtavad segad (tabel katki, valem puudub, veerud segamini), logi see LuunaOS monitoringu agenti jaoks (kvaliteediraport).  

### 4.2 Tabelid

- Tabelid on juba markdown-tabelitena; enne täiendavat töötlemist:
  - kontrolli päiseid, ridade arvu ja veergude järjekorda
  - vajadusel normaliseeri tabel n8n/Airtable importiks.
- Suured finants- või raportitabelid võivad olla keerukad, aga Fire-PDF annab neile rohkem aega ja tokensi – ära lõika neid agressiivselt.[page:1]

### 4.3 Valemid

- Valemid on LaTeX, kasuta neid:
  - analüüsiks (nt sümboliline matemaatika, kui sul on eraldi matemaatika-agent)
  - renderdamiseks UI-s (frontendi agent, dokumentatsiooni komponendid).
- Kui LaTeX tundub katki, märgi see kvaliteediprobleemina, aga ära automaatselt ümberkirjuta ilma kontekstita.

### 4.4 Mitme veeruga tekst

- Lugemisjärjekord on juba neuronaalselt tuletatud; eelda, et tekst on õiges järjestuses.[page:1]
- Kui avastad loogikavigu (lause keskel kontekst hüppab teise veergu), märgi see, aga ära tee käsitsi re-flow’d, välja arvatud eriprotsessides (nt human-in-the-loop).

## 5. Agentide töövood LuunaOS-is

### 5.1 PDF-parsimise põhiworkflow

**Workflow: `pdf_to_markdown_pipeline`**

- Sisend: PDF URL, failitee või binaar (lokalne).
- Sammud:
  - `routing-agent` otsustab, kas kasutada Firecrawl API /parse või lokaalset Fire-PDF integratsiooni.
  - `firepdf-agent`:
    - saadab dokumendi parsimisse.
    - võtab vastu markdown, tabeleid, LaTeX-valemeid.
    - tagastab struktureeritud objekti:  
      - `pages[]`, `tables[]`, `formulas[]`, `sections[]`.
  - `postprocess-agent`:
    - normaliseerib tabelid (CSV/Airtable-ready).
    - puhastab tekstiblokid (headingud, sektsioonid).
  - `storage-agent`:
    - salvestab väljundi lokaalsesse baasi, Airtable’i või n8n workflow-sse.

### 5.2 GPU/CUDA koormuse haldus (RTX 3090)

**Workflow: `gpu_lane_routing`**

- Eesmärk: kopeerida Fire-PDF mõtteviisi – suured dokumendid ei tohi mõjutada väikeste latentsust.[page:1]
- Loogika:
  - Agent klassifitseerib dokumendi:
    - väiksed: ≤ 5 lehte
    - keskmised: 6–50 lehte
    - suured: > 50 lehte
  - Iga klass läheb eraldi GPU queue’sse (lane):
    - `lane_small`: lühike timeout, kõrge prioriteet.
    - `lane_medium`: standard.
    - `lane_large`: madalam prioriteet, lubatud pikem runtime.
- Tekstipõhised lehed:
  - CPU-only worker; GPU-t ei kasutata, kui Fire-PDF klassifitseeris lehe tekstipõhiseks.[page:1]
- Skännitud/pildirikkad:
  - GPU worker; GLM-OCR või muu VLM.

## 6. Seosed teiste Firecrawl funktsioonidega

Agent peab teadma, et Fire-PDF on osa laiemast Firecrawl ökosüsteemist:[page:1]

- `/scrape`, `/search`, `/crawl`, `/interact` ja `/monitor` tegelevad web-data hankimisega.[page:1]
- Fire-PDF on fokusseeritud dokumentide (/parse) LLM-ready struktuuriks muutmisele.[page:1]
- Web-scale `/monitor` saab agenti teavitada, kui uued PDF-id ilmuvad (nt uus raport, whitepaper).[page:1]

Soovitus agentidele:

- Kui `/monitor` leiab uue PDF-i:
  - kohe käivita `pdf_to_markdown_pipeline`.
  - tulemuse põhjal loo:
    - kokkuvõtted,
    - highlight’id,
    - küsimus-vastus endpointid.

## 7. Agentide API-kasutus (abstraktne kirjeldus)

> Tähtis: ära pane siia reaalseid võtmeid, paroole ega tokeneid.

Agentivorming:

- `firepdf-agent` peab oskama:
  - saata dokumendi Firecrawl /parse endpointi või lokaalsele Fire-PDF teegile.
  - oodata markdown + struktuuri tagasitulekut.
  - valida CPU vs GPU tee vastavalt Fire-PDF klassifikatsioonile (kui lokaalne integratsioon).
- `routing-agent`:
  - otsustab: kas kasutada pilveteenust või lokaalset Fire-PDF deployment’i (nt Rust teenus GPU-l).
  - arvestab privaatsust, kulusid ja latentsust.

## 8. Salvestamine Airtable’i ja n8n-i

### 8.1 Airtable schema agentidele

Soovitatav tabel:

| Väli           | Tüüp          | Kirjeldus                              |
|----------------|---------------|----------------------------------------|
| `doc_id`       | Text          | Unikaalne dokumendi ID                 |
| `source_url`   | URL           | PDF allikas                            |
| `page_index`   | Number        | Lehe indeks                            |
| `section_id`   | Text          | Sektsiooni ID või pealkiri             |
| `content_md`   | Long text     | Markdown sisu Fire-PDF väljundist      |
| `has_tables`   | Checkbox      | Kas lehel on tabelid                   |
| `has_formulas` | Checkbox      | Kas lehel on valemeid                  |
| `tables_json`  | Long text     | JSON tabelistruktuur                   |
| `formulas_tex` | Long text     | LaTeX valemite loend                   |

Agentide reegel:

- `storage-agent`:
  - konverteerib markdown + struktuuri ülaltoodud skeemiks.
  - pushib kirjed Airtable’i API kaudu (või lokaalsesse DB-sse, kui privaatsus nõuab).

### 8.2 n8n workflow

Workflow `firepdf_ingest`:

- Trigger:
  - webhook, `/monitor` event või cron.
- Sammud:
  - Node: `HTTP Request` – PDF allalaadimine.
  - Node: `Custom Function` – edastab PDF-i Fire-PDF pipeline’i (pilv või lokaalne teenus).
  - Node: `Split In Batches` – iga leht/sektsioon eraldi.
  - Node: `Airtable` – salvestab ülalkirjeldatud skeemi.
  - Node: `Notify` – teavitab LuunaOS agenti uuest ingestist (nt Webhook LuunaOS-i).

## 9. Kvaliteedimonitoring ja riskid

Agentid peavad arvestama järgmiste riskidega:

- **OCR-vead** skännitud dokumentides:
  - vale numbrid finantstabelites,
  - katkised valemid.
- **Layout-anomaaliad**:
  - mitme veeruga tekst vales järjekorras.
- **Timeoutid** väga suurte dokumentide puhul:
  - kuigi Fire-PDF optimeerib, lehe tasemel võivad tekkida pikkad jooksud (tabelid kuni 25s).[page:1]

Riskide leevendamine:

- Käivita `quality-agent`, mis:
  - teeb spot-check’i ridade ja summade osas (finants),
  - kontrollib, kas LaTeX valemid parsitavad (nt kompileeritavad).
- Tulemused:
  - logi LuunaOS sisemisse kvaliteedilogisse,
  - märgi kirjed Airtable’is väljade `quality_score`, `issues`.

## 10. Agentide prompt-mall (näidis)

Agentiprompt Fire-PDF väljundi kasutamiseks:

> Sa oled `firepdf-postprocess-agent` LuunaOS-is.  
> Sulle antakse Fire-PDF poolt genereeritud markdown, tabelid ja LaTeX-valemid.  
> Sinu ülesanne:
> - säilitada lugemisjärjekord,
> - normaliseerida tabelid CSV/Airtable vormi,
> - jätta LaTeX valemid muutmata, kui need on süntaktiliselt korrektsed,
> - lisada metaandmed: `doc_id`, `page_index`, `section_id`.  
> Väljund: JSON objekt skeemiga:
> ```json
> {
>   "doc_id": "...",
>   "pages": [
>     {
>       "page_index": 0,
>       "section_id": "Introduction",
>       "content_md": "...",
>       "tables": [ ... ],
>       "formulas": [ "..." ]
>     }
>   ]
> }
> ```

---