Skip to main content

crit crit

Why wait for someone to optimize an LLM for your GPU when an AI agent can build a specialized inference engine in a few hours?

Version 0.11.0 License Apache-2.0 crit-hub engines CI

Summary • Quick start • What crit solves • Case studies • How crit works • API • CLI • crit-hub • Limitations • Documentation


Summary

crit is a toolkit for optimizing or building inference engines tailored to your hardware and desired model.


Quick start

Give one of these prompts to your coding agent and specify your target LLM or target engine:

Use github.com/crit-labs/crit to build an optimized inference engine for <huggingface_url>.
Use github.com/crit-labs/crit to optimize my own inference engine in <engine_reference>.

What crit solves

The boring stuff has already been built ⏱️

Requests, memory management and cleanup eat up development time before optimization even starts. crit supplies a clean foundation so you can get to the work that makes your engine fast.

Curated high-impact inference strategies 📊

Don't rebuild inference strategies from scratch. We studied established inference engines and distilled their core speedup strategies into reusable code, so you can apply what works to your model and hardware quickly.

Physics-based evaluation suite 🔬

A benchmark score alone doesn't tell you what's still left on the table. crit measures your hardware's limits and shows how close your engine gets, with quality and correctness checks along the way.


Case Studies

We gave Claude Opus 5.5 a target LLM along with the crit repository and let it cook autonomously.

What it shows Evidence
Fast engines Qwen3.8-27B on one RTX 5090: 252 tok/s greedy decode, 4x its own first working candidate, and 7,425 tok/s prefill, with the full 262,144-token context
No quality traded for speed Perplexity within 0.1% of the reference, 5.8% of the drift budget; drafting reproduces plain greedy decoding token for token
Hours, not weeks 4h 15m and seven candidates from the run's first command to the selected engine, $42 at API list prices
Every step is evidence Each candidate is sealed with its exact source and its Eval result, so the table below is a record, not a recollection
Honest about what is left Prefill runs at 50% of the GPU's measured compute ceiling; Eval reports that gap next to the score
Next Gemma 4 31B (dense), and Qwen3.8-Flash-Next and Nemotron 3.5 Super 120B, mixture-of-experts models larger than VRAM

📋 Dense LLM, Qwen architecture → Inspect engine

Goal: Get to a fast, working engine for a dense model as quickly as possible. Limit: A fixed candidate budget.

4h 15m

Development time

252.4 tok/s

Decode

7,425 tok/s

Prefill

150 ms

TTFT

+0.1%

Perplexity vs reference

0.0028

Mean KL divergence


mtp7-device-confidence runs Qwen3.8-27B in its original NVFP4 weights on one RTX 5090, with the model's full 262,144 tokens of context. One coding agent built it from scratch on crit 0.5.0, writing its own kernels on Core without using another inference engine as a reference. It drafts up to 7 tokens per round with the model's own built-in draft layer and stops once the drafter's confidence in its latest draft falls below 0.5; the GPU makes that decision inside one CUDA graph per round, so the host never waits mid-round.

Decode and prefill of each of the seven candidates over the run's 4h 15m: decode jumps from 62 to 225 tok/s when drafting arrives with candidate 2 and ends at 252 tok/s; prefill climbs from 5,176 to 7,425 tok/s

Candidate What changed Decode Prefill TTFT Dev time, cumulative Agent tokens, cumulative API equivalent, cumulative
1 Working engine: reads the checkpoint as stored, 8-bit KV cache, no drafting 62 tok/s 5,176 tok/s 210 ms 0h 25m 16.1M $4.25
2 Drafts 4 tokens ahead with the model's draft layer, tensor-core decode GEMVs 225 tok/s 5,584 tok/s 187 ms 1h 06m 42.9M $12.55
3 8-bit prompt attention 227 tok/s 6,010 tok/s 184 ms 1h 37m 70.7M $19.73
4 cuBLASLt for the prompt's 4-bit and 8-bit matrix multiplies 216 tok/s 7,111 tok/s 156 ms 2h 23m 108.0M $29.68
5 Drafts 7 tokens ahead 244 tok/s 7,408 tok/s 151 ms 3h 02m 128.2M $34.58
6 Stops drafting once the drafter's confidence falls below 0.5, decided on the host (superseded: host waits made rounds jitter and failed the lower-context check) 243 tok/s 7,102 tok/s 152 ms 3h 59m 154.6M $41.96
7 The same stopping rule, decided on the GPU inside one CUDA graph per round 252 tok/s 7,425 tok/s 150 ms 4h 15m 155.7M $42.30

The last three columns are running totals from the run's first command (01:16:25 UTC) to each candidate's seal, and for candidate 7 to its selection, so its row is the whole run. Agent tokens and API equivalent count the agent's messages in that span, from its Claude Code session transcript: Claude Opus 5.5 for every message, priced at Anthropic's API list prices ($4/MTok input, $20/MTok output, $8/MTok 1-hour cache writes, $0.20/MTok cache reads; 99% of the tokens are cache reads). The agent writes the next candidate while the previous one is measured, so most of candidate 7 was built before candidate 6 was sealed: from there to its selection added only 16 minutes and 1.1M tokens.

Measured with crit Eval (v6) at the full 262,144-token context. Decode is greedy (temperature 0), the geometric mean over six prompts, from a chat question to a 14K-token agent session; Eval decodes each engine's own output, so candidates 3 and 4 have the same round time but accept different numbers of drafts.

  • Long context: a prompt that fills all 262,144 tokens gets its first token after 79 s, then decodes at 244 tok/s. On prompts outside Eval's speed suite, in 8 languages and code, it decodes at 163 tok/s.
  • Quality: perplexity stays within 0.1% of the reference, 5.8% of the drift budget, and drafting never changes the output: it is token for token what plain decoding produces.
  • Sampled requests: this engine drafts only on greedy requests. With sampling (temperature 0.6 to 1.0, including the defaults crit serve applies) it decodes one token per pass, at 59–60 tok/s on the same six cases, measured outside Eval. crit Eval v7 measures sampled decode too.

📋 Dense LLM, Gemma architecture → TBD

TBD. We are rebuilding this case study with crit 0.5.0; its engine and figures follow shortly.


📋 MoE LLM, VRAM overload, Qwen architecture → TBD

TBD. We are rebuilding this case study with crit 0.5.0; its engine and figures follow shortly.


📋 MoE LLM, VRAM overload, Nemotron architecture → TBD

TBD. We are rebuilding this case study with crit 0.5.0; its engine and figures follow shortly.


How crit works

An agent, or you, builds the engine as a series of candidates. Each candidate is a complete, servable engine, measured the same way, and each next one is chosen from the last one's numbers.

flowchart LR
    recon["Reconnaissance<br/>model, hardware,<br/>crit guides"] --> limits["crit eval<br/>the hardware's limits"]
    limits --> c1["Candidate 1<br/>a working engine"]
    c1 --> measure["crit eval<br/>scores vs limits"]
    measure --> decide{"Decision<br/>algorithm"}
    decide -->|"build: the biggest<br/>gap first"| next["Candidate 2 … X"]
    next --> measure
    decide -->|"stop: nothing left<br/>beyond the noise"| final["Final candidate,<br/>served by crit serve"]
  1. Reconnaissance. Gather everything the engine depends on before writing code: the user's model, hardware, workload, quality and context needs; the model's files (crit run ... recon reads its config, tokenizer, chat template, sampling defaults and draft layers); its model card and reference implementation; crit's agent instructions, guides and docs; and any crit-hub engine to start from.
  2. Learn the hardware's limits. crit eval probe measures the GPU, and Eval turns the measurements into the fastest decode, prefill and time to first token this model could reach on it.
  3. Build candidate 1: a working engine on Core, measured by Eval. It sets the baseline.
  4. Decide what the next candidate changes. The decision algorithm reads the last Eval and names the KPI furthest from its limit, the levers that close the gap, and a forecast crit checks after the build.
  5. Build candidate 2, 3, …, each measured by Eval and compared with its forecast.
  6. Stop at the final candidate once neither decode nor prefill can still move beyond its noise. It is selected, sealed with its source and evidence, and served through an OpenAI-compatible API.

Every step is recorded through the CLI: each candidate freezes its source by hash, each measurement points at that exact package, and the run's cost is counted from the agent's own transcripts (run records).


📗 Core → Full guide

Core is the plumbing every engine needs, distilled from about 30 bespoke inference engines.

We took apart how each engine handles requests, memory, text and model files, kept the base features they all rebuild, and turned them into one native SDK. Your engine keeps what makes it fast: the model, its kernels, its layouts and its execution strategy.

Part What it does
Runtime Admits, schedules, cancels and retires requests, and publishes their output
Engine libraries A C ABI that turns an engine into a shared library, with stock Eval and serve adapters
Memory Resource budgets, reservations and host-memory admission
Text Tokenizer and chat template loading, stop strings and streamed reply text
Sampling Sampling rules, penalties, log-probabilities and greedy draft acceptance
State cache KV pages, recurrent state slots and prefix-cache snapshots
Model files Safetensors and GGUF checkpoints, config.json, generation defaults and stop tokens
Files Strict JSON, read-only, chunked and mapped file reads, SHA-256
Structured output Token masks for choices, JSON schemas and grammars
Device graphs CUDA graph capture and replay to cut launch overhead
CUDA backend Allocations, streams, shared device memory and device time per category
Tracing A bounded lifecycle trace with operator ranges and NVTX
Contracts Who owns what between Core and your engine

Try the Core + Inference walkthrough.


📕 Inference → Full guide

Inference is our register of speed-up strategies, curated from about 50 inference engines.

We studied what makes each engine fast and turned every strategy that holds beyond one model or GPU into an entry. Your agent picks the entries that match its engine's bottleneck and builds them into the engine on Core.

Bottleneck Example entries
One token per pass Speculative decoding, draft trees, device-side rounds, EAGLE-3 and DFlash drafters
Weight bytes per pass Quantized projections, stored-tile FP8 and NVFP4 GEMMs, GGUF projections
Long context FP8 KV attention, flash prefill, paged attention, prefix checkpoints
Model larger than VRAM Expert residency, device expert cache, dense layer offload
Hybrid recurrent layers Recurrent layer kernels, recurrent state recovery

All 37 entries are in the full guide, or run crit inference search <query>.

Every entry has the same layout

Part What it holds
README.md When to use it, how it works, a worked example, how to adapt it, its costs and how to validate it
code/ Real implementation code, C++, CUDA or Python, with runnable examples
entry.json When to use and avoid it, what the code provides, what the engine must supply and what it must preserve

What gets in: the contribution criteria

Criterion Means
Shown value A measured gain, a reproduced and fixed bug, or a capability engines had to rebuild themselves
No overfitting Nothing in it is true only for the model or GPU where it was found
Broad use Dense, MoE, hybrid and multimodal models and other CUDA GPUs use it unchanged or are unaffected

📚 Eval → Full guide

crit-eval is a speed and quality measurement tool to compare inference engines honestly.

There is no shared way to measure a bespoke inference engine.

Different bespoke inference engines report vastly different types of numbers. An honest comparison requires downloading and running the engines yourself. crit-eval finally makes apples-to-apples comparison possible.

Physics-based evaluation lets you see what performance is left on the table.

crit-eval measures your GPU's memory bandwidth and matrix-multiply rates and turns them into a limit for each score. Its evaluation report can tell your coding agent how much performance can still be squeezed out of your inference engine.

Speed that can't hide a quality loss.

Many inference engines push decode and prefill speed with no regard for quality. crit-eval treats quality as a first-class KPI. It measures not only inference speed but also quality regressions.

A hardware report rounds out the evaluation.

The same model on the same inference engine but on two different machines can also lead to different inference speeds, even if the GPU is the same. We make this transparent by also reporting the runner's hardware configuration.


📘 Kernels → Full guide

Kernels helps you find and assess existing kernels for your data format and hardware, including the Hugging Face Kernel Hub. It checks declared compatibility, shows mismatches and gaps, and retains chosen artifacts with exact versions and license notices. Your engine then measures whether the kernel helps.


📙 Models → Full guide

Models produces transformed weights when a run allows them, starting with post-training quantization to FP8 or NVFP4 (round-to-nearest or GPTQ). It exports a checkpoint engines can read, runs it in your engine through Eval against the original model, and records the recipe, calibration data, seed, file hashes and cost.


🔌 API → Overview · Full guide

crit serve loads a sealed candidate, keeps it resident and answers OpenAI-compatible chat requests, including streaming, tool calls, stop strings and structured output. The same engine also speaks the Anthropic Messages, OpenAI Responses and Ollama APIs, so Claude Code, Codex and local chat UIs need only a base URL, and GET /metrics serves Prometheus metrics. Eval measures every candidate through this same server, so the numbers you read are the numbers you get. Engines implement the adapter contract.


📓 CLI → Overview

One crit command drives everything: crit run keeps the run's records (plans, candidates, measurements, selection, cost), crit eval runs the common suite, crit serve serves an engine, and crit kernels, crit models and crit inference reach the other parts. Records are written only through it, so each plan, candidate, Eval and seal is checked as it is recorded.


Miscellaneous


🔭 crit-hub → Repository

crit-hub collects bespoke inference engines in one repository to make discovery super easy. Each engine pins its runnable source, the exact checkpoint it was built on, what was measured, its known limits and a link to the repository of whoever contributed it. Use them as jump-off point for further optimization.


🚫 Limitations
Area Current status
Multi-GPU setups Expected to work with engine-specific partitioning and communication; not yet tested end to end.
macOS Not yet tested. Current CI covers Windows and Linux.
AMD and Apple GPUs No bundled ROCm or Metal backend. The current GPU backend uses CUDA.
Model formats Hugging Face safetensors, PyTorch state dicts (.bin, .pt) and Optimum ONNX exports, unquantized or quantized as FP8, NVFP4, compressed-tensors int, AWQ, GPTQ, MLX, bitsandbytes or MatMulNBits, and GGUF, a lone .gguf included: its config, tokenizer and chat template are derived from its metadata for the llama, qwen2, qwen3, qwen3moe, qwen35 and qwen35moe architectures and byte-level BPE tokenizers (others need the base model's files beside it), and Eval's reference reads those architectures. A new format is one ModelFormat in crit_core.model. Core's C++ model library reads safetensors only; engines read a GGUF's tensors through crit_core.model's offsets.

Documentation

To… Read
Build and compare engines Building engines · Agent instructions · Run records
Integrate the native runtime Core · Contracts · Core + Inference walkthrough
Choose or adapt a technique Inference
Find and adapt kernels Kernels
Quantize weights and record the transform Models
Compare speed, quality and speculative output Eval
Serve an engine through the OpenAI, Anthropic or Ollama API API · Serving · Adapter contract
Find a crit command CLI
Change crit or run its tests What belongs in crit · Contributing · Licensing
See release history Changelog

Metadata

Release files for crit 0.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for crit 0.11.0
File Size Uploaded Provenance Actions
crit-0.11.0.tar.gz 582.6 kB With provenance Details for crit-0.11.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for crit 0.11.0
File Interpreter ABI Platform Actions
crit-0.11.0-py3-none-any.whl Python 3 none any Details for crit-0.11.0-py3-none-any.whl

Total release size: 849.8 kB

Release files / crit-0.11.0.tar.gz

Download URL crit-0.11.0.tar.gz
Size 582.6 kB
Tags Source
SHA-256 checksum
How to use checksums
14e12310f5675ecbf4aedc96935c6ec849ebe828f3081f3f314be8d66193e92a
BLAKE2b-256 checksum
How to use checksums
305070a9b91726eaa330c7acc5d6917df21fb0a5158832498d6efbdcee14e248
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / crit-0.11.0-py3-none-any.whl

Download URL crit-0.11.0-py3-none-any.whl
Size 267.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ba47a986d4f096b74ee86953d29b028af3d84f237f1788ec6c532e496ac78478
BLAKE2b-256 checksum
How to use checksums
785130991ce711754595258f83d9c87daa3eda5355d4574486db8c7e70884ced
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for crit 0.11.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for crit-0.11.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page