@mcptoolshop/style-dataset-lab 1.1.0 → 1.2.1

package/README.pt-BR.md

@@ -13,91 +13,133 @@
 
 # style-dataset-lab
 
-Ferramenta para criação de conjuntos de dados visuais – gera, organiza e exporta dados de treinamento multimodais para o ajuste fino de modelos de linguagem visuais (VLM).
+Uma linha de produção para a criação de conjuntos de dados visuais – desde regras predefinidas até prompts estruturados, passando pela geração no ComfyUI, até dados de treinamento selecionados e vinculados a regras predefinidas.
 
 ## O que é isso
 
-Um conjunto de ferramentas para construir a "verdade visual" que pode ser usada para treinamento. Cada elemento contém três coisas:
+Uma **linha de produção** para a criação de conjuntos de dados visuais estruturados para treinamento. Você define regras de estilo (regras predefinidas), compõe prompts, gera imagens com o ComfyUI, seleciona os resultados com base em critérios específicos, associa as avaliações às regras predefinidas e exporta em 10 formatos através do [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset).
+
+A linha de produção é independente de qualquer jogo específico. Cada jogo possui seu próprio diretório de dados em `games/<nome>/`; os 13 scripts e modelos vazios são compartilhados. Cada ativo gerado contém três elementos.
 
 1. **Pixels da imagem** – gerados pelo ComfyUI com total rastreabilidade (checkpoint, LoRA, seed, sampler, cfg).
 2. **Explicação detalhada** – por que este elemento está ou não de acordo com o estilo definido, com base em uma "constituição" de estilo.
 3. **Avaliação de qualidade** – aprovado/rejeitado, com pontuações por dimensão e regras citadas.
 
-A saída é integrada ao [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) para produzir dados de treinamento multimodais em 10 formatos: TRL, LLaVA, Qwen2-VL, Axolotl, LLaMA-Factory, ShareGPT, pares para RLHF, DPO, legendagem e classificação.
-
 ## Modelo de segurança
 
 **Apenas local.** O style-dataset-lab se comunica com o ComfyUI em `localhost:8188` e nunca faz solicitações de rede externas. Sem telemetria, sem análise, sem envio de dados. A geração de imagens ocorre inteiramente na sua GPU. Os registros e os dados de referência permanecem no seu sistema de arquivos.
 
-## Estatísticas do conjunto de dados
+## O que o pacote npm oferece:
+
+`npm install @mcptoolshop/style-dataset-lab` fornece:
 
-| Métrica | Valor |
-|--------|-------|
-| Registros organizados | 1,182 |
-| Total de elementos | 2.571 (893 aprovados, 887 variações com estilo pictórico) |
-| Variações de prompts | 28 |
-| Categorias visuais | 18 (roupas, navios, interiores, equipamentos, ambientes, espécies, estações, sinalização, iluminação, carga, arquitetura, criaturas, superfícies, vida cotidiana, planetas, danos/reparos, biologia alienígena, detalhes realistas) |
-| Comparativos | 6 criados por humanos + 71 criados sinteticamente |
-| Tipos de rejeição distintos | 30+ |
-| Sistema de pacotes de identidade | Personagens nomeados com DNA de facção, patente e referências visuais. |
-| Formatos de exportação | 10 (via @mcptoolshop/repo-dataset) |
+- **13 scripts** – para geração, seleção, comparação, vinculação a regras predefinidas, estilo pictórico, geração de identidade, geração ControlNet/IP-Adapter, seleção em massa, migração.
+- **Modelos vazios** – um modelo inicial, um guia de avaliação e um conjunto de exemplos de prompts, localizados em `templates/`.
+
+O pacote npm **não** inclui dados de jogos. Clone o repositório se você quiser o exemplo do Star Freight (1.182 registros, 28 sequências de prompts, 18 categorias visuais).
 
 ## Instalação
 
 ```bash
-npm install -g @mcptoolshop/style-dataset-lab
+# Get the pipeline scripts + templates
+npm install @mcptoolshop/style-dataset-lab
+
+# Or clone the repo for the Star Freight example data
+git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
+cd style-dataset-lab
+npm install
 ```
 
-Em seguida, clone um projeto ou inicialize um novo espaço de trabalho para conjuntos de dados:
+Para iniciar um novo jogo a partir dos modelos:
 
 ```bash
-git clone https://github.com/mcp-tool-shop-org/style-dataset-lab my-dataset
-cd my-dataset
-npm install
+# Copy templates into your game directory
+mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
+cp -r templates/canon games/my-game/canon
+cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
+# Edit the canon and prompts, then generate
+```
+
+## Estrutura do monorepository
+
+A linha de produção está localizada nos diretórios `scripts/` e `templates/`. Cada jogo está em `games/<nome>/`, com suas próprias regras predefinidas, registros e ativos. Os scripts aceitam o argumento `--game <nome>` (o padrão é `star-freight`).
+
+```
+style-dataset-lab/
+  scripts/                  13 pipeline scripts (generate, curate, compare, etc.)
+  templates/                Blank starting point for new games
+    canon/                  Starter constitution + review rubric
+    inputs/prompts/         Example prompt pack
+  games/
+    star-freight/           Star Freight example (1,182 records, repo-only)
+      canon/                Style constitution, review rubric, species canon
+      records/              Per-asset JSON (provenance + judgment + canon)
+      comparisons/          A-vs-B preference judgments
+      inputs/               Prompt packs, identity packets, references
+      outputs/              Generated images (gitignored)
+      exports/              repo-dataset output (gitignored)
+    <your-game>/            Add more games with the same structure
 ```
 
-## Fluxo de trabalho
+## Fluxo de trabalho da linha de produção
+
+A linha de produção completa, desde as regras predefinidas até a exportação para treinamento:
 
 ```bash
-# 1. Start ComfyUI
-# (point it at your checkpoint + LoRA setup)
+# 1. Write your canon -- style constitution + review rubric
+#    (start from templates/ or write from scratch)
 
-# 2. Generate candidates from a prompt pack
-npm run generate -- inputs/prompts/wave1.json
-npm run generate -- inputs/prompts/wave1.json --dry-run
+# 2. Create prompt packs in inputs/prompts/
+#    (see templates/inputs/prompts/example-wave.json)
 
-# 3. Generate identity-packet characters
-npm run generate:identity -- inputs/identity-packets/wave27a-identity-spine.json
+# 3. Start ComfyUI and generate candidates
+npm run generate -- --game star-freight inputs/prompts/wave1.json
+npm run generate -- --game star-freight inputs/prompts/wave1.json --dry-run
 
-# 4. Generate painterly variants of approved assets
-npm run painterly -- <asset_id>
+# 4. Generate identity-packet characters (named subjects)
+npm run generate:identity -- --game star-freight inputs/identity-packets/wave27a.json
 
 # 5. Curate -- approve, reject, or mark borderline
-npm run curate -- <asset_id> approved "explanation" --scores "silhouette:0.9,palette:0.8"
-npm run curate -- <asset_id> rejected "explanation" --failures "too_clean,wrong_material"
+npm run curate -- --game star-freight <asset_id> approved "explanation"
+npm run curate -- --game star-freight <asset_id> rejected "explanation" --failures "too_clean"
+
+# 6. Generate painterly variants of approved assets
+npm run painterly -- --game star-freight
+
+# 7. Bind canon explanations to curated assets
+npm run canon-bind -- --game star-freight
 
-# 6. Bind canon explanations to assets
-npm run canon-bind -- <asset_id>
+# 8. Record pairwise comparisons
+npm run compare -- --game star-freight <asset_a> <asset_b> a "A has better faction read"
 
-# 7. Record pairwise comparisons
-npm run compare -- <asset_a> <asset_b> a "A has better faction read because..."
+# 9. Export training data via repo-dataset
+repo-dataset visual generate ./games/star-freight --format trl
+repo-dataset visual inspect ./games/star-freight
+```
+
+## Adicionando um novo jogo
 
-# 8. Export training data via repo-dataset
-npm run export
-npm run inspect
-npm run validate
+```bash
+# Create structure and copy blank templates
+mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
+cp -r templates/canon games/my-game/canon
+cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
+
+# Edit your canon/constitution.md and canon/review-rubric.md
+# Edit your prompt pack, then run the pipeline with --game my-game
 ```
 
-## Estrutura de diretórios
+## Estrutura do diretório por jogo
+
+Cada diretório `games/<nome>/` contém:
 
 ```
-canon/                  Style constitution, review rubric, identity gates, species canon
+canon/                  Style constitution, review rubric, species canon, identity gates
 inputs/
   prompts/              Prompt packs per wave (JSON: subjects, variations, defaults)
   references/           IP-Adapter reference images
-  control/              ControlNet control images
   control-guides/       ControlNet guide overlays
-  identity-packets/     Named character identity spines (faction DNA, rank, visual anchors)
+  identity-packets/     Named character identity spines
 outputs/
   candidates/           Raw generations (gitignored)
   approved/             Curated approved (gitignored)
@@ -107,8 +149,6 @@ outputs/
 records/                Per-asset JSON (provenance + judgment + canon binding)
 comparisons/            A-vs-B preference judgments
 exports/                repo-dataset output (gitignored)
-scripts/                generate, curate, compare, canon-bind, painterly, identity gen
-workflows/              Reusable ComfyUI workflow templates
 ```
 
 ## Configuração de geração

package/README.zh.md

@@ -13,91 +13,133 @@
 
 # style-dataset-lab
 
-视觉数据集工厂 -- 用于生成、整理和导出多模态训练数据，以进行大型视觉语言模型（VLM）的微调。
+一个用于创建视觉数据集的生产流水线，从规范规则到结构化提示，再到 ComfyUI 生成，最终得到经过筛选、符合规范的训练数据。
 
 ## 这是什么
 
-一个用于**构建可训练的视觉真理**的工具集。每个资源都包含以下三方面：
+一个用于构建结构化视觉训练数据集的**流水线**。 您可以编写风格规则（规范），编写提示，使用 ComfyUI 生成图像，并根据每个维度进行评分进行筛选，将判断结果与规范规则关联，并通过 [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) 以 10 种格式导出。
 
-1. **图像像素** -- 由 ComfyUI 生成，并包含完整的溯源信息（检查点、LoRA、种子、采样器、CFG）。
-2. **规范解释** -- 解释为什么该图像符合或不符合特定风格，并基于风格规范进行判断。
-3. **质量评估** -- 经过批准/拒绝，并提供每个维度的评分以及引用规则。
+该流水线不依赖于特定的游戏。 每个游戏都有自己的数据目录，位于 `games/<name>/` 目录下；13 个脚本和空白模板是共享的。 每个生成的资源都包含以下三项：
 
-输出结果通过 [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) 生成多模态训练数据，提供 10 种格式：TRL、LLaVA、Qwen2-VL、Axolotl、LLaMA-Factory、ShareGPT、RLHF 对、DPO、图像描述和分类。
+1. **图像像素**：由 ComfyUI 生成，包含完整的溯源信息（检查点、LoRA、种子、采样器、CFG）。
+2. **规范解释**：解释为什么该图像符合或不符合风格，并基于风格规范进行说明。
+3. **质量判断**：通过批准/拒绝，并根据每个维度的评分引用相关规则。
 
 ## 安全模型
 
-**仅本地运行。** style-dataset-lab 只与本地 `localhost:8188` 上的 ComfyUI 进行通信，不会进行任何外部网络请求。没有遥测数据，没有分析功能，不会向外部发送数据。图像生成完全在您的 GPU 上进行。记录和规范数据都存储在您的文件系统中。
+**仅本地运行。** `style-dataset-lab` 只与本地 `localhost:8188` 上的 ComfyUI 进行通信，不会进行任何外部网络请求。 没有遥测数据，没有分析功能，不会向外部发送数据。 图像生成完全在您的 GPU 上进行。 记录和规范数据都存储在您的文件系统中。
 
-## 数据集统计信息
+## npm 包包含的内容
 
-| 指标 | 数值 |
-|--------|-------|
-| 整理记录 | 1,182 |
-| 总资源数 | 2,571 (其中 893 个已批准，887 个为绘画风格变体) |
-| 提示词组合 | 28 |
-| 视觉类别 | 18 种 (包括：服装、船只、室内、设备、环境、物种、站点、标识、照明、货物、**架构**、生物、表面、日常生活、行星、损坏/修复、外星生物、细节)。 |
-| 成对比较 | 6 个人工标注 + 71 个合成数据 |
-| 不同类型的拒绝 | 30+ |
-| 身份包系统 | 具有派系 DNA、等级和视觉特征的命名角色。 |
-| 导出格式 | 10 种 (通过 `@mcptoolshop/repo-dataset`) |
+`npm install @mcptoolshop/style-dataset-lab` 会为您提供：
+
+- **13 个脚本**：用于生成、筛选、比较、与规范关联、生成绘画风格图像、生成身份图像、使用 ControlNet/IP-Adapter 生成图像、批量筛选、数据迁移。
+- **空白模板**：位于 `templates/` 目录下，包含起始规范、审查标准和示例提示包。
+
+该 npm 包**不包含**游戏数据。 如果您想使用 Star Freight 示例，请克隆该仓库（包含 1182 条记录，28 个提示集，18 个视觉类别）。
 
 ## 安装
 
 ```bash
-npm install -g @mcptoolshop/style-dataset-lab
+# Get the pipeline scripts + templates
+npm install @mcptoolshop/style-dataset-lab
+
+# Or clone the repo for the Star Freight example data
+git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
+cd style-dataset-lab
+npm install
 ```
 
-然后克隆一个项目或初始化一个新的数据集工作区：
+要从模板开始一个新的游戏：
 
 ```bash
-git clone https://github.com/mcp-tool-shop-org/style-dataset-lab my-dataset
-cd my-dataset
-npm install
+# Copy templates into your game directory
+mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
+cp -r templates/canon games/my-game/canon
+cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
+# Edit the canon and prompts, then generate
+```
+
+## 单仓库结构
+
+流水线位于 `scripts/` 和 `templates/` 目录下。 每个游戏位于 `games/<name>/` 目录下，包含自己的规范、记录和资源。 脚本接受 `--game <name>` 参数（默认为 `star-freight`）。
+
 ```
+style-dataset-lab/
+  scripts/                  13 pipeline scripts (generate, curate, compare, etc.)
+  templates/                Blank starting point for new games
+    canon/                  Starter constitution + review rubric
+    inputs/prompts/         Example prompt pack
+  games/
+    star-freight/           Star Freight example (1,182 records, repo-only)
+      canon/                Style constitution, review rubric, species canon
+      records/              Per-asset JSON (provenance + judgment + canon)
+      comparisons/          A-vs-B preference judgments
+      inputs/               Prompt packs, identity packets, references
+      outputs/              Generated images (gitignored)
+      exports/              repo-dataset output (gitignored)
+    <your-game>/            Add more games with the same structure
+```
+
+## 流水线工作流程
 
-## 工作流程
+从规范到训练数据导出的完整流水线：
 
 ```bash
-# 1. Start ComfyUI
-# (point it at your checkpoint + LoRA setup)
+# 1. Write your canon -- style constitution + review rubric
+#    (start from templates/ or write from scratch)
 
-# 2. Generate candidates from a prompt pack
-npm run generate -- inputs/prompts/wave1.json
-npm run generate -- inputs/prompts/wave1.json --dry-run
+# 2. Create prompt packs in inputs/prompts/
+#    (see templates/inputs/prompts/example-wave.json)
 
-# 3. Generate identity-packet characters
-npm run generate:identity -- inputs/identity-packets/wave27a-identity-spine.json
+# 3. Start ComfyUI and generate candidates
+npm run generate -- --game star-freight inputs/prompts/wave1.json
+npm run generate -- --game star-freight inputs/prompts/wave1.json --dry-run
 
-# 4. Generate painterly variants of approved assets
-npm run painterly -- <asset_id>
+# 4. Generate identity-packet characters (named subjects)
+npm run generate:identity -- --game star-freight inputs/identity-packets/wave27a.json
 
 # 5. Curate -- approve, reject, or mark borderline
-npm run curate -- <asset_id> approved "explanation" --scores "silhouette:0.9,palette:0.8"
-npm run curate -- <asset_id> rejected "explanation" --failures "too_clean,wrong_material"
+npm run curate -- --game star-freight <asset_id> approved "explanation"
+npm run curate -- --game star-freight <asset_id> rejected "explanation" --failures "too_clean"
+
+# 6. Generate painterly variants of approved assets
+npm run painterly -- --game star-freight
 
-# 6. Bind canon explanations to assets
-npm run canon-bind -- <asset_id>
+# 7. Bind canon explanations to curated assets
+npm run canon-bind -- --game star-freight
 
-# 7. Record pairwise comparisons
-npm run compare -- <asset_a> <asset_b> a "A has better faction read because..."
+# 8. Record pairwise comparisons
+npm run compare -- --game star-freight <asset_a> <asset_b> a "A has better faction read"
 
-# 8. Export training data via repo-dataset
-npm run export
-npm run inspect
-npm run validate
+# 9. Export training data via repo-dataset
+repo-dataset visual generate ./games/star-freight --format trl
+repo-dataset visual inspect ./games/star-freight
 ```
 
-## 目录结构
+## 添加新的游戏
+
+```bash
+# Create structure and copy blank templates
+mkdir -p games/my-game/{records,comparisons,inputs/prompts,outputs/{candidates,approved,rejected,borderline,painterly},exports}
+cp -r templates/canon games/my-game/canon
+cp templates/inputs/prompts/example-wave.json games/my-game/inputs/prompts/wave1.json
+
+# Edit your canon/constitution.md and canon/review-rubric.md
+# Edit your prompt pack, then run the pipeline with --game my-game
+```
+
+## 每个游戏目录的布局
+
+每个 `games/<name>/` 目录包含：
 
 ```
-canon/                  Style constitution, review rubric, identity gates, species canon
+canon/                  Style constitution, review rubric, species canon, identity gates
 inputs/
   prompts/              Prompt packs per wave (JSON: subjects, variations, defaults)
   references/           IP-Adapter reference images
-  control/              ControlNet control images
   control-guides/       ControlNet guide overlays
-  identity-packets/     Named character identity spines (faction DNA, rank, visual anchors)
+  identity-packets/     Named character identity spines
 outputs/
   candidates/           Raw generations (gitignored)
   approved/             Curated approved (gitignored)
@@ -107,8 +149,6 @@ outputs/
 records/                Per-asset JSON (provenance + judgment + canon binding)
 comparisons/            A-vs-B preference judgments
 exports/                repo-dataset output (gitignored)
-scripts/                generate, curate, compare, canon-bind, painterly, identity gen
-workflows/              Reusable ComfyUI workflow templates
 ```
 
 ## 生成设置
@@ -124,7 +164,7 @@ scheduler: karras
 speed: ~9s per image (RTX 5080)
 ```
 
-其他生成模式：ControlNet（姿势/深度引导）、IP-Adapter（参考驱动）以及身份包（命名角色一致性）。
+其他生成模式：ControlNet（姿势/深度引导）、IP-Adapter（参考驱动）和身份包（用于保持角色一致性）。
 
 ## 要求
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mcptoolshop/style-dataset-lab",
-  "version": "1.1.0",
-  "description": "Visual dataset factory — generate, curate, and export multimodal training data for VLM fine-tuning",
+  "version": "1.2.1",
+  "description": "Visual dataset pipeline — canon to prompts to ComfyUI generation to curated, canon-bound training data",
   "type": "module",
   "scripts": {
     "generate": "node scripts/generate.js",
@@ -15,9 +15,7 @@
   },
   "files": [
     "scripts/",
-    "games/*/canon/",
-    "games/*/inputs/",
-    "package.json",
+    "templates/",
     "README.md",
     "LICENSE",
     "SECURITY.md",

package/templates/canon/constitution.md

@@ -0,0 +1,44 @@
+# Style Constitution
+
+> Define the visual rules that every generated asset must follow.
+> Each rule gets an ID, category, and description. The curation scripts score assets against these rules.
+
+## Core Rules
+
+### Silhouette & Shape Language
+
+- **SIL-01**: [Describe the silhouette requirements — what shapes define your style?]
+- **SIL-02**: [Describe faction/character shape differentiation]
+
+### Color & Palette
+
+- **COL-01**: [Describe the color rules — palette constraints, faction colors, mood]
+- **COL-02**: [Describe what colors are forbidden and why]
+
+### Material & Texture
+
+- **MAT-01**: [Describe material rules — worn vs clean, organic vs synthetic]
+- **MAT-02**: [Describe texture expectations — grit level, surface detail]
+
+### Composition & Framing
+
+- **CMP-01**: [Describe framing rules — camera angle, subject placement]
+
+### Mood & Atmosphere
+
+- **MOD-01**: [Describe the emotional tone — tense, serene, chaotic]
+
+## Scoring Dimensions
+
+Assets are scored 0.0–1.0 on each dimension during curation:
+
+| Dimension | What it measures |
+|-----------|-----------------|
+| silhouette | Shape language clarity and faction read |
+| palette | Color accuracy and mood alignment |
+| material | Surface texture and wear level |
+| composition | Framing and visual hierarchy |
+| mood | Emotional tone match |
+| detail | Level of meaningful detail |
+| consistency | Coherence with existing approved assets |
+| originality | Avoids generic/stock-art patterns |

package/templates/canon/review-rubric.md

@@ -0,0 +1,30 @@
+# Review Rubric
+
+## Quick Decision Tree
+
+1. Does the image pass the **style test**? (Would it look at home next to approved assets?)
+   - No → REJECT with cited rule violations
+2. Does it pass **all constitution rules** at ≥0.6 score?
+   - No → Check if fixable with img2img → BORDERLINE or REJECT
+3. Does it add **new signal** the dataset doesn't have?
+   - Yes → APPROVE
+   - No (duplicate composition/subject) → REJECT as redundant
+
+## Approval Criteria
+
+- All scoring dimensions ≥ 0.6
+- No critical rule violations
+- Adds value to the dataset (new subject, angle, or variation)
+
+## Rejection Criteria
+
+- Any scoring dimension < 0.4
+- Violates a core constitution rule
+- Too similar to existing approved assets
+- Generic/stock-art quality (no distinctive style)
+
+## Borderline Criteria
+
+- One or two dimensions between 0.4–0.6
+- Fixable with img2img post-processing
+- Strong composition but weak on style details

package/templates/inputs/prompts/example-wave.json

@@ -0,0 +1,27 @@
+{
+  "wave": "wave1",
+  "description": "First generation wave — core subjects for your visual style",
+  "defaults": {
+    "checkpoint": "dreamshaperXL_v21TurboDPMSDE.safetensors",
+    "lora": { "name": "classipeintxl_v21.safetensors", "weight": 1.0 },
+    "width": 1024,
+    "height": 1024,
+    "steps": 8,
+    "cfg": 2.0,
+    "sampler": "dpmpp_sde",
+    "scheduler": "karras",
+    "negative": "photorealistic, photograph, 3d render, smooth CG, sharp photo detail"
+  },
+  "subjects": [
+    {
+      "id": "subject_a",
+      "variations": 2,
+      "prompt": "oil painting, visible brushstrokes, [DESCRIBE YOUR SUBJECT HERE], painterly concept art, canvas grain"
+    },
+    {
+      "id": "subject_b",
+      "variations": 2,
+      "prompt": "oil painting, visible brushstrokes, [DESCRIBE YOUR SUBJECT HERE], painterly concept art, canvas grain"
+    }
+  ]
+}