Metadata-Version: 2.4
Name: pastetoprint-sdk
Version: 0.2.0
Summary: Offline PTDF PDF generation, local Ollama and confirmed Windows printing.
License-Expression: LicenseRef-Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# pasteToPrint Python SDK

`pastetoprint-sdk` prepája Python s existujúcim lokálnym modulom
`@pastetoprint/local-pdf`. PTDF validácia, fonty, rozloženie A4 a samotná
tvorba PDF zostávajú v jednom existujúcom rendereri.

Python balíček používa iba štandardnú knižnicu. Nevyžaduje Python balíček
`ollama`, API token, účet ani verejné pasteToPrint API. Dokument posiela
lokálnemu Node procesu cez stdin; obsah nejde do argumentov príkazu ani do
dočasného PTDF súboru. Podporuje Python 3.10+, Node.js 20+ a vopred
nainštalovaný Chrome, Edge alebo Chromium.

Verzia **0.2.0** pridáva fyzickú tlač vo Windows cez `PrintManager` a
`pastetoprint-print`: výber tlačiarne, počet kópií, povinné potvrdenie,
sledovanie frontu a trvalú ochranu pred duplicitami. Použitie a význam
stavov sú v [PRINTING.md](PRINTING.md).

## Inštalácia

Existujúci lokálny PDF modul pripravte podľa
[`../pdf/README.md`](../pdf/README.md). Python SDK nainštalujte z pripraveného
wheel archívu bez internetu a bez ďalších Python závislostí:

```powershell
python -m pip install --no-index --no-deps C:\balicky\pastetoprint_sdk-0.2.0-py3-none-any.whl
```

Nastavte cestu k PDF modulu alebo ju odovzdajte pri vytvorení klienta:

```powershell
$env:PASTETOPRINT_PDF_MODULE = 'C:\laragon\www\pasteToPrint\integrations\pdf'
```

Pri samostatnej npm inštalácii použite cestu ku konkrétnemu
`node_modules/@pastetoprint/local-pdf` adresáru. SDK automaticky neinštaluje
Node, npm balíčky, prehliadač ani jazykové modely. Pred odpojením od siete
musia byť pripravené všetky lokálne závislosti. Balíček nie je publikovaný
na PyPI.

## PDF jedným volaním

```python
import pastetoprint

document = pastetoprint.from_text(
    'Príliš žltý kôň úpenlivo erdží.\n\nDruhý odsek správy.',
    title='Pracovná správa',
    template='business',
)
result = pastetoprint.render_pdf(document, 'sprava.pdf')
print(result.path)
```

`from_text` vytvorí A4 PTDF. Neprázdny titul vloží aj ako prvý viditeľný
nadpis. Prázdne riadky oddeľujú odseky, jednotlivé zalomenia sa zachovajú.
Text sa interpretuje ako čistý text. Pre tabuľky, zoznamy a ďalšie
štruktúrované prvky odovzdajte priamo PTDF bloky.

## Klient a nastavenie okrajov

```python
from pastetoprint import LocalPdfClient

pdf = LocalPdfClient(
    renderer_path=r'C:\laragon\www\pasteToPrint\integrations\pdf',
    timeout_ms=30_000,
)
result = pdf.render_text(
    'Obsah dokumentu',
    'sprava.pdf',
    title='Mesačná správa',
    template='business',
    orientation='portrait',
    margins_mm={'top': 20, 'right': 15, 'bottom': 20, 'left': 15},
)
```

`render_pdf(document, output_path)` prijíma hotový PTDF objekt.
`render_text(text, output_path)` najprv použije `from_text`.
`PdfResult` obsahuje absolútnu cestu, veľkosť, papier a účinné okraje;
`as_dict()` vráti aj potvrdenie offline vykresľovania. Existujúci súbor
sa prepíše iba s `overwrite=True`. Cieľový adresár musí existovať.
Voliteľné `node_path` a `browser_path` sú cesty k lokálnym programom.
Príkazy sa vykonávajú bez shellu a okno procesu je na Windows skryté.

## Ollama: príprava lokálneho modelu

Pred odpojením od internetu nainštalujte Ollama a stiahnite vhodný lokálny
model, napríklad [`gemma3:1b`](https://ollama.com/library/gemma3:1b):

```powershell
ollama pull gemma3:1b
```

Ukončite už spustenú Ollama a spustite server s vypnutými cloudovými
funkciami. Táto premenná musí patriť procesu servera, preto je potrebný
jeho reštart:

```powershell
$env:OLLAMA_NO_CLOUD = '1'
ollama serve
```

Postup vypnutia cloudu opisuje
[oficiálne FAQ Ollama](https://docs.ollama.com/faq#how-do-i-disable-ollamas-cloud-features).
SDK vyžaduje verziu Ollama s lokálnym `/api/status` endpointom, ktorý
vracia `cloud.disabled: true`. Staršia alebo neoveriteľná konfigurácia
vráti chybu pred odoslaním zadania.

## Funkčný príklad: Ollama → text → PTDF → A4 PDF

V druhom termináli spustite nainštalovaný príklad:

```powershell
pastetoprint-ollama --model gemma3:1b --output sprava.pdf
```

Použije krátke zadanie s označenými ukážkovými údajmi zo servisnej dielne.
Vlastné zadanie možno načítať z UTF-8 súboru:

```powershell
pastetoprint-ollama --model gemma3:1b --prompt-file zadanie.txt --output sprava.pdf --title "Pracovná správa"
```

Ak nechcete použiť premennú pre cestu k rendereru:

```powershell
pastetoprint-ollama --model gemma3:1b --renderer "C:\laragon\www\pasteToPrint\integrations\pdf" --output sprava.pdf
```

Zo zdrojového balíčka je rovnaký príklad dostupný ako
`python examples/ollama_report.py`; nainštalovaný modul aj ako
`python -m pastetoprint.example`. `--help` vypíše ďalšie voľby, napríklad
`--ollama-timeout`, `--max-tokens`, `--browser` a explicitné `--force`.

Rovnaký tok vo vlastnom kóde:

```python
from pastetoprint import LocalPdfClient
from pastetoprint.ollama import OllamaClient

text = OllamaClient().generate(
    model='gemma3:1b',
    prompt='Po slovensky zhrň tieto ukážkové údaje: plán 12 kontrol, hotových 10, zostávajú 2.',
)
result = LocalPdfClient().render_text(
    text, 'sprava.pdf', title='Pracovná správa', template='business',
)
```

Klient používa [Ollama Generate API](https://docs.ollama.com/api/generate)
s `stream: false` a spracuje výhradne pole `response`, bez prípadného
interného uvažovania modelu. Neúplný výsledok alebo odpoveď ukončená
limitom tokenov vráti chybu namiesto vytvorenia skrátenej správy.

## Hranice lokálneho toku

- Ollama klient prijíma iba HTTP loopback adresy. `localhost` prevedie
  na `127.0.0.1`; externé adresy, prihlasovacie údaje a presmerovania odmieta.
- Python HTTP klient ignoruje proxy premenné. API tokeny sa nepoužívajú.
- Pred odoslaním zadania overí vypnutý cloud cez `/api/status` a metadáta
  lokálneho modelu cez `/api/show`. Cloudové názvy a vzdialené aliasy odmieta.
- Chýbajúci model sa automaticky nesťahuje. Pri chybe sa nepoužije iný model,
  verejný endpoint ani cloudový renderer.
- HTTP požiadavka má jeden časový limit aj pre pomaly prichádzajúce
  hlavičky a celé telo odpovede. Predvolený limit je 180 sekúnd na požiadavku.
- PDF sa tvorí cez existujúci renderer s blokovanými sieťovými požiadavkami.
  Python SDK obsah dokumentu ani zadanie nevypisuje do logov.

Tieto kontroly predpokladajú dôveryhodný lokálny server a lokálne programy.
Ollama a jej model musia byť pripravené pred offline prevádzkou.

## Vývoj a overenie

Zo zdrojového adresára SDK:

```powershell
$env:PYTHONPATH = (Join-Path $PWD 'src')
python -m unittest discover -s tests -v
```

Testy používajú reálny PDF renderer a loopback simuláciu API Ollama.
Overujú prenos zadania až po lokálnej kontrole, odmietnutie cloudu a
presmerovaní, časové a veľkostné limity, A4 PDF, štyri okraje, diakritiku
a ochranu existujúcich súborov. Simulácia API nevykonáva jazykový model.
Skutočnú inferenciu overíte spustením vyššie uvedeného príkladu proti
vlastnej Ollama a vopred stiahnutému modelu.

Balíček možno vytvoriť s vopred nainštalovanými build nástrojmi
`setuptools>=77` a `wheel`:

```powershell
python -m pip wheel --no-build-isolation --no-deps . --wheel-dir dist
python tests/check_package.py dist/pastetoprint_sdk-0.2.0-py3-none-any.whl
```

Kontrola balíčka vytvorí čisté Python prostredie, nainštaluje wheel bez
indexu a závislostí a cez nainštalovaný príklad vygeneruje PDF proti
loopback simulácii Ollama. Renderer musí byť vopred nainštalovaný.
Balíček zachováva existujúci licenčný režim aplikácie; kód a fonty PDF
modulu sa distribuujú samostatne s jeho licenčnými oznámeniami.

Tlačové testy používajú simulovaný tlačový front a simulovanú odpoveď
používateľa. Natívna Windows kontrola číta zariadenia, overí nastavenie A4
a vykresľuje PDF bez vytvorenia úlohy. Skutočné odoslanie sa overuje iba po
potvrdení konkrétneho dokumentu používateľom; pozri [PRINTING.md](PRINTING.md).
