\n\n# doppler-gpu\n\n[](https://github.com/clocksmith/doppler/actions/workflows/check-green.yml)\n[](https://www.npmjs.com/package/doppler-gpu)\n[](https://github.com/clocksmith/doppler/blob/main/LICENSE)\n\nDoppler is a model compiler, release foundry, and WebGPU runtime for JavaScript.\nForge turns supported model sources into signed immutable Capsules with\nModelIR-derived, qualified TargetPlans. Runtime verifies, selects, binds, and\nexecutes the declared JavaScript/WGSL program. Browser and Node paths are\nqualified separately; Bun remains experimental.\n\n## Mission, goal, and value\n\nMake useful AI capabilities installable, inspectable, and maintainable as\napplication dependencies. Success means an independent application voluntarily\nretains Doppler for a measured improvement and ships a second revision with less\nrelease effort. Free adoption counts; benchmarks alone do not prove it.\n\nApplications control trust and updates. This checkout introduces the breaking\n[Capsule naming migration](docs/capsule-naming-migration.md); former Pack APIs\nand schemas are not accepted. Capsule v2 and v3 are supported;\n[Capsule v3](docs/capsule-identity-migration.md) separates executable identity from\nrelease events. Doe, Poolday, and Reploid are optional, not prerequisites.\n\nBuild local generation, embeddings, or reranking, or contribute improvements to\nsource interpretation, kernels, loading, and release reliability. See the\n[goals](docs/goals.md) and [contribution guide](docs/contributing.md).\n\n## How to use Doppler\n\nRun the CLI without installing a global package:\n\n```bash\nnpx doppler-gpu \"Summarize WebGPU in one sentence\"\nnpx doppler-gpu --model qwen3-0.8b --prompt \"Write a haiku about GPUs\"\nnpx doppler-gpu --list-models\n```\n\nThe live browser demo is at [d4da.com/doppler](https://d4da.com/doppler).\nThe first documentation path is [getting started](https://github.com/clocksmith/doppler/blob/main/docs/getting-started.md),\nfollowed by the [Capsule Runtime API](https://github.com/clocksmith/doppler/blob/main/docs/api/root.md).\n\nFor the release-foundry path, the installed command is `doppler release`; from\nnpm use `npx --package doppler-gpu doppler release`. It consumes a pinned\n`production-release/v1` manifest and signed exact-device receipts, then emits an\n`eligible` or `blocked` decision and retained evidence. It never activates or\ndeploys the customer application. See the [release platform contract](docs/model-release-platform.md)\nand [CLI reference](docs/cli.md).\n\n### Capsule Runtime API\n\n```js\nimport { openCapsule } from 'doppler-gpu/host';\nimport { reviewedRelease } from './reviewed-release.js';\n\nconst session = await openCapsule(reviewedRelease.capsuleUrl, {\n trustedSigners: reviewedRelease.trustedSigners,\n acceptedTargetPlanDigests: reviewedRelease.acceptedTargetPlanDigests,\n});\ntry {\n const result = await session.rerank({\n application: reviewedRelease.application,\n query: 'Which API provides browser GPU compute?',\n documents: ['WebGPU exposes GPU compute.', 'WebSocket transports messages.'],\n options: {},\n });\n console.log(result, session.selectedTargetPlanDigest);\n} finally {\n await session.close();\n}\n```\n\n`reviewedRelease` is application-owned configuration, not metadata trusted merely\nbecause it was downloaded. It identifies a reranker Capsule, accepted plans, trusted\npublishers, and the application/workload/oracle contract. The host entry composes\nthe existing device, artifact-store, and program ports; trust and upgrades remain\nexplicit. See the [Electron integration](examples/electron-document-search/README.md)\nand [retained evaluation](docs/integration/reranker-evaluation.md).\n\nAdvanced applications can still inject every port through `doppler-gpu` or\n`doppler-gpu/runtime`. Both routes verify the same Capsule and initial execution\nidentity. The host facade does not add model operations or broaden qualification.\n\nDiscover repository commands with `npm run` or `npm pkg get scripts` (JSON).\nUse `doppler --help` for the installed CLI.\n\nThe former manifest-loading facade remains available only as an explicit\ncompatibility import:\n\n```js\nimport { dr } from 'doppler-gpu/compat';\n\nconst session = await dr.open('qwen3-0.8b');\nconst result = await session.generate('Describe WebGPU briefly');\nawait session.close();\n```\n\n### OpenAI-compatible server\n\n```bash\nnpx doppler-serve --model qwen3-0.8b --port 8080\n```\n\nThe server accepts requests at `http://localhost:8080/v1`. Registry IDs resolve\nto hosted RDRR artifacts from `clocksmith/rdrr` by default.\n\n### LoRA loading and training\n\n```bash\nnpx doppler-gpu lora --config ./workload.json --surface node\n```\n\nDoppler supports SafeTensors LoRA loading and hot swap at runtime. SFT/LoRA\ntraining is available through the experimental Node, Bun, and browser training\nsurface. Cataloged adapter identities and lifecycle states are listed in\n[`models/adapters/catalog.json`](models/adapters/catalog.json). See the\n[LoRA format](docs/lora-format.md), [training handbook](docs/training-handbook.md),\nand [Training API](docs/api/training.md).\n\n\n\n## Supported RDRR model types\n\nDoppler classifies artifacts by what they consume and produce. This is\nseparate from lineage (`family`), runtime implementation (`modelType`), and\nartifact-size tier.\n\n| Type | Input → output | Runtime-verified / cataloged | Representative lanes |\n| --- | --- | --- | --- |\n| Text generators | text → text | 13 / 17 | gemma-3-1b-it-q4k-ehf16-af32 gemma-3-270m-it-f16-af32 gemma-3-270m-it-q4k-ehf16-af32 +14 more |\n| Multimodal generators | audio + image + text → text | 3 / 3 | gemma-4-e2b-it-q4k-ehf16-af16-int4ple gemma-4-e2b-it-q4k-ehf16-af32 gemma-4-e2b-it-q4k-ehf16-af32-int4ple |\n| Diffusion language models | text → text | 0 / 1 | diffusiongemma-26b-a4b-it-q4k-ehf16-af16 |\n| Translation specialists | text → text | 2 / 2 | translategemma-4b-1b-enes-q4k-ehf16-af32 translategemma-4b-it-q4k-ehf16-af32 |\n| Language embedders | text → pooled-embedding | 2 / 2 | google-embeddinggemma-300m-q4k-ehf16-af32 qwen-3-embedding-0-6b-q4k-ehf16-af32 |\n| Rerankers | text-pair → relevance-score | 2 / 2 | qwen-3-reranker-0-6b-f16-af32 qwen-3-reranker-0-6b-q4k-ehf16-af32 |\n| Protein encoders | protein-sequence → pooled-embedding + token-embedding + token-logits | 3 / 3 | amplify-120m-f16-af32 esm2-t12-35m-ur50d-f32-af32 esmc-300m-f32-af32 |\n| Nucleotide encoders | dna-sequence → pooled-embedding + token-embedding | 1 / 1 | nucleotide-transformer-v2-50m-f32-af32 |\n\nThe [full model-support matrix](https://github.com/clocksmith/doppler/blob/main/docs/model-support-matrix.md)\nlists every lane and its lifecycle evidence. Classification says what an\nartifact is shaped to do; only lifecycle receipts establish what is\nverified, and a runtime pass does not by itself qualify every declared input\nmodality.\n\n\n\n## Evidence\n\nDoppler has accepted browser WebGPU comparisons with higher steady-state inference throughput\n(higher is faster) than Transformers.js where the declared workload correctness and\nthroughput gates pass. Loading is a separate measurement; the referenced\nVulkan embedding and reranker artifacts load faster in Transformers.js. The\n[scoreboard](https://github.com/clocksmith/doppler/blob/main/docs/model-competition-scoreboard.md)\nlinks the receipts and the [benchmark methodology](https://github.com/clocksmith/doppler/blob/main/docs/benchmark-methodology.md)\ndefines the gates.\n\n\n\n## Release and execution flow\n\n```mermaid\nflowchart TB\n S[Pinned source checkpoint] --> F[Forge: inspect, normalize, lower]\n F --> V[Verify and qualify TargetPlans]\n V --> P[Package and sign immutable Capsule]\n P --> A{Application acceptance}\n A -- fail --> N[Reject with finding]\n A -- pass --> K[Promote supported release]\n K --> R[Runtime: validate, select, bind, execute, observe]\n R --> Q[Requalify, roll back, or revoke]\n```\n\nCandidates begin as pinned source truth. Forge owns graph-changing work and\nemits an immutable Capsule only after verification and qualification. Application\nacceptance authorizes promotion. Runtime never repairs or specializes the Capsule;\nit selects a qualified TargetPlan, binds resources, executes declared commands,\nand emits evidence for continuing qualification and recovery decisions.\n\n## Long-term vision\n\nDoppler is intended to support a growing set of local model families and\nruntime variants without hiding the model contract or execution path. Registered\nvariant calibration, paired performance gates, and WGSL experiments remain\nhuman-reviewed. Ouroboros and Reploid sit above Doppler as orchestration or\nproduct layers; Doppler owns the artifact and execution boundary.\n\nNew model families require RDRR conversion and may require tokenizer, graph, or\nkernel support. Native packed-Q4K LoRA support is available for the declared\nQwen target; other packed-Q4K training targets use external backends.\n\n## Limits and current status\n\nWebGPU is required. Use a current Chromium browser; Node installs the WebGPU\nprovider as an optional dependency. A runtime pass does not verify every input\nmodality, and a receipt records what ran without establishing output quality.\nThroughput comparisons are valid only when the workload, timing scope, and\ncorrectness path are comparable. Unsupported paths fail closed.\n\n## Repository map\n\n- [Component charters](https://github.com/clocksmith/doppler/blob/main/CATSCAN.md) — recursive repository and subsystem intent\n- [Component index](https://github.com/clocksmith/doppler/blob/main/docs/component-index.md) — generated authority and parent map\n- [`src/`](src/) — runtime, model loading, inference, and execution contracts\n- [`demo/`](demo/) — browser demo and its public API boundary\n- [`models/adapters/`](models/adapters/) — adapter catalog, lifecycle, identity, and evidence metadata\n- [`benchmarks/`](benchmarks/) — vendor comparisons and retained results\n- [`docs/`](docs/) — APIs, architecture, formats, methodology, and release matrices\n- [`tests/`](tests/) — runtime, contract, browser, and benchmark tests\n- [`tools/`](tools/) — conversion, qualification, and operator tools\n\n## Read next\n\n- [Documentation index](https://github.com/clocksmith/doppler/blob/main/docs/INDEX.md)\n- [Architecture](https://github.com/clocksmith/doppler/blob/main/docs/architecture.md)\n- [RDRR format](https://github.com/clocksmith/doppler/blob/main/docs/rdrr-format.md)\n- [Local GPU challenger framework](https://github.com/clocksmith/doppler/blob/main/docs/local-gpu-challenger-framework.md)\n- [Program Bundles](https://github.com/clocksmith/doppler/blob/main/docs/integration/program-bundle.md)\n\n## License\n\n[MIT License](LICENSE). See [NOTICE](NOTICE) for attribution.\n","readmeFilename":"README.md"}
![\"doppler\"](\"assets/doppler-logo.svg\"){kind=logo}
\n