@melite/image-tagger 0.2.0-alpha → 0.2.3-rc.4

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.
Files changed (3) hide show
  1. package/README.md +2 -6
  2. package/package.json +27 -14
  3. package/src/card.ts +199 -0
package/README.md CHANGED
@@ -1,15 +1,11 @@
1
- ---
2
- description: Caption-and-tag card over four tagger families — wd14, joytag, florence2, and joycaption.
3
- kind: package-library
4
- ---
5
-
6
1
  # @melite/image-tagger
7
2
 
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.
3
+ `@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`), which the manifest spells again as the explicit `./card` door; there is no tool or client face.
9
4
 
10
5
  ## Contract
11
6
 
12
7
  - `.` — 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).
8
+ - `./card` — the same card module as the root face, re-exported as the explicit named door (one file, two specifiers).
13
9
  - `./package.json` — the manifest.
14
10
 
15
11
  ## Model Experience
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
- "version": "0.2.0-alpha",
2
+ "version": "0.2.3-rc.4",
3
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 (no tool face, no ui/, no agents/ — the view is constructed by @melite/card-base from the emission)",
5
+ "description": "Caption-and-tag card over four tagger families — wd14, joytag, florence2, and joycaption.",
6
6
  "exports": {
7
7
  ".": {
8
8
  "types": "./lib/card.d.ts",
@@ -16,31 +16,44 @@
16
16
  },
17
17
  "dependencies": {
18
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"
25
- },
26
- "devDependencies": {
27
- "@types/node": "^22.20.0",
28
- "typescript": "^5.9.3",
29
- "@deepseek-ai/cordis": "^4.0.5"
19
+ "@melite/comfyui-card-kit": "0.2.3-rc.4",
20
+ "@melite/models-florence2": "0.2.3-rc.4",
21
+ "@melite/models-joycaption": "0.2.3-rc.4",
22
+ "@melite/models-wd14": "0.2.3-rc.4",
23
+ "@melite/contracts": "0.2.3-rc.4",
24
+ "@melite/models-joytag": "0.2.3-rc.4"
30
25
  },
31
26
  "name": "@melite/image-tagger",
32
27
  "files": [
33
28
  "lib/card.js",
34
29
  "lib/**/*.js",
35
- "lib/**/*.d.ts"
30
+ "lib/**/*.d.ts",
31
+ "src/card.ts",
32
+ "src/agents"
36
33
  ],
37
34
  "peerDependencies": {
38
35
  "@deepseek-ai/cordis": "^4.0.5"
39
36
  },
37
+ "repository": {
38
+ "type": "git",
39
+ "url": "https://github.com/JayDataEngineer/melite.git",
40
+ "directory": "packages/image/tagger"
41
+ },
42
+ "keywords": [
43
+ "melite",
44
+ "comfyui",
45
+ "cordis",
46
+ "agent",
47
+ "media-generation",
48
+ "library"
49
+ ],
40
50
  "scripts": {
41
51
  "build": "tsc -p tsconfig.build.json",
42
52
  "typecheck": "tsc --noEmit"
43
53
  },
54
+ "engines": {
55
+ "node": ">=22.18.0"
56
+ },
44
57
  "publishConfig": {
45
58
  "access": "public"
46
59
  }
package/src/card.ts ADDED
@@ -0,0 +1,199 @@
1
+ import type {} from '@melite/comfyui-card-kit/card-definition'
2
+ import type {} from '@melite/comfyui-card-kit/service-faces'
3
+ // Tier 3 — the tagger card (the wd14_t1 / joytag_t1 / florence2_t1 /
4
+ // joycaption_t1 renderer ports; the image prompt-inversion card).
5
+ // Decl + admission + family dispatch — the four arms live in their
6
+ // OWN families' declared actions (packages/models/{wd14,joytag,
7
+ // florence2,joycaption}/src/actions.ts, each pinned to a committed
8
+ // golden); the kit keeps only the shared SaveText tail and the
9
+ // caption vocabularies this card serves. The lane is weightless,
10
+ // every wire value comes from params.
11
+ import type { Context } from '@melite/comfyui-card-kit/card-definition'
12
+ import z from '@deepseek-ai/schemastery'
13
+ import { declaredAction, finalizeTagger, TAGGER_CAPTION_TASKS, TAGGER_CAPTION_TYPES, TAGGER_CAPTION_LENGTHS, TAGGER_EXTRA_OPTIONS, instantiateAction } from '@melite/comfyui-card-kit'
14
+ import { vocabulary } from '@melite/comfyui-card-kit/vocab'
15
+ import { bag } from '@melite/contracts/extraKeys'
16
+ import { DECL as wd14Decl } from '@melite/models-wd14'
17
+ import { DECL as joytagDecl } from '@melite/models-joytag'
18
+ import { DECL as florence2Decl } from '@melite/models-florence2'
19
+ import { DECL as joycaptionDecl } from '@melite/models-joycaption'
20
+ import type { ModelFacts } from '@melite/comfyui-card-kit/facts'
21
+ import type { GraphBuilder } from '@melite/comfyui-card-kit/graph'
22
+ import { inputImageExtra } from '@melite/comfyui-card-kit/fields'
23
+ import { callableSchema, gatedResolve } from '@melite/comfyui-card-kit/admission'
24
+
25
+ // THE FAMILY BINDINGS (the atom vocabulary, stroke 3): each boarded
26
+ // family's declared action composes — the card delegates, never
27
+ // authors nodes. Keyed by OWNING FAMILY (`model.family ?? model.id`
28
+ // at dispatch — a route id keys nothing, the derived-row law); an
29
+ // unbound family refuses loud at the dispatch.
30
+ export const ACTION_BINDINGS: Record<string, (p: Record<string, unknown>, model: ModelFacts, g: GraphBuilder, runId: string) => void> = {
31
+ [wd14Decl.id]: (p, model, g, runId) => {
32
+ instantiateAction(declaredAction(wd14Decl, 'tag'), p, model, g, runId)
33
+ },
34
+ [joytagDecl.id]: (p, model, g, runId) => {
35
+ instantiateAction(declaredAction(joytagDecl, 'tag'), p, model, g, runId)
36
+ },
37
+ [florence2Decl.id]: (p, model, g, runId) => {
38
+ instantiateAction(declaredAction(florence2Decl, 'tag'), p, model, g, runId)
39
+ },
40
+ [joycaptionDecl.id]: (p, model, g, runId) => {
41
+ instantiateAction(declaredAction(joycaptionDecl, 'tag'), p, model, g, runId)
42
+ },
43
+ }
44
+
45
+ // requiresByFamily: declared on the seam owner
46
+ // (card-definition.ts:64, moved there 2026-11-05 per the card-UI
47
+ // audit's A15 — boundary types live with their owner, not as local
48
+ // module augmentations at each consumer).
49
+
50
+ // the wire param surface (TaggerCard — the union vocab; each arm
51
+ // wires its subset). Ride keys carry NO .default (ABSENT: the
52
+ // compose-door cascade overlays model defaults, then explicit
53
+ // params): input_image is required (refused blank in compose);
54
+ // exclude_tags/add_tag/remove_tag/extra_option are defaultless
55
+ // optionals, each backfilled by the families whose arms read it
56
+ // (wd14→exclude_tags, joytag→add_tag/remove_tag,
57
+ // joycaption→extra_option). Bare z.string() is the image-gen prompt
58
+ // precedent (optional at parse, refused loud at compose).
59
+ // THE WEIGHTS LAW (2026-09-22 — the variant rail owns the
60
+ // checkpoint; the schema declares NO weights knob): Model/Variant/
61
+ // Quant is the ONE picker — the validate layer stamps the selected
62
+ // variant's resolver_defaults into the body (stampCardOverlay,
63
+ // absent-keys-only), the compose door overlays the family default,
64
+ // the lane reads p.checkpoint. The key rides `admits` below (the
65
+ // input-prep crop/media_type/scale precedent: admitted route stamps,
66
+ // never rendered). A card-level checkpoint knob — select or text —
67
+ // is a second picker around the card system and is forbidden here.
68
+ // JoyCaption's upstream takes any repo id or local path, so its
69
+ // family keeps ONE Standard variant on the family default; custom
70
+ // paths ride explicit params (API/bare bodies).
71
+ const schema = z.object({
72
+ input_image: z.string().role('path').description("Input image").extra('extra', bag(inputImageExtra({ tooltip: 'The image to invert. Absolute mount path or artifact ref.' }))),
73
+ // FAMILY-SCOPED NUMBERS (the 2026-11-12 refused-face burn: a
74
+ // number knob with no floor on the families that never read it
75
+ // rendered "undefined — REFUSED: not a number"). Every knob
76
+ // scopes to the families whose declared action consumes it
77
+ // (wd14: threshold/character_threshold/exclude_tags/
78
+ // replace_underscore/trailing_comma; joytag: threshold/add_tag/
79
+ // remove_tag; florence2: caption_task; joycaption: caption_type/
80
+ // caption_length/extra_option) — an unscoped number is a
81
+ // refused face waiting to happen, a scoped one never renders
82
+ // for the family that has no floor for it.
83
+ 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)." })),
84
+ 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)." })),
85
+ 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)." })),
86
+ 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)." })),
87
+ 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)." })),
88
+ 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)." })),
89
+ 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)." })),
90
+ 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' })),
91
+ 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' })),
92
+ // the FORM subset (the named six) of the kit's full set (which
93
+ // also carries the node's 20-260 word counts, for bare/API
94
+ // bodies) — a named subset, never a retyped copy that can
95
+ // drift from the node's own vocabulary (the card-plane
96
+ // audit's H2)
97
+ 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' })),
98
+ // the FULL kit list: the card had retyped a 14-option subset and
99
+ // one entry had ALREADY drifted into a truncated fork of the
100
+ // upstream canned string, which rode verbatim into the node
101
+ // (the card-plane audit's H2 — the one entry proved it)
102
+ 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' })),
103
+ // NO filename_prefix (card: "the run routes outputs by run id
104
+ // (compose stamps `<run>/tags`) — a user knob here was silently
105
+ // overwritten, a dead promise"). Old drafts naming it still parse
106
+ // (schemastery non-strict object + the door's explicit-params
107
+ // overlay) and compose never reads it.
108
+ })
109
+
110
+ const schemaFn = callableSchema(schema)
111
+
112
+ export const inject = ['comfyui']
113
+
114
+ // THE IDENTITY RUNG (native 2026-09-10 — migrated from the frozen
115
+ // identity ring; the card owns its label/description/genre/icon).
116
+ export const identity = {
117
+ label: 'Tagger',
118
+ description: 'Image prompt inversion — booru keyword tags (WD14, JoyTag) and natural-language captions (Florence-2, JoyCaption) for recreating images in NovelAI / Pony / FLUX / Ideogram. Tags persist as a tags.txt run artifact.',
119
+ genre: 'image',
120
+ icon: 'tag',
121
+ principles: [
122
+ 'input_image is required — the tag is anchored on it (absolute mount path or a prior-run artifact ref)',
123
+ 'threshold is the general-tag confidence floor; character_threshold is the person-identity floor (higher — names are cheap to overclaim)',
124
+ 'exclude_tags prunes what you already know is wrong — comma-separated, matched case-insensitively by the node',
125
+ 'The lane outputs tags.txt (SaveText) — the queue trades in artifacts, not bare strings',
126
+ 'First run downloads the WD14 weights (.onnx + .csv) — light ONNX lane, ~4 GB VRAM',
127
+ "JoyTag reads a pack-local checkpoint (no auto-download) and takes add/remove tag lists instead of WD14's character floor",
128
+ ],
129
+ }
130
+
131
+ export function apply(ctx: Context): void {
132
+ ctx.effect(() => ctx.comfyui.registerCard({
133
+ id: 'tagger',
134
+ // stage-row id the compose emits (purge S-decls verdict: the
135
+ // retired row carried "" — engine truth wins).
136
+ skeleton: 'tagger',
137
+ // the four boarded families (derived — the DECL ids are the
138
+ // one spelling; RULE 5).
139
+ boarded: [wd14Decl.id, joytagDecl.id, florence2Decl.id, joycaptionDecl.id],
140
+ tags: ['image', 'tag', 'analyze'],
141
+ identity,
142
+ // THE DISCOVERY ROWS (migrated 2026-09-10 from the frozen
143
+ // discovery export — the card owns its sidebar, surface, and
144
+ // flow-stage declarations; the discovery arms derive from here).
145
+ sidebar: { key: 'image', order: 19 },
146
+ flowKinds: {
147
+ inputs: { input_image: 'image' },
148
+ outputs: { default: 'text' },
149
+ requiresModel: false,
150
+ },
151
+ // THE SAVETEXT BINDING (the tagger publish-plane gap, 2026-10-24):
152
+ // the default channel resolves to the arm's SaveText mint — every
153
+ // arm ends in the shared taggerSaveText tail (one SaveText per
154
+ // graph), so the '*' wildcard (resolveCardFlowOutputs takes the
155
+ // LAST node of the class — the h3-timeline SaveVideo precedent)
156
+ // names the producer on both the single and merge paths. Without
157
+ // it the merge path resolved {} and the assert passed vacuously.
158
+ flowOutputBindings: [
159
+ { channel: 'default', node: '*', nodeClass: 'SaveText' },
160
+ ],
161
+ // Per-family gates (requires_by_family declaration — each arm's
162
+ // pack is checked only for its own family; a wd14 run never
163
+ // demands the florence pack). The flat list carries the UNION
164
+ // for flat consumers; the door gates the ACTIVE family's slice
165
+ // (gateway _find_card_requires precedent).
166
+ requires: ['ComfyUI-WD14-Tagger', 'Comfyui_joytag', 'ComfyUI-Florence2', 'joycaption_comfyui'],
167
+ requiresByFamily: {
168
+ wd14: ['ComfyUI-WD14-Tagger'],
169
+ joytag: ['Comfyui_joytag'],
170
+ florence2: ['ComfyUI-Florence2'],
171
+ joycaption: ['joycaption_comfyui'],
172
+ },
173
+ schema: schemaFn,
174
+ // checkpoint rides admits (the service's admission-extras law):
175
+ // the variant rail's route stamp, admitted but never rendered —
176
+ // no form field, no second picker.
177
+ admits: ['checkpoint'],
178
+ compose(p, model, g, runId) {
179
+ // THE SCHEMA GATE (the audio-trio admission precedent — the
180
+ // card's own declaration validates the last hop into the
181
+ // engine): schemastery walk enforces declared types + bounds
182
+ // (threshold/character_threshold are 0–1 — a threshold=5 draft
183
+ // refuses LOUD here, never composes), fills declared defaults.
184
+ // The composer's reads below are reads of the GATED doc.
185
+ const doc = gatedResolve('tagger', schemaFn, ['checkpoint', 'model'], p)
186
+ const img = typeof doc.input_image === 'string' ? doc.input_image : ''
187
+ if (!img.trim()) {
188
+ throw new Error("required param 'input_image' missing or blank on the tagger card (the tagger inverts an image; nothing to tag is a refusal)")
189
+ }
190
+ const bound = ACTION_BINDINGS[model.family ?? model.id]
191
+ if (bound) bound(doc, model, g, runId)
192
+ else {
193
+ throw new Error(
194
+ `no declared action for family '${String(model.family ?? model.id)}' on the tagger card — every boarded family (wd14, joytag, florence2, joycaption) composes its own declared segment; this address owns none`)
195
+ }
196
+ },
197
+ finalize: finalizeTagger,
198
+ }))
199
+ }