Katalog modelů jsou deklarativní data a směrování je jejich vysvětlitelná projekce

49. Katalog modelů jsou deklarativní data a směrování je jejich vysvětlitelná projekce

Kontext

AI workeři tohoto repozitáře běží na modelech a repozitář o nich nevěděl nic. Které modely existují, co každý umí, jak velký je jeho kontext, který název je aliasem kterého — tato fakta žila v hlavách workerů a v roztroušené próze, což je přesně ten tvar (ručně udržovaná pravda na konzumenta), který odmítá každá jiná část této kódové báze. Schéma zachycení deklaruje volitelná pole model a tokens, která nikdo nevyplňuje; docs/ECONOMICS.md pojmenovává chybějící telemetrii na straně poskytovatele; relace zaznamenávají volnotextové worker.

Dvě stávající rozhodnutí omezují jakoukoli opravu. ADR 0024/0032 utratilo slovo „provider“ za AI klientské nástroje (Claude Code, Codex, Gemini CLI) a brání ho: dodavatel modelu musí být jiné podstatné jméno. A ADR 0032 drží HTTP klienty, TLS, async runtime a SDK mimo crate — takže „registr“, který živě sonduje dodavatele, objevuje modely přes jejich API nebo měří zdraví jejich voláním, je zde vyloučen.

Rozhodnutí

Deklarativní katalog modelů, přesně v duchu share/providers.yaml:

1. Jedna deklarace. share/models.yaml deklaruje vendory (strany, které modely obsluhují — slovo „provider“ zůstává obsazené) a modely: kanonické id, nativní id vendora, aliasy, typovaná slova schopností, kontextové okno, stav životního cyklu, jednu volitelnou poznámku. Pořadí deklarace je významné: je to pořadí preferencí směrování.
2. Fakta nesou provenienci, nebo zůstanou venku. Položky uvádějí, co mohla pojmenovaná reference ověřit (dodané položky: reference modelů Anthropic, jak byla cachována ve stanovený den). Ceny záměrně chybí — cena, kterou nástroj nemůže ověřit živě, je fakt, který nesmí tvrdit — a vendoři, které nikdo neověřil, chybí místo toho, aby se hádali. credential_env pojmenovává proměnnou prostředí; hlásí se jen její přítomnost, žádná cesta kódu hodnotu nečte a schéma katalogu nemá pole, kde by se tajemství mohlo skrýt (test tuto vlastnost dokazuje).
3. Dvě schopnosti, každý povrch. models.list (katalog, zúžitelný, s vlastní diagnostikou katalogu — duplicitní aliasy, nedeklarovaní vendoři) a models.route (který model vybere uvedená potřeba). Každá s jednou deklarací capability!, takže CLI (majordomus models ...), /api/v1/models*, OpenAPI, nástroje MCP a stránka Models v Cockpitu jsou projekce, které se nemohou rozejít, a žádný konzument nedrží vlastní název modelu.
4. Směrování je čistá funkce s připojenými důvody. Vstup: požadovaná slova schopností, minimální kontext, dodavatel, jen lokální, nebo přímo pojmenovaný model (přesto kontrolovaný proti požadavkům). Výstup: vybraný model a proč, zbytek vyhovujících jako záložní řetěz a každý vyloučený model s první kontrolou, kterou nesplnil. Žádný stav, žádné odhady zdraví, žádný neprůhledný dispečer: stejná otázka dostane stejnou odpověď a „proč to vybralo X / vyloučilo Z“ je v samotné odpovědi.
5. Žádná živá vrstva, záměrně. Nic nevolá dodavatele, nevypisuje modely přes API ani nezkoumá zdraví. Kde se jednou bude chtít živý fakt, platí precedens ADR 0032 (vnější vrstva zapisuje; crate čte soubory) nebo nové ADR výslovně přehodnotí postoj k závislostem. Zaznamenávání, který model skutečně provedl práci relace, patří adaptérům capture/lifecycle (jejich schéma už pole deklaruje) — práce na hooku poskytovatele, zde jmenovaná jako navazující krok, ne propašovaná do tohoto crate.

Zamítnuté alternativy

• Živý registr poskytovatelů a modelů se stavem zdraví a využitím. Dvojnásob zakázáno: crate nemá HTTP klienta a nesmí ho kvůli tomu získat (ADR 0032) a odpověď o zdraví vypočtená ze sond, které tento nástroj nemůže provést, by byla vymyšlená. Pravdivé tu může být deklarované data a přítomnost přihlašovacího údaje; co pravdivé být nemůže, je označeno jako nepřítomné, nikoli vymyšleno.
• Znovupoužití slova „provider“. ADR 0032 ho výslovně odmítá; druhý registr pod stejným podstatným jménem jako share/providers.yaml je právě ta nejednoznačnost, před kterou varovalo.
• Politika směrování jako roztroušená logika v místech volání. Vadou je tvar if/else na volajícího; opravou je čistá funkce nad deklarovanými daty, promítnutá jako schopnost.
• Katalog pro každý repozitář pod .ai/. Fakta o modelech jsou fakta o světě, do kterého se distribuce dodává, ne o jednom repozitáři; adresář share je místem, kde takové deklarace žijí (providers.yaml, distribution.yaml). Repozitář, který potřebuje vlastní doplňky, je pozdější výslovné rozšíření rozlišování share, ne druhý formát souboru teď.

Důsledky

• Přidání modelu nebo dodavatele je úprava share/models.yaml; následují všechny povrchy a diagnostika models.list zachytí duplicitní alias nebo nedeklarovaného dodavatele při prvním čtení. Nic jiného se neupravuje — vlastnost nulové registrace na spotřebitele, kterou testy drží pro mesh, platí zde stejným mechanismem (jedna deklarace, jedno sestavení registru, odvozené projekce).
• Katalog může zastarat, a poctivě: položky nesou datum svého původu v hlavičce souboru, zastaralost je vidět tam, kde ji lze posoudit, a neexistuje auto-refresh, který by tiše přepisoval fakta.
• Výměna schopností meshe může později nést sanitizované povědomí o schopnostech modelů (uzel inzerující inference reasoning nebo local) čtením téhož katalogu — jedna pravda o tom, co uzly flotily umějí, bez přihlašovacích údajů kdekoli poblíž.