@melite/models-anima 0.1.4-alpha → 0.1.5-pre-alpha

package/README.md

@@ -0,0 +1,36 @@
+---
+description: Anima text-to-image family, a Cosmos-Predict2 anime and illustration diffusion lane with Danbooru-style prompting.
+kind: package-library
+---
+
+# @melite/models-anima
+
+The Anima family — anime and illustration text-to-image on the comfyui engine, built on the Cosmos-Predict2 base with Danbooru-style prompting. The package owns the declaration, the lane's weight facts, and the t2i action; the image-gen card binds the action and owns the compose surface around it.
+
+The lane pins its weights in lane_inputs: unet `anima-base-v1.0.safetensors`, text encoder `qwen_3_06b_base.safetensors`, VAE `qwen_image_vae.safetensors`, clip type `stable_diffusion`, stock `EmptyLatentImage` latent. Three provisions rows download them (circlestone-labs/Anima, Qwen/Qwen3-0.6B-Base, Comfy-Org/Qwen-Image_ComfyUI). Defaults are 1024×1024, 30 steps, er_sde over simple, cfg 4; the recipes are draft (8 steps) and detailed (30 steps); the single F32 cell peaks at 20 GB. The prompt field is required — a draft without one refuses, because every image lane states what the picture is.
+
+The family's action is t2i: the stock diffuse topology — CLIPTextEncode pair, EmptyLatentImage at card resolution, KSampler, decode and save under `<run>/gen`. The facts door reads the resolved lane_inputs into the closed T2IFacts shape; a drifted latent class refuses rather than silently rerouting. Anima boards no mods: loras, controlnets, and ip-adapter bags refuse loud, never silently drop.
+
+## Declaration
+
+`src/index.ts` declares the DECL and the `family-anima` plugin; `src/actions.ts` owns the t2i segment and its typed facts and params.
+
+## Model Experience
+
+#### What the model sees
+
+None — the package contributes no model-visible input. The DECL serves the estate's model catalog (label, description, variants, defaults) and the image-gen card that boards the family; it registers no session events and writes no prompt segments.
+
+#### Token effect
+
+Zero-direct token effect — the package registers a model family and composes engine graphs; it writes no prompt text into any model request.
+
+#### KV Cache effect
+
+Independent — the package contributes no persistent prompt prefix, so registering or removing the family invalidates nothing cached.
+
+## Known Limitations and Deferred Work
+
+- **Required prompt** — the relations row makes prompt mandatory; a textless draft refuses at the family door instead of composing an undefined image.
+- **F32 only** — one cell, 20 GB peak; no quantized variants ride the DECL.
+- **No adapter flavor** — no loras or controlnets packs board the family; a stated adapter bag refuses loud, so adapter-driven styling is out of scope here.

package/lib/actions.js

@@ -1,7 +1,8 @@
 import { loadTextPair, decodeSave, stackLoras, stackControlNets } from "@melite/comfyui-card-kit";
 import { fireLoras, fireControlNets, refuseIPAdapterFiring } from "@melite/comfyui-card-kit/guard";
-import { requireText } from "@melite/comfyui-card-kit/facts";
+import { parseDiffusionLaneFacts } from "@melite/comfyui-card-kit/facts";
 import { diffusionParamRows } from "@melite/comfyui-card-kit/paramRows";
+import { checkAnimaPromptTags } from "./promptTags.js";
 /** The t2i facts door: the resolved lane_inputs parsed into the
  *  closed shape. A drifted latent class refuses here, never
  *  silently routes to another topology. `sampling_shift: 0` is
@@ -10,23 +11,11 @@ import { diffusionParamRows } from "@melite/comfyui-card-kit/paramRows";
  *  @param raw the resolved lane_inputs (family ⊕ variant)
  *  @returns the typed facts the segment factory reads */
 export function parseT2IFacts(raw) {
-    const text = (key) => requireText(raw, key, "anima t2i");
-    const node = raw.latent_node;
-    if (node !== "EmptyLatentImage") {
-        throw new Error(`anima t2i: lane_inputs.latent_node = ${JSON.stringify(node)} — the t2i action builds on EmptyLatentImage`);
-    }
-    const shift = raw.sampling_shift;
-    if (shift !== undefined && typeof shift !== "number") {
-        throw new Error(`anima t2i: lane_inputs.sampling_shift = ${JSON.stringify(shift)} — a number is required`);
-    }
-    return {
-        unet: text("unet"),
-        text_encoder: text("text_encoder"),
-        vae: text("vae"),
-        clip_type: text("clip_type"),
-        latent_node: node,
-        sampling_shift: shift,
-    };
+    // The checks + refusal prose live in the kit (J2 consolidation,
+    
+    // family's own typed shape (the self-containment contract, B4).
+    const f = parseDiffusionLaneFacts(raw, "anima t2i", { key: "latent_node", node: "EmptyLatentImage" });
+    return { unet: f.unet, text_encoder: f.text_encoder, vae: f.vae, clip_type: f.clip_type, latent_node: f.node, sampling_shift: f.sampling_shift };
 }
 /** The text-to-image action: the stock diffuse topology — CLIP
  *  encoder pair (positive + negative), EmptyLatentImage at card
@@ -57,6 +46,13 @@ export const t2i = {
         // vocabulary, mod-level owned; anima boards no pack, the picks
         // are always empty — the call stays so a stated bag refuses).
         unet = stackControlNets(g, unet, vae, fireControlNets(model, p));
+        // THE TAG-GRAMMAR DOOR (features/001 A4): the Danbooru grammar
+        // is mechanical — a malformed prompt refuses here with the
+        // fragment named, never reaches the encoder silently rewritten.
+        checkAnimaPromptTags("prompt", p.prompt);
+        if (p.negative_prompt !== undefined) {
+            checkAnimaPromptTags("negative_prompt", p.negative_prompt);
+        }
         const pos = g.node("CLIPTextEncode", { clip, text: p.prompt });
         const neg = g.node("CLIPTextEncode", { clip, text: p.negative_prompt ?? "" });
         const latent = g.node(facts.latent_node, { batch_size: 1, width: p.width, height: p.height });

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 { t2i, parseT2IFacts, type T2IFacts, type T2IParams } from "./actions.js";
+export { family as default };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -14,6 +14,11 @@ export const DECL = {
         "cfg": 4
     },
     "genre": "image",
+    // MASK-C (the image-gen region gap — deliberate no-board): no
+    // mods key (absent ≡ boards nothing) — the anime T2I lane takes no
+    // region input upstream and no edit lane shares these weights.
+    // Serving the surface would promise what no lane builds; a stated
+    // mask refuses LOUD at admission like every undeclared key.
     "variants": [
         {
             "id": "standard",
@@ -45,6 +50,14 @@ export const DECL = {
             "wire_defaults": { "steps": 30 },
             "cells": [],
         },
+        {
+            "id": "settled-negative",
+            "label": "Settled negative",
+            "hint": "Stamps the guide's settled negative set. TRIM RULE: the negative stays short — broadening a negative concept degrades quality, so this row is the whole set, never a base to widen.",
+            "group": "Recipe",
+            "wire_defaults": { "negative_prompt": "worst quality, low quality, score_1, score_2, score_3, artist name" },
+            "cells": [],
+        },
         {
             "id": "default",
             "label": "Default",
@@ -69,6 +82,20 @@ export const DECL = {
             "default": "default"
         }
     ],
+    // THE LANE SURFACE (the edit-2511 precedent): exactly the knobs the
+    // create card serves — no reference seat (operator ruling,
+    
+    "params": [
+        "prompt",
+        "negative_prompt",
+        "width",
+        "height",
+        "seed",
+        "steps",
+        "cfg",
+        "sampler",
+        "scheduler",
+    ],
     "lane_inputs": {
         "clip_type": "stable_diffusion",
         "latent_node": "EmptyLatentImage",
@@ -138,4 +165,9 @@ export const family = {
 // segment the image-gen card binds. The card imports this beside
 // the DECL — the family's whole offer, one face.
 export { t2i, parseT2IFacts } 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/lib/promptTags.d.ts

@@ -0,0 +1,9 @@
+/** Refuse a prompt or negative that breaks the Danbooru tag
+ *  grammar. Called from the t2i build before any node renders —
+ *  a malformed grammar dies at compose time with the offending
+ *  fragment named, never at the encoder.
+ *  @param field the param seat being judged ("prompt" or "negative_prompt")
+ *  @param text the raw param value
+ *  @throws Error naming the refusal class and the offending fragment */
+export declare function checkAnimaPromptTags(field: "prompt" | "negative_prompt", text: string): void;
+//# sourceMappingURL=promptTags.d.ts.map

package/lib/promptTags.js

@@ -0,0 +1,49 @@
+// @melite/models-anima/src/promptTags — the Danbooru tag-grammar
+
+// is mechanical, so the family REFUSES a prompt that breaks it —
+// never silently rewrites (a rewritten prompt is a different
+// picture, and the author never learns their tags are malformed).
+// Three refusal classes, one door: missing space after a comma,
+// doubled comma, underscore in a tag. The score-tag exception is
+// the recipe's own rule (score_1..score_9 are the one legal
+// underscore form — "spaces instead of underscores, except score
+// tags").
+/** An underscore-bearing token that is NOT a score tag
+ *  (score_[0-9] with optional decimals) — the recipe's one legal
+ *  underscore form. */
+function isScoreTag(token) {
+    return /^score_[0-9](\.[0-9]+)?$/.test(token);
+}
+/** Refuse a prompt or negative that breaks the Danbooru tag
+ *  grammar. Called from the t2i build before any node renders —
+ *  a malformed grammar dies at compose time with the offending
+ *  fragment named, never at the encoder.
+ *  @param field the param seat being judged ("prompt" or "negative_prompt")
+ *  @param text the raw param value
+ *  @throws Error naming the refusal class and the offending fragment */
+export function checkAnimaPromptTags(field, text) {
+    const segments = text.split(",");
+    for (let i = 0; i < segments.length; i += 1) {
+        const seg = segments[i];
+        // class 2 — doubled comma: an empty segment anywhere except a
+        // trailing one (a prompt ending in a single comma is the
+        // prefix convention, not a doubled separator).
+        if (seg.trim() === "" && i < segments.length - 1) {
+            throw new Error(`anima ${field}: doubled comma at segment ${i + 1} — one comma, one space, then the next tag (${JSON.stringify(text)})`);
+        }
+        // class 1 — missing space after a comma: the separator grammar
+        // is ", " (comma + space); a comma glued to the next tag
+        // refuses (the first segment has no comma in front of it).
+        if (i > 0 && seg !== "" && !seg.startsWith(" ")) {
+            throw new Error(`anima ${field}: missing space after comma before ${JSON.stringify(seg)} — the separator is comma + space (${JSON.stringify(text)})`);
+        }
+        // class 3 — underscore in a tag: Danbooru tags use spaces;
+        // the score tags are the exception, per the recipe.
+        for (const token of seg.trim().split(/\s+/)) {
+            if (token.includes("_") && !isScoreTag(token)) {
+                throw new Error(`anima ${field}: underscore in tag ${JSON.stringify(token)} — tags use spaces; only score tags (score_1..score_9) keep the underscore (${JSON.stringify(text)})`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=promptTags.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melite/models-anima",
-  "version": "0.1.4-alpha",
+  "version": "0.1.5-pre-alpha",
   "license": "SSPL-1.0",
   "type": "module",
   "exports": {
@@ -11,8 +11,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@melite/comfyui-cordis": "0.1.4-alpha",
-    "@melite/comfyui-card-kit": "0.1.4-alpha"
+    "@melite/comfyui-card-kit": "0.1.5-pre-alpha"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",