@melite/models-yue2 0.1.4-alpha → 0.2.0-alpha

package/README.md

@@ -0,0 +1,42 @@
+---
+description: YuE2 music family — YuE2-3B style-plus-lyrics song generation with ABC planning, on the ComfyUI engine from the official Comfy-Org release.
+kind: package-library
+---
+
+# @melite/models-yue2
+
+`@melite/models-yue2` is the model family package for YuE2-3B music generation (`form_music`, genre audio, engine comfyui): a style caption plus lyrics go in, an ABC plan is drafted, and a song comes out as mp3. The DECL boards the official Comfy-Org release (`Comfy-Org/YuE2`, the `audio_yue2_text2music` template) and declares the `compose` action, one provision, and the required `prompt` relation. The estate boot mounts it as a Cordis plugin through `ctx.models.registerFamily` inside `ctx.effect`; the music card binds the action. The lane is this package's own `actions.ts`, pinned to committed goldens in `tests/golden/`.
+
+## Declaration
+
+One checkpoint carries model, clip, and VAE (`yue2_3b_int8_convrot.safetensors`, provisioned from Comfy-Org at ~3.96 GB, sha256-pinned; the INT8 ConvRot cell declares an ~8 GB VRAM peak). Variant recipes: `short_sting` stamps `duration` 5 (the schema floor) and `full_length` stamps 360 (the ceiling); `Default` stamps nothing. The `compose` action's params: `prompt` (required — every music lane states what the song is), `lyrics`, `mode` (`full` / `melody` / `off`), `duration` (bounds 5–360), `n_diffusion_steps` (1–200), and a seed-sentinel `seed`. The build plans ABC with `YuE2GenerateABC` (mode `off` composes no planner), sizes the latent from `YuE2GenerateMusic`'s seconds output, samples with KSampler dpm_2 / sgm_uniform at cfg 1, and saves mp3 V0 under `<run>/music`.
+
+```
+.
+./package.json
+```
+
+## Model Experience
+
+### Request context and condition
+
+#### What the model sees
+
+- **prompt** — required; the style caption.
+- **lyrics** — the sung words (absent rides as empty).
+- **mode** — the ABC-planning pick.
+- **duration / n_diffusion_steps / seed** — length, sampler depth, and the minted seed.
+
+#### Token effect
+
+Zero-direct token effect — the fields ride the composed ComfyUI graph; the caption and lyrics are engine-side, never harness context.
+
+#### KV Cache effect
+
+Independent — each composition is its own engine request; no shared prefix.
+
+## Known Limitations and Deferred Work
+
+- **One quant boarded** — only the INT8 ConvRot cell exists; the bf16 cell and the SheetSage2 cover encoder stay unboarded until a cover lane exists (the DECL's own source note).
+- **Guidance is fixed** — cfg rides at 1 by design (guidance lives on the AR side); there is no cfg knob.
+- **Song quality** — musicality and lyric adherence are not verified against the running model.

package/lib/actions.js

@@ -31,6 +31,27 @@ export const compose = {
     ],
     facts: parseYue2Facts,
     build({ p, facts, g, runId }) {
+        
+        // mode precedent, music3/actions.ts: the DECL surface drops the
+        // knob, the build refuses the legacy draft). guidance_scale +
+        // lm_cfg_scale are the MiniMax lane's vocabulary (KSampler cfg +
+        // MiniMaxMusic3TextEncode cfg_scale) — the yue2 DECL serves
+        // neither (index.ts params), YuE2GenerateABC/YuE2GenerateMusic
+        // declare no such input, and KSampler cfg is the lane's fixed 1.
+        
+        // at compose — the SD-1 wedge (authored-on-music3, switched to
+        // yue2). Refuse loud in the knob's own voice; the schema
+        // default 1.7 rides (the stated default IS the unstated
+        // compose), and an absent knob (direct action callers) rides.
+        for (const [knob, lane] of [["guidance_scale", "KSampler cfg"], ["lm_cfg_scale", "the lyric-encoder guidance"]]) {
+            const v = p[knob];
+            if (v !== undefined && v !== 1.7) {
+                throw new Error(`yue2 compose: ${knob} '${String(v)}' fires nothing on this lane — ` +
+                    `${knob} is the MiniMax lane's vocabulary (${lane}); ` +
+                    "the YuE2 nodes read style+lyrics+mode only, KSampler cfg is the lane's fixed 1. " +
+                    "Drop it, or switch lane (model=music3) to steer the MiniMax guidance");
+            }
+        }
         const seed = p.seed;
         const ckpt = g.node("CheckpointLoaderSimple", { ckpt_name: facts.checkpoint });
         const style = p.prompt;
@@ -40,6 +61,12 @@ export const compose = {
         // GenerateMusic rides an empty abc (the engine's own off mode);
         // full/melody ride YuE2GenerateABC with the same style + lyrics.
         let abc = "";
+        // Off is CARD vocabulary the node enum cannot spell (full|melody)
+        // and mode is engine-REQUIRED — the off arm wires the engine's
+        // own default 'full' over the EMPTY abc (the off semantics live
+        // in the missing conditioning, never in a mode literal the enum
+        // refuses).
+        const nodeMode = mode === "off" ? "full" : mode;
         if (mode !== "off") {
             abc = g.node("YuE2GenerateABC", {
                 clip: ckpt.out(1), style, lyrics, seed, mode,
@@ -48,7 +75,7 @@ export const compose = {
             }).out(0);
         }
         const music = g.node("YuE2GenerateMusic", {
-            clip: ckpt.out(1), style, lyrics, abc, seed, mode,
+            clip: ckpt.out(1), style, lyrics, abc, seed, mode: nodeMode,
             max_duration: p.duration, temperature: 1.0, top_p: 0.95, top_k: 100,
             repetition_penalty: 1.2,
         });

package/lib/index.d.ts

@@ -1,6 +1,7 @@
 import type { Plugin } from "@deepseek-ai/cordis";
-import type { ModelDecl } from "@melite/comfyui-cordis/model-contract";
+import type { ModelDecl } from '@melite/comfyui-card-kit/model-contract';
 export declare const DECL: ModelDecl;
 export declare const family: Plugin;
 export { compose, parseYue2Facts, type Yue2Facts, type Yue2Params } from "./actions.js";
+export { family as default };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -11,6 +11,15 @@ export const DECL = {
         "note": "The official Comfy-Org release (template audio_yue2_text2music); int8 convrot is the template's own quant pick. The bf16 cell and the SheetSage2 cover encoder stay unboarded until a cover lane exists."
     },
     "genre": "audio",
+    
+    // user-provided seats (prompt, lyrics) — the compose caller
+    // provides them. No variant-class rows: this family's served
+    // face exposes no steps+cfg pair (the census's surface-derived
+    // carve).
+    "required_defaults": [
+        { "name": "prompt", "class": "user" },
+        { "name": "lyrics", "class": "user" }
+    ],
     "variants": [
         {
             "id": "standard",
@@ -19,10 +28,9 @@ export const DECL = {
             "route": "yue2",
             "cells": [
                 {
-                    "source": {
-                        "filename": "YuE2"
-                    },
-                    "quant": "int8",
+                    
+                    // Comfy-Org checkpoint the provisions row carries.
+                    "quant": "int8_convrot",
                     "label": "INT8 ConvRot",
                     "route": "yue2",
                     "vram_peak_gb": 8,
@@ -30,7 +38,7 @@ export const DECL = {
             ]
         },
         {
-            "id": "short_sting",
+            "id": "short-sting",
             "label": "Short Sting",
             "hint": "Duration 5s — the card schema's own floor (a sting or loop).",
             "group": "Recipe",
@@ -38,7 +46,7 @@ export const DECL = {
             "cells": [],
         },
         {
-            "id": "full_length",
+            "id": "full-length",
             "label": "Full Length",
             "hint": "Duration 360s — the card schema's own ceiling (full-song length).",
             "group": "Recipe",
@@ -95,6 +103,19 @@ export const DECL = {
             },
         ],
     },
+    // THE LANE SURFACE (the z-image precedent): exactly the knobs the
+    // music card serves. guidance_scale + lm_cfg_scale are NOT served
+    
+    // the MiniMax lane's vocabulary, unread on the YuE2 lane (KSampler
+    // cfg is the lane's fixed 1, neither YuE2 node takes the input).
+    // Dropping them from the surface makes the compose door refuse a
+    // legacy draft stating them (unknown-param refusal, layer 1);
+    // actions.ts refuses them at the card path (layer 2). The card
+    // schema keeps them (music3's seat) with visible_when music3.
+    "params": [
+        "prompt", "lyrics", "duration", "mode",
+        "n_diffusion_steps", "seed",
+    ],
     // THE DECLARED ACTIONS (the atom vocabulary, stroke 3):
     // the compose action the music card binds (the YuE2-3B lane).
     // The admission gate runs the facts parse at registration.
@@ -108,4 +129,9 @@ export const family = {
     },
 };
 export { compose, parseYue2Facts } from "./actions.js";
+// The Loader-row face: DSH loads plugin rows by bare specifier and
+// unwraps `exports.default ?? exports` (vendor/cordis_plugins/loader
+// unwrapExports) — the default export IS the row-loadable plugin. The
+// named `family` stays the library face (engine loadFamilies).
+export { family as default };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@melite/models-yue2",
-  "version": "0.1.4-alpha",
-  "license": "SSPL-1.0",
+  "version": "0.2.0-alpha",
+  "license": "AGPL-3.0-or-later",
   "type": "module",
   "exports": {
     ".": {
@@ -11,13 +11,12 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@melite/comfyui-card-kit": "0.1.4-alpha",
-    "@melite/comfyui-cordis": "0.1.4-alpha"
+    "@melite/comfyui-card-kit": "0.2.0-alpha"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "typescript": "^5.9.3",
-    "@deepseek-ai/cordis": "^4.0.4"
+    "@deepseek-ai/cordis": "^4.0.5"
   },
   "files": [
     "lib/index.js",
@@ -25,7 +24,7 @@
     "lib/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.4"
+    "@deepseek-ai/cordis": "^4.0.5"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",