Skip to content

README.md

Latest commit

 

History

History
260 lines (178 loc) · 18.4 KB

README.md

File metadata and controls

260 lines (178 loc) · 18.4 KB
Raw

🌐 English · All languages

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

🖼️ OmniGlyph — Kontekst som bilde

Kutt Claude-regningen din med 59–70 % ved å rendre tung kontekst som tette PNG-sider — samme innhold, i en brøkdel av tokenene.

Modeller fakturerer tekst per token, men fakturerer et bilde etter dimensjonene — ikke etter hvor mye tekst som er i det.


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

CI npm version License: MIT Node ≥18

Del av OmniRoute-familien · 🌐 Alle språk

📊 The numbers — measured, not estimated

mål resultat kvittering
Reduksjon i totalregning, ende til ende 59–70 % produksjonsspor, 13 709 forespørsler
Tokens per konvertert blokk 10× færre (28 080 tegn: 14 040 → 1 460 tokens) billing sweep
Nøyaktighet i faktureringsformelen null avvik på tvers av 22 count_tokens-prober, 2 modeller × 2 nivåer benchmarks/billing-sweep/results/
Eksakt lesenøyaktighet, produksjonskonfigurasjon 30/30 (100 %) på Claude Fable 5 density frontier
Stille konfabulasjoner i ~300 leseprober 0 — hver bom avstår som ILEGIVEL benchmarks/density-frontier/results/

Modell-scorekort (kan den lese tette renderinger? n=30 per arm, deterministisk scoring):

modell lesing dom
Claude Fable 5 100 % eksakt ✅ produksjonsmål
Claude Opus 4.8 77–87 % ved 4× glyffstørrelse ⚠️ opt-in sikker modus (besparelser faller til ~2×)
GPT-5.5 0/60 — og blåser opp svarene sine ~40× i forsøket ❌ blokkert av porten, med bevis
Gemini 2.5-flash 0/26 — og konfabulerer i stedet for å avstå ❌ blokkert (delvis test, kvotebegrenset)

Fordelen er Fable-spesifikk i dag — andre synsmodeller klarer ennå ikke å tolke tette glyffer. Benchmark-riggen tester enhver ny modell på nytt med én kommando.

🤔 Hvorfor OmniGlyph?

Hver langkjørende agent-økt drar med seg den samme dødvekten i hver eneste forespørsel: systemprompten, verktøydokumentasjonen og gammel historikk — fakturert på nytt per token, hver runde. OmniGlyph er en lokal proxy som skriver om disse tunge delene til tette PNG-sider før de forlater maskinen din:

  • Eksakt faktureringsmatematikk, ikke heuristikk — den beregner leverandørens faktiske bildetoken-formel (målt til null avvik) og konverterer kun når matematikken lønner seg.
  • Fail-closed by design — modeller som ikke klarer å lese tette renderinger blokkeres av en port, med benchmark-kvitteringer. Ingen stille kvalitetstap.
  • Privat og lokal-først — omskrivingen skjer på 127.0.0.1; ingenting ekstra sendes noe sted.
  • Reproduserbart — hvert tall over har en kvittering i benchmarks/*/results/, som kan kjøres på nytt med én kommando.

⚡ Hurtigstart

npx omniglyph                                     # proxy på 127.0.0.1:47821
ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude  # pek Claude Code mot den

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

Fungerer begge veier:

  • API-nøkkel (betal per token): regningen din faller 59–70 % ende til ende.
  • Abonnementsøkt: du betaler ikke mindre, men bruksgrensene telles i tokens — så grensene dine strekker seg ~2–3×.

Dashboard på http://127.0.0.1:47821/: tokens spart, hver tekst→bilde-konvertering side om side, kill switch, live modell-chips. Svar strømmer normalt — kun forespørselen komprimeres, aldri modellens utdata.

🔌 Bruk med Claude-klienter

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.

🖥️ Dashboardet

Et fullstendig lokalt dashboard følger med i pakken — offline, én fil, ingen eksterne forespørsler. Seks sider, oppdatert live over SSE mens forespørsler strømmer gjennom:

Overview: KPI-kort for mission control, sparklinje for besparelser og live event-feed

  • Overview — mission control: besparelse i %, spart $, latency p95, cache-treffer, feil, live feed.
  • Live Flow — pipelinen som en nodegraf: client → gate → renderer / passthrough → API, med en partikkel per reell forespørsel.
  • Telemetry — et token/$-odometer og en live forespørselstidslinje; klikk på en hvilken som helst forespørsel for å se nøyaktig hvilke deler som ble til bilder, og les kildeteksten bak hver side.
  • Benchmarks — kvitteringene fra rammeverket, rendret fra benchmarks/*/results/, én rad per modell·konfig-eksperiment, og kjør benchmarks fra UI-en: $0-dry-runs strømmer utdataene sine live; live-kjøringer forblir sperret bak API-nøkkelen din pluss en eksplisitt kostnadsbekreftelse.
  • Sessions / History — øktene som har spart flest tokens, og hver eneste hendelse på disk.
Live Flow Benchmarks
Forespørselspipelinen som en live nodegraf Benchmark-kvitteringer og dry-runs i UI-en

Telemetry: odometer og live forespørselstidslinje

⚙️ Slik fungerer det

tung forespørselsblokk ──► lønnsomhetsport ──► omflyt + rendring (1-bit 5×8-atlas)
                       (eksakt faktureringsmatematikk)     ──► 1568×728 PNG-sider ──► spleis tilbake, cache-vennlig
  • Fakturering beregnes eksakt, før konvertering: Anthropic fakturerer ⌈w/28⌉ × ⌈h/28⌉ + 4 tokens per bilde (28 px-patcher — målt til null avvik). En full side bærer 28 080 tegn for 1 460 tokens ≈ 19 tegn/token, mot ~2 tegn/token for tett tekst. Porten konverterer kun når matematikken lønner seg.
  • Hva som konverteres: den statiske systempromten + verktøydokumentasjon, gammel sammenslått historikk, store verktøyresultater.
  • Hva som aldri konverteres: dine meldinger, nylige runder, modellens utdata, spredt prosa, byte-eksakte verdier (hasher/ID-er blir med som tekst), og enhver modell som mislyktes i lesebenchmarken.

📚 Biblioteksbruk (uten proxy)

Alt proxyen gjør per forespørsel finnes også som et dokumentert, importerbart API:

import { renderTextToImages, transformAnthropicMessages } from "omniglyph";

// Rendre en vilkårlig tekst til tette 1-bit PNG-sider
const { pages } = await renderTextToImages(bigToolOutput, { reflow: true });
// pages[i].png: Uint8Array · pages[i].width × pages[i].height

// Eller kjør hele forespørselstransformasjonen selv — port, faktureringsmatematikk og alt
const { body, applied, reason } = await transformAnthropicMessages({
  body: requestBytes,           // den rå /v1/messages JSON-kroppen
  model: "claude-fable-5",
});

options.keepSharp(block) fastholder blokker som tekst; options.emitRecoverable returnerer originalene til de bilderenderte blokkene. Den eksakte faktureringsmatematikken leveres også ved pakkeroten (anthropicImageTokens, resolveAnthropicVisionTier, openAIVisionTokens) — det er dette OmniRoute bruker. Ren JS-kjøretid (Node og edge/Workers). Fullt overflateomfang: src/core/index.ts.

📤 Offline eksport — ingen proxy, ingen Claude Code

Ikke på Claude Code? Rendre konteksten til PNG-sider lokalt og lim dem inn i Cursor, ChatGPT eller en hvilken som helst chat som godtar bildeopplastinger. Ingen proxy, ingen API-nøkkel, ingen konto satt opp:

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

Du får én mappe med alt du trenger for å legge det rett inn i chatten:

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 rendrer din ikke-committede diff, --diff <ref> et commit-område, --open viser mappen (macOS). Alt kjører på maskinen din — eksportstien starter aldri proxyen og kaller aldri en modell. Kjør omniglyph export --help for alle flagg.

🧭 The honest part

  • Det er tapsbringende (lossy). Byte-eksakt gjenkalling fra bilder er iboende upålitelig. Iverksatte tiltak: eksakte identifikatorer reiser som tekst ved siden av bildet, og den målte produksjonskonfigurasjonen ga null stille konfabulasjoner — mislykkede lesninger avstår.
  • Kun Fable 5 er godkjent i dag, med kvitteringer. GPT-5.5 og Gemini 2.5-flash kan målbart ikke lese tette renderinger; Opus 4.8 trenger 4× større glyffer. Porten håndhever dette.
  • Vi fant og unngikk en faktureringsfelle: det høyoppløste bildenivået fakturerer 3,3× mer per side, men synsmodellen mottar ikke den ekstra oppløsningen — større sider leser dårligere. Målt, dokumentert i docs/benchmarks/BENCHMARKS.md, ikke aktivert.
  • Priser endrer seg; det varige målet er tokenkuttet, som proxyen logger per forespørsel mot en gratis count_tokens-motfaktisk verdi.

🧠 FAQ

Jeg slo det på midt i en økt og forbruket skjøt i været — hvorfor? En økt som kjørte uten OmniGlyph har hele prefikset sitt cachet hos Anthropic som tekst til 0,1× lesetakst; den første forespørselen med bilder ville betalt alt dette på nytt som en fersk cache-skriving til 1,25× i én enkelt prompt. Proxyen beskytter mot dette: en økt den aldri har gjort om til bilder får denne engangskostnaden regnet inn i break-even-porten og bytter til bilder bare hvis det fortsatt lønner seg — ellers forblir økten tekst, og besparelsen begynner med din neste nye økt.

Er 59–70 % ende-til-ende, eller bare på forespørslene den rørte ved? Ende til ende — hele regningen. De fleste komprimeringsverktøy rapporterer besparelser bare på biten de rørte ved, noe som smigrer tallet. Vår nevner er hver eneste forespørsel: de små som porten med rette lot være urørt, alle cache-skrivinger og -lesinger, og alle utdata-tokens (som proxyen aldri komprimerer). Tallet for kun-komprimert er høyere og oppgis separat, aldri som hovedtallet.

Hvordan måles besparelsen? Begge sider av samme forespørsel, på samme tidspunkt. For hver /v1/messages-POST avfyrer proxyen en gratis count_tokens-probe på den opprinnelige, ukomprimerte kroppen (det kontrafaktiske) parallelt med den faktiske videresendingen, og leser leverandørens faktisk fakturerte bruksblokk fra svaret — begge havner i samme hendelsesrad. Cache-prising anvendes identisk på begge sider, slik at cache-rabatten går ut med seg selv og ikke kan dobbelttelles som "besparelse". Formelen ligger i src/core/baseline.ts; utled den selv fra din egen hendelseslogg.

Hvorfor skulle en feillesing være en konfabulasjon i stedet for en lesefeil? Fordi modellsyn ikke er OCR: siden blir til patch-embeddinger, aldri diskrete tegn, så det finnes ingen glyff-for-glyff-sikkerhet å feile høylytt på — når piksler underbestemmer en glyff, fyller språkmodellens prior gapet med noe plausibelt. Denne mekanismen er nøyaktig hvorfor OmniGlyph er fail-closed om det: byte-eksakte verdier reiser alltid som tekst ved siden av bildet, modeller som mistolker blokkeres av porten, og den målte produksjonskonfigurasjonen ga null stille konfabulasjoner i ~300 leseprober — mislykkede lesninger avstår.

Hva med byte-eksakt arbeid (hasher, ID-er, hemmeligheter)? Nylige runder og eksakte identifikatorer forblir tekst by design. For arbeidsmengder som er utelukkende byte-eksakte, rut dem til en modell utenfor tillatelseslisten (f.eks. en underagent på en annen Claude-modell) — alt utenfor tillatelseslisten passerer byte-identisk gjennom, urørt.

Avgjorde ikke DeepSeek-OCR om dette fungerer? Det beviste at kanalen fungerer — med et enkoder/dekoder-par trent for oppgaven. Skepsisen stammer fra en tid da ingen ferdig produksjonsmodell kunne lese tette renderinger; det har endret seg, og modell-scorekortet over viser nøyaktig hvem som leser dem i dag, med kvitteringer. Benchmark-riggen tester enhver ny modell på nytt med én kommando — porten følger dataene, ikke hypen.

Kan jeg bruke det uten Claude Code — Cursor, ChatGPT, en enkel pipe? Ja, på to måter. Som en proxy fungerer det med enhver klient som lar deg sette API-base-URL-en (ANTHROPIC_BASE_URL, eller OpenAI-base-URL-en) — Claude Code, dine egne skript, hva som helst over HTTP. Og for verktøy som ikke kan bruke proxy, rendrer Offline eksport over konteksten til PNG-sider som du limer inn for hånd — omniglyph export --stdin leser til og med rett fra en Unix-pipe.

Hvordan gjør det egentlig tekst om til et bilde? Det flyter om teksten og maler den med et 1-bit 5×8-piksel glyffatlas på tette 1568×728 PNG-sider — én bit per piksel, ingen anti-aliasing, slik at modellen fakturerer siden etter dimensjonene, ikke etter hvor mange tegn som er inni. Slik fungerer det over har pipelinen; benchmark-dokumentet har geometrien og hvorfor tettere ikke alltid er billigere.

🔬 Reproduser hvert tall

pnpm install && pnpm test                                     # full suite
node benchmarks/billing-sweep/run.mjs --dry-run               # billing predictions, $0
pnpm exec tsx benchmarks/density-frontier/run.ts --dry-run    # cost table, $0
# med nøkler: ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY (eller --via-cli for et Claude Code-abonnement)

The two benchmark harnesses running in dry-run mode

Full metodikk og hver resultattabell: docs/benchmarks/BENCHMARKS.md. Rå per-svar-kvitteringer: benchmarks/*/results/*.jsonl.

🚀 OmniRoute-familien

OmniGlyph leveres også som en innebygd komprimeringsmotor inni OmniRoute — den gratis AI-gatewayen. Der kjører den som omniglyph-motoren (frittstående enkeltmodus eller stablet med de andre motorene), med fail-closed-porter og bildebevisst tokenregnskap.

🛠️ Teknologistabel

lag teknologi
Språk TypeScript (strict), ESM
Kjøretid Node ≥18 · Cloudflare Workers (wrangler.toml)
Rendring eget 1-bit glyffatlas (Spleen/Unifont-avledet, lisenser i assets/) → PNG
Tester Vitest — TDD, pluss dokumentasjonsintegritet og rebrand-vakter
Benchmarks benchmarks/-rigger (billing-sweep, density-frontier) med JSONL-kvitteringer

Prosjektstruktur

sti hva
src/ proxyen: transformasjonspipeline, eksakt fakturering per leverandør, renderer, verter (Node + Cloudflare Workers)
benchmarks/ riggene som produserte hvert tall over — kan kjøres på nytt
docs/ BENCHMARKS · ARCHITECTURE · ROADMAP

📧 Støtte og fellesskap

🙏 Anerkjennelser

OmniGlyph står på skuldrene til ett prosjekt spesielt — denne seksjonen er vår permanente takk.

Prosjekt Hvordan det formet OmniGlyph
pxpipe · teamchong Oppdagelsen hele dette prosjektet er bygget på. pxpipe beviste, med kvitteringer, at en produksjons-LLMs synskanal kan bære tett tekstuell kontekst til en brøkdel av tokenkostnaden — og at konverteringen må avgjøres per forespørsel av eksakt faktureringsmatematikk, aldri av magefølelse. Den tette 1-bit-renderingen, lønnsomhetsporten, count_tokens-motfaktiske verdien, den fail-closed modell-tillatelseslisten og "mål før du påstår"-dokumentasjonskulturen ble alle pionert der. OmniGlyph nedstammer direkte fra den kodebasen (MIT — den originale opphavsrettslinjen forblir i vår LICENSE).
Spleen · Frederic Cambus 5×8-bitmapfontfamilien vårt tette 1-bit-glyffatlas er avledet fra (lisens i assets/).
GNU Unifont · Unifoundry Dekning for glyffene utenfor Spleens rekkevidde i det samme atlaset (lisens i assets/).

Hvis du finner OmniGlyph nyttig, gi også opphavsprosjektet en stjerne — oppdagelsen var deres. 🙏

📄 Lisens

MIT — se LICENSE.