@mcptoolshop/style-dataset-lab 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.2.0] - 2026-04-16
+
+### Added
+
+- **Training + implementation spine** -- complete model-asset pipeline from export package to trained asset
+  - `sdlab training-profile list/show` -- training profile management (what kind of model asset to produce)
+  - `sdlab training-manifest create/validate/show/list` -- frozen training contracts with export hash and config fingerprint
+  - `sdlab training-package build/show/list` -- trainer-ready packages with adapter boundary
+  - `sdlab eval-run create/score/show/list` -- score generated outputs against eval packs, produce scorecards
+  - `sdlab implementation-pack build/show/list` -- prompt examples, known failures, subject continuity, reingest guide
+  - `sdlab reingest generated/audit` -- re-ingest accepted generated outputs as new records with provenance
+- **Adapter system** for trainer-specific packaging:
+  - `generic-image-caption` -- image folders + metadata JSONL
+  - `diffusers-lora` -- image + caption .txt sidecars for diffusers fine-tuning
+- **Two starter training profiles** for Star Freight: `character-style-lora`, `environment-mood-lora`
+- **New library modules:** `lib/training-profiles.js`, `lib/training-manifests.js`, `lib/training-packages.js`, `lib/eval-runs.js`, `lib/implementation-packs.js`, `lib/reingest.js`, `lib/adapters/generic-image-caption.js`, `lib/adapters/diffusers-lora.js`
+
+### Key properties
+
+- Training manifests are frozen -- if config, export, or profile changes, a new manifest is required
+- Adapters transform layout but never mutate inclusion or split truth
+- Generated outputs re-enter through normal review (no bypass)
+- Every eval run links back to a training manifest and eval pack (no orphans)
+
 ## [2.1.0] - 2026-04-16
 
 ### Added

package/README.es.md

@@ -13,158 +13,187 @@
 
 # style-dataset-lab
 
-Una canalización de producción para la creación de conjuntos de datos visuales: desde reglas establecidas hasta indicaciones estructuradas, pasando por la generación con ComfyUI, hasta la creación de datos de entrenamiento curados y sujetos a reglas.
+Convierta el material visual aprobado en conjuntos de datos versionados, respaldados por revisiones, divisiones, paquetes de exportación y paquetes de evaluación.
 
 ## ¿Qué es esto?
 
-Una **canalización** para la creación de conjuntos de datos visuales de entrenamiento estructurados. Se definen reglas de estilo (establecidas), se crean indicaciones, se genera contenido con ComfyUI, se realiza una curación con puntuación por dimensión, se asocian juicios a las reglas establecidas y se exporta en 10 formatos a través de [`@mcptoolshop/repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset).
+Una **línea de producción de conjuntos de datos y un canon visual**. Defina cómo se verá su proyecto. Seleccione cuidadosamente de acuerdo con las reglas establecidas. Cree paquetes de conjuntos de datos reproducibles con divisiones seguras contra fugas de información. Genere paquetes de evaluación para la verificación futura del modelo.
 
-La canalización es independiente del juego. Cada juego tiene su propio directorio de datos dentro de `games/<nombre>/`; los 13 scripts y las plantillas vacías se comparten. Cada activo generado contiene tres elementos:
+La línea de producción genera cuatro elementos:
 
-1. **Píxeles de la imagen** -- generados por ComfyUI con información completa de origen (checkpoint, LoRA, semilla, sampler, cfg).
-2. **Explicación de la regla establecida** -- la razón por la cual la imagen es o no está de acuerdo con el estilo definido, basada en una constitución de estilo.
-3. **Juicio de calidad** -- aprobado/rechazado con puntuaciones por dimensión y reglas citadas.
+| Elemento | ¿Qué es? |
+|----------|-----------|
+| **Snapshot** | Selección de registros elegibles, congelada y con huella digital. Cada inclusión tiene un registro explícito de la razón. |
+| **Split** | Partición segura contra fugas de información para entrenamiento/validación/prueba. Los registros que comparten una misma familia siempre se incluyen en la misma división. |
+| **Export package** | Conjunto de datos autónomo: manifiesto, metadatos, imágenes, divisiones, descripción del conjunto de datos y sumas de verificación. |
+| **Eval pack** | Tareas de verificación que respetan el canon: cobertura de categorías, desviación prohibida, referencia/estándar, coherencia temática. |
 
-## Modelo de seguridad
-
-**Solo local.** style-dataset-lab se comunica con ComfyUI en `localhost:8188` y nunca realiza solicitudes a la red externa. No hay telemetría, ni análisis, ni conexión a servidores externos. La generación de imágenes se realiza completamente en su GPU. Los registros y los datos de la regla establecida permanecen en su sistema de archivos.
-
-## ¿Qué incluye el paquete npm?
-
-`npm install @mcptoolshop/style-dataset-lab` le proporciona:
+Cada elemento en la línea de producción contiene tres cosas:
 
-- **13 scripts** -- para generar, curar, comparar, asociar a la regla establecida, generar imágenes con estilo pictórico, generar identidades, generar imágenes con ControlNet/IP-Adapter, curación masiva, migración.
-- **Plantillas vacías** -- una constitución de inicio, una rúbrica de revisión y un paquete de ejemplos de indicaciones en `templates/`.
+1. **Origen** -- historial completo de generación (punto de control, LoRA, semilla, muestreador, configuración, tiempo de ejecución)
+2. **Cumplimiento del canon** -- qué reglas establecidas cumple, no cumple o cumple parcialmente este elemento.
+3. **Evaluación de calidad** -- aprobado/rechazado/límite con puntuaciones por dimensión.
 
-El paquete npm **no** incluye datos del juego. Clone el repositorio si desea el ejemplo de Star Freight (1182 registros, 28 oleadas de indicaciones, 18 categorías visuales).
+Funciona para arte de juegos, diseño de personajes, diseño de criaturas, arquitectura, conceptos de vehículos/mecánica y cualquier dominio donde la producción visual deba mantenerse dentro de los parámetros establecidos.
 
-## Instalación
+## Comienzo rápido
 
 ```bash
-# Get the pipeline scripts + templates
-npm install @mcptoolshop/style-dataset-lab
+# Install the CLI + pipeline
+npm install -g @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
+# Scaffold a new project
+sdlab init my-project --domain character-design
+
+# Validate the project structure
+sdlab project doctor --project my-project
 ```
 
-Para comenzar un nuevo juego a partir de las plantillas:
+Dominios disponibles: `game-art`, `character-design`, `creature-design`, `architecture`, `vehicle-mech` o `generic`.
+
+## Interfaz de línea de comandos (CLI)
 
 ```bash
-# 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
+sdlab init <name> [--domain <domain>]     # Scaffold a new project
+sdlab project doctor [--project <name>]   # Validate project config
+
+sdlab generate <pack> [--project <name>]  # Generate candidates via ComfyUI
+sdlab generate:identity <packet>          # Named-subject identity images
+sdlab generate:controlnet                 # ControlNet-guided generation
+sdlab generate:ipadapter                  # IP-Adapter reference-guided
+
+sdlab curate <id> <status> <explanation>  # Record review judgment
+sdlab compare <a> <b> <winner> <reason>   # Pairwise A-vs-B comparison
+sdlab bind [--project <name>]             # Bind records to constitution rules
+sdlab painterly [--project <name>]        # Post-processing style pass
+
+sdlab snapshot create [--profile <name>]  # Create frozen dataset snapshot
+sdlab snapshot list                       # List all snapshots
+sdlab snapshot diff <a> <b>               # Compare two snapshots
+sdlab eligibility audit                   # Audit record training eligibility
+sdlab split build [--snapshot <id>]       # Build train/val/test split
+sdlab split audit <id>                    # Audit split for leakage + balance
+sdlab card generate                       # Generate dataset card (md + JSON)
+sdlab export build [--snapshot <id>]      # Build versioned export package
+sdlab eval-pack build                     # Build canon-aware eval pack
 ```
 
-## Estructura del monorepositorio
+Todos los comandos aceptan `--project <nombre>` (por defecto: `star-freight`).
+
+## Modelo del proyecto
 
-La canalización se encuentra en `scripts/` y `templates/`. Cada juego se encuentra en `games/<nombre>/` con su propia regla establecida, registros y activos. Los scripts aceptan `--game <nombre>` (por defecto, `star-freight`).
+Cada proyecto es un directorio autónomo dentro de `projects/` con su propio canon, configuración y datos:
 
 ```
-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
+projects/
+  my-project/
+    project.json            Project identity + generation defaults
+    constitution.json       Rules array with rationale templates
+    lanes.json              Subject lanes with detection patterns
+    rubric.json             Scoring dimensions + thresholds
+    terminology.json        Group vocabulary + detection order
+    canon/                  Style constitution (markdown)
+    records/                Per-asset JSON (provenance + judgment + canon)
+    inputs/prompts/         Prompt packs (JSON)
+    outputs/                Generated images (gitignored)
+    comparisons/            A-vs-B preference judgments
+    snapshots/              Frozen dataset snapshots
+    splits/                 Train/val/test partitions
+    exports/                Versioned export packages
+    eval-packs/             Canon-aware eval instruments
 ```
 
-## Flujo de trabajo de la canalización
+## Línea de producción
 
-La canalización completa, desde la regla establecida hasta la exportación para el entrenamiento:
-
-```bash
-# 1. Write your canon -- style constitution + review rubric
-#    (start from templates/ or write from scratch)
+```
+canon → generate → curate → bind → snapshot → split → export → eval
+  |        |          |        |        |         |        |       |
+rules   ComfyUI   judgment  rules   frozen    subject  package  verify
+                                    selection isolation
+```
 
-# 2. Create prompt packs in inputs/prompts/
-#    (see templates/inputs/prompts/example-wave.json)
+1. **Definir el canon** -- escriba su constitución de estilo y rúbrica de revisión.
+2. **Generar** -- ComfyUI genera candidatos con un origen completo.
+3. **Seleccionar** -- apruebe/rechace con puntuaciones por dimensión y modos de fallo.
+4. **Vincular** -- vincule cada elemento a las reglas establecidas con veredictos de cumplimiento/incumplimiento/parcial.
+5. **Captura** -- congele los registros elegibles en una selección determinista y con huella digital.
+6. **Dividir** -- particione en entrenamiento/validación/prueba con aislamiento temático y equilibrio de categorías.
+7. **Exportar** -- cree un paquete autónomo con manifiesto, metadatos, imágenes y sumas de verificación.
+8. **Evaluar** -- genere instrumentos de prueba que respeten el canon para la verificación del modelo.
 
-# 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
+La conversión de formato a formatos posteriores (TRL, LLaVA, Parquet, etc.) se gestiona mediante [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset). `sdlab` es responsable de la veracidad del conjunto de datos; `repo-dataset` lo convierte en formatos especializados.
 
-# 4. Generate identity-packet characters (named subjects)
-npm run generate:identity -- --game star-freight inputs/identity-packets/wave27a.json
+## Plantillas de dominio
 
-# 5. Curate -- approve, reject, or mark borderline
-npm run curate -- --game star-freight <asset_id> approved "explanation"
-npm run curate -- --game star-freight <asset_id> rejected "explanation" --failures "too_clean"
+Cada plantilla de dominio incluye definiciones de categorías, reglas establecidas, rúbricas de puntuación y estructuras de terminología diseñadas para ese contexto de producción:
 
-# 6. Generate painterly variants of approved assets
-npm run painterly -- --game star-freight
+| Dominio | Categorías | Preocupaciones clave |
+|--------|-------|-------------|
+| **game-art** | personaje, entorno, accesorio, interfaz de usuario, nave, interior, equipo | Silueta a escala de juego, diferenciación de facciones, desgaste/envejecimiento |
+| **character-design** | retrato, cuerpo entero, vista de 360 grados, hoja de expresiones, pose de acción | Precisión de las proporciones, lógica del vestuario, interpretación de la personalidad, claridad de los gestos |
+| **creature-design** | concepto, ortográfico, estudio de detalles, acción, referencia de escala, hábitat | Plausibilidad anatómica, lógica evolutiva, distinción de siluetas |
+| **architecture** | exterior, interior, paisaje urbano, detalle estructural, ruina, paisaje | Plausibilidad estructural, consistencia de materiales, perspectiva, coherencia de la época |
+| **vehicle-mech** | exterior, cabina, componente, esquema, hoja de siluetas, variante de daño | Lógica mecánica, lenguaje de diseño funcional, puntos de acceso, descripción de daños. |
 
-# 7. Bind canon explanations to curated assets
-npm run canon-bind -- --game star-freight
+## Producción del conjunto de datos
 
-# 8. Record pairwise comparisons
-npm run compare -- --game star-freight <asset_a> <asset_b> a "A has better faction read"
+Estructura completa del conjunto de datos: instantánea, división, exportación, evaluación.
 
-# 9. Export training data via repo-dataset
-repo-dataset visual generate ./games/star-freight --format trl
-repo-dataset visual inspect ./games/star-freight
+```
+snapshot  -->  split  -->  export  -->  eval-pack
+   |            |            |             |
+  frozen     subject      package       canon-aware
+  selection  isolation    (manifest,    test instruments
+             + lane       metadata,     (4 task types)
+             balance      images,
+                          checksums,
+                          card)
 ```
 
-## Añadir un nuevo juego
+Las **instantáneas** congelan una selección determinista de registros elegibles. Cada inclusión tiene un registro de la razón. Las huellas de configuración garantizan la reproducibilidad.
+
+Las **divisiones** asignan los registros a particiones de entrenamiento/validación/prueba, con aislamiento de sujetos (ninguna familia de sujetos aparece en múltiples divisiones) y distribución equilibrada por "carril". Un generador de números pseudoaleatorios con semilla garantiza resultados idénticos a partir de la misma semilla.
+
+Los **paquetes de exportación** son autocontenidos: manifiesto, metadata.jsonl, imágenes (enlaces simbólicos o copias), divisiones, tarjeta del conjunto de datos (Markdown + JSON) y sumas de verificación en formato BSD. Todo lo necesario para reconstruir el conjunto de datos desde cero.
+
+Los **paquetes de evaluación** son instrumentos de prueba que tienen en cuenta el canon y que incluyen cuatro tipos de tareas: cobertura de "carriles", deriva prohibida, anclaje/referencia y continuidad del sujeto. Demuestran que la estructura del conjunto de datos está alimentando futuras evaluaciones de modelos, y no solo se están volviendo a depositar archivos.
+
+Exportación a formatos posteriores a través de [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) (TRL, LLaVA, Qwen2-VL, JSONL, Parquet, y más). `repo-dataset` se encarga de la conversión de formatos; `sdlab` es responsable de la integridad del conjunto de datos.
+
+## Ejemplo de Star Freight
+
+Clona el repositorio para obtener un ejemplo de funcionamiento completo: 1182 registros, 28 oleadas de indicaciones, 5 facciones, 7 "carriles", 24 reglas constitucionales y 892 activos aprobados de un RPG de ciencia ficción.
 
 ```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
+git clone https://github.com/mcp-tool-shop-org/style-dataset-lab
+cd style-dataset-lab
+
+# Validate the project
+sdlab project doctor --project star-freight
 
-# Edit your canon/constitution.md and canon/review-rubric.md
-# Edit your prompt pack, then run the pipeline with --game my-game
+# Run the full dataset spine
+sdlab snapshot create --project star-freight    # 839 eligible records
+sdlab split build --project star-freight        # ~80/10/10, zero leakage
+sdlab export build --project star-freight       # package with checksums
+sdlab eval-pack build --project star-freight    # 78 eval records
 ```
 
-## Estructura del directorio por juego
+## Migración desde la versión 1.x
 
-Cada directorio `games/<nombre>/` contiene:
+La versión 2.0 cambia el nombre de `games/` a `projects/` y `--game` a `--project`:
 
-```
-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-guides/       ControlNet guide overlays
-  identity-packets/     Named character identity spines
-outputs/
-  candidates/           Raw generations (gitignored)
-  approved/             Curated approved (gitignored)
-  rejected/             Curated rejected (gitignored)
-  borderline/           Curated borderline (gitignored)
-  painterly/            Painterly-style variants (gitignored)
-records/                Per-asset JSON (provenance + judgment + canon binding)
-comparisons/            A-vs-B preference judgments
-exports/                repo-dataset output (gitignored)
-```
+```bash
+# Rename your data directory
+mv games projects
 
-## Configuración de la generación
-
-```yaml
-checkpoint: dreamshaperXL_v21TurboDPMSDE.safetensors
-lora: classipeintxl_v21.safetensors (weight: 1.0)
-resolution: 1024x1024
-steps: 8
-cfg: 2.0
-sampler: dpmpp_sde
-scheduler: karras
-speed: ~9s per image (RTX 5080)
+# --game still works with a deprecation warning (removed in v3.0)
+sdlab bind --game star-freight   # works, prints warning
+sdlab bind --project star-freight # canonical form
 ```
 
-Modos de generación adicionales: ControlNet (guiado por pose/profundidad), IP-Adapter (guiado por referencia) y paquetes de identidad (consistencia de personajes nombrados).
+## Modelo de seguridad
+
+**Solo local.** Se comunica con ComfyUI en `localhost:8188`. No hay telemetría, ni análisis, ni solicitudes externas. Las imágenes permanecen en tu GPU y sistema de archivos.
 
 ## Requisitos