@melite/image-tagger 0.1.4-alpha → 0.2.0-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 ADDED
@@ -0,0 +1,36 @@
1
+ ---
2
+ description: Caption-and-tag card over four tagger families — wd14, joytag, florence2, and joycaption.
3
+ kind: package-library
4
+ ---
5
+
6
+ # @melite/image-tagger
7
+
8
+ `@melite/image-tagger` is the image captioning card (`id: 'tagger'`): one image in, a caption or tag list out as a `tags.txt` run artifact. Four families board, each through its own declared `tag` action: `wd14`, `joytag`, `florence2`, and `joycaption`. The lane is weightless — models load, nothing else computes. The package's single source module is the root face the cardPackages SSOT composes (`@melite/image-tagger`); there is no tool or client face.
9
+
10
+ ## Contract
11
+
12
+ - `.` — the card definition and registration (the root module carries `inject = ['comfyui']`). Schema: `input_image` (required); `threshold` — the general-tag confidence floor; `character_threshold` — the person-identity floor, deliberately higher; and four defaultless optionals backfilled per family: `exclude_tags` (wd14), `add_tag`/`remove_tag` (joytag), and `extra_option` (joycaption). Ride keys carry NO `.default` — the model picks the floor by default, the caller overrides explicitly. The per-family requirement map is declared here by augmenting `CardDefinition` (`requiresByFamily`), and the SaveText tail plus the caption vocabularies (`TAGGER_CAPTION_TASKS`, `TAGGER_CAPTION_TYPES`, `TAGGER_CAPTION_LENGTHS`, `TAGGER_EXTRA_OPTIONS`) come from `@melite/comfyui-card-kit`. There is NO weights knob — the Model/Variant/Quant rail is the only picker, and validation stamps `resolver_defaults` (absent keys only).
13
+ - `./package.json` — the manifest.
14
+
15
+ ## Model Experience
16
+
17
+ ### Request context and condition
18
+
19
+ A run conditions the tagger graph only when the card composes; no agent tool face ships.
20
+
21
+ #### What the model sees
22
+
23
+ The active tagger model receives `input_image` plus the gated thresholds and the family's tag knobs as graph inputs.
24
+
25
+ #### Token effect
26
+
27
+ zero-direct — the package contributes no prompt or schema to any language-model context.
28
+
29
+ #### KV Cache effect
30
+
31
+ independent — nothing here appends to or reshapes a session cache.
32
+
33
+ ## Known Limitations and Deferred Work
34
+
35
+ - **No weights knob** — the variant rail owns checkpoints; the 2026-09-22 weights-law removal is total.
36
+ - **Per-family key subsets** — each optional tag key backfills on exactly one family; asking a key of the wrong family refuses rather than ignoring.
package/lib/card.d.ts CHANGED
@@ -1,15 +1,7 @@
1
- import type { Context } from '@deepseek-ai/cordis';
1
+ import type { Context } from '@melite/comfyui-card-kit/card-definition';
2
2
  import type { ModelFacts } from '@melite/comfyui-card-kit/facts';
3
3
  import type { GraphBuilder } from '@melite/comfyui-card-kit/graph';
4
4
  export declare const ACTION_BINDINGS: Record<string, (p: Record<string, unknown>, model: ModelFacts, g: GraphBuilder, runId: string) => void>;
5
- declare module '@melite/comfyui-cordis/service' {
6
- interface CardDefinition {
7
- /** Per-family extension packs — the requires_by_family declaration.
8
- * The compose door gates the active family's slice, never the
9
- * flat union alone. */
10
- requiresByFamily?: Record<string, readonly string[]>;
11
- }
12
- }
13
5
  export declare const inject: string[];
14
6
  export declare const identity: {
15
7
  label: string;
package/lib/card.js CHANGED
@@ -6,7 +6,8 @@ import { DECL as wd14Decl } from '@melite/models-wd14';
6
6
  import { DECL as joytagDecl } from '@melite/models-joytag';
7
7
  import { DECL as florence2Decl } from '@melite/models-florence2';
8
8
  import { DECL as joycaptionDecl } from '@melite/models-joycaption';
9
- import { gatedResolve } from '@melite/comfyui-cordis';
9
+ import { inputImageExtra } from '@melite/comfyui-card-kit/fields';
10
+ import { callableSchema, gatedResolve } from '@melite/comfyui-card-kit/admission';
10
11
  // THE FAMILY BINDINGS (the atom vocabulary, stroke 3): each boarded
11
12
  // family's declared action composes — the card delegates, never
12
13
  // authors nodes. Keyed by OWNING FAMILY (`model.family ?? model.id`
@@ -26,6 +27,10 @@ export const ACTION_BINDINGS = {
26
27
  instantiateAction(declaredAction(joycaptionDecl, 'tag'), p, model, g, runId);
27
28
  },
28
29
  };
30
+ // requiresByFamily: declared on the seam owner
31
+
32
+ // audit's A15 — boundary types live with their owner, not as local
33
+ // module augmentations at each consumer).
29
34
  // the wire param surface (TaggerCard — the union vocab; each arm
30
35
  // wires its subset). Ride keys carry NO .default (ABSENT: the
31
36
  // compose-door cascade overlays model defaults, then explicit
@@ -48,39 +53,44 @@ export const ACTION_BINDINGS = {
48
53
  // family keeps ONE Standard variant on the family default; custom
49
54
  // paths ride explicit params (API/bare bodies).
50
55
  const schema = z.object({
51
- input_image: z.string().role('path').description("Input image").extra('extra', bag({ order: 0, group: "input", width: 1, tooltip: "The image to invert. Absolute mount path or artifact ref.", required: true, wtype: 'image', })),
52
- threshold: z.number().description("Threshold").min(0).max(1).step(0.05).default(0.35).extra('extra', bag({ order: 1, group: "tagger", width: 1, tooltip: "General-tag confidence floor." })),
53
- character_threshold: z.number().description("Character threshold").min(0).max(1).step(0.05).default(0.85).extra('extra', bag({ order: 2, group: "tagger", width: 1, tooltip: "Character-tag confidence floor — keep high." })),
54
- exclude_tags: z.string().description("Exclude tags").extra('extra', bag({ order: 3, group: "tagger", width: 1, tooltip: "Comma-separated tags to prune from the output." })),
55
- replace_underscore: z.boolean().description("Replace underscores").default(false).extra('extra', bag({ order: 4, group: "tagger", width: 1, tooltip: "Emit \"silver hair\" instead of \"silver_hair\"." })),
56
- trailing_comma: z.boolean().description("Trailing comma").default(false).extra('extra', bag({ order: 5, group: "tagger", width: 1, tooltip: "Terminate the tag list with a comma (prompt-paste shape)." })),
57
- add_tag: z.string().description("Add tag").extra('extra', bag({ order: 6, group: "tagger", width: 1, tooltip: "JoyTag: tags force-prepended to the output (comma-separated). Ignored by WD14." })),
58
- remove_tag: z.string().description("Remove tag").extra('extra', bag({ order: 7, group: "tagger", width: 1, tooltip: "JoyTag: tags pruned from the output (comma-separated). Ignored by WD14." })),
59
- caption_task: vocabulary([...TAGGER_CAPTION_TASKS]).description("Caption task").default("more_detailed_caption").extra('extra', bag({ order: 8, group: "tagger", width: 1, tooltip: "Florence-2: the vision task (live task vocabulary). Ignored by WD14/JoyTag.", wtype: 'select' })),
60
- caption_type: vocabulary([...TAGGER_CAPTION_TYPES]).description("Caption style").default("Descriptive").extra('extra', bag({ order: 9, group: "tagger", width: 1, tooltip: "JoyCaption: the caption template (live vocabulary). Ignored by WD14/JoyTag/Florence-2.", wtype: 'select' })),
56
+ input_image: z.string().role('path').description("Input image").extra('extra', bag(inputImageExtra({ tooltip: 'The image to invert. Absolute mount path or artifact ref.' }))),
57
+
58
+ // number knob with no floor on the families that never read it
59
+ // rendered "undefined — REFUSED: not a number"). Every knob
60
+ // scopes to the families whose declared action consumes it
61
+ // (wd14: threshold/character_threshold/exclude_tags/
62
+ // replace_underscore/trailing_comma; joytag: threshold/add_tag/
63
+ // remove_tag; florence2: caption_task; joycaption: caption_type/
64
+ // caption_length/extra_option) — an unscoped number is a
65
+ // refused face waiting to happen, a scoped one never renders
66
+ // for the family that has no floor for it.
67
+ threshold: z.number().description("Threshold").min(0).max(1).step(0.05).extra('extra', bag({ order: 1, group: "tagger", width: 1, families: ["wd14", "joytag"], tooltip: "General-tag confidence floor (WD14 + JoyTag)." })),
68
+ character_threshold: z.number().description("Character threshold").min(0).max(1).step(0.05).extra('extra', bag({ order: 2, group: "tagger", width: 1, families: ["wd14"], tooltip: "Character-tag confidence floor — keep high (WD14 only)." })),
69
+ exclude_tags: z.string().description("Exclude tags").extra('extra', bag({ order: 3, group: "tagger", width: 1, families: ["wd14"], tooltip: "Comma-separated tags to prune from the output (WD14 only)." })),
70
+ replace_underscore: z.boolean().description("Replace underscores").extra('extra', bag({ order: 4, group: "tagger", width: 1, families: ["wd14"], tooltip: "Emit \"silver hair\" instead of \"silver_hair\" (WD14 only)." })),
71
+ trailing_comma: z.boolean().description("Trailing comma").extra('extra', bag({ order: 5, group: "tagger", width: 1, families: ["wd14"], tooltip: "Terminate the tag list with a comma (prompt-paste shape; WD14 only)." })),
72
+ add_tag: z.string().description("Add tag").extra('extra', bag({ order: 6, group: "tagger", width: 1, families: ["joytag"], tooltip: "JoyTag: tags force-prepended to the output (comma-separated)." })),
73
+ remove_tag: z.string().description("Remove tag").extra('extra', bag({ order: 7, group: "tagger", width: 1, families: ["joytag"], tooltip: "JoyTag: tags pruned from the output (comma-separated)." })),
74
+ caption_task: vocabulary([...TAGGER_CAPTION_TASKS]).default("more_detailed_caption").description("Caption task").extra('extra', bag({ order: 8, group: "tagger", width: 1, families: ["florence2"], tooltip: "Florence-2: the vision task (live task vocabulary).", wtype: 'select' })),
75
+ caption_type: vocabulary([...TAGGER_CAPTION_TYPES]).default("Descriptive").description("Caption style").extra('extra', bag({ order: 9, group: "tagger", width: 1, families: ["joycaption"], tooltip: "JoyCaption: the caption template (live vocabulary).", wtype: 'select' })),
61
76
  // the FORM subset (the named six) of the kit's full set (which
62
77
  // also carries the node's 20-260 word counts, for bare/API
63
78
  // bodies) — a named subset, never a retyped copy that can
64
79
  // drift from the node's own vocabulary (the card-plane
65
80
  // audit's H2)
66
- caption_length: vocabulary([...TAGGER_CAPTION_LENGTHS]).description("Caption length").default("long").extra('extra', bag({ order: 10, group: "tagger", width: 1, tooltip: "JoyCaption: target length (the named six; the node also takes word counts 20-260, which bare/API bodies may send). Ignored by other families.", wtype: 'select' })),
81
+ caption_length: vocabulary([...TAGGER_CAPTION_LENGTHS]).default("long").description("Caption length").extra('extra', bag({ order: 10, group: "tagger", width: 1, families: ["joycaption"], tooltip: "JoyCaption: target length (the named six; the node also takes word counts 20-260, which bare/API bodies may send).", wtype: 'select' })),
67
82
  // the FULL kit list: the card had retyped a 14-option subset and
68
83
  // one entry had ALREADY drifted into a truncated fork of the
69
84
  // upstream canned string, which rode verbatim into the node
70
85
  // (the card-plane audit's H2 — the one entry proved it)
71
- extra_option: vocabulary([...TAGGER_EXTRA_OPTIONS]).description("Extra instruction").extra('extra', bag({ order: 11, group: "tagger", width: 1, tooltip: "JoyCaption: one appended instruction (the full 27-option list rides bare/API bodies; the engine's own vulgar-caption row is dropped at this surface — release hygiene). Ignored by other families.", wtype: 'select' })),
86
+ extra_option: vocabulary([...TAGGER_EXTRA_OPTIONS]).default("").description("Extra instruction").extra('extra', bag({ order: 11, group: "tagger", width: 1, families: ["joycaption"], tooltip: "JoyCaption: one appended instruction (the full 27-option list rides bare/API bodies; the engine's own vulgar-caption row is dropped at this surface — release hygiene).", wtype: 'select' })),
72
87
  // NO filename_prefix (card: "the run routes outputs by run id
73
88
  // (compose stamps `<run>/tags`) — a user knob here was silently
74
89
  // overwritten, a dead promise"). Old drafts naming it still parse
75
90
  // (schemastery non-strict object + the door's explicit-params
76
91
  // overlay) and compose never reads it.
77
92
  });
78
- /** The schema's callable face — ONE cast serving both seams (the
79
- * registration's schema carrier and the compose strict resolve's
80
- * judge): schemastery schemas are callable (Schema.resolve) but
81
- * carry a typed data parameter, while both card-seam consumers
82
- * take unknown. */
83
- const schemaFn = schema;
93
+ const schemaFn = callableSchema(schema);
84
94
  export const inject = ['comfyui'];
85
95
 
86
96
  // identity ring; the card owns its label/description/genre/icon).
@@ -118,6 +128,16 @@ export function apply(ctx) {
118
128
  outputs: { default: 'text' },
119
129
  requiresModel: false,
120
130
  },
131
+
132
+ // the default channel resolves to the arm's SaveText mint — every
133
+ // arm ends in the shared taggerSaveText tail (one SaveText per
134
+ // graph), so the '*' wildcard (resolveCardFlowOutputs takes the
135
+ // LAST node of the class — the h3-timeline SaveVideo precedent)
136
+ // names the producer on both the single and merge paths. Without
137
+ // it the merge path resolved {} and the assert passed vacuously.
138
+ flowOutputBindings: [
139
+ { channel: 'default', node: '*', nodeClass: 'SaveText' },
140
+ ],
121
141
  // Per-family gates (requires_by_family declaration — each arm's
122
142
  // pack is checked only for its own family; a wd14 run never
123
143
  // demands the florence pack). The flat list carries the UNION
package/package.json CHANGED
@@ -1,29 +1,32 @@
1
1
  {
2
- "version": "0.1.4-alpha",
3
- "license": "SSPL-1.0",
2
+ "version": "0.2.0-alpha",
3
+ "license": "AGPL-3.0-or-later",
4
4
  "type": "module",
5
- "description": "the tagger card (the image lane) — one card one package: card.ts host face + ui/ studio + agents/ context",
5
+ "description": "the tagger card (the image lane) — one card one package: card.ts host face (no tool face, no ui/, no agents/ — the view is constructed by @melite/card-base from the emission)",
6
6
  "exports": {
7
7
  ".": {
8
8
  "types": "./lib/card.d.ts",
9
9
  "default": "./lib/card.js"
10
10
  },
11
- "./package.json": "./package.json"
11
+ "./package.json": "./package.json",
12
+ "./card": {
13
+ "types": "./lib/card.d.ts",
14
+ "default": "./lib/card.js"
15
+ }
12
16
  },
13
17
  "dependencies": {
14
- "@deepseek-ai/schemastery": "^3.18.4",
15
- "@melite/comfyui-card-kit": "0.1.4-alpha",
16
- "@melite/comfyui-cordis": "0.1.4-alpha",
17
- "@melite/models-joytag": "0.1.4-alpha",
18
- "@melite/models-joycaption": "0.1.4-alpha",
19
- "@melite/models-florence2": "0.1.4-alpha",
20
- "@melite/contracts": "0.1.4-alpha",
21
- "@melite/models-wd14": "0.1.4-alpha"
18
+ "@deepseek-ai/schemastery": "^3.18.5",
19
+ "@melite/comfyui-card-kit": "0.2.0-alpha",
20
+ "@melite/contracts": "0.2.0-alpha",
21
+ "@melite/models-florence2": "0.2.0-alpha",
22
+ "@melite/models-wd14": "0.2.0-alpha",
23
+ "@melite/models-joycaption": "0.2.0-alpha",
24
+ "@melite/models-joytag": "0.2.0-alpha"
22
25
  },
23
26
  "devDependencies": {
24
27
  "@types/node": "^22.20.0",
25
28
  "typescript": "^5.9.3",
26
- "@deepseek-ai/cordis": "^4.0.4"
29
+ "@deepseek-ai/cordis": "^4.0.5"
27
30
  },
28
31
  "name": "@melite/image-tagger",
29
32
  "files": [
@@ -32,7 +35,7 @@
32
35
  "lib/**/*.d.ts"
33
36
  ],
34
37
  "peerDependencies": {
35
- "@deepseek-ai/cordis": "^4.0.4"
38
+ "@deepseek-ai/cordis": "^4.0.5"
36
39
  },
37
40
  "scripts": {
38
41
  "build": "tsc -p tsconfig.build.json",