Skip to content

README.md

Latest commit

 

History

History
260 lines (178 loc) · 19.2 KB

README.md

File metadata and controls

260 lines (178 loc) · 19.2 KB
Raw

🌐 English · All languages

A real render: system prompt + tool docs packed into one dense 1568×728 page

🖼️ OmniGlyph — Kontext ako obrázok

Znížte svoj účet za Claude o 59 – 70 % tak, že objemný kontext vykreslíte ako husté PNG stránky — ten istý obsah, za zlomok tokenov.

Modely účtujú text po tokenoch, ale obrázok účtujú podľa jeho rozmerov — nie podľa toho, koľko textu je vnútri.


59–70% Bill Cut 10x Fewer Tokens 100% Read Accuracy Zero Confabulations

CI npm version License: MIT Node ≥18

Súčasť rodiny OmniRoute · 🌐 Všetky jazyky

📊 The numbers — measured, not estimated

metrika výsledok dôkaz
Zníženie účtu end-to-end 59 – 70 % produkčná stopa, 13 709 požiadaviek
Tokeny na konvertovaný blok 10× menej (28 080 znakov: 14 040 → 1 460 tokenov) billing sweep
Presnosť účtovacieho vzorca rezíduum nula naprieč 22 sondami count_tokens, 2 modely × 2 úrovne benchmarks/billing-sweep/results/
Presnosť presného čítania, produkčná konfigurácia 30/30 (100 %) na Claude Fable 5 density frontier
Tiché konfabulácie v ~300 sondách čítania 0 — každý neúspech sa zdrží ako ILEGIVEL benchmarks/density-frontier/results/

Skóre modelov (dokáže čítať husté rendery? n=30 na skupinu, deterministické hodnotenie):

model čítanie verdikt
Claude Fable 5 100 % presne ✅ produkčný cieľ
Claude Opus 4.8 77 – 87 % pri 4× veľkosti glyfov ⚠️ voliteľný bezpečný režim (úspory klesnú na ~2×)
GPT-5.5 0/60 — a nafukuje svoje odpovede ~40× pri snahe ❌ zablokované bránou, s dôkazom
Gemini 2.5-flash 0/26 — a namiesto zdržania sa konfabuluje ❌ zablokované (čiastočný test, obmedzené kvótou)

Výhoda je dnes špecifická pre Fable — ostatné vizuálne enkodéry zatiaľ nedokážu rozlíšiť husté glyfy. Benchmarkový harness otestuje akýkoľvek nový model jedným príkazom.

🤔 Prečo OmniGlyph?

Každá dlhotrvajúca agentská session ťahá na každej požiadavke tú istú mŕtvu váhu: systémový prompt, dokumentáciu nástrojov a starú históriu — preúčtovanú za token, každé kolo. OmniGlyph je lokálny proxy, ktorý tieto objemné časti prepíše na husté PNG stránky predtým, než opustia váš počítač:

  • Presná účtovacia matematika, nie heuristiky — počíta reálny vzorec poskytovateľa pre tokeny obrázka (meraný na nulové rezíduum) a konvertuje iba vtedy, keď matematika vyhráva.
  • Fail-closed dizajn — modely, ktoré nedokážu čítať husté rendery, blokuje brána, s benchmarkovými dôkazmi. Žiadna tichá strata kvality.
  • Súkromné a lokálne-first — prepis sa deje na 127.0.0.1; nič navyše sa nikam neposiela.
  • Reprodukovateľné — každé číslo vyššie má dôkaz v benchmarks/*/results/, opätovne spustiteľný jedným príkazom.

⚡ Rýchly štart

npx omniglyph                                     # proxy na 127.0.0.1:47821
ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude  # nasmerujte naň Claude Code

Quickstart: start the proxy, check the dashboard, point Claude Code at it

Funguje oboma spôsobmi:

  • API kľúč (platba za token): váš účet klesne o 59 – 70 % end-to-end.
  • Predplatiteľská session: neplatíte menej, ale limity používania sa počítajú v tokenoch — takže vaše limity sa natiahnu ~2 – 3×.

Dashboard na http://127.0.0.1:47821/: ušetrené tokeny, každá konverzia text→obrázok vedľa seba, vypínač, živé čipy modelov. Odpovede prúdia normálne — komprimuje sa iba požiadavka, nikdy výstup modelu.

🔌 Použitie s klientmi Claude

Start the proxy in one terminal, then point the client at it.

Claude Code CLI (macOS/Linux):

npx omniglyph
ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude

Claude Code CLI (Windows PowerShell):

npx omniglyph
$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:47821"
claude

Claude Desktop uses the same ANTHROPIC_BASE_URL environment variable for its bundled Claude Code runtime — start omniglyph first, then launch Claude Desktop from an environment where ANTHROPIC_BASE_URL is set to http://127.0.0.1:47821.

🖥️ Dashboard

Kompletný lokálny dashboard sa dodáva priamo v balíku — offline, jeden súbor, žiadne externé požiadavky. Šesť stránok, aktualizovaných naživo cez SSE, ako plynú požiadavky:

Overview: KPI karty typu mission-control, sparkline úspor a živý feed udalostí

  • Overview — mission control: úspora %, ušetrené $, latencia p95, zásahy do cache, chyby, živý feed.
  • Live Flow — pipeline ako uzlový graf: client → gate → renderer / passthrough → API, s časticou pre každú skutočnú požiadavku.
  • Telemetry — odometer tokenov/$ a živá časová os požiadaviek; kliknutím na ktorúkoľvek požiadavku uvidíte presne, ktoré časti sa stali obrázkami, a prečítate si zdrojový text za každou stránkou.
  • Benchmarks — dôkazy z harnessu vykreslené z benchmarks/*/results/, jeden riadok na experiment model·konfigurácia, a spustenie benchmarkov priamo z UI: $0 dry-runy streamujú svoj výstup naživo; živé behy ostávajú zamknuté za vaším API kľúčom a výslovným potvrdením nákladov.
  • Sessions / History — top session podľa ušetrených tokenov a každá udalosť na disku.
Live Flow Benchmarks
Pipeline požiadaviek ako živý uzlový graf Dôkazy z benchmarkov a dry-runy priamo v UI

Telemetry: odometer a živá časová os požiadaviek

⚙️ Ako to funguje

objemný blok požiadavky ──► brána ziskovosti ──► reflow + render (1-bitová 5×8 atlasová mriežka)
                       (presná účtovacia matematika)     ──► 1568×728 PNG stránky ──► spätné zošitie, priateľské k cache
  • Účtovanie sa počíta presne, pred konverziou: Anthropic účtuje ⌈w/28⌉ × ⌈h/28⌉ + 4 tokenov na obrázok (28 px záplaty — merané na nulové rezíduum). Celá stránka nesie 28 080 znakov za 1 460 tokenov ≈ 19 znakov/token, oproti ~2 znakom/token pri hustom texte. Brána konvertuje iba vtedy, keď matematika vyhráva.
  • Čo sa konvertuje: statický systémový prompt + dokumentácia nástrojov, stará zbalená história, veľké výstupy nástrojov.
  • Čo sa nikdy nekonvertuje: vaše správy, nedávne kolá, výstup modelu, riedka próza, hodnoty na úrovni bajtov (hashe/ID cestujú popri texte), a akýkoľvek model, ktorý neprešiel benchmarkom čítania.

📚 Použitie ako knižnica (bez proxy)

Všetko, čo proxy robí pri každej požiadavke, je zároveň zdokumentované, importovateľné API:

import { renderTextToImages, transformAnthropicMessages } from "omniglyph";

// Vykreslite ľubovoľný text do hustých 1-bitových PNG stránok
const { pages } = await renderTextToImages(bigToolOutput, { reflow: true });
// pages[i].png: Uint8Array · pages[i].width × pages[i].height

// Alebo si sami spustite celú transformáciu požiadavky — brána, presná účtovacia matematika a všetko
const { body, applied, reason } = await transformAnthropicMessages({
  body: requestBytes,           // surové telo JSON /v1/messages
  model: "claude-fable-5",
});

options.keepSharp(block) pripne bloky ako text; options.emitRecoverable vráti originály obrázkových blokov. Presná účtovacia matematika sa dodáva aj v koreni balíka (anthropicImageTokens, resolveAnthropicVisionTier, openAIVisionTokens) — presne to používa OmniRoute. Čistý JS runtime (Node aj edge/Workers). Celé rozhranie: src/core/index.ts.

📤 Offline export — bez proxy, bez Claude Code

Nepoužívate Claude Code? Vykreslite kontext do PNG stránok lokálne a vložte ich do Cursor, ChatGPT alebo akéhokoľvek chatu, ktorý prijíma nahrávanie obrázkov. Bez proxy, bez API kľúča, bez zapojeného účtu:

npx omniglyph export --include "*.ts" src/   # render a folder to image pages
cat big.log | npx omniglyph export --stdin   # …or pipe any text through

Dostanete jeden priečinok so všetkým, čo stačí pustiť do chatu:

OmniGlyph-export-<hash>/
  page-001.png …   the rendered image pages — attach these
  factsheet.txt    verbatim precision tokens (paths, SHAs, ids, numbers)
  prompt.txt       a paste-ready instruction that points the model at the pages
  manifest.json    metadata + the text-vs-image token report (% saved)

--git vykreslí váš necommitnutý diff, --diff <ref> rozsah commitov, --open zobrazí priečinok (macOS). Všetko beží u vás na počítači — exportná cesta nikdy nespustí proxy a nikdy nezavolá model. Spustite omniglyph export --help pre všetky prepínače.

🧭 The honest part

  • Je to stratové. Presné čítanie na úrovni bajtov z obrázkov je zo svojej podstaty nespoľahlivé. Nasadené zmierňovania: presné identifikátory cestujú ako text vedľa obrázka a meraná produkčná konfigurácia priniesla nulové tiché konfabulácie — neúspešné čítania sa zdržia.
  • Dnes je schválený iba Fable 5, s dôkazmi. GPT-5.5 a Gemini 2.5-flash merateľne nedokážu čítať husté rendery; Opus 4.8 potrebuje 4× väčšie glyfy. Brána toto vynucuje.
  • Našli a vyhli sme sa účtovacej pasci: vysokorozlišovacia úroveň obrázka účtuje 3,3× viac za stránku, ale vizuálny enkodér nedostáva navyše rozlíšenie — väčšie stránky sa čítajú horšie. Merané, zdokumentované v docs/benchmarks/BENCHMARKS.md, nenasadené.
  • Ceny sa menia; trvalá metrika je zníženie tokenov, ktoré proxy loguje na požiadavku oproti bezplatnému kontrafaktuálu count_tokens.

🧠 FAQ

Zapol som to uprostred sedenia a spotreba vystrelila — prečo? Sedenie bežiace bez OmniGlyph má celý prefix uložený u Anthropic v cache ako text za čítaciu sadzbu 0,1×; prvá požiadavka s obrázkami by to všetko znovu zaplatila ako nový zápis do cache za 1,25× v jedinom prompte. Proxy pred tým chráni: sedenie, ktoré nikdy nepreviedlo na obrázky, započíta tento jednorazový náklad do break-even brány a na obrázky prepne, len ak sa to stále oplatí — inak sedenie ostáva textom a úspory začínajú ďalším novým sedením.

Je tých 59 – 70 % end-to-end, alebo len na požiadavkách, ktorých sa to dotklo? End-to-end — celý účet. Väčšina kompresných nástrojov vykazuje úspory iba na časti, ktorej sa dotkli, čo číslo skresľuje v ich prospech. Náš menovateľ je každá požiadavka: tie malé, ktoré brána správne nechala nedotknuté, všetky zápisy a čítania z cache a všetky výstupné tokeny (ktoré proxy nikdy nekomprimuje). Číslo počítané iba z komprimovanej časti vychádza vyššie a uvádza sa samostatne, nikdy ako hlavné číslo.

Ako sa meria úspora? Obe strany tej istej požiadavky, v tom istom okamihu. Pri každom POST na /v1/messages proxy vypáli bezplatnú sondu count_tokens na pôvodné nekomprimované telo (kontrafaktuál) paralelne so skutočným presmerovaním a načíta zo skutočnej odpovede blok použitia, ktorý účtoval poskytovateľ — oboje pristane v tom istom riadku udalosti. Cenotvorba cache sa uplatňuje identicky na oboch stranách, takže zľava za cache sa vyruší a nedá sa dvojito započítať ako „úspora“. Vzorec je v src/core/baseline.ts; odvoďte si ho znova z vlastného logu udalostí.

Prečo by mal byť neúspech konfabuláciou namiesto chyby čítania? Pretože vizuálny modul modelu nie je OCR: stránka sa zmení na embeddingy záplat, nikdy na diskrétne znaky, takže neexistuje miera istoty na úrovni glyfu, na ktorej by mohlo čítanie nahlas zlyhať — keď pixely nedostatočne určujú glyf, jazykový prior doplní medzeru niečím pravdepodobným. Presne kvôli tomuto mechanizmu je OmniGlyph v tomto ohľade fail-closed: hodnoty na úrovni bajtov vždy cestujú ako text vedľa obrázka, modely, ktoré čítajú nesprávne, blokuje brána, a meraná produkčná konfigurácia priniesla nulové tiché konfabulácie v ~300 sondách čítania — neúspešné čítania sa zdržia.

Čo s prácou na úrovni bajtov (hashe, ID, tajomstvá)? Nedávne kolá a presné identifikátory ostávajú textom podľa dizajnu. Pre záťaže, ktoré sú celé na úrovni bajtov, ich smerujte na model mimo zoznamu povolených (napr. subagenta na inom modeli Claude) — čokoľvek mimo zoznamu povolených prechádza bajtovo identické, nedotknuté.

Nevyriešil DeepSeek-OCR už otázku, či to funguje? Dokázal, že kanál funguje — s párom enkodér/dekodér natrénovaným presne na túto úlohu. Skepticizmus pochádza z obdobia, keď žiadny bežný produkčný model nevedel čítať husté rendery; to sa zmenilo a skóre modelov vyššie presne ukazuje, kto ich dnes dokáže čítať, s dôkazmi. Benchmarkový harness otestuje akýkoľvek nový model jedným príkazom — brána sa riadi dátami, nie hype.

Dá sa to použiť bez Claude Code — Cursor, ChatGPT, obyčajná pipe? Áno, dvoma spôsobmi. Ako proxy funguje s akýmkoľvek klientom, ktorý vám umožní nastaviť základnú URL API (ANTHROPIC_BASE_URL alebo základnú URL OpenAI) — Claude Code, vaše vlastné skripty, čokoľvek cez HTTP. A pre nástroje, ktoré nedokážu použiť proxy, Offline export vyššie vykreslí kontext do PNG stránok, ktoré vložíte ručne — omniglyph export --stdin dokonca číta priamo z Unix pipe.

Ako vlastne premení text na obrázok? Text preformátuje (reflow) a vykreslí ho 1-bitovým 5×8 pixelovým atlasom glyfov na husté 1568×728 PNG stránky — jeden bit na pixel, bez anti-aliasingu, takže model účtuje stránku podľa jej rozmerov, nie podľa toho, koľko znakov je vnútri. Ako to funguje vyššie obsahuje pipeline; dokument benchmarkov obsahuje geometriu a to, prečo hustejšie nie je vždy lacnejšie.

🔬 Zreprodukujte každé číslo

pnpm install && pnpm test                                     # celá sada
node benchmarks/billing-sweep/run.mjs --dry-run               # predikcie účtovania, $0
pnpm exec tsx benchmarks/density-frontier/run.ts --dry-run    # tabuľka nákladov, $0
# s kľúčmi: ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY (alebo --via-cli pre predplatiteľskú session Claude Code)

The two benchmark harnesses running in dry-run mode

Kompletná metodika a všetky tabuľky výsledkov: docs/benchmarks/BENCHMARKS.md. Surové dôkazy po jednotlivých odpovediach: benchmarks/*/results/*.jsonl.

🚀 Rodina OmniRoute

OmniGlyph sa tiež dodáva ako natívny kompresný engine vnútri OmniRoute — bezplatnej AI brány. Tam beží ako engine omniglyph (samostatný single mode alebo vrstvený s ostatnými enginmi), s fail-closed bránami a účtovaním tokenov s ohľadom na obrázky.

🛠️ Technologický stack

vrstva technológia
Jazyk TypeScript (strict), ESM
Runtime Node ≥18 · Cloudflare Workers (wrangler.toml)
Renderovanie vlastná 1-bitová atlasová mriežka glyfov (odvodená zo Spleen/Unifont, licencie v assets/) → PNG
Testy Vitest — TDD, plus stráže integrity dokumentácie a rebrandingu
Benchmarky harnessy v benchmarks/ (billing-sweep, density-frontier) s JSONL dôkazmi

Štruktúra projektu

cesta čo
src/ proxy: transformačný pipeline, presné účtovanie na poskytovateľa, renderer, hosty (Node + Cloudflare Workers)
benchmarks/ harnessy, ktoré vyprodukovali každé číslo vyššie — opätovne spustiteľné
docs/ BENCHMARKS · ARCHITECTURE · ROADMAP

📧 Podpora a komunita

🙏 Poďakovania

OmniGlyph stojí na pleciach jedného projektu obzvlášť — táto sekcia je naše trvalé poďakovanie.

Projekt Ako ovplyvnil OmniGlyph
pxpipe · teamchong Objav, na ktorom je postavený celý tento projekt. pxpipe s dôkazmi preukázal, že vizuálny kanál produkčného LLM dokáže niesť hustý textový kontext za zlomok nákladov na tokeny — a že o konverzii sa musí rozhodovať pri každej požiadavke presnou účtovacou matematikou, nikdy podľa pocitu. Husté 1-bitové vykresľovanie, brána ziskovosti, kontrafaktuál count_tokens, fail-closed zoznam povolených modelov a kultúra dokumentácie „najprv zmerať, potom tvrdiť“ — to všetko tam vzniklo ako prvé. OmniGlyph priamo vychádza z tohto kódu (MIT — pôvodný riadok copyrightu ostáva v našej LICENSE).
Spleen · Frederic Cambus Rodina bitmapových fontov 5×8, z ktorej vychádza náš hustý 1-bitový atlas glyfov (licencia v assets/).
GNU Unifont · Unifoundry Pokrytie glyfov nad rámec rozsahu Spleen v tom istom atlase (licencia v assets/).

Ak vám OmniGlyph príde užitočný, dajte hviezdičku aj pôvodnému projektu — objav bol ich. 🙏

📄 Licencia

MIT — pozri LICENSE.