Skip to content

one-surface(parakeet): fold Parakeet ASR onto the C ABI (ROW 1) - #121

Closed
localai-bot wants to merge 1 commit into
mainfrom
row/PARAKEET-ONE-SURFACE
Closed

one-surface(parakeet): fold Parakeet ASR onto the C ABI (ROW 1)#121
localai-bot wants to merge 1 commit into
mainfrom
row/PARAKEET-ONE-SURFACE

Conversation

@localai-bot

@localai-bot localai-bot commented Aug 7, 2026

Copy link
Copy Markdown
Collaborator

ROW 1 of the ARCH-ONE-SURFACE fold plan (fold #4, audio transcription): grow the ABI -> rewrite the example -> delete the parallel implementation. This PR is the helper claim (operator-helper protocol); head is ONE records-coupled commit for the squash-merge flow.

What landed (order was binding)

  • Correctness anchor FIRST: deterministic tiny CTC+RNNT checkpoints + clip committed (tests/vllm/models/fixtures/parakeet_e2e, generator in scripts/mm/), transcript goldens captured from the PRE-refactor binary at main@f98e1e48 before any change. The fold gate (test_parakeet_transcription_fold) holds library seam == replicated old pipeline == committed goldens, per head.
  • W1 tokenizer + library: vllm::Tokenizer implements Metaspace split:true (encode pre-split, MergedWithNext) and the bare Metaspace DECODER (HF decode_chain; the pre-refactor DecodeIds semantics) instead of refusing; Mistral/Gemma Sequence chain regression-pinned; metaspace.rs cases ported. vllm::multimodal::ParakeetTranscriber absorbs WAV ingest (DecodeWavPcm16Mono), head dispatch and id->text; the example's private ReadWav16BitMono/LoadVocab/DecodeIds are deleted.
  • W2 registry: ParakeetForCTC/ForRNNT/ForTDT registered with the SupportsTranscription mirror on ModelInfo (interfaces.py:1110-1118) - BEYOND-PIN breadth, recorded (pinned vLLM has Parakeet only as the NemotronH audio component). Refuse-by-task everywhere: VT_CHECK(false) refuse-stub forward (runner-routing REFUSE contract), loader refusal via new non-throwing PeekHfArchitectures BEFORE the text HfConfig parse. Registry pins 30 -> 33.
  • W3 C ABI: vllm_transcribe + params/result structs, ABI v10 -> 11; vllm_engine_load task-dispatches; text and ASR handles refuse each other actionably. First REAL-checkpoint load gated through the public ABI (closes the audit's severity note). FEATURES abi-capability row -> reachable; scripts/abi-capability-allowlist.txt shrinks.
  • W4 server: task-conditional /v1/audio/transcriptions (multipart file, response_format json/text) through the SAME seam; serving-less ApiServer ctor mirrors vLLM's supported_tasks-conditional registration (generate routes 404 on an ASR server); verified live with curl.
  • W5 example: examples/parakeet_transcribe is a THIN vllm.h client (vllm::shared); stdout byte-identical to the pre-fold binary on both fixtures; scripts/example-abi-allowlist.txt shrinks and MAX_INTERNAL_REACHING ratchets 12 -> 11 (equality pin + spec claims moved in the same change).

Gates

  • Full CPU build clean (-Werror, 0 warnings); ctest 349/349.
  • scripts/agent-preflight.sh EXIT=0 ("All gates green"), including the surface guard now enforcing THIS shrink; all record checkers green unpiped.
  • Every new test mutation-verified red/green (tokenizer decode rule + split gate, CTC collapse, transcription-only flag, ABI dispatch + input validation, server response_format + route gate).

Residuals (recorded in state.md)

run_batch transcription line; verbose_json/srt/vtt response formats (400 naming the residual); no pretrained checkpoint re-downloaded (safe defaults - fold rests on the committed synthetic pair + P4/P6 pretrained evidence); Whisper/Voxtral remain off-registry (fold #9/#10).

🤖 Generated with Claude Code

https://claude.ai/code/session_014fZAcg1WcU8V629k6HWKys

mudler added a commit that referenced this pull request Aug 7, 2026
ARCH-ONE-SURFACE ROW 1 on row/PARAKEET-ONE-SURFACE: grow the ABI, rewrite the
example, delete the parallel implementation - audio transcription becomes the
first remediated lane of the ONE SURFACE program, gated BYTE-IDENTICAL to the
pre-fold example.

Correctness anchor FIRST: deterministic tiny CTC+RNNT fixtures + clip
(tests/vllm/models/fixtures/parakeet_e2e, scripts/mm/parakeet_e2e_fixture_gen
.py) with transcript goldens captured from the PRE-refactor binary at
main@f98e1e48 before any change; the fold gate
(tests/vllm/models/test_parakeet_transcription_fold.cpp) holds library seam ==
replicated old pipeline == committed goldens for both heads.

W1a tokenizer: Metaspace split=true implemented instead of refused
(MergedWithNext pre-split; a bare Metaspace DECODER node selects HF's
decode_chain rule - the pre-refactor DecodeIds semantics); Mistral/Gemma
Sequence chain regression-pinned; metaspace.rs cases ported
(tests/vllm/test_tokenizer_metaspace_split.cpp).

W1b/c library: vllm::multimodal::ParakeetTranscriber absorbs WAV ingest
(DecodeWavPcm16Mono), the model_type head dispatch and tokenizer decode; the
example's private ReadWav16BitMono/LoadVocab/DecodeIds are deleted.

W2 registry: ParakeetForCTC/ForRNNT/ForTDT registered with the
SupportsTranscription mirror on ModelInfo (interfaces.py:1110-1118); BEYOND-PIN
breadth recorded (pinned vLLM: Parakeet = NemotronH audio component,
registry.py:511-513). Refuse-by-task everywhere: the forward is a
VT_CHECK(false) refuse stub (runner-routing REFUSE contract), the loader
refuses via the new non-throwing PeekHfArchitectures BEFORE the text HfConfig
parse, and registry count pins move 30 -> 33.

W3 C ABI: vllm_transcribe + vllm_transcription_params(_default) +
vllm_transcription(_free), ABI v10 -> 11; vllm_engine_load task-dispatches a
transcription-only dir onto the same seam; text entrypoints and
vllm_transcribe refuse each other's handles actionably. First real-checkpoint
load gated through the public ABI (test_capi v11 cases). FEATURES
abi-capability row flips to reachable; abi-capability-allowlist SHRINKS.

W4 server: task-conditional /v1/audio/transcriptions (multipart file,
response_format json/text; verbose_json/srt/vtt named residuals) through the
SAME seam; serving-less ApiServer construction = vLLM's supported_tasks-
conditional registration (generate routes 404 on an ASR server);
examples/server dispatches by resolved arch; verified live with curl.
run_batch transcription line stays a named residual.

W5 example: examples/parakeet_transcribe is a THIN vllm.h client
(vllm::shared), stdout byte-identical to the pre-fold binary on both
fixtures; example-abi-allowlist SHRINKS and MAX_INTERNAL_REACHING ratchets
12 -> 11 with the equality pin + spec claims moved in the same change.

Gates: full CPU build clean (-Werror, 0 warnings); ctest 349/349; surface
guard + mutation suites green enforcing the shrink; every new test
mutation-verified (tokenizer decode rule + split gate, CTC collapse,
transcription-only flag, ABI dispatch + input validation, server
response_format + route gate). Records: STATUS/BENCHMARKS/FEATURES keyed
rows, model-matrix rows, state.md entry + NOW refresh, both ONE-SURFACE
specs mark ROW 1 landed.

FOLLOWING_AGENTS_PROTOCOL
Assisted-by: Claude Code:claude-fable-5 [ClaudeCode]
@mudler
mudler force-pushed the row/PARAKEET-ONE-SURFACE branch from a26a225 to 162a21e Compare August 7, 2026 20:06
ARCH-ONE-SURFACE ROW 1 on row/PARAKEET-ONE-SURFACE: grow the ABI, rewrite the
example, delete the parallel implementation - audio transcription becomes the
first remediated lane of the ONE SURFACE program, gated BYTE-IDENTICAL to the
pre-fold example.

Correctness anchor FIRST: deterministic tiny CTC+RNNT fixtures + clip
(tests/vllm/models/fixtures/parakeet_e2e, scripts/mm/parakeet_e2e_fixture_gen
.py) with transcript goldens captured from the PRE-refactor binary at
main@f98e1e48 before any change; the fold gate
(tests/vllm/models/test_parakeet_transcription_fold.cpp) holds library seam ==
replicated old pipeline == committed goldens for both heads.

W1a tokenizer: Metaspace split=true implemented instead of refused
(MergedWithNext pre-split; a bare Metaspace DECODER node selects HF's
decode_chain rule - the pre-refactor DecodeIds semantics); Mistral/Gemma
Sequence chain regression-pinned; metaspace.rs cases ported
(tests/vllm/test_tokenizer_metaspace_split.cpp).

W1b/c library: vllm::multimodal::ParakeetTranscriber absorbs WAV ingest
(DecodeWavPcm16Mono), the model_type head dispatch and tokenizer decode; the
example's private ReadWav16BitMono/LoadVocab/DecodeIds are deleted.

W2 registry: ParakeetForCTC/ForRNNT/ForTDT registered with the
SupportsTranscription mirror on ModelInfo (interfaces.py:1110-1118); BEYOND-PIN
breadth recorded (pinned vLLM: Parakeet = NemotronH audio component,
registry.py:511-513). Refuse-by-task everywhere: the forward is a
VT_CHECK(false) refuse stub (runner-routing REFUSE contract), the loader
refuses via the new non-throwing PeekHfArchitectures BEFORE the text HfConfig
parse, and registry count pins move 30 -> 33.

W3 C ABI: vllm_transcribe + vllm_transcription_params(_default) +
vllm_transcription(_free), ABI v10 -> 11; vllm_engine_load task-dispatches a
transcription-only dir onto the same seam; text entrypoints and
vllm_transcribe refuse each other's handles actionably. First real-checkpoint
load gated through the public ABI (test_capi v11 cases). FEATURES
abi-capability row flips to reachable; abi-capability-allowlist SHRINKS.

W4 server: task-conditional /v1/audio/transcriptions (multipart file,
response_format json/text; verbose_json/srt/vtt named residuals) through the
SAME seam; serving-less ApiServer construction = vLLM's supported_tasks-
conditional registration (generate routes 404 on an ASR server);
examples/server dispatches by resolved arch; verified live with curl.
run_batch transcription line stays a named residual.

W5 example: examples/parakeet_transcribe is a THIN vllm.h client
(vllm::shared), stdout byte-identical to the pre-fold binary on both
fixtures; example-abi-allowlist SHRINKS and MAX_INTERNAL_REACHING ratchets
12 -> 11 with the equality pin + spec claims moved in the same change.

Gates: full CPU build clean (-Werror, 0 warnings); ctest 349/349; surface
guard + mutation suites green enforcing the shrink; every new test
mutation-verified (tokenizer decode rule + split gate, CTC collapse,
transcription-only flag, ABI dispatch + input validation, server
response_format + route gate). Records: STATUS/BENCHMARKS/FEATURES keyed
rows, model-matrix rows, state.md entry + NOW refresh, both ONE-SURFACE
specs mark ROW 1 landed.

FOLLOWING_AGENTS_PROTOCOL
Assisted-by: Claude Code:claude-fable-5 [ClaudeCode]
@mudler
mudler force-pushed the row/PARAKEET-ONE-SURFACE branch from 162a21e to 5984be3 Compare August 7, 2026 20:33
@localai-bot

Copy link
Copy Markdown
Collaborator Author

Landed on main as fc636c7 (mudler-authored squash via commit-tree). Two-round review per protocol (round-1 found 2 test gaps, kill-confirmed fixed, scoped re-review MERGE-CLEAN). Operator-run gates on the merged tree pre-push: keyed-record auto-merge verified byte-identical to the deterministic rebuild (main wholesale + branch delta, all 5 files); fold/metaspace/capi/api_server suites 4/4 SUCCESS on a fresh build; eleven record/doc/guard gates unpiped 00000000000. The C ABI is now v11 with vllm_transcribe — the first non-text capability on the one surface; registry 33 archs; guard ratchet 12→11. Fold ROW 2 (MiniMax-H3 video ABI slice) dispatches next.

mudler added a commit that referenced this pull request Aug 7, 2026
…I v11, /v1/audio/transcriptions, thin-client example (#121)

ONE-SURFACE fold ROW 1. The library absorbs everything the example
privately owned: Metaspace split:true decode lands in vllm::Tokenizer
(replacing the FromHfJson refusal), WAV ingest reuses the existing
DecodeWavPcm16Mono, and a ParakeetTranscriber seam composes processor
-> conformer encoder -> CTC/RNNT/TDT head -> tokenizer decode. Three
Parakeet head archs register via REGISTER_VLLM_MODEL (registry 30->33)
with transcription-only task refusal both directions. include/vllm.h
gains vllm_transcribe + params/default/free idiom, VLLM_ABI_VERSION
10->11 (floor-pinned >= 11 in test_capi). The server routes
/v1/audio/transcriptions through the same seam, gated on a transcriber
engine (socket-level 404 pin on text servers, /v1/videos-precedent
style). examples/parakeet_transcribe is rewritten as a vllm.h-only
thin client - stdout byte-identical to the pre-fold binary - and the
surface guard ratchet shrinks 12->11 with its equality pin.

Correctness: three-arm fold gate (library seam == replicated old
pipeline == committed goldens captured at f98e1e4 pre-refactor) on
synthetic CTC+RNNT fixtures; Mistral/DeepSeek real-checkpoint
tokenizer parity unchanged. Two-round review per protocol: round-1
mutation review found 2 test gaps (route gate on text servers
untested; ABI floor unpinned), fixed and kill-confirmed by a scoped
re-review, MERGE-CLEAN. Operator re-ran the fold/tokenizer/capi/server
suites on this merged tree: 4/4 SUCCESS.

FOLLOWING_AGENTS_PROTOCOL
Assisted-by: Claude Code:claude-fable-5 [ClaudeCode]
@localai-bot localai-bot closed this Aug 7, 2026
mudler added a commit that referenced this pull request Aug 7, 2026
…binary at branch base

The three-arm fold gate's arm C, captured BEFORE any refactor (the #121
discipline): minimax_h3_video_fold_fixture.h writes a deterministic tiny
checkpoint set (857KB F32 ComfyUI-GGUF DiT at the :3786 reduced geometry, the
reduced ViT3D video VAE + BigVGAN audio VAE as on-disk safetensors+config.json,
prompt embeds), and the committed goldens are what the PRE-fold
minimax-h3-gen binary at this branch base rendered on it:

  minimax-h3-gen --dit dit.gguf --keep-quant --video-vae ... --audio-vae ...
    --prompt-embeds prompt_embeds.f32 --partition fl2va --steps 3 --frames 5
    --height 32 --width 32 --device cpu --ffmpeg /bin/true

8 PPM frames (32x32) + audio.wav (stereo, 32000 Hz), byte-stable across two
runs (diff -r clean), plus the pre-fold minimax-h3-mux --print-only argv for
both the audio and silent forms. The fold gate to come holds the library seam,
the replicated old pipeline, and the rewritten thin clients to these bytes.

Also captured (for the refuse-both-directions pin): vllm_engine_load on this
H3 fixture dir today returns status 2 with 'hf_config: cannot open
.../config.json'.

FOLLOWING_AGENTS_PROTOCOL
Assisted-by: Claude Code:claude-fable-5 [ClaudeCode]
mudler added a commit that referenced this pull request Aug 7, 2026
…le, allowlist 11->10

ROW 7 ONE-SURFACE B4 (§20.3, task #281), rebased on #121 (Parakeet took v11).

- include/vllm.h + src/capi/vllm_c.cpp: vllm_complete_tokens (ABI v12) —
  blocking completion from a PRE-TOKENIZED prompt (vLLM TokensPrompt, the
  AsyncLLM token-id add_request overload), returning the generated token ids
  and optionally the detokenized vllm_completion. Purely additive; capi gate
  test_capi 35/35·290 with null-contract + truncation + string-leg-identity
  cases (mutation-verified).
- examples/kimi_linear_gen: REWRITTEN as a thin public-ABI client (vllm.h +
  vllm::shared only) — vllm_engine_load + vllm_complete_tokens over the §12
  golden's pre-tokenized prompts, two-length-diff steady-rate report. The
  private harness (internal bf16-resident loader + KimiDecodeCache incremental
  drive) is deleted from examples; the CLI-incremental REFERENCE leg moves to
  the env-gated tests/vllm/models/test_kimi_linear_fold_gate.cpp
  (VT_KIMI_MODEL_DIR/VT_KIMI_GOLDEN_DIR; skips in the CPU suite), where
  internal headers are legitimate.
- scripts/example-abi-allowlist.txt: kimi_linear_gen row REMOVED;
  MAX_INTERNAL_REACHING 11->10; equality pin + spec claims moved in the same
  change (test_check_surface_coverage 46 passed; surface-coverage OK: 10
  internal-reachers, kimi is the third clean ABI client).
- docs/FEATURES.md capability table: Pre-tokenized completion row (reachable).

FOLLOWING_AGENTS_PROTOCOL
Assisted-by: Claude Code:claude-fable-5 [ClaudeCode]
mudler added a commit that referenced this pull request Aug 7, 2026
…-> 12

ARCH-ONE-SURFACE ROW 2, the C surface over the W1 seam — the ratified shapes
(.agents/specs/one-surface-abi.md:92-108) as shipped: vllm_video_engine (an
opaque handle SEPARATE from vllm_engine, because H3 loads a checkpoint SET,
not a config.json directory), vllm_video_model_params/_default,
vllm_video_params/_default, vllm_video_result, vllm_video_engine_load/free,
vllm_video_generate, vllm_video_result_free — plus the engine-free
vllm_video_mux_argv(+_params_default,+_free) composer the minimax-h3-mux
thin client needs (a disclosed append beyond the ratified proposal; the
encoding contract stays the library's, the caller execs). Deviations from
the proposal, each argued in the spec: + prompt_embeds_path (without an
encoder there is NO conditioning path), + partition (the #77 guard refuses
every render without it), + fp4_resident and + output_dir; - task/duration
(derivable / expressible via num_frames); ref_image stays the ratified
SINGLE image (multi-image ref2va remains C++-seam-reachable, named residual).
mux_argv is NULL-terminated (execvp-ready). Zero values preserve behaviour
(noise_aug <= 0 resolves to the 1.0 pin engine-side).

Refuse-both-directions: the seam now refuses a config.json-style directory
LOUDLY naming vllm_engine_load; vllm_engine_load on the H3 fixture dir keeps
failing byte-for-byte as captured at v11 (status 2, missing config.json).

Gates: vllm_capi_c_check (strict-C11 compile) green; test_capi 40/40 (373
assertions) including the v12 section — the FULL golden e2e through the C
marshalling (frames+WAV byte-identical to the pre-fold binary's committed
goldens, mux argv pinned), the zero-value contract, both refusal directions,
and the argument contract; ABI floor pin advanced >= 11 -> >= 12 (the #121
lesson — the == checks move with the macro).

FOLLOWING_AGENTS_PROTOCOL
Assisted-by: Claude Code:claude-fable-5 [ClaudeCode]
mudler added a commit that referenced this pull request Aug 7, 2026
…— vllm_video_*, ABI v12, /v1/videos via the library seam, thin-client examples

ONE-SURFACE fold ROW 2 (row/H3-VIDEO-ABI, task #283; the #121 precedent's
shape: three-arm fold gate, guard-ratchet shrink). The library absorbs
everything the examples privately owned.

GOLDENS FIRST: minimax_h3_video_fold_fixture.h writes a deterministic tiny
checkpoint set (857KB F32 ComfyUI-GGUF DiT at the test_minimax_h3.cpp:3786
reduced geometry, on-disk reduced ViT3D/BigVGAN VAEs + config.json, prompt
embeds); the PRE-fold minimax-h3-gen binary AT THE BRANCH BASE (fc636c7)
rendered it (--partition fl2va --steps 3 --frames 5 --height/width 32, CPU,
keep-quant; run-to-run deterministic, diff -r clean) and its 8 frames + WAV +
both minimax-h3-mux --print-only argv lines are the committed goldens in
fixtures/minimax_h3_video_fold/.

W1 seam: vllm::multimodal::MiniMaxH3VideoEngine absorbs the 1293-line example
driver AND the server's 354-line /v1/videos twin — 4 DiT loader arms (GGUF
keep-quant / dequant-bf16 host+streamed / bf16-shard stream / NVFP4
bf16+fp4-resident), VAE decoder + lazy encoder halves, the H3-Encoder tower
staged once (GGUF or bf16 shards), the #77 partition guard, fl2va/ref2va
conditioning, the byte-exact splitmix64 Box-Muller noise streams
(VT_H3_GAUSSIAN_NOISE honored; seeded requests derive the audio stream via
splitmix64), artifact writing and mux-argv assembly. The library SPAWNS
NOTHING (mkdir -p became std::filesystem; ffmpeg stays caller-side — the
ratified 2026-08-03 boundary). MiniMaxH3VideoGenParamsFromRequest is the ONE
/v1/videos mapping so HTTP and FFI cannot drift.

W2 ABI: the ratified vllm_video_* slice (one-surface-abi.md:92-108) —
vllm_video_engine_load/free, vllm_video_model_params/_default,
vllm_video_params/_default, vllm_video_generate, vllm_video_result/_free —
plus the engine-free vllm_video_mux_argv(+_params_default,+_free) composer
the mux thin client needs. VLLM_ABI_VERSION 11 -> 12; test_capi floor pin
>= 12 (the == checks move with the macro). As-shipped deltas vs the proposal
argued in the spec (+prompt_embeds_path/+partition/+fp4_resident/+output_dir;
-task/-duration; ONE ref_image). Zero values preserve behaviour. Refusals
both directions: vllm_video_engine_load on a text dir names vllm_engine_load;
vllm_engine_load on the H3 dir fails byte-for-byte as captured at v11.

W3 server: the VideoState block is DELETED; /v1/videos = seam Load + a runner
lambda (FromRequest -> Generate -> fork/execvp(mux_argv)). Direct MiniMaxH3
refs 54 -> 7, all seam type names. DISCLOSED numeric deltas on the server arm
(no goldens existed; the drift WAS the defect): legacy single-stream uniform
noise -> the shared ratified recipe; host-f32 GGUF default -> keep-quant; new
--video-dequant-bf16 flag.

W4 examples: minimax_h3_gen (1293 -> 216 lines) + minimax_h3_mux are
vllm.h+vllm::shared thin clients, BOTH byte-identical to the pre-fold
binaries on the fixture (frames+WAV cmp clean; mux argv diff clean; the
pre-fold diagnostic modes died with the private pipeline — named residual).
Ratchet: both example-abi-allowlist rows removed, MAX_INTERNAL_REACHING
11 -> 9 with the equality pin + spec claims moved; the abi-capability video
row closes; FEATURES video row -> reachable naming the four symbols.

Gates: three-arm fold gate test_minimax_h3_video_fold 4 cases / 131
assertions GREEN (seam == replicated pre-fold pipeline == committed goldens,
byte-identical; partition-guard + input refusals; FromRequest
field-complete); test_capi 40/373 incl. the v12 golden e2e THROUGH the C
marshalling; vllm_capi_c_check strict-C11 green; test_minimax_h3 75/75
unchanged; test_openai_api_server 45/566 incl. the socket-level
routes-do-not-exist-without-a-runner 404 pin; test_video_api 14/14;
check-surface-coverage green with the SHRINK enforced + its 46-test mutation
suite. GB10 real-video re-verification through the v12 ABI is a NAMED
RESIDUAL (box on the Kimi campaign); records updated
(STATUS/BENCHMARKS/FEATURES/NOW/state/model-matrix + both specs).

FOLLOWING_AGENTS_PROTOCOL
Assisted-by: Claude Code:claude-fable-5 [ClaudeCode]
mudler added a commit that referenced this pull request Aug 7, 2026
…— vllm_video_*, ABI v12, /v1/videos via the library seam, thin-client examples

ONE-SURFACE fold ROW 2 (row/H3-VIDEO-ABI, task #283; the #121 precedent's
shape: three-arm fold gate, guard-ratchet shrink). The library absorbs
everything the examples privately owned.

GOLDENS FIRST: minimax_h3_video_fold_fixture.h writes a deterministic tiny
checkpoint set (857KB F32 ComfyUI-GGUF DiT at the test_minimax_h3.cpp:3786
reduced geometry, on-disk reduced ViT3D/BigVGAN VAEs + config.json, prompt
embeds); the PRE-fold minimax-h3-gen binary AT THE BRANCH BASE (fc636c7)
rendered it (--partition fl2va --steps 3 --frames 5 --height/width 32, CPU,
keep-quant; run-to-run deterministic, diff -r clean) and its 8 frames + WAV +
both minimax-h3-mux --print-only argv lines are the committed goldens in
fixtures/minimax_h3_video_fold/.

W1 seam: vllm::multimodal::MiniMaxH3VideoEngine absorbs the 1293-line example
driver AND the server's 354-line /v1/videos twin — 4 DiT loader arms (GGUF
keep-quant / dequant-bf16 host+streamed / bf16-shard stream / NVFP4
bf16+fp4-resident), VAE decoder + lazy encoder halves, the H3-Encoder tower
staged once (GGUF or bf16 shards), the #77 partition guard, fl2va/ref2va
conditioning, the byte-exact splitmix64 Box-Muller noise streams
(VT_H3_GAUSSIAN_NOISE honored; seeded requests derive the audio stream via
splitmix64), artifact writing and mux-argv assembly. The library SPAWNS
NOTHING (mkdir -p became std::filesystem; ffmpeg stays caller-side — the
ratified 2026-08-03 boundary). MiniMaxH3VideoGenParamsFromRequest is the ONE
/v1/videos mapping so HTTP and FFI cannot drift.

W2 ABI: the ratified vllm_video_* slice (one-surface-abi.md:92-108) —
vllm_video_engine_load/free, vllm_video_model_params/_default,
vllm_video_params/_default, vllm_video_generate, vllm_video_result/_free —
plus the engine-free vllm_video_mux_argv(+_params_default,+_free) composer
the mux thin client needs. VLLM_ABI_VERSION 11 -> 12; test_capi floor pin
>= 12 (the == checks move with the macro). As-shipped deltas vs the proposal
argued in the spec (+prompt_embeds_path/+partition/+fp4_resident/+output_dir;
-task/-duration; ONE ref_image). Zero values preserve behaviour. Refusals
both directions: vllm_video_engine_load on a text dir names vllm_engine_load;
vllm_engine_load on the H3 dir fails byte-for-byte as captured at v11.

W3 server: the VideoState block is DELETED; /v1/videos = seam Load + a runner
lambda (FromRequest -> Generate -> fork/execvp(mux_argv)). Direct MiniMaxH3
refs 54 -> 7, all seam type names. DISCLOSED numeric deltas on the server arm
(no goldens existed; the drift WAS the defect): legacy single-stream uniform
noise -> the shared ratified recipe; host-f32 GGUF default -> keep-quant; new
--video-dequant-bf16 flag.

W4 examples: minimax_h3_gen (1293 -> 216 lines) + minimax_h3_mux are
vllm.h+vllm::shared thin clients, BOTH byte-identical to the pre-fold
binaries on the fixture (frames+WAV cmp clean; mux argv diff clean; the
pre-fold diagnostic modes died with the private pipeline — named residual).
Ratchet: both example-abi-allowlist rows removed, MAX_INTERNAL_REACHING
11 -> 9 with the equality pin + spec claims moved; the abi-capability video
row closes; FEATURES video row -> reachable naming the four symbols.

Gates: three-arm fold gate test_minimax_h3_video_fold 4 cases / 131
assertions GREEN (seam == replicated pre-fold pipeline == committed goldens,
byte-identical; partition-guard + input refusals; FromRequest
field-complete); test_capi 40/373 incl. the v12 golden e2e THROUGH the C
marshalling; vllm_capi_c_check strict-C11 green; test_minimax_h3 75/75
unchanged; test_openai_api_server 45/566 incl. the socket-level
routes-do-not-exist-without-a-runner 404 pin; test_video_api 14/14;
check-surface-coverage green with the SHRINK enforced + its 46-test mutation
suite. GB10 real-video re-verification through the v12 ABI is a NAMED
RESIDUAL (box on the Kimi campaign); records updated
(STATUS/BENCHMARKS/FEATURES/NOW/state/model-matrix + both specs).

FOLLOWING_AGENTS_PROTOCOL
Assisted-by: Claude Code:claude-fable-5 [ClaudeCode]
mudler added a commit that referenced this pull request Aug 7, 2026
…odel_params.device, ABI v14, --device on server + cli

ONE-SURFACE fold ROW 8 (row/DEVICE-KNOB, task #284), the smallest: an
embedder can now ASK for a device instead of inheriting the
accelerator-first probe. Mirrors vLLM's DeviceConfig.device names
(vllm/config/device.py:13 @ 555967922; an explicit device is assigned
VERBATIM and never substituted, device.py:61-66 - upstream's own
--device flag was removed in v0.10, bc8a8ce5e, so the field mirrors
the surviving config surface).

include/vllm.h gains vllm_model_params.device (int32, 0=auto/1=cpu/
2=cuda; 0 MUST be auto so zero-initialized structs keep the pre-v14
probe byte-identical; cpu-before-cuda follows the shipped v12
vllm_video_model_params.device precedent shifted by the auto slot).
VLLM_ABI_VERSION -> 14 per the operator's version-collision heads-up
(#122 reconciles the Kimi vllm_complete_tokens slice to v13 at its
landing; the changelog names the gap and this branch rebases after).
Floor pin advanced to >= 14 (the #121 == lesson). New
vllm/config/device.h (+.cpp): vllm::Device, DeviceFromString,
DeviceName. Plumb: EngineParams::device -> SelectQueue explicit arms
via the pure LoadedEngine::ResolveExplicitDeviceType (explicit cpu
NEVER probes; explicit cuda requires the registered kCUDA platform and
fails LOUD otherwise; explicit-arm queue-creation failures propagate,
unlike auto's byte-identical catch-and-fall-back). FromModelDir
resolves an explicit device BEFORE any path/config I/O (DeviceConfig
resolves at config time, arg_utils.py:1878), so a device error is
never masked by a path error. capi validates 0/1/2 and refuses
explicit cuda on the CPU-hosted transcription stack. Thin clients:
--device auto|cpu|cuda on vllm-cli (ABI field only) and the server
(DeviceFromString; --video-device untouched, separate engine).

Also folds the #123 review's three MINOR findings (tests/docs only):
c_header_compile.c actually references the v11+v12 surface + the v14
field (its "every entry point" claim went stale at v10); the v12
changelog block moved to chronological position; the H3 fold fixture
flag list gained --keep-quant.

Gates: full CPU build -Werror clean; test_capi (4 new v14 cases +
floor), test_loaded_engine_dense (+3 device cases incl. the pure
policy matrix that pins "explicit cpu beats a REGISTERED accelerator"
CPU-side), test_dlopen, test_openai_api_server (+explicit-cpu serving
smoke), test_minimax_h3_video_fold, test_model_loader_gguf,
test_platform all green; surface-coverage green, ratchet UNTOUCHED at
9; STATUS ratchet paid by removing a stale back-to-back merge
duplicate (279200 -> 279150). Ten mutations killed and reverted
(defaults, zero-map, range, both plumb sites, ctor arm, unconditional
fallback, policy flip, parse flip, forgotten bump); kills recorded in
.agents/state.md. Residuals: CUDA-build A/B (no dgx in scope) and the
pending #122 rebase, both named in the state entry.

FOLLOWING_AGENTS_PROTOCOL
Assisted-by: Claude Code:claude-fable-5 [ClaudeCode]
mudler added a commit that referenced this pull request Aug 7, 2026
…odel_params.device, ABI v14, --device on server + cli

ONE-SURFACE fold ROW 8 (row/DEVICE-KNOB, task #284), the smallest: an
embedder can now ASK for a device instead of inheriting the
accelerator-first probe. Mirrors vLLM's DeviceConfig.device names
(vllm/config/device.py:13 @ 555967922; an explicit device is assigned
VERBATIM and never substituted, device.py:61-66 - upstream's own
--device flag was removed in v0.10, bc8a8ce5e, so the field mirrors
the surviving config surface).

include/vllm.h gains vllm_model_params.device (int32, 0=auto/1=cpu/
2=cuda; 0 MUST be auto so zero-initialized structs keep the pre-v14
probe byte-identical; cpu-before-cuda follows the shipped v12
vllm_video_model_params.device precedent shifted by the auto slot).
VLLM_ABI_VERSION 13 -> 14 on top of #122's vllm_complete_tokens v13
(rebased onto 9f772ca; the changelog now reads v10..v14 chronological
- the v12-after-v11 move is the #123-review minor kept through the
rebase). Floor pin advanced to >= 14 (the #121 == lesson). New
vllm/config/device.h (+.cpp): vllm::Device, DeviceFromString,
DeviceName. Plumb: EngineParams::device -> SelectQueue explicit arms
via the pure LoadedEngine::ResolveExplicitDeviceType (explicit cpu
NEVER probes; explicit cuda requires the registered kCUDA platform and
fails LOUD otherwise; explicit-arm queue-creation failures propagate,
unlike auto's byte-identical catch-and-fall-back). FromModelDir
resolves an explicit device BEFORE any path/config I/O (DeviceConfig
resolves at config time, arg_utils.py:1878), so a device error is
never masked by a path error. capi validates 0/1/2 and refuses
explicit cuda on the CPU-hosted transcription stack. Thin clients:
--device auto|cpu|cuda on vllm-cli (ABI field only) and the server
(DeviceFromString; --video-device untouched, separate engine).

Also folds the #123 review's three MINOR findings (tests/docs only):
c_header_compile.c actually references the v11+v12 surface + the v14
field (composed with #122's vllm_complete_tokens reference; its "every
entry point" claim went stale at v10); the v12 changelog block moved
to chronological position; the H3 fold fixture flag list gained
--keep-quant.

Gates: full CPU build -Werror clean; test_capi (4 new v14 cases +
floor >= 14, #122's v13 cases green alongside), test_loaded_engine_dense
(+3 device cases incl. the pure policy matrix that pins "explicit cpu
beats a REGISTERED accelerator" CPU-side), test_dlopen,
test_openai_api_server (+explicit-cpu serving smoke),
test_minimax_h3_video_fold, test_model_loader_gguf, test_platform all
green; surface-coverage green, allowlist ratchet UNTOUCHED at 8 (post
#122); STATUS ratchet paid by removing a stale back-to-back merge
duplicate (279200 -> 279150, measured 279111 post-rebase). Ten
mutations killed and reverted (defaults, zero-map, range, both plumb
sites, ctor arm, unconditional fallback, policy flip, parse flip,
forgotten bump); kills recorded in .agents/state.md. Residual:
CUDA-build A/B (no dgx in scope), named in the state entry.

FOLLOWING_AGENTS_PROTOCOL
Assisted-by: Claude Code:claude-fable-5 [ClaudeCode]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants