From 011732b47bfe54d81be69cb930d2b21d8a89f8d9 Mon Sep 17 00:00:00 2001 From: haaziq-sl <286741220+haaziq-sl@users.noreply.github.com> Date: Thu, 5 Nov 2026 15:24:46 +0400 Subject: [PATCH] Import inferencekit --- .claude-plugin/marketplace.json | 44 + .github/workflows/ci.yml | 120 + .gitignore | 7 + AGENTS.md | 73 + CONTRIBUTING.md | 45 + LICENSE | 202 ++ NOTICE | 9 + README.md | 244 ++ SECURITY.md | 29 + THIRD_PARTY_NOTICES.md | 77 + assets/hero-speedups.png | Bin 0 -> 157883 bytes assets/inferencekit-kitten.png | Bin 0 -> 747533 bytes docs/examples.md | 59 + docs/install.md | 93 + docs/media-benchmarks.md | 87 + plugin/.claude-plugin/plugin.json | 30 + plugin/.mcp.json | 14 + plugin/agents/claims-skeptic.md | 31 + plugin/agents/engine-scout.md | 39 + plugin/agents/log-reader.md | 21 + plugin/agents/profile-analyst.md | 42 + plugin/agents/quant-scout.md | 51 + plugin/bin/ikstep | 4 + plugin/commands/bench.md | 23 + plugin/commands/optimize-inference.md | 15 + plugin/commands/perf-report.md | 17 + plugin/commands/profile.md | 22 + plugin/hooks/deadline.py | 89 + plugin/hooks/hooks.json | 3 + plugin/opencode/README.md | 61 + plugin/opencode/agents/claims-skeptic.md | 36 + plugin/opencode/agents/engine-scout.md | 44 + plugin/opencode/agents/log-reader.md | 26 + plugin/opencode/agents/profile-analyst.md | 47 + plugin/opencode/agents/quant-scout.md | 56 + plugin/opencode/commands/bench.md | 28 + .../opencode/commands/optimize-inference.md | 20 + plugin/opencode/commands/perf-report.md | 22 + plugin/opencode/commands/profile.md | 27 + plugin/opencode/install.py | 201 ++ plugin/opencode/sync.py | 136 ++ plugin/skills/benchmarking/SKILL.md | 134 + .../benchmarking/references/ceilings.md | 117 + .../benchmarking/references/engine-configs.md | 90 + .../benchmarking/references/launch-cost.md | 68 + .../benchmarking/references/reward-hacks.md | 62 + .../skills/benchmarking/references/serving.md | 69 + .../benchmarking/references/statistics.md | 70 + .../benchmarking/references/video-checks.md | 36 + .../references/worked-example-qwen3-8b.md | 71 + .../skills/evaluating-quantization/SKILL.md | 92 + .../references/bytes-and-fit.md | 101 + .../references/formats.md | 76 + .../references/measure-and-score.md | 106 + .../references/small-gpu.md | 57 + .../scripts/gguf_bytes_per_token.py | 229 ++ plugin/skills/inference-triage/SKILL.md | 157 ++ .../inference-triage/references/amd-rocm.md | 110 + .../references/apple-silicon.md | 141 ++ .../skills/inference-triage/references/cpu.md | 99 + .../references/evidence-rules.md | 56 + .../inference-triage/references/hardware.md | 52 + .../references/other-accelerators.md | 19 + .../references/symptom-map.md | 51 + plugin/skills/optimizing-inference/SKILL.md | 108 + .../references/affordability.md | 19 + .../references/candidates.md | 142 ++ .../references/capacity.md | 135 + .../references/ceilings.md | 58 + .../references/engine-contribution.md | 46 + .../references/fidelity.md | 27 + .../references/harness-commands.md | 117 + .../optimizing-inference/references/intake.md | 224 ++ .../optimizing-inference/references/ledger.md | 31 + .../references/manifest.md | 77 + .../references/non-interactive.md | 57 + .../references/parallel.md | 33 + .../references/parallelism.md | 75 + .../optimizing-inference/references/plan.md | 11 + .../references/remote-host.md | 167 ++ .../references/speculative.md | 28 + .../references/starting-questions.md | 39 + .../optimizing-inference/references/state.md | 65 + .../references/stop-point.md | 117 + .../optimizing-inference/references/tuning.md | 141 ++ .../optimizing-inference/references/video.md | 90 + .../references/workload.md | 92 + .../scripts/bytes_per_token.py | 273 +++ .../optimizing-inference/scripts/ikstep.py | 730 ++++++ plugin/skills/optimizing-kernels/SKILL.md | 143 ++ .../references/attention-split-k.md | 47 + .../references/byte-cuts.md | 128 + .../references/commit-ledger.md | 69 + .../references/compiler-inspection.md | 39 + .../optimizing-kernels/references/fp8-gemv.md | 88 + .../references/launch-overhead.md | 61 + .../optimizing-kernels/references/lessons.md | 74 + .../references/moe-decode.md | 35 + .../optimizing-kernels/references/prefill.md | 33 + .../optimizing-kernels/skeleton/README.md | 183 ++ .../skeleton/ikengine/__init__.py | 2 + .../skeleton/ikengine/engine.py | 160 ++ .../skeleton/ikengine/engine_api.py | 124 + .../skeleton/ikengine/graph_loop.py | 126 + .../skeleton/ikengine/loader.py | 267 ++ .../skeleton/ikengine/models/__init__.py | 41 + .../skeleton/ikengine/models/dense.py | 3 + .../skeleton/ikengine/models/gemma4.py | 767 ++++++ .../skeleton/ikengine/models/qwen3_5.py | 562 +++++ .../skeleton/ikengine/moe.py | 123 + .../skeleton/ikengine/qlinear.py | 288 +++ .../skeleton/ikengine/ref_dense.py | 403 +++ .../skeleton/ikengine/sampler.py | 123 + .../skeleton/ikengine/serve.py | 1446 +++++++++++ .../skeleton/ikengine/tools/__init__.py | 1 + .../skeleton/ikengine/tools/validate_model.py | 653 +++++ plugin/skills/profiling/SKILL.md | 118 + .../profiling/references/capture-hygiene.md | 61 + .../references/ncu-capture-recipes.md | 48 + .../profiling/references/ncu-metrics.md | 57 + .../profiling/references/six-questions.md | 80 + .../profiling/references/torch-profiler.md | 65 + plugin/skills/proving-correctness/SKILL.md | 181 ++ .../references/byte-identity-ladder.md | 30 + .../references/gsm8k-parity.md | 28 + .../proving-correctness/references/quality.md | 82 + .../references/token-agreement.md | 74 + plugin/skills/reporting-perf-claims/SKILL.md | 118 + .../references/claims-lint.md | 28 + .../references/verdict-rules.md | 43 + .../references/wording-guide.md | 77 + .../skills/researching-optimizations/SKILL.md | 32 + .../references/sources.md | 19 + pyproject.toml | 81 + schemas/evidence.v1.json | 130 + schemas/evidence.v2.json | 499 ++++ schemas/intake.v1.json | 276 +++ schemas/run-manifest.v1.json | 118 + scripts/build_prompts.py | 48 + scripts/release/build-constraints.txt | 94 + scripts/release/build_wheel.sh | 82 + scripts/release/check_versions.py | 231 ++ src/inferencekit/__init__.py | 9 + src/inferencekit/__main__.py | 5 + src/inferencekit/analysis/__init__.py | 1 + src/inferencekit/analysis/ncu_csv.py | 284 +++ src/inferencekit/analysis/nsys_sqlite.py | 518 ++++ src/inferencekit/canonical.py | 104 + src/inferencekit/checkpoint.py | 396 +++ src/inferencekit/cli.py | 274 +++ src/inferencekit/cuda/bw_peak.cu | 252 ++ src/inferencekit/cuda/torch_bw.py | 60 + src/inferencekit/engines/__init__.py | 7 + src/inferencekit/engines/adapters.py | 190 ++ src/inferencekit/engines/clip/__init__.py | 13 + src/inferencekit/engines/clip/comfyui.py | 749 ++++++ .../engines/clip/diffusers_ltx.py | 601 +++++ src/inferencekit/engines/clip/noise.py | 46 + src/inferencekit/engines/clip/official_ltx.py | 316 +++ src/inferencekit/engines/clip/server.py | 542 +++++ src/inferencekit/engines/clip/stepdump.py | 182 ++ src/inferencekit/engines/gates.py | 94 + src/inferencekit/engines/sglang_worker.py | 86 + src/inferencekit/engines/vllm_worker.py | 129 + src/inferencekit/evidence.py | 427 ++++ src/inferencekit/gpuinfo.py | 93 + src/inferencekit/hardware.py | 135 + src/inferencekit/mcp_server.py | 178 ++ src/inferencekit/ops/__init__.py | 30 + src/inferencekit/ops/bench.py | 184 ++ src/inferencekit/ops/bench_audio.py | 384 +++ src/inferencekit/ops/bench_clip.py | 819 +++++++ src/inferencekit/ops/bench_image.py | 393 +++ src/inferencekit/ops/bench_rounds.py | 297 +++ src/inferencekit/ops/bench_serve.py | 866 +++++++ src/inferencekit/ops/ceiling.py | 135 + src/inferencekit/ops/compare.py | 378 +++ src/inferencekit/ops/correctness.py | 153 ++ src/inferencekit/ops/doctor.py | 486 ++++ src/inferencekit/ops/gates.py | 1772 ++++++++++++++ src/inferencekit/ops/gates_clip.py | 930 +++++++ src/inferencekit/ops/intake.py | 1321 ++++++++++ src/inferencekit/ops/ledger.py | 749 ++++++ src/inferencekit/ops/manifest.py | 309 +++ src/inferencekit/ops/ncu.py | 183 ++ src/inferencekit/ops/nsys.py | 224 ++ src/inferencekit/ops/prompts.py | 316 +++ src/inferencekit/ops/quality.py | 2161 +++++++++++++++++ src/inferencekit/ops/quality_clip.py | 690 ++++++ src/inferencekit/ops/quality_clip_steps.py | 341 +++ src/inferencekit/ops/report.py | 317 +++ src/inferencekit/ops/review.py | 119 + src/inferencekit/ops/rocprof.py | 89 + src/inferencekit/ops/roofline.py | 392 +++ src/inferencekit/ops/store.py | 61 + src/inferencekit/proc.py | 172 ++ src/inferencekit/prompts/ATTRIBUTION.md | 56 + src/inferencekit/prompts/__init__.py | 167 ++ src/inferencekit/prompts/build.py | 518 ++++ src/inferencekit/prompts/dev-load.jsonl.gz | Bin 0 -> 239038 bytes .../prompts/dev-load.manifest.json | 212 ++ src/inferencekit/prompts/dev.jsonl.gz | Bin 0 -> 87529 bytes src/inferencekit/prompts/dev.manifest.json | 214 ++ src/inferencekit/prompts/exclusions.json | 54 + src/inferencekit/quality/__init__.py | 23 + src/inferencekit/quality/client.py | 66 + .../quality/data/gsm8k_LICENSE.txt | 21 + src/inferencekit/quality/fake.py | 329 +++ src/inferencekit/quality/gsm8k.py | 224 ++ src/inferencekit/quality/logprobs.py | 106 + src/inferencekit/quality/metrics.py | 235 ++ src/inferencekit/quality/niah.py | 63 + src/inferencekit/quality/parquet.py | 296 +++ src/inferencekit/quality/sampling.py | 262 ++ src/inferencekit/quality/step_replay.py | 217 ++ src/inferencekit/quality/video_metrics.py | 304 +++ src/inferencekit/registry.py | 206 ++ src/inferencekit/review/__init__.py | 6 + src/inferencekit/review/diff.py | 163 ++ src/inferencekit/review/media.py | 181 ++ src/inferencekit/review/page.py | 920 +++++++ src/inferencekit/review/rundir.py | 844 +++++++ src/inferencekit/roofline_headers.py | 504 ++++ src/inferencekit/serve/__init__.py | 8 + src/inferencekit/serve/audio_client.py | 330 +++ src/inferencekit/serve/client.py | 446 ++++ src/inferencekit/serve/clip_client.py | 351 +++ src/inferencekit/serve/clip_rounds.py | 429 ++++ src/inferencekit/serve/image_client.py | 373 +++ src/inferencekit/serve/loadgen.py | 136 ++ src/inferencekit/serve/metrics.py | 203 ++ src/inferencekit/serve/profiles.py | 105 + src/inferencekit/serve/prompts_io.py | 125 + src/inferencekit/serve/rounds.py | 1111 +++++++++ src/inferencekit/serve/servers.py | 897 +++++++ src/inferencekit/stats.py | 249 ++ tests/cheats/__init__.py | 0 tests/cheats/fake_engine.py | 280 +++ tests/conftest.py | 57 + tests/fakes/__init__.py | 1 + tests/fakes/e2e_engine.py | 127 + tests/fakes/fake_openai_server.py | 251 ++ tests/fakes_clip/__init__.py | 1 + tests/fakes_clip/fake_comfyui.py | 389 +++ tests/fakes_clip/fake_pipelines.py | 200 ++ tests/fakes_clip/fake_steps.py | 228 ++ tests/fakes_ikstep/fake_inferencekit.py | 131 + tests/fakes_rounds/fake_server.py | 122 + tests/fakes_rounds/logs/generic.log | 3 + tests/fakes_rounds/logs/llamacpp.log | 19 + tests/fakes_rounds/logs/llamacpp_cpu.log | 7 + tests/fakes_rounds/logs/sglang.log | 9 + tests/fakes_rounds/logs/sglang_old.log | 3 + tests/fakes_rounds/logs/trtllm.log | 6 + tests/fakes_rounds/logs/vllm.log | 14 + tests/fakes_rounds/stub_bench_serve.py | 78 + tests/fakes_skeleton/__init__.py | 2 + tests/fakes_skeleton/engines.py | 252 ++ .../fixtures/ikstep/gates-baseline-void.json | 1 + tests/fixtures/ikstep/gates.json | 1 + tests/fixtures/ikstep/gsm8k-baseline.json | 1 + tests/fixtures/ikstep/gsm8k.json | 1 + tests/fixtures/ikstep/manifest.json | 143 ++ tests/fixtures/ikstep/metrics.json | 1 + tests/fixtures/ikstep/rounds-failed.json | 1 + tests/fixtures/ikstep/rounds.json | 1 + tests/fixtures/ikstep/sampling-baseline.json | 1 + tests/fixtures/ikstep/sampling.json | 1 + tests/fixtures/ikstep/score-file.json | 1 + tests/fixtures/ikstep/score.json | 1 + tests/fixtures/ikstep/serve.json | 1 + tests/fixtures/ikstep/trajectory.json | 1 + tests/fixtures/intake/llm-qwen-5090.yaml | 67 + tests/fixtures/parquet/gsm8k_tiny.parquet | Bin 0 -> 2224 bytes .../parquet/nulls_gzip_plain_v2.parquet | Bin 0 -> 1325 bytes .../parquet/required_uncompressed.parquet | Bin 0 -> 635 bytes tests/test_audio_client.py | 274 +++ tests/test_bench.py | 69 + tests/test_bench_audio.py | 206 ++ tests/test_bench_clip.py | 772 ++++++ tests/test_bench_image.py | 161 ++ tests/test_bench_rounds.py | 893 +++++++ tests/test_bench_serve.py | 393 +++ tests/test_bench_serve_evidence.py | 89 + tests/test_bench_serve_load.py | 176 ++ tests/test_byte_floor.py | 100 + tests/test_chat_template_kwargs.py | 120 + tests/test_cli_terse.py | 179 ++ tests/test_clip_adapters.py | 1381 +++++++++++ tests/test_compare.py | 113 + tests/test_compare_media.py | 84 + tests/test_compare_serve.py | 96 + tests/test_correctness.py | 53 + tests/test_deadline_hook.py | 331 +++ tests/test_doctor_counters.py | 273 +++ tests/test_e2e_fake.py | 328 +++ tests/test_engine_skeleton_core.py | 1101 +++++++++ tests/test_engine_skeleton_serve.py | 1367 +++++++++++ tests/test_evidence.py | 104 + tests/test_gates.py | 807 ++++++ tests/test_gates_clip.py | 720 ++++++ tests/test_gguf_bytes_script.py | 84 + tests/test_hardware.py | 127 + tests/test_ikstep.py | 377 +++ tests/test_ikstep_jobs.py | 693 ++++++ tests/test_image_client.py | 232 ++ tests/test_image_tradeoff.py | 130 + tests/test_intake.py | 1218 ++++++++++ tests/test_interfaces.py | 127 + tests/test_kernel_recipes.py | 274 +++ tests/test_ledger.py | 388 +++ tests/test_manifest.py | 270 ++ tests/test_ncu_summarize.py | 139 ++ tests/test_nsys_analyze.py | 262 ++ tests/test_opencode.py | 143 ++ tests/test_packaging.py | 286 +++ tests/test_plain_english.py | 102 + tests/test_proc.py | 66 + tests/test_prompts.py | 287 +++ tests/test_prompts_gzip.py | 157 ++ tests/test_quality.py | 739 ++++++ tests/test_quality_clip.py | 481 ++++ tests/test_quality_clip_steps.py | 220 ++ tests/test_quality_gsm8k_data.py | 158 ++ tests/test_quality_sampling.py | 720 ++++++ tests/test_quality_stats.py | 143 ++ tests/test_review.py | 499 ++++ tests/test_review_media.py | 233 ++ tests/test_review_video.py | 296 +++ tests/test_rocprof.py | 57 + tests/test_roofline.py | 111 + tests/test_roofline_headers.py | 576 +++++ tests/test_skeleton_gemma4.py | 606 +++++ tests/test_skeleton_qwen35.py | 641 +++++ tests/test_skill_flow.py | 266 ++ tests/test_skills.py | 386 +++ tests/test_stats.py | 121 + uv.lock | 1178 +++++++++ 338 files changed, 72150 insertions(+) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .github/workflows/ci.yml create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 NOTICE create mode 100644 README.md create mode 100644 SECURITY.md create mode 100644 THIRD_PARTY_NOTICES.md create mode 100644 assets/hero-speedups.png create mode 100644 assets/inferencekit-kitten.png create mode 100644 docs/examples.md create mode 100644 docs/install.md create mode 100644 docs/media-benchmarks.md create mode 100644 plugin/.claude-plugin/plugin.json create mode 100644 plugin/.mcp.json create mode 100644 plugin/agents/claims-skeptic.md create mode 100644 plugin/agents/engine-scout.md create mode 100644 plugin/agents/log-reader.md create mode 100644 plugin/agents/profile-analyst.md create mode 100644 plugin/agents/quant-scout.md create mode 100755 plugin/bin/ikstep create mode 100644 plugin/commands/bench.md create mode 100644 plugin/commands/optimize-inference.md create mode 100644 plugin/commands/perf-report.md create mode 100644 plugin/commands/profile.md create mode 100644 plugin/hooks/deadline.py create mode 100644 plugin/hooks/hooks.json create mode 100644 plugin/opencode/README.md create mode 100644 plugin/opencode/agents/claims-skeptic.md create mode 100644 plugin/opencode/agents/engine-scout.md create mode 100644 plugin/opencode/agents/log-reader.md create mode 100644 plugin/opencode/agents/profile-analyst.md create mode 100644 plugin/opencode/agents/quant-scout.md create mode 100644 plugin/opencode/commands/bench.md create mode 100644 plugin/opencode/commands/optimize-inference.md create mode 100644 plugin/opencode/commands/perf-report.md create mode 100644 plugin/opencode/commands/profile.md create mode 100755 plugin/opencode/install.py create mode 100755 plugin/opencode/sync.py create mode 100644 plugin/skills/benchmarking/SKILL.md create mode 100644 plugin/skills/benchmarking/references/ceilings.md create mode 100644 plugin/skills/benchmarking/references/engine-configs.md create mode 100644 plugin/skills/benchmarking/references/launch-cost.md create mode 100644 plugin/skills/benchmarking/references/reward-hacks.md create mode 100644 plugin/skills/benchmarking/references/serving.md create mode 100644 plugin/skills/benchmarking/references/statistics.md create mode 100644 plugin/skills/benchmarking/references/video-checks.md create mode 100644 plugin/skills/benchmarking/references/worked-example-qwen3-8b.md create mode 100644 plugin/skills/evaluating-quantization/SKILL.md create mode 100644 plugin/skills/evaluating-quantization/references/bytes-and-fit.md create mode 100644 plugin/skills/evaluating-quantization/references/formats.md create mode 100644 plugin/skills/evaluating-quantization/references/measure-and-score.md create mode 100644 plugin/skills/evaluating-quantization/references/small-gpu.md create mode 100644 plugin/skills/evaluating-quantization/scripts/gguf_bytes_per_token.py create mode 100644 plugin/skills/inference-triage/SKILL.md create mode 100644 plugin/skills/inference-triage/references/amd-rocm.md create mode 100644 plugin/skills/inference-triage/references/apple-silicon.md create mode 100644 plugin/skills/inference-triage/references/cpu.md create mode 100644 plugin/skills/inference-triage/references/evidence-rules.md create mode 100644 plugin/skills/inference-triage/references/hardware.md create mode 100644 plugin/skills/inference-triage/references/other-accelerators.md create mode 100644 plugin/skills/inference-triage/references/symptom-map.md create mode 100644 plugin/skills/optimizing-inference/SKILL.md create mode 100644 plugin/skills/optimizing-inference/references/affordability.md create mode 100644 plugin/skills/optimizing-inference/references/candidates.md create mode 100644 plugin/skills/optimizing-inference/references/capacity.md create mode 100644 plugin/skills/optimizing-inference/references/ceilings.md create mode 100644 plugin/skills/optimizing-inference/references/engine-contribution.md create mode 100644 plugin/skills/optimizing-inference/references/fidelity.md create mode 100644 plugin/skills/optimizing-inference/references/harness-commands.md create mode 100644 plugin/skills/optimizing-inference/references/intake.md create mode 100644 plugin/skills/optimizing-inference/references/ledger.md create mode 100644 plugin/skills/optimizing-inference/references/manifest.md create mode 100644 plugin/skills/optimizing-inference/references/non-interactive.md create mode 100644 plugin/skills/optimizing-inference/references/parallel.md create mode 100644 plugin/skills/optimizing-inference/references/parallelism.md create mode 100644 plugin/skills/optimizing-inference/references/plan.md create mode 100644 plugin/skills/optimizing-inference/references/remote-host.md create mode 100644 plugin/skills/optimizing-inference/references/speculative.md create mode 100644 plugin/skills/optimizing-inference/references/starting-questions.md create mode 100644 plugin/skills/optimizing-inference/references/state.md create mode 100644 plugin/skills/optimizing-inference/references/stop-point.md create mode 100644 plugin/skills/optimizing-inference/references/tuning.md create mode 100644 plugin/skills/optimizing-inference/references/video.md create mode 100644 plugin/skills/optimizing-inference/references/workload.md create mode 100644 plugin/skills/optimizing-inference/scripts/bytes_per_token.py create mode 100644 plugin/skills/optimizing-inference/scripts/ikstep.py create mode 100644 plugin/skills/optimizing-kernels/SKILL.md create mode 100644 plugin/skills/optimizing-kernels/references/attention-split-k.md create mode 100644 plugin/skills/optimizing-kernels/references/byte-cuts.md create mode 100644 plugin/skills/optimizing-kernels/references/commit-ledger.md create mode 100644 plugin/skills/optimizing-kernels/references/compiler-inspection.md create mode 100644 plugin/skills/optimizing-kernels/references/fp8-gemv.md create mode 100644 plugin/skills/optimizing-kernels/references/launch-overhead.md create mode 100644 plugin/skills/optimizing-kernels/references/lessons.md create mode 100644 plugin/skills/optimizing-kernels/references/moe-decode.md create mode 100644 plugin/skills/optimizing-kernels/references/prefill.md create mode 100644 plugin/skills/optimizing-kernels/skeleton/README.md create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/__init__.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/engine.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/engine_api.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/graph_loop.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/loader.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/models/__init__.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/models/dense.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/models/gemma4.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/models/qwen3_5.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/moe.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/qlinear.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/ref_dense.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/sampler.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/serve.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/tools/__init__.py create mode 100644 plugin/skills/optimizing-kernels/skeleton/ikengine/tools/validate_model.py create mode 100644 plugin/skills/profiling/SKILL.md create mode 100644 plugin/skills/profiling/references/capture-hygiene.md create mode 100644 plugin/skills/profiling/references/ncu-capture-recipes.md create mode 100644 plugin/skills/profiling/references/ncu-metrics.md create mode 100644 plugin/skills/profiling/references/six-questions.md create mode 100644 plugin/skills/profiling/references/torch-profiler.md create mode 100644 plugin/skills/proving-correctness/SKILL.md create mode 100644 plugin/skills/proving-correctness/references/byte-identity-ladder.md create mode 100644 plugin/skills/proving-correctness/references/gsm8k-parity.md create mode 100644 plugin/skills/proving-correctness/references/quality.md create mode 100644 plugin/skills/proving-correctness/references/token-agreement.md create mode 100644 plugin/skills/reporting-perf-claims/SKILL.md create mode 100644 plugin/skills/reporting-perf-claims/references/claims-lint.md create mode 100644 plugin/skills/reporting-perf-claims/references/verdict-rules.md create mode 100644 plugin/skills/reporting-perf-claims/references/wording-guide.md create mode 100644 plugin/skills/researching-optimizations/SKILL.md create mode 100644 plugin/skills/researching-optimizations/references/sources.md create mode 100644 pyproject.toml create mode 100644 schemas/evidence.v1.json create mode 100644 schemas/evidence.v2.json create mode 100644 schemas/intake.v1.json create mode 100644 schemas/run-manifest.v1.json create mode 100755 scripts/build_prompts.py create mode 100644 scripts/release/build-constraints.txt create mode 100755 scripts/release/build_wheel.sh create mode 100755 scripts/release/check_versions.py create mode 100644 src/inferencekit/__init__.py create mode 100644 src/inferencekit/__main__.py create mode 100644 src/inferencekit/analysis/__init__.py create mode 100644 src/inferencekit/analysis/ncu_csv.py create mode 100644 src/inferencekit/analysis/nsys_sqlite.py create mode 100644 src/inferencekit/canonical.py create mode 100644 src/inferencekit/checkpoint.py create mode 100644 src/inferencekit/cli.py create mode 100644 src/inferencekit/cuda/bw_peak.cu create mode 100644 src/inferencekit/cuda/torch_bw.py create mode 100644 src/inferencekit/engines/__init__.py create mode 100644 src/inferencekit/engines/adapters.py create mode 100644 src/inferencekit/engines/clip/__init__.py create mode 100644 src/inferencekit/engines/clip/comfyui.py create mode 100644 src/inferencekit/engines/clip/diffusers_ltx.py create mode 100644 src/inferencekit/engines/clip/noise.py create mode 100644 src/inferencekit/engines/clip/official_ltx.py create mode 100644 src/inferencekit/engines/clip/server.py create mode 100644 src/inferencekit/engines/clip/stepdump.py create mode 100644 src/inferencekit/engines/gates.py create mode 100644 src/inferencekit/engines/sglang_worker.py create mode 100644 src/inferencekit/engines/vllm_worker.py create mode 100644 src/inferencekit/evidence.py create mode 100644 src/inferencekit/gpuinfo.py create mode 100644 src/inferencekit/hardware.py create mode 100644 src/inferencekit/mcp_server.py create mode 100644 src/inferencekit/ops/__init__.py create mode 100644 src/inferencekit/ops/bench.py create mode 100644 src/inferencekit/ops/bench_audio.py create mode 100644 src/inferencekit/ops/bench_clip.py create mode 100644 src/inferencekit/ops/bench_image.py create mode 100644 src/inferencekit/ops/bench_rounds.py create mode 100644 src/inferencekit/ops/bench_serve.py create mode 100644 src/inferencekit/ops/ceiling.py create mode 100644 src/inferencekit/ops/compare.py create mode 100644 src/inferencekit/ops/correctness.py create mode 100644 src/inferencekit/ops/doctor.py create mode 100644 src/inferencekit/ops/gates.py create mode 100644 src/inferencekit/ops/gates_clip.py create mode 100644 src/inferencekit/ops/intake.py create mode 100644 src/inferencekit/ops/ledger.py create mode 100644 src/inferencekit/ops/manifest.py create mode 100644 src/inferencekit/ops/ncu.py create mode 100644 src/inferencekit/ops/nsys.py create mode 100644 src/inferencekit/ops/prompts.py create mode 100644 src/inferencekit/ops/quality.py create mode 100644 src/inferencekit/ops/quality_clip.py create mode 100644 src/inferencekit/ops/quality_clip_steps.py create mode 100644 src/inferencekit/ops/report.py create mode 100644 src/inferencekit/ops/review.py create mode 100644 src/inferencekit/ops/rocprof.py create mode 100644 src/inferencekit/ops/roofline.py create mode 100644 src/inferencekit/ops/store.py create mode 100644 src/inferencekit/proc.py create mode 100644 src/inferencekit/prompts/ATTRIBUTION.md create mode 100644 src/inferencekit/prompts/__init__.py create mode 100644 src/inferencekit/prompts/build.py create mode 100644 src/inferencekit/prompts/dev-load.jsonl.gz create mode 100644 src/inferencekit/prompts/dev-load.manifest.json create mode 100644 src/inferencekit/prompts/dev.jsonl.gz create mode 100644 src/inferencekit/prompts/dev.manifest.json create mode 100644 src/inferencekit/prompts/exclusions.json create mode 100644 src/inferencekit/quality/__init__.py create mode 100644 src/inferencekit/quality/client.py create mode 100644 src/inferencekit/quality/data/gsm8k_LICENSE.txt create mode 100644 src/inferencekit/quality/fake.py create mode 100644 src/inferencekit/quality/gsm8k.py create mode 100644 src/inferencekit/quality/logprobs.py create mode 100644 src/inferencekit/quality/metrics.py create mode 100644 src/inferencekit/quality/niah.py create mode 100644 src/inferencekit/quality/parquet.py create mode 100644 src/inferencekit/quality/sampling.py create mode 100644 src/inferencekit/quality/step_replay.py create mode 100644 src/inferencekit/quality/video_metrics.py create mode 100644 src/inferencekit/registry.py create mode 100644 src/inferencekit/review/__init__.py create mode 100644 src/inferencekit/review/diff.py create mode 100644 src/inferencekit/review/media.py create mode 100644 src/inferencekit/review/page.py create mode 100644 src/inferencekit/review/rundir.py create mode 100644 src/inferencekit/roofline_headers.py create mode 100644 src/inferencekit/serve/__init__.py create mode 100644 src/inferencekit/serve/audio_client.py create mode 100644 src/inferencekit/serve/client.py create mode 100644 src/inferencekit/serve/clip_client.py create mode 100644 src/inferencekit/serve/clip_rounds.py create mode 100644 src/inferencekit/serve/image_client.py create mode 100644 src/inferencekit/serve/loadgen.py create mode 100644 src/inferencekit/serve/metrics.py create mode 100644 src/inferencekit/serve/profiles.py create mode 100644 src/inferencekit/serve/prompts_io.py create mode 100644 src/inferencekit/serve/rounds.py create mode 100644 src/inferencekit/serve/servers.py create mode 100644 src/inferencekit/stats.py create mode 100644 tests/cheats/__init__.py create mode 100644 tests/cheats/fake_engine.py create mode 100644 tests/conftest.py create mode 100644 tests/fakes/__init__.py create mode 100644 tests/fakes/e2e_engine.py create mode 100644 tests/fakes/fake_openai_server.py create mode 100644 tests/fakes_clip/__init__.py create mode 100644 tests/fakes_clip/fake_comfyui.py create mode 100644 tests/fakes_clip/fake_pipelines.py create mode 100644 tests/fakes_clip/fake_steps.py create mode 100644 tests/fakes_ikstep/fake_inferencekit.py create mode 100644 tests/fakes_rounds/fake_server.py create mode 100644 tests/fakes_rounds/logs/generic.log create mode 100644 tests/fakes_rounds/logs/llamacpp.log create mode 100644 tests/fakes_rounds/logs/llamacpp_cpu.log create mode 100644 tests/fakes_rounds/logs/sglang.log create mode 100644 tests/fakes_rounds/logs/sglang_old.log create mode 100644 tests/fakes_rounds/logs/trtllm.log create mode 100644 tests/fakes_rounds/logs/vllm.log create mode 100644 tests/fakes_rounds/stub_bench_serve.py create mode 100644 tests/fakes_skeleton/__init__.py create mode 100644 tests/fakes_skeleton/engines.py create mode 100644 tests/fixtures/ikstep/gates-baseline-void.json create mode 100644 tests/fixtures/ikstep/gates.json create mode 100644 tests/fixtures/ikstep/gsm8k-baseline.json create mode 100644 tests/fixtures/ikstep/gsm8k.json create mode 100644 tests/fixtures/ikstep/manifest.json create mode 100644 tests/fixtures/ikstep/metrics.json create mode 100644 tests/fixtures/ikstep/rounds-failed.json create mode 100644 tests/fixtures/ikstep/rounds.json create mode 100644 tests/fixtures/ikstep/sampling-baseline.json create mode 100644 tests/fixtures/ikstep/sampling.json create mode 100644 tests/fixtures/ikstep/score-file.json create mode 100644 tests/fixtures/ikstep/score.json create mode 100644 tests/fixtures/ikstep/serve.json create mode 100644 tests/fixtures/ikstep/trajectory.json create mode 100644 tests/fixtures/intake/llm-qwen-5090.yaml create mode 100644 tests/fixtures/parquet/gsm8k_tiny.parquet create mode 100644 tests/fixtures/parquet/nulls_gzip_plain_v2.parquet create mode 100644 tests/fixtures/parquet/required_uncompressed.parquet create mode 100644 tests/test_audio_client.py create mode 100644 tests/test_bench.py create mode 100644 tests/test_bench_audio.py create mode 100644 tests/test_bench_clip.py create mode 100644 tests/test_bench_image.py create mode 100644 tests/test_bench_rounds.py create mode 100644 tests/test_bench_serve.py create mode 100644 tests/test_bench_serve_evidence.py create mode 100644 tests/test_bench_serve_load.py create mode 100644 tests/test_byte_floor.py create mode 100644 tests/test_chat_template_kwargs.py create mode 100644 tests/test_cli_terse.py create mode 100644 tests/test_clip_adapters.py create mode 100644 tests/test_compare.py create mode 100644 tests/test_compare_media.py create mode 100644 tests/test_compare_serve.py create mode 100644 tests/test_correctness.py create mode 100644 tests/test_deadline_hook.py create mode 100644 tests/test_doctor_counters.py create mode 100644 tests/test_e2e_fake.py create mode 100644 tests/test_engine_skeleton_core.py create mode 100644 tests/test_engine_skeleton_serve.py create mode 100644 tests/test_evidence.py create mode 100644 tests/test_gates.py create mode 100644 tests/test_gates_clip.py create mode 100644 tests/test_gguf_bytes_script.py create mode 100644 tests/test_hardware.py create mode 100644 tests/test_ikstep.py create mode 100644 tests/test_ikstep_jobs.py create mode 100644 tests/test_image_client.py create mode 100644 tests/test_image_tradeoff.py create mode 100644 tests/test_intake.py create mode 100644 tests/test_interfaces.py create mode 100644 tests/test_kernel_recipes.py create mode 100644 tests/test_ledger.py create mode 100644 tests/test_manifest.py create mode 100644 tests/test_ncu_summarize.py create mode 100644 tests/test_nsys_analyze.py create mode 100644 tests/test_opencode.py create mode 100644 tests/test_packaging.py create mode 100644 tests/test_plain_english.py create mode 100644 tests/test_proc.py create mode 100644 tests/test_prompts.py create mode 100644 tests/test_prompts_gzip.py create mode 100644 tests/test_quality.py create mode 100644 tests/test_quality_clip.py create mode 100644 tests/test_quality_clip_steps.py create mode 100644 tests/test_quality_gsm8k_data.py create mode 100644 tests/test_quality_sampling.py create mode 100644 tests/test_quality_stats.py create mode 100644 tests/test_review.py create mode 100644 tests/test_review_media.py create mode 100644 tests/test_review_video.py create mode 100644 tests/test_rocprof.py create mode 100644 tests/test_roofline.py create mode 100644 tests/test_roofline_headers.py create mode 100644 tests/test_skeleton_gemma4.py create mode 100644 tests/test_skeleton_qwen35.py create mode 100644 tests/test_skill_flow.py create mode 100644 tests/test_skills.py create mode 100644 tests/test_stats.py create mode 100644 uv.lock diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..f6bebf0 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,44 @@ +{ + "name": "inferencekit", + "owner": { + "name": "Stellon Labs" + }, + "metadata": { + "description": "Make your model serve faster on your GPU, and prove it. Skills for Claude Code, Codex and OpenCode, plus a CLI and MCP server: your agent picks and tunes inference engines, can write GPU kernels, and backs every number with client-timed benchmarks, anti-cheat gates and quality checks.", + "version": "0.1.0" + }, + "plugins": [ + { + "name": "inferencekit", + "source": "./plugin", + "description": "Make your model serve faster on your GPU, and prove it. Skills for Claude Code, Codex and OpenCode, plus a CLI and MCP server: your agent picks and tunes inference engines, can write GPU kernels, and backs every number with client-timed benchmarks, anti-cheat gates and quality checks.", + "version": "0.1.0", + "author": { + "name": "Stellon Labs" + }, + "license": "Apache-2.0", + "category": "development", + "tags": [ + "inference", + "llm", + "serving", + "benchmarking", + "capacity", + "profiling", + "quantization", + "roofline", + "gpu", + "nvidia", + "cuda", + "mcp", + "nsight-systems", + "nsight-compute", + "correctness", + "vllm", + "sglang", + "llama.cpp", + "tensorrt-llm" + ] + } + ] +} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..4a8bd53 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,120 @@ +name: ci + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + +jobs: + test: + name: tests (Python ${{ matrix.python }}) + runs-on: ubuntu-24.04 + timeout-minutes: 20 + strategy: + fail-fast: false + matrix: + python: ["3.10", "3.12"] + steps: + - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false + - uses: astral-sh/setup-uv@v10.2.0 + with: + version: "0.12.7" + python-version: ${{ matrix.python }} + enable-cache: true + - name: Versions agree (pyproject, __version__, plugin, marketplace, MCP pin) + run: uv run --no-project python scripts/release/check_versions.py + - name: Install (uv.lock must be current) + run: uv sync --locked --all-extras + - name: Tests + run: uv run --locked --all-extras pytest -q -rs + + plugin: + name: Claude Code plugin manifests + runs-on: ubuntu-24.04 + timeout-minutes: 10 + steps: + - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false + - uses: actions/setup-node@v7.0.0 + with: + node-version: "22" + - name: Validate the plugin + run: npx -y @anthropic-ai/claude-code@2.1.296 plugin validate ./plugin + - name: Validate the marketplace + run: npx -y @anthropic-ai/claude-code@2.1.296 plugin validate . + + codex: + # Codex reads the Claude-compatible marketplace (.claude-plugin/marketplace.json) and plugin + # manifests. Advisory: a Codex CLI change must not block a merge, but it should be visible. + name: Codex plugin install (advisory) + runs-on: ubuntu-24.04 + timeout-minutes: 10 + continue-on-error: true + steps: + - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false + - uses: actions/setup-node@v7.0.0 + with: + node-version: "22" + - name: Use a throwaway Codex home + run: | + mkdir -p "$RUNNER_TEMP/codex-home" + echo "CODEX_HOME=$RUNNER_TEMP/codex-home" >> "$GITHUB_ENV" + - name: Add the marketplace and install the plugin + run: | + npx -y @openai/codex@0.162.1 plugin marketplace add "$GITHUB_WORKSPACE" + npx -y @openai/codex@0.162.1 plugin add inferencekit@inferencekit + npx -y @openai/codex@0.162.1 plugin list | tee plugins.txt + grep -E '^inferencekit@inferencekit +installed, enabled' plugins.txt + - name: The plugin's MCP server is registered with the pinned launcher + run: | + npx -y @openai/codex@0.162.1 mcp list | tee mcp.txt + version="$(python3 -c 'import json; print(json.load(open("plugin/.claude-plugin/plugin.json"))["version"])')" + grep -F "inferencekit-cli[mcp]==$version inferencekit mcp serve" mcp.txt + + opencode: + # OpenCode has no marketplace for plugins: plugin/opencode/install.py wires the skills, commands, subagents and + # MCP server into its config. Advisory, like the Codex job: an OpenCode change must not block a merge. + name: OpenCode install (advisory) + runs-on: ubuntu-24.04 + timeout-minutes: 10 + continue-on-error: true + steps: + - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false + - uses: actions/setup-node@v7.0.0 + with: + node-version: "22" + - name: Install into a throwaway config home + run: | + echo "XDG_CONFIG_HOME=$RUNNER_TEMP/opencode-config" >> "$GITHUB_ENV" + XDG_CONFIG_HOME="$RUNNER_TEMP/opencode-config" python3 plugin/opencode/install.py + - name: OpenCode loads the skills, commands, subagents and MCP entry + run: | + npx -y opencode-ai@1.19.0 debug skill > skills.json + npx -y opencode-ai@1.19.0 debug config > config.json + python3 - <<'PY' + import json + skills = {s["name"] for s in json.load(open("skills.json"))} + cfg = json.load(open("config.json")) + version = json.load(open("plugin/.claude-plugin/plugin.json"))["version"] + assert {"inference-triage", "optimizing-inference", "benchmarking", "profiling", "optimizing-kernels", + "proving-correctness", "evaluating-quantization", "reporting-perf-claims"} <= skills, skills + assert {"optimize-inference", "bench", "profile", "perf-report"} <= set(cfg.get("command", {})) + assert {"engine-scout", "quant-scout", "profile-analyst", "claims-skeptic"} <= set(cfg.get("agent", {})) + assert cfg["mcp"]["inferencekit"]["command"][:3] == ["uvx", "--from", f"inferencekit-cli[mcp]=={version}"] + print("OpenCode sees", sorted(skills)) + PY diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b2cdc65 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +.venv/ +__pycache__/ +*.pyc +runs/ +*.nsys-rep +*.ncu-rep +*.sqlite diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d67b4dc --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,73 @@ +# AGENTS.md: always-on rules for inference performance work + +These rules apply to any agent doing inference performance work with this repository or the inferencekit tools, including agents that read only this file. Procedures live in `plugin/skills//SKILL.md`; each rule's reason is in `plugin/skills/inference-triage/references/evidence-rules.md` (same numbers). + +## Tools + +- CLI `inferencekit `; MCP server `inferencekit mcp serve` (stdio; every command is also a tool with the same arguments; launcher `uvx --from 'inferencekit-cli[mcp]==0.1.0' inferencekit mcp serve`). Commands and flags: `inferencekit --help` and `inferencekit --help`. +- Measure: `doctor`, `ceiling bw`, `roofline`, `bench rounds` (runs `bench serve` per engine per round, fresh process, balanced order: published numbers), `bench serve` (one client-timed call), `bench decode` (engine-timed; engines without a server), `bench image`, `bench audio` (client-timed media screening; contracts in `docs/media-benchmarks.md`), `compare` (matching benchmark kinds; load records are refused). +- Check: `gates run`, `prompts verify|show`, `quality trajectory|score|gsm8k|sampling`, `correctness`. +- Diagnose: `nsys capture|analyze`, `ncu capture|summarize`. +- Record and report: `intake template|validate`, `manifest validate`, `evidence list|show`, `ledger trailers`, `history`, `review build`, `report`. +- Evidence lands in `runs/`; `runs/`, `*.nsys-rep`, `*.ncu-rep` and `*.sqlite` are git-ignored. Never commit them. +- Hardware routing starts with `doctor`: NVIDIA uses Nsight Systems then Nsight Compute; AMD ROCm uses rocprofv3 with architecture-specific counter support; Apple Silicon uses Instruments, Metal/Xcode and MLX captures. `doctor` reads AMD DRM sysfs and Apple system facts; unknown details stay unknown. `ceiling bw` and nsys/ncu capture remain NVIDIA-only. Retrieve current official docs when architecture, runtime, flags or profiler support is uncertain; see `plugin/skills/inference-triage/references/hardware.md`. +- Subagents (`plugin/agents/`): `engine-scout` (one engine's support, sourced), `quant-scout` (one model's quantized checkpoints, bytes per token and fit from headers), `profile-analyst` (one profile's bottleneck), `claims-skeptic` (refutes a report's claims), `log-reader` (one question about a big log or doc, answered in at most 40 lines). They do GPU-free work only; any agent can follow the files as checklists. + +## Which skill + +| Need | Skill | +|---|---| +| Make a model fast end to end; which engine; hit a target | `optimizing-inference` | +| Find current optimizations and turn sources into experiments | `researching-optimizations` | +| Not sure where to start | `inference-triage` | +| tok/s, TTFT, capacity `N*`, ceilings, engine vs engine, before vs after | `benchmarking` | +| Where the time goes; why one kernel is slow | `profiling` | +| Custom engine, compiler inspection or kernel work for the task | `optimizing-kernels` | +| Is it still the same model; did quality regress | `proving-correctness` | +| Fit consumer memory while meeting latency and quality; minimize memory | `optimizing-inference` (affordability reference) | +| Should I quantize; which quant; will it fit; a big model on a small GPU | `evaluating-quantization` | +| Writing up or auditing a claim | `reporting-perf-claims` | + +## Evidence rules (numbers are stable: skills and evals cite them) + +1. Label every number **observed** (cite the evidence id), **derived** (show the formula) or **inferred** (name the measurement that would confirm it). +2. Claim verdicts are **PASS / FAIL / UNPROVEN / NOT RUN**. +3. Missing data is UNPROVEN (attempted, insufficient) or NOT RUN (never attempted); never zero, blank or PASS. +4. Combine checks with the precedence FAIL > UNPROVEN > PASS: any FAIL fails the whole; else any UNPROVEN makes it UNPROVEN. A check that does not apply is NOT RUN and is skipped; one that applies but ended NOT RUN counts as UNPROVEN; if nothing ran, the whole is NOT RUN. +5. Write the claim (metric, threshold, workload, bucket, decision rule) before measuring. +6. A speedup needs interleaved rounds and a paired ratio CI95 that excludes 1 (`bench rounds` `_ratio_to_best` for served engines, `compare` for `bench decode`); quote the conservative bound. +7. Comparison verdicts `improved | regressed | within_noise | inconclusive` come only from the tools: `bench rounds`' paired ratio CI for served engines, or `inferencekit compare` for two records of the same kind and workload (`bench decode`, single-user `bench serve`, `bench clip`, `bench image` or `bench audio`). Media timing alone leaves quality and lifecycle proof UNPROVEN. +8. Never compare speed across precisions (weights, activations, KV cache, lm_head). A format trade-off (`evaluating-quantization`) reports speed only paired with quality, labelled cross-precision. A numerics change the task explicitly allows is ranked, declared and labelled "numerics changed". +9. Compare against each baseline's best documented configuration for the goal measured, at a pinned version. +10. Quote the settings actually in effect (the engine's resolved config and logs), not the intended config; prove each knob took effect. +11. Report decode against a measured ceiling, not the datasheet: `inferencekit ceiling bw` on NVIDIA; on other hardware, a vendor or STREAM-style read-bandwidth measurement saved with the run (`plugin/skills/inference-triage/references/hardware.md`). +12. Profiles rank where time went; they never prove a speedup. Nsight Compute durations are never end-to-end evidence. +13. Every published claim and the final result needs a correctness or quality proof, an interleaved A/B with a CI and, for each claimed change, a profile showing the mechanism; the final candidate and any commit you hand over need the full proof, once (`bench rounds`, all gates, quality, all of GSM8K for LLMs, `quality sampling` when token sampling is timed; image and speech need their pre-registered modality checks, never LLM proxy gates). Inside the change loop each candidate gets one fast correctness check (greedy token identity, or logprob agreement for a numerics change, vs the previous build) and a screen; the first candidate that screens at >= 1.2x and the first at >= 1.5x of the baseline (or the task's target) get a light check (`plugin/skills/optimizing-inference/references/state.md`, "Best so far"). Between milestones a best is screened, not verified. +14. Bitwise identity is expected only for pure refactors within one engine; otherwise judge quality against the A/A noise floor, with margins at divergence. +15. Compute the Amdahl bound before optimising a kernel. Size it with critical-path time per step (`critical_pct_of_step`), not summed kernel durations; `kernel_sum_us / span_us > 1` means kernels overlap. +16. Publish losses, refuted ideas and NOT RUN items with the wins. +17. Never extrapolate to GPUs, precisions, contexts, buckets or concurrency levels you did not measure. +18. Published LLM numbers come only from `inferencekit bench serve` (client-side timer); label every `bench decode` number "engine-timed". Images and speech require a pre-registered client-timed modality adapter including final image decoding or first playable audio. A token endpoint is not proof of image latency or speech TTFA. +19. Each round starts every engine as a fresh process, in a balanced order (`inferencekit bench rounds`); R is pre-registered (default: the smallest multiple of the Williams period that is at least 3, i.e. 4 for 2 engines, 6 for 3, 4 for 4; the period is the shortest run of rounds in which each engine follows every other one equally often; never below 3), or an adaptive plan is (`bench rounds --ci-target`, `--min-rounds`, a maximum `--rounds`; it stops at whole Williams periods); CIs are bootstrapped over rounds; warmups never count. +20. Run `inferencekit gates run --base-url --engine