@melite/models-h3 0.1.5-pre-alpha → 0.2.2-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,39 +1,34 @@
1
- ---
2
- description: MiniMax H3 family, joint video and audio generation across timeline, single-shot, and keyframe lanes.
3
- kind: package-library
4
- ---
5
-
6
1
  # @melite/models-h3
7
2
 
8
- The MiniMax H3 family — joint video and audio generation, one family owning three lanes (the one-model law): multi-window timeline films on route `h3-timeline`, single-shot FL2VA and Ref2VA clips on route `h3-fl2va`, and the keyframe lane. The survivor-id correction (2026-09-22) fixed the fold: the family is `h3`, a model names a checkpoint, and a variant names a lane — the old `h3-timeline` address survives as the timeline lane's route, and a dead-era draft addressing `h3` resolves to the family default, the timeline lane, the one deliberate behavior shift. The family serves a catalog row (offered, comfyui) with a studio block: the `video/h3-timeline` tenant owns the card's parameters — calls, keyframes, sampling, SLA sparsity, sharpen, interpolation, super-resolution, audio, loras, document.
3
+ The MiniMax H3 family — joint video and audio generation, one family owning three lanes (the one-model law): multi-window timeline films on route `h3-timeline`, single-shot FL2VA and Ref2VA clips on route `h3-fl2va`, and the keyframe lane. The survivor-id correction (2026-09-22): the family is `h3`, a model names a checkpoint, a variant names a lane; the old `h3-timeline` address survives as the timeline lane's route, and a dead-era draft addressing `h3` resolves to the family default — the timeline lane, the one deliberate behavior shift. It serves a catalog row (offered, comfyui) with a studio block: the `video/h3-timeline` tenant owns the card's parameters — calls, keyframes, sampling, SLA sparsity, sharpen, interpolation, super-resolution, audio, loras, document.
9
4
 
10
- Provisions pin the downloaded weights with sha256 digests, byte sizes, and target folders. The mods row boards the loras pack and marries steps with max: eleven user-picked distill and refiner rows (LightX2V, Kijai, the arena winners, DMAD, TaoMate) — no recipe stamps them; the absent-bag default builds from the catalog's `h3_lightx2v_turbo` row, and a missing row refuses at load.
5
+ Provisions pin the downloaded weights with sha256 digests, byte sizes, and target folders. The mods row boards the loras pack with steps married at max: eleven user-picked distill and refiner rows (LightX2V, Kijai, the arena winners, DMAD, TaoMate); no recipe stamps them, the absent-bag default builds from the catalog's `h3_lightx2v_turbo` row, and a missing row refuses at load.
11
6
 
12
- The film action is the single seat of the video lane: the card's schema gate runs card-side, then dispatches here; the action owns the t4r guide admission, the clips law, the lora steps, and both renderers, and returns the artifact handle. The timeline contract pins the frame math: 22-frame seam overlap, the 22+17k carried grid capped at 362 frames, and the 9-slot image bus with caps (8 images, 3 videos, 3 audios, 8 refmods). The film mix owns the audio placement math — one owner that both the compose stamps and the film-time overlay read; a positioned clip row without a numeric start frame refuses loud. The schema module mirrors the h3-timeline card's param schema 1:1 — one spelling, never a second copy.
7
+ The film action is the video lane's single seat: the card's schema gate runs card-side, then dispatches here; the action owns the t4r guide admission, the clips law, the lora steps, and both renderers, returning the artifact handle. The timeline contract pins the frame math: 22-frame seam overlap, the 22+17k carried grid capped at 362 frames, and the 9-slot image bus with caps (8 images, 3 videos, 3 audios, 8 refmods). The film mix owns the audio placement math — one owner for the compose stamps and the film-time overlay; a positioned clip row without a numeric start frame refuses loud. The schema module mirrors the h3-timeline card's param schema 1:1 — one spelling, never a second copy.
13
8
 
14
- Beyond the package entry, the manifest exports `./mods/loras` (the flavor rows), `./actions` (the film action), `./schema` (the param carrier), `./timelineContract` (the frame grid), and `./filmMix` (the audio mix).
9
+ The manifest also exports `./mods/loras` (the flavor rows), `./actions` (the film action), `./schema` (the param carrier), `./timelineContract` (the frame grid), and `./filmMix` (the audio mix).
15
10
 
16
11
  ## Declaration
17
12
 
18
- `src/index.ts` declares the DECL and the `family-h3` plugin; the subpath modules above are the family's published seams for the card, the flow, and the agents that read them.
13
+ `src/index.ts` declares the DECL and the `family-h3` plugin; the subpath modules above are the published seams for the card, flow, and agents. The timeline lane serves the three-member quant offer (the 2026-10-26 cure: "the system needs ALL THREE") — `int8` (the smhfacct hybrid default), `int8_convrot_pruned` (the Comfy-Org pruned ConvRot dit, already provisioned), `int8_convrot` (the 34 GB non-pruned per-cell tier) — beside the community Singularity fine-tune at `int8_pruned` (convrot unstated upstream; a pick-only per-variant `lane_inputs.unet` override; the first+last-frame audition and VRAM peaks owed to the bench experiments).
19
14
 
20
15
  ## Model Experience
21
16
 
22
17
  #### What the model sees
23
18
 
24
- None — the package contributes no model-visible input. The DECL serves the estate's model catalog (label, description, variants, defaults) and the h3-timeline card that boards the family; it registers no session events and writes no prompt segments.
19
+ None — the DECL serves the estate's model catalog and the h3-timeline card; it registers no session events and writes no prompt segments.
25
20
 
26
21
  #### Token effect
27
22
 
28
- Zero-direct token effect — the package registers a model family and composes engine graphs; it writes no prompt text into any model request.
23
+ Zero-direct — the package registers a family and composes engine graphs; it writes no prompt text into any model request.
29
24
 
30
25
  #### KV Cache effect
31
26
 
32
- Independent — the package contributes no persistent prompt prefix, so registering or removing the family invalidates nothing cached.
27
+ Independent — no persistent prompt prefix; registering or removing the family invalidates nothing cached.
33
28
 
34
29
  ## Known Limitations and Deferred Work
35
30
 
36
- - **LoRA steps marry at max** — while a counting bag row rides, steps are the bag's (the higher designed count wins across the rows); an authored step count loses to the designed one.
37
- - **The carried grid refuses off-grid spans** — authored ranges must land on the 22+17k grid; the contract asserts and refuses with the legal neighboring end frames rather than snapping silently.
38
- - **Ref caps are loud** — 9 image-bus slots (8 loose references, 7 with a last-frame anchor), 3 videos, 3 audios, 8 refmods; an over-cap stack refuses at the gate, never rides silent.
31
+ - **LoRA steps marry at max** — while a counting bag row rides, steps are the bag's (the higher designed count wins); an authored step count loses.
32
+ - **The carried grid refuses off-grid spans** — authored ranges must land on the 22+17k grid; refusals name the legal neighboring end frames, never snapping silently.
33
+ - **Ref caps are loud** — 9 image-bus slots (8 loose references, 7 with a last-frame anchor), 3 videos, 3 audios, 8 refmods; an over-cap stack refuses at the gate, never silent.
39
34
  - **Dense-LoRA adaln drops are watched, not yet guarded** — a dense row can silently drop 51 adaln_proj keys on the pruned base; the guard rides the arena's first stacked load.
package/lib/actions.d.ts CHANGED
@@ -1,5 +1,65 @@
1
1
  import type { OutputHandle } from '@melite/comfyui-card-kit/graph';
2
+ import { GraphBuilder } from '@melite/comfyui-card-kit/graph';
2
3
  import type { ComfyActionSpec } from '@melite/comfyui-card-kit';
4
+
5
+
6
+ export declare const H3_DEFAULT_LORA_ID = "h3_silver_dareties";
7
+ /** The absent-bag default as a RESOLVED ROW — the same catalog row the
8
+ * compose default builds, exposed so the card can serve it as the
9
+ * ghost chip: the face then shows the adapter the film will actually
10
+ * run instead of an empty bag. One owner: the catalog. */
11
+ export declare const h3DefaultLoraEntry: () => {
12
+ id: string;
13
+ strength: number;
14
+ steps: number;
15
+ };
16
+
17
+
18
+
19
+
20
+
21
+
22
+
23
+ export declare function h3LoraStackOf(p: Record<string, unknown>): string;
24
+ /** THE MARRIED SHIFT'S ONE OWNER (same law as the lora plane): the
25
+ * sigma-shift grid the doc's lora plane owns — a pinned shift is the
26
+ * user's word, an unstated one marries the bag's highest-count row
27
+ * (marriedBagKnob), else the doc's own row. Both renderers read this.
28
+ * @param p the walked doc params */
29
+ export declare function h3ShiftVideoOf(p: Record<string, unknown>): number;
30
+
31
+
32
+
33
+
34
+
35
+
36
+
37
+
38
+
39
+
40
+
41
+
42
+ export declare const LANE_FILES: {
43
+ readonly clip: "qwen3vl_32b_minimax_h3_int8_convrot.safetensors";
44
+ readonly vae_video: "minimax_h3_video_vae_int8_convrot.safetensors";
45
+ readonly vae_audio: "minimax_h3_audio_vae_fp32.safetensors";
46
+ readonly sr_vae: "ema_vae_fp16.safetensors";
47
+ };
48
+
49
+
50
+
51
+
52
+
53
+
54
+ export declare const FILM_AUDIO_RATE = 48000;
55
+ /** THE JOIN-RATE DOOR: one spelling for every audio leg that feeds a
56
+ * join's CreateVideo — the leg passes MeliteAudioResample at
57
+ * FILM_AUDIO_RATE (engine-core bandlimited sinc; equal-rate input
58
+ * passes the SAME dict through, so a leg already at the film rate
59
+ * pays nothing but the stated law).
60
+ * @param g the run's graph builder
61
+ * @param audio the leg's AUDIO output handle */
62
+ export declare function filmJoinAudio(g: GraphBuilder, audio: OutputHandle): OutputHandle;
3
63
  /** The h3 facts door: the resolved lane_inputs parsed into the
4
64
  * loader names the renderers read (the unet from the row; the
5
65
  * three invariants from the package's own LANE_FILES).
@@ -17,27 +77,50 @@ export declare function parseH3Facts(raw: unknown): H3Facts;
17
77
  * Exported so the card's single-call lift judges through the same
18
78
  * re-check (the h3-b duplicate is gone: one owner). */
19
79
  export declare const assertOverlayGated: (doc: Record<string, unknown>, where: string) => void;
20
- export interface WindowHandles {
21
- latOut: OutputHandle;
22
- vdec: OutputHandle;
23
- vadec: OutputHandle;
24
- /** the DELIVERED clip — post-trim, post-sharpen: exactly the
25
- * streams that window's own SaveVideo plays; the film concat's
26
- * currency (the film must not differ from its windows). */
27
- filmImages: OutputHandle;
28
- filmAudio: OutputHandle;
29
- /** the window's SaveVideo VIDEO passthrough — the film tail's
30
- * ordering wire: the MeliteUnload boundary consumes it, so the
31
- * file loaders provably wait for the saves (and the passthrough
32
- * tensor dies at the boundary — the §20 law). Assigned by BOTH
33
- * family arms (every family path saves); the film tail refuses
34
- * loud if a future arm forgets. */
35
- savePassthrough?: OutputHandle;
36
- }
80
+
81
+
82
+
83
+
84
+
85
+
86
+
87
+
88
+
89
+
90
+
91
+ export declare function chainSaveBoundaries(g: GraphBuilder, saves: readonly OutputHandle[]): OutputHandle;
92
+ /** THE FILE-JOIN PRIMITIVE, half 2 — the concat + container (the
93
+ * film tail's own law, ONE spelling for every join-by-file seat):
94
+ * MeliteConcatVideos decodes the saved FILES back CPU-side strictly
95
+ * after the boundary token; CreateVideo → SaveVideo delivers the
96
+ * joined film.
97
+ * @param g the run's graph builder
98
+ * @param prefixes the members' SaveVideo prefixes, film order
99
+ * @param after the boundary chain's final token (the ordering proof)
100
+ * @param out the joined film's filename_prefix
101
+ * @param opts.audio an audio override for the container mux (the
102
+ * film's mixed stem); absent = the concat's own decoded audio
103
+ * @param opts.append an exact saved-file path wired as the LAST
104
+ * member after the prefix list (the multi-window extend's assembled
105
+ * extension — ChainAssemble's video_path output; DAG-proven by its
106
+ * own data dependency, no boundary needed)
107
+ * @returns the joined film's SaveVideo passthrough */
108
+ export declare function concatSavedFilms(g: GraphBuilder, prefixes: readonly string[], after: OutputHandle, out: string, opts?: {
109
+ audio?: OutputHandle;
110
+ append?: OutputHandle;
111
+ }): OutputHandle;
37
112
  /** The seam's cross-window wires: the RAW decode + sampler handles
38
113
  * of one rendered window (pre-trim, pre-sharpen — the true tail). */
39
114
  export interface WindowHandles {
40
115
  latOut: OutputHandle;
116
+ /** the drift-control anchor's currency — the SAME-RATE latent the
117
+ * next window's continuation consumes as previous_latent: pass 1's
118
+ * sampled latent (or the refine rider's in-band polish when it
119
+ * mounts without the upscale handoff — the chained-texture law);
120
+ * NEVER the latent-upscale handoff's 2× output (F44-execute: a 2×
121
+ * anchor against window k+1's base-rate continuation target is a
122
+ * shape-refused graph). latOut stays the DELIVERED half's latent. */
123
+ seamLatent: OutputHandle;
41
124
  vdec: OutputHandle;
42
125
  vadec: OutputHandle;
43
126
  /** the DELIVERED clip — post-trim, post-sharpen: exactly the