nette · zipper · Oct 3, 2025 · Apr 27, 2026 · Oct 21, 2025 · Oct 31, 2025
diff --git a/.gitattributes b/.gitattributes
@@ -1,3 +1,9 @@
-.gitattributes export-ignore
-.gitignore export-ignore
-*.texy linguist-language=Text
+.gitattributes  export-ignore
+.github/        export-ignore
+.gitignore      export-ignore
+AGENTS.md       export-ignore
+docs/           export-ignore
+tests/          export-ignore
+
+*.php*          diff=php
+*.sh            text eol=lf
diff --git a/AGENTS.md b/AGENTS.md
diff --git a/ai-access/cs/@home.texy b/ai-access/cs/@home.texy
@@ -0,0 +1,162 @@
+AI Access: jedno PHP rozhraní pro OpenAI, Claude, Gemini, DeepSeek a Grok
+*************************************************************************
+
+<div class=perex>
+
+AI Access je PHP knihovna, která sjednocuje práci s jazykovými modely. Místo pěti různých API a pěti různých formátů odpovědí píšeš jeden kód, který mluví s ChatGPT od OpenAI, s Claude od Anthropicu, s Gemini od Googlu, s DeepSeekem i s Grokem od xAI. Přepnutí mezi nimi je změna jediného řádku.
+
+Zvládá celý pracovní postup: konverzaci, streamování odpovědí, volání nástrojů (function calling), strukturovaný výstup podle JSON schématu, obrázky a dokumenty na vstupu, generování obrázků, embeddingy pro vyhledávání i dávkové zpracování za poloviční cenu.
+
+Nemá žádné závislosti. Jen čisté PHP 8.3 a curl, žádné SDK od výrobce a žádné konflikty verzí ve tvém projektu.
+
+</div>
+
+
+K čemu je jazykový model v aplikaci dobrý
+=========================================
+
+Jestli jsi žádné AI API zatím nevolal, princip je jednodušší, než se zvenčí zdá. Pošleš text a model pošle text zpátky. Všechno ostatní jsou nadstavby nad tímhle jedním pohybem.
+
+V praxi z toho vyroste překvapivě široká škála úloh a stojí za to je znát dřív, než se pustíš do kódu, protože podle toho poznáš, kterou část dokumentace vlastně potřebuješ:
+
+- **Psaní a přepisování textu.** Shrnutí článku, návrh odpovědi na e-mail, překlad, korektura. Nejběžnější a nejjednodušší případ, stačí ti [obyčejná konverzace |chat].
+- **Klasifikace a rozhodování.** Je tahle registrace spam? Do které kategorie patří tenhle dotaz? Model odpoví jedním slovem a ty se podle toho zachováš.
+- **Vytahování dat z nestrukturovaného textu.** Z faktury, životopisu nebo e-mailu potřebuješ pole, která umíš uložit do databáze. Na to je [strukturovaný výstup |structured-output], kde modelu předepíšeš JSON schéma a on ho dodrží.
+- **Odpovídání nad vlastními daty.** Model o tvé dokumentaci nic neví, ale když mu k dotazu přiložíš relevantní úryvky, odpoví přesně. Najít ty správné úryvky je práce pro [embeddingy |embeddings], což je právě to vyhledávání podle významu, kterému se říká RAG.
+- **Práce s obrázky a dokumenty.** Popiš, co je na fotce, přečti údaje z účtenky, shrň přiložené PDF. Viz [obrázky a dokumenty na vstupu |multimodal].
+- **Akce, ne jen text.** Model může požádat o zavolání tvojí funkce, dostat výsledek a pokračovat. Tak vzniká asistent, který se opravdu podívá do tvé databáze, místo aby si odpověď vymyslel. Viz [volání nástrojů |tools].
+- **Hromadné zpracování.** Když nepotřebuješ odpověď hned, [dávkové zpracování |batch] ti dá tytéž modely za polovinu ceny.
+
+Co AI Access naopak není: není to agentní framework, nesnaží se za tebe vymýšlet prompty ani si nedrží konverzace v databázi. Je to vrstva, která mluví s API providerů, a končí přesně tam, kde začínají rozhodnutí tvojí aplikace.
+
+
+Instalace
+=========
+
+```shell
+composer require ai-access/ai-access
+```
+
+Vyžaduje PHP 8.3 nebo novější a rozšíření curl, json a fileinfo, která bývají všude.
+
+
+První zpráva
+============
+
+Potřebuješ klíč od providera, kterého chceš použít. Vydávají je ve svých konzolích [OpenAI |https://platform.openai.com/api-keys], [Anthropic |https://console.anthropic.com/settings/keys], [Google |https://aistudio.google.com/app/apikey], [DeepSeek |https://platform.deepseek.com/api_keys] a [xAI |https://console.x.ai/team/default/api-keys].
+
+```php
+$client = new AIAccess\Provider\OpenAI\Client($apiKey);
+
+$response = $client->createChat('gpt-5.6-luna')
+	->sendMessage('Napiš haiku o PHP.');
+
+echo $response->getText();
+```
+
+To je celé. `createChat()` otevře konverzaci nad zvoleným modelem, `sendMessage()` pošle zprávu a vrátí odpověď.
+
+Jméno modelu je obyčejný řetězec, ne konstanta ani výčtový typ. Zní to jako maličkost, ale znamená to, že nový model funguje v den, kdy ho provider vydá, a nemusíš čekat na aktualizaci knihovny. Ověřit, že model pořád existuje, umí [seznam modelů |providers#Jaké modely provider právě nabízí].
+
+
+Přepnutí providera je jeden řádek
+=================================
+
+Tohle je hlavní slib knihovny, tak ať je vidět hned. Když klient zná i model, mění se opravdu jen ten jeden řádek:
+
+```php
+$client = new AIAccess\Provider\Claude\Client($apiKey, chatModel: 'claude-sonnet-5');
+$client = new AIAccess\Provider\Gemini\Client($apiKey, chatModel: 'gemini-3.5-flash-lite');
+$client = new AIAccess\Provider\DeepSeek\Client($apiKey, chatModel: 'deepseek-v4-flash');
+$client = new AIAccess\Provider\Grok\Client($apiKey, chatModel: 'grok-4.3');
+
+// zbytek kódu je pro všechny stejný
+$chat = $client->createChat();
+```
+
+[Jméno modelu patří ke klíči |providers#Výchozí modely], protože obojí je vlastní jednomu provideru. V reálné aplikaci si klienta zaregistruješ do [DI kontejneru |dependency-injection:] a přepnutí providera je pak změna v konfiguraci, ne v kódu.
+
+
+Pět API, která se neshodnou na ničem
+====================================
+
+Když si vlastní obal nad providery napíšeš sám, u prvních dvou to vypadá na pár hodin práce. Problém začne u třetího, protože každý z nich má jinou představu o tom, jak vypadá rozhovor s modelem. Tady je malý výběr toho, v čem se liší:
+
+| v čem se liší              | Claude               | OpenAI                             | Gemini                    | Grok a DeepSeek    |
+|----------------------------|----------------------|------------------------------------|---------------------------|--------------------|
+| endpoint                   | `v1/messages`        | `v1/responses`                     | `:generateContent`        | `chat/completions` |
+| autentizace                | hlavička `x-api-key` | `Bearer`                           | hlavička `x-goog-api-key` | `Bearer`           |
+| tvar požadavku             | `messages[]`         | `input[]` a `instructions`         | `contents[].parts[]`      | `messages[]`       |
+| jak se jmenuje role modelu | `assistant`          | `assistant`                        | **`model`**               | `assistant`        |
+| klíče spotřeby tokenů      | `input_tokens`       | totéž                              | `promptTokenCount`        | `prompt_tokens`    |
+| kde je důvod ukončení      | `stop_reason`        | `status`, pak `incomplete_details` | `finishReason`            | `finish_reason`    |
+
+Poslední řádek má háček, který stojí za vyslovení nahlas: Gemini v `finishReason` **nikdy** neohlásí, že model chce zavolat nástroj. Zůstane tam `STOP` a samotné volání najdeš až mezi částmi odpovědi. Kdo to neví, napíše kód, který tiše ignoruje polovinu toho, co model řekl, a nedozví se o tom.
+
+Takových drobností jsou desítky a žádná z nich není zajímavá práce. AI Access je má vyřešené a otestované proti skutečným odpovědím API, ne proti vymyšlenému JSONu.
+
+Zároveň ale nepředstírá, že rozdíly neexistují. Sjednocuje to, co mají provideři opravdu společné, a kde se liší, dá ti to najevo typem nebo výjimkou hned při psaní kódu, ne až chybou z produkce.
+
+
+Co knihovna umí
+===============
+
+| Schopnost                                 | OpenAI | Claude | Gemini | DeepSeek | Grok | Generický klient |
+|-------------------------------------------|--------|--------|--------|----------|------|------------------|
+| [Konverzace |chat]                        | ✅     | ✅     | ✅     | ✅       | ✅   | ✅               |
+| [Reasoning effort |options]               | ✅     | ✅     | ✅     | ✅       | ✅   | ✅               |
+| [Volání nástrojů |tools]                  | ✅     | ✅     | ✅     | ✅       | ✅   | ✅               |
+| [Streamování |streaming]                  | ✅     | ✅     | ✅     | ✅       | ✅   | ✅               |
+| [Obrázky na vstupu |multimodal]           | ✅     | ✅     | ✅     | ➖       | ✅   | ✅               |
+| [Dokumenty na vstupu |multimodal]         | ✅     | ✅     | ✅     | ➖       | ➖   | ➖               |
+| [Strukturovaný výstup |structured-output] | ✅     | ✅     | ✅     | ➖       | ✅   | ✅               |
+| [Generování obrázků |images]              | ✅     | ➖     | ✅     | ➖       | ✅   | ➖               |
+| [Dávkové zpracování |batch]               | ✅     | ✅     | ✅     | ➖       | ➖   | ➖               |
+| [Embeddingy |embeddings]                  | ✅     | ➖     | ✅     | ➖       | ➖   | ➖               |
+| [Seznam modelů |providers]                   | ✅     | ✅     | ✅     | ✅       | ✅   | ✅               |
+
+Kde je minus, tam buď provider takové API nemá, nebo ho knihovna zatím nezabaluje.
+
+Poslední sloupec je generický klient pro cokoli, co mluví dialektem `chat/completions`: běžící Ollamu na tvém notebooku, Mistral, OpenRouter, Together, vLLM nebo Azure. Značka u něj znamená něco jiného než u ostatních, totiž co knihovna umí poslat; jestli to opravdu funguje, rozhoduje endpoint a model, na který ho namíříš. Podrobnosti najdeš u [providerů |providers].
+
+
+Navržená, ne nabalená
+=====================
+
+Nastavení specifická pro providera jsou pojmenované argumenty, ne klíče ve sdíleném poli. Rozdíl poznáš hned při psaní: IDE ti u každého providera nabídne přesně to, co daný provider umí, místo aby pole tiše spolklo klíč, který nikam nedojde. K tomu striktní typy všude a readonly hodnotové objekty.
+
+Hierarchie výjimek je postavená na jediné otázce, která v produkci opravdu dává smysl, totiž jestli má cenu volání zopakovat:
+
+```php
+try {
+	$response = $chat->sendMessage('...');
+
+} catch (AIAccess\ApiException $e) {
+	// provider řekl ne; $e->getCode() nese HTTP status
+	if ($e->getCode() === 429) {
+		// překročený limit, zkus to za chvíli
+	}
+
+} catch (AIAccess\CommunicationException $e) {
+	// výpadek sítě nebo nečitelná odpověď, opakování může pomoct
+}
+```
+
+`LogicException` schválně stojí mimo tenhle strom, protože chyba ve tvém vlastním kódu není nic, co by měla produkce odchytávat a přecházet. Celou hierarchii rozebírá kapitola o [ošetření chyb |errors].
+
+Opakování mimochodem nemusíš psát ručně. Knihovna má [dekorátory HTTP vrstvy |http], které umí opakovat po limitech a výpadcích, logovat každý požadavek nebo odpovědi během vývoje cachovat, aby tě opětovné spouštění skriptu nestálo peníze.
+
+
+Kam dál
+=======
+
+- [Začínáme |getting-started] - klíče, první volání a co dělat, když něco nesedí
+- [Konverzace |chat] - historie, systémová instrukce, čtení odpovědi a spotřeby tokenů
+- [Nastavení a reasoning effort |options] - kolik přemýšlení si od modelu vyžádáš
+- [Streamování |streaming] - odpověď čti, zatímco ji model teprve píše
+- [Volání nástrojů |tools] - model se zeptá, tvůj kód odpoví, smyčka se uzavře sama
+- [Strukturovaný výstup |structured-output] - JSON schéma místo proseb v promptu
+- [Provideři |providers] - co který umí, čím se liší a jak zapojit Ollamu nebo OpenRouter
+
+.[note]
+A když si při psaní kódu necháváš pomáhat od AI agenta, mrkni na [Nette AI |ai:]. Najdeš tam plugin pro Claude Code, který agenta naučí Nette, a MCP Inspector, díky kterému se agent podívá přímo do tvojí běžící aplikace.
diff --git a/ai-access/cs/@left-menu.texy b/ai-access/cs/@left-menu.texy
@@ -0,0 +1,14 @@
+- [Přehled |@home]
+- [Začínáme |getting-started]
+- [Konverzace |chat]
+- [Nastavení a reasoning effort |options]
+- [Streamování |streaming]
+- [Volání nástrojů |tools]
+- [Strukturovaný výstup |structured-output]
+- [Obrázky a dokumenty |multimodal]
+- [Generování obrázků |images]
+- [Embeddingy |embeddings]
+- [Dávkové zpracování |batch]
+- [Ošetření chyb |errors]
+- [HTTP vrstva |http]
+- [Provideři a modely |providers]
diff --git a/ai-access/cs/@meta.texy b/ai-access/cs/@meta.texy
@@ -0,0 +1 @@
+{{sitename: AI Access}}