@mcptoolshop/style-dataset-lab 2.0.0 → 2.2.0

package/lib/training-packages.js

@@ -0,0 +1,241 @@
+/**
+ * Training package builder.
+ *
+ * Builds trainer-ready dataset packages from training manifests.
+ * Adapters transform the canonical layout for specific training targets
+ * but never mutate inclusion or split truth.
+ */
+
+import { readFile, writeFile, mkdir, readdir, symlink, copyFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { existsSync } from 'node:fs';
+import { createHash, randomBytes } from 'node:crypto';
+import { loadTrainingManifest } from './training-manifests.js';
+import { loadTrainingProfile } from './training-profiles.js';
+import { loadSplitPartition } from './split.js';
+import { loadRecord } from './records.js';
+import { loadProjectConfig, detectLane, detectGroup } from './config.js';
+
+/**
+ * Generate a training package ID: tp-YYYYMMDD-HHMMSS-XXXX
+ */
+function generatePackageId() {
+  const now = new Date();
+  const date = now.toISOString().replace(/[-:T]/g, '').slice(0, 14);
+  const rand = randomBytes(2).toString('hex');
+  return `tp-${date.slice(0, 8)}-${date.slice(8, 14)}-${rand}`;
+}
+
+async function sha256File(filePath) {
+  const data = await readFile(filePath);
+  return createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * Load an adapter module by name.
+ */
+async function loadAdapter(adapterTarget) {
+  const adapterPath = `./adapters/${adapterTarget}.js`;
+  try {
+    return await import(adapterPath);
+  } catch {
+    throw new Error(
+      `Adapter "${adapterTarget}" not found. Available: generic-image-caption, diffusers-lora`
+    );
+  }
+}
+
+/**
+ * Build a training package from a manifest.
+ *
+ * @param {string} projectRoot
+ * @param {string} manifestId
+ * @param {Object} options — { copy?, adapterOverride? }
+ * @returns {Promise<{packageId: string, records: number, images: number}>}
+ */
+export async function buildTrainingPackage(projectRoot, manifestId, options = {}) {
+  const manifest = await loadTrainingManifest(projectRoot, manifestId);
+  const profile = await loadTrainingProfile(projectRoot, manifest.training_profile_id);
+  const config = loadProjectConfig(projectRoot);
+  const adapterTarget = options.adapterOverride || manifest.adapter_target;
+  const adapter = await loadAdapter(adapterTarget);
+
+  const recordsDir = join(projectRoot, 'records');
+  const packageId = generatePackageId();
+  const packageDir = join(projectRoot, 'training', 'packages', packageId);
+
+  // Load split partitions
+  const partitions = {};
+  let totalRecords = 0;
+  let totalImages = 0;
+
+  for (const partition of ['train', 'val', 'test']) {
+    const entries = await loadSplitPartition(projectRoot, manifest.source_split_id, partition);
+    const records = [];
+
+    for (const entry of entries) {
+      const record = await loadRecord(recordsDir, entry.record_id);
+      if (!record) continue;
+
+      // Filter by profile's eligible lanes
+      const prompt = record.provenance?.prompt || '';
+      const lane = detectLane(record.id, prompt, config.lanes);
+      if (profile.eligible_lanes.length > 0 && !profile.eligible_lanes.includes(lane)) {
+        continue;
+      }
+
+      const group = detectGroup(record.id, prompt, config.terminology);
+      records.push({ record, lane, group });
+    }
+
+    partitions[partition] = records;
+    totalRecords += records.length;
+  }
+
+  // Let the adapter build the package layout
+  const adapterResult = await adapter.buildPackage({
+    packageDir,
+    partitions,
+    profile,
+    manifest,
+    config,
+    projectRoot,
+    copy: options.copy || false,
+  });
+
+  totalImages = adapterResult.imageCount || 0;
+
+  // Generate checksums for all files in the package
+  const checksumEntries = [];
+  const allFiles = await collectFiles(packageDir);
+  for (const filePath of allFiles.sort()) {
+    const relPath = relative(packageDir, filePath);
+    if (relPath === 'checksums.txt') continue;
+    const hash = await sha256File(filePath);
+    checksumEntries.push(`SHA256 (${relPath}) = ${hash}`);
+  }
+  await writeFile(join(packageDir, 'checksums.txt'), checksumEntries.join('\n') + '\n');
+
+  // Write package manifest (last — references everything)
+  const packageManifest = {
+    training_package_id: packageId,
+    created_at: new Date().toISOString(),
+    created_by: 'sdlab-training-package-v1',
+    training_manifest_id: manifestId,
+    training_profile_id: manifest.training_profile_id,
+    adapter_target: adapterTarget,
+    source_export_id: manifest.source_export_id,
+    source_snapshot_id: manifest.source_snapshot_id,
+    source_split_id: manifest.source_split_id,
+    config_fingerprint: manifest.config_fingerprint,
+    counts: {
+      total_records: totalRecords,
+      train: partitions.train.length,
+      val: partitions.val.length,
+      test: partitions.test.length,
+      images: totalImages,
+      checksums: checksumEntries.length,
+    },
+  };
+  await writeFile(join(packageDir, 'manifest.json'), JSON.stringify(packageManifest, null, 2) + '\n');
+
+  // Write README
+  const readme = generatePackageReadme(packageManifest, profile, manifest, adapterTarget);
+  await writeFile(join(packageDir, 'README.md'), readme);
+
+  return { packageId, records: totalRecords, images: totalImages };
+}
+
+function generatePackageReadme(pkg, profile, manifest, adapter) {
+  return `# Training Package: ${pkg.training_package_id}
+
+**Profile:** ${profile.label} (${profile.profile_id})
+**Adapter:** ${adapter}
+**Target:** ${profile.target_family} / ${profile.asset_type}
+**Created:** ${pkg.created_at}
+
+## Source chain
+
+- Training manifest: \`${manifest.training_manifest_id}\`
+- Export: \`${manifest.source_export_id}\`
+- Snapshot: \`${manifest.source_snapshot_id}\`
+- Split: \`${manifest.source_split_id}\`
+- Config fingerprint: \`${manifest.config_fingerprint.slice(0, 16)}...\`
+
+## Counts
+
+| Partition | Records |
+|-----------|---------|
+| Train | ${pkg.counts.train} |
+| Val | ${pkg.counts.val} |
+| Test | ${pkg.counts.test} |
+| **Total** | **${pkg.counts.total_records}** |
+
+Images: ${pkg.counts.images}
+
+## Checksums
+
+All files in this package are checksummed in \`checksums.txt\` (BSD format).
+
+## Provenance
+
+This package was produced by [Style Dataset Lab](https://github.com/mcp-tool-shop-org/style-dataset-lab).
+Every included record has been human-reviewed, canon-bound, and verified against project constitution rules.
+The dataset split ensures no subject family appears in multiple partitions.
+`;
+}
+
+async function collectFiles(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await collectFiles(full));
+    } else {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * List all training packages.
+ */
+export async function listTrainingPackages(projectRoot) {
+  const dir = join(projectRoot, 'training', 'packages');
+  if (!existsSync(dir)) return [];
+
+  const entries = await readdir(dir, { withFileTypes: true });
+  const packages = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.startsWith('tp-')) continue;
+    const manifestPath = join(dir, entry.name, 'manifest.json');
+    if (!existsSync(manifestPath)) continue;
+    try {
+      const data = JSON.parse(await readFile(manifestPath, 'utf-8'));
+      packages.push({
+        id: data.training_package_id,
+        created_at: data.created_at,
+        profile: data.training_profile_id,
+        adapter: data.adapter_target,
+        records: data.counts.total_records,
+        images: data.counts.images,
+      });
+    } catch { /* skip */ }
+  }
+
+  return packages.sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+
+/**
+ * Load a training package manifest.
+ */
+export async function loadTrainingPackage(projectRoot, packageId) {
+  const path = join(projectRoot, 'training', 'packages', packageId, 'manifest.json');
+  if (!existsSync(path)) {
+    throw new Error(`Training package "${packageId}" not found at ${path}`);
+  }
+  return JSON.parse(await readFile(path, 'utf-8'));
+}

package/lib/training-profiles.js

@@ -0,0 +1,97 @@
+/**
+ * Training profile management.
+ *
+ * A training profile defines how a project wants to turn an export package
+ * into a trainable model asset. Profiles never select data directly — they
+ * define eligibility rules and packaging expectations.
+ */
+
+import { readFile, readdir, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+const REQUIRED_FIELDS = ['profile_id', 'label', 'target_family', 'asset_type', 'eligible_lanes', 'adapter_targets'];
+
+/**
+ * Validate a training profile object.
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateProfile(profile) {
+  const errors = [];
+  for (const field of REQUIRED_FIELDS) {
+    if (profile[field] === undefined || profile[field] === null) {
+      errors.push(`missing required field: ${field}`);
+    }
+  }
+  if (profile.eligible_lanes && !Array.isArray(profile.eligible_lanes)) {
+    errors.push('eligible_lanes must be an array');
+  }
+  if (profile.adapter_targets && !Array.isArray(profile.adapter_targets)) {
+    errors.push('adapter_targets must be an array');
+  }
+  if (profile.adapter_targets?.length === 0) {
+    errors.push('adapter_targets must have at least one target');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Load a training profile from a project.
+ */
+export async function loadTrainingProfile(projectRoot, profileId) {
+  const path = join(projectRoot, 'training', 'profiles', `${profileId}.json`);
+  if (!existsSync(path)) {
+    throw new Error(`Training profile "${profileId}" not found at ${path}`);
+  }
+  const data = JSON.parse(await readFile(path, 'utf-8'));
+  const { valid, errors } = validateProfile(data);
+  if (!valid) {
+    throw new Error(`Training profile "${profileId}" is invalid:\n  ${errors.join('\n  ')}`);
+  }
+  return data;
+}
+
+/**
+ * List all training profiles in a project.
+ */
+export async function listTrainingProfiles(projectRoot) {
+  const dir = join(projectRoot, 'training', 'profiles');
+  if (!existsSync(dir)) return [];
+
+  const files = (await readdir(dir)).filter(f => f.endsWith('.json')).sort();
+  const profiles = [];
+
+  for (const file of files) {
+    try {
+      const data = JSON.parse(await readFile(join(dir, file), 'utf-8'));
+      profiles.push({
+        profile_id: data.profile_id,
+        label: data.label,
+        target_family: data.target_family,
+        asset_type: data.asset_type,
+        lanes: data.eligible_lanes?.length || 0,
+        adapters: data.adapter_targets || [],
+      });
+    } catch {
+      // Skip malformed
+    }
+  }
+
+  return profiles;
+}
+
+/**
+ * Save a training profile to a project.
+ */
+export async function saveTrainingProfile(projectRoot, profile) {
+  const { valid, errors } = validateProfile(profile);
+  if (!valid) {
+    throw new Error(`Invalid training profile:\n  ${errors.join('\n  ')}`);
+  }
+  const dir = join(projectRoot, 'training', 'profiles');
+  await mkdir(dir, { recursive: true });
+  await writeFile(
+    join(dir, `${profile.profile_id}.json`),
+    JSON.stringify(profile, null, 2) + '\n'
+  );
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mcptoolshop/style-dataset-lab",
-  "version": "2.0.0",
-  "description": "Canon-bound visual dataset pipeline — define project canon, generate and curate assets, bind to constitution rules, export trustworthy training data",
+  "version": "2.2.0",
+  "description": "Visual canon and dataset production pipeline — snapshots, splits, versioned exports, eval packs, and canon-bound curation for any image production domain",
   "type": "module",
   "bin": {
     "sdlab": "./bin/sdlab.js"
@@ -28,16 +28,18 @@
   ],
   "keywords": [
     "dataset",
-    "visual",
+    "computer-vision",
     "training-data",
+    "image-dataset",
+    "evaluation",
+    "curation",
+    "canon",
+    "visual-development",
     "concept-art",
-    "visual-canon",
-    "art-direction",
-    "dataset-pipeline",
-    "comfyui",
-    "vlm",
-    "fine-tuning",
-    "multimodal"
+    "style-guide",
+    "lora",
+    "multimodal",
+    "comfyui"
   ],
   "homepage": "https://mcp-tool-shop-org.github.io/style-dataset-lab/",
   "repository": {

package/scripts/canon-bind.js

@@ -20,93 +20,7 @@ import { readFileSync, writeFileSync, readdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { getProjectName } from '../lib/args.js';
 import { REPO_ROOT } from '../lib/paths.js';
-import { loadConstitution, loadLanes, loadRubric, loadTerminology } from '../lib/config.js';
-
-// ─── Config-Driven Detection ────────────────────────────────────────
-
-/**
- * Detect lane from asset ID using project lane config.
- * Tests each lane's id_patterns as regex against the lowercase ID.
- * Returns the first match, or the default_lane.
- */
-function detectLane(id, prompt, lanesConfig) {
-  const lower = id.toLowerCase();
-  for (const lane of lanesConfig.lanes) {
-    if (!lane.id_patterns || lane.id_patterns.length === 0) continue;
-    for (const pattern of lane.id_patterns) {
-      if (new RegExp(pattern).test(lower)) return lane.id;
-    }
-  }
-  return lanesConfig.default_lane;
-}
-
-/**
- * Detect group (faction) from asset ID and prompt using terminology config.
- * Mirrors the exact detection order from the original hardcoded detectFaction():
- *   1. Primary ID patterns per group
- *   2. Cross-group patterns (e.g. ^cf_ → detect from ID suffix)
- *   3. Edge defaults (e.g. ^edge_ → compact)
- *   4. Prompt-based fallback patterns
- *   5. Null-faction patterns (generic rejects with no faction)
- *   6. ID fallback patterns (specific reject/borderline IDs)
- */
-function detectGroup(id, prompt, termConfig) {
-  // Explicit ordering for ID-based and prompt-based detection phases.
-  // These can differ — e.g. ID checks reach before keth, but prompt
-  // checks veshan before keth before orryn before reach.
-  const idOrder = termConfig.id_detection_order || Object.keys(termConfig.groups);
-  const promptOrder = termConfig.prompt_detection_order || Object.keys(termConfig.groups);
-
-  // 1. Primary ID patterns per group (id_detection_order)
-  for (const groupName of idOrder) {
-    const group = termConfig.groups[groupName];
-    if (!group?.id_patterns) continue;
-    for (const pattern of group.id_patterns) {
-      if (new RegExp(pattern).test(id)) return groupName;
-    }
-  }
-
-  // 2. Cross-group patterns
-  for (const [pattern, behavior] of Object.entries(termConfig.cross_group_patterns || {})) {
-    if (new RegExp(pattern).test(id)) {
-      if (behavior === 'detect_from_id_suffix') {
-        for (const groupName of idOrder) {
-          if (id.includes(groupName)) return groupName;
-        }
-      }
-      return null;
-    }
-  }
-
-  // 3. Edge defaults
-  for (const [pattern, groupName] of Object.entries(termConfig.edge_defaults || {})) {
-    if (new RegExp(pattern).test(id)) return groupName;
-  }
-
-  // 4. Prompt-based fallback (prompt_detection_order)
-  if (prompt) {
-    const p = prompt.toLowerCase();
-    for (const groupName of promptOrder) {
-      const group = termConfig.groups[groupName];
-      if (!group?.prompt_patterns || group.prompt_patterns.length === 0) continue;
-      for (const keyword of group.prompt_patterns) {
-        if (new RegExp(keyword).test(p)) return groupName;
-      }
-    }
-  }
-
-  // 5. Null-faction patterns (generic rejects — no faction)
-  for (const pattern of termConfig.null_faction_patterns || []) {
-    if (new RegExp(pattern).test(id)) return null;
-  }
-
-  // 6. ID fallback patterns
-  for (const [pattern, groupName] of Object.entries(termConfig.id_fallbacks || {})) {
-    if (new RegExp(pattern).test(id)) return groupName;
-  }
-
-  return null;
-}
+import { loadConstitution, loadLanes, loadRubric, loadTerminology, detectLane, detectGroup } from '../lib/config.js';
 
 /**
  * Build rationale string from rule's template, interpolating variables.

package/scripts/card.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+/**
+ * card.js — Generate dataset cards.
+ *
+ * Usage:
+ *   sdlab card generate --snapshot <id> --split <id> [--project <name>]
+ */
+
+import { join } from 'node:path';
+import { writeFile } from 'node:fs/promises';
+import { getProjectName } from '../lib/args.js';
+import { REPO_ROOT } from '../lib/paths.js';
+import { listSnapshots } from '../lib/snapshot.js';
+import { listSplits } from '../lib/split.js';
+import { generateCard } from '../lib/card.js';
+
+export async function run(argv = process.argv.slice(2)) {
+  const projectName = getProjectName(argv);
+  const projectRoot = join(REPO_ROOT, 'projects', projectName);
+  const subcommand = argv.find(a => !a.startsWith('--')) || 'generate';
+  const args = argv.filter(a => a !== subcommand);
+
+  if (subcommand === 'generate') {
+    // Find snapshot
+    let snapshotId;
+    const snapIdx = args.indexOf('--snapshot');
+    if (snapIdx >= 0) {
+      snapshotId = args[snapIdx + 1];
+    } else {
+      const snapshots = await listSnapshots(projectRoot);
+      if (snapshots.length === 0) throw new Error('No snapshots found. Run: sdlab snapshot create');
+      snapshotId = snapshots[snapshots.length - 1].id;
+    }
+
+    // Find split
+    let splitId;
+    const splitIdx = args.indexOf('--split');
+    if (splitIdx >= 0) {
+      splitId = args[splitIdx + 1];
+    } else {
+      const splits = await listSplits(projectRoot);
+      if (splits.length === 0) throw new Error('No splits found. Run: sdlab split build');
+      splitId = splits[splits.length - 1].id;
+    }
+
+    console.log(`\x1b[1msdlab card generate\x1b[0m — ${projectName}`);
+    console.log(`  Snapshot: ${snapshotId}`);
+    console.log(`  Split:    ${splitId}`);
+    console.log('');
+
+    const { markdown, json } = await generateCard(projectRoot, snapshotId, splitId);
+
+    // Write to project root
+    const mdPath = join(projectRoot, 'dataset-card.md');
+    const jsonPath = join(projectRoot, 'dataset-card.json');
+    await writeFile(mdPath, markdown);
+    await writeFile(jsonPath, JSON.stringify(json, null, 2) + '\n');
+
+    console.log(`  \x1b[32m✓\x1b[0m dataset-card.md`);
+    console.log(`  \x1b[32m✓\x1b[0m dataset-card.json`);
+
+  } else {
+    throw new Error(`Unknown subcommand: ${subcommand}. Use: generate`);
+  }
+}
+
+if (process.argv[1] && (process.argv[1].endsWith('card.js') || process.argv[1].endsWith('card'))) {
+  run().catch((err) => {
+    console.error(err.message || err);
+    process.exit(1);
+  });
+}

package/scripts/doctor.js

@@ -33,6 +33,14 @@ const REQUIRED_DIRS = [
   'outputs/approved',
   'outputs/rejected',
   'exports',
+  'snapshots',
+  'splits',
+  'eval-packs',
+  'training/profiles',
+  'training/manifests',
+  'training/packages',
+  'training/eval-runs',
+  'training/implementations',
 ];
 
 function pass(msg) { console.log(`  \x1b[32m✓\x1b[0m ${msg}`); }

package/scripts/eligibility.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+/**
+ * eligibility.js — Audit training/eval eligibility for all project records.
+ *
+ * Usage:
+ *   sdlab eligibility audit [--project <name>]
+ */
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getProjectName } from '../lib/args.js';
+import { REPO_ROOT } from '../lib/paths.js';
+import { loadProjectConfig, loadSelectionProfile } from '../lib/config.js';
+import { evaluateEligibility, categorizeExclusions } from '../lib/eligibility.js';
+
+export async function run(argv = process.argv.slice(2)) {
+  const projectName = getProjectName(argv);
+  const projectRoot = join(REPO_ROOT, 'projects', projectName);
+
+  const profileIdx = argv.indexOf('--profile');
+  const profileId = profileIdx >= 0 ? argv[profileIdx + 1] : null;
+  const profile = loadSelectionProfile(projectRoot, profileId);
+  const config = loadProjectConfig(projectRoot);
+
+  const recordsDir = join(projectRoot, 'records');
+  const files = (await readdir(recordsDir)).filter(f => f.endsWith('.json')).sort();
+
+  console.log(`\x1b[1msdlab eligibility audit\x1b[0m — ${projectName}`);
+  console.log(`  Profile: ${profileId || 'training-default (built-in)'}`);
+  console.log(`  Records: ${files.length}`);
+  console.log('');
+
+  const eligible = [];
+  const excluded = [];
+  const nearMiss = []; // Records with exactly 1 failing reason
+
+  for (const file of files) {
+    const raw = await readFile(join(recordsDir, file), 'utf-8');
+    const record = JSON.parse(raw);
+
+    const result = evaluateEligibility(record, profile, config.lanes, config.terminology);
+
+    if (result.eligible) {
+      eligible.push(record.id);
+    } else {
+      excluded.push({ record_id: record.id, reasons: result.reasons });
+      if (result.reasons.length === 1) {
+        nearMiss.push({ record_id: record.id, reason: result.reasons[0] });
+      }
+    }
+  }
+
+  console.log(`  \x1b[32m✓\x1b[0m Eligible: ${eligible.length}`);
+  console.log(`  \x1b[31m✗\x1b[0m Excluded: ${excluded.length}`);
+  console.log('');
+
+  // Categorize exclusions
+  const categories = categorizeExclusions(excluded);
+  console.log('  Exclusion breakdown:');
+  for (const [cat, count] of Object.entries(categories)) {
+    if (count > 0) {
+      const bar = '█'.repeat(Math.min(Math.round(count / files.length * 50), 50));
+      console.log(`    ${cat.padEnd(20)} ${String(count).padStart(4)}  ${bar}`);
+    }
+  }
+
+  // Near-miss improvement opportunities
+  if (nearMiss.length > 0) {
+    console.log(`\n  Improvement opportunities (${nearMiss.length} records with 1 failing check):`);
+    const byReason = {};
+    for (const nm of nearMiss) {
+      byReason[nm.reason] = (byReason[nm.reason] || 0) + 1;
+    }
+    for (const [reason, count] of Object.entries(byReason).sort((a, b) => b[1] - a[1]).slice(0, 5)) {
+      console.log(`    ${count} records: ${reason}`);
+    }
+  }
+
+  console.log('');
+  const pct = ((eligible.length / files.length) * 100).toFixed(1);
+  console.log(`  Eligibility rate: ${pct}% (${eligible.length}/${files.length})`);
+}
+
+// Direct execution guard
+if (process.argv[1] && (process.argv[1].endsWith('eligibility.js') || process.argv[1].endsWith('eligibility'))) {
+  run().catch((err) => {
+    console.error(err.message || err);
+    process.exit(1);
+  });
+}