@mcptoolshop/style-dataset-lab 1.2.1 → 2.1.0

package/lib/card.js

@@ -0,0 +1,145 @@
+/**
+ * Dataset card generation — markdown + JSON twin.
+ *
+ * Produces a human-readable dataset card summarizing provenance,
+ * selection criteria, split strategy, and distribution statistics.
+ */
+
+import { loadSnapshot, loadSnapshotIncluded } from './snapshot.js';
+import { loadSplit, loadSplitAudit } from './split.js';
+import { loadProjectConfig } from './config.js';
+
+/**
+ * Generate a dataset card from snapshot + split + project config.
+ *
+ * @param {string} projectRoot
+ * @param {string} snapshotId
+ * @param {string} splitId
+ * @returns {Promise<{markdown: string, json: Object}>}
+ */
+export async function generateCard(projectRoot, snapshotId, splitId) {
+  const config = loadProjectConfig(projectRoot);
+  const snapshot = await loadSnapshot(projectRoot, snapshotId);
+  const split = await loadSplit(projectRoot, splitId);
+  const audit = await loadSplitAudit(projectRoot, splitId);
+  const included = await loadSnapshotIncluded(projectRoot, snapshotId);
+
+  const json = {
+    dataset_name: `${config.meta.name}-visual`,
+    version: config.meta.version || '1.0.0',
+    created_at: new Date().toISOString(),
+    created_by: 'sdlab-card-v1',
+    project: {
+      name: config.meta.name,
+      display_name: config.meta.display_name,
+      domain: config.meta.domain,
+    },
+    snapshot: {
+      id: snapshot.snapshot_id,
+      created_at: snapshot.created_at,
+      config_fingerprint: snapshot.config_fingerprint,
+      total_records: snapshot.counts.total_records,
+      included: snapshot.counts.included,
+      excluded: snapshot.counts.excluded,
+    },
+    selection: snapshot.selection_profile,
+    split: {
+      id: split.split_id,
+      strategy: split.profile.strategy,
+      seed: split.profile.seed,
+      ratios: {
+        train: split.profile.train_ratio,
+        val: split.profile.val_ratio,
+        test: split.profile.test_ratio,
+      },
+      counts: split.counts,
+      leakage_free: audit.leakage_check.passed,
+    },
+    lane_balance: audit.lane_balance,
+    constitution: {
+      rule_count: config.constitution.rules?.length || 0,
+    },
+    rubric: {
+      dimension_count: config.rubric.dimensions?.length || 0,
+      thresholds: config.rubric.thresholds,
+    },
+  };
+
+  const markdown = renderMarkdown(json, config);
+
+  return { markdown, json };
+}
+
+function renderMarkdown(card, config) {
+  const lines = [];
+  const add = (s = '') => lines.push(s);
+
+  add(`# ${card.dataset_name}`);
+  add();
+  add(`**Project:** ${card.project.display_name}  `);
+  add(`**Domain:** ${card.project.domain}  `);
+  add(`**Version:** ${card.version}  `);
+  add(`**Generated:** ${card.created_at}  `);
+  add();
+
+  add('## Selection');
+  add();
+  add(`- **Snapshot:** \`${card.snapshot.id}\``);
+  add(`- **Config fingerprint:** \`${card.snapshot.config_fingerprint.slice(0, 16)}...\``);
+  add(`- **Total records evaluated:** ${card.snapshot.total_records}`);
+  add(`- **Included:** ${card.snapshot.included} (${(card.snapshot.included / card.snapshot.total_records * 100).toFixed(1)}%)`);
+  add(`- **Excluded:** ${card.snapshot.excluded}`);
+  add();
+
+  add('### Selection criteria');
+  add();
+  const sel = card.selection;
+  if (sel.require_judgment) add('- Requires human judgment');
+  if (sel.require_status?.length) add(`- Status: ${sel.require_status.join(', ')}`);
+  if (sel.require_canon_bound) add('- Must be canon-bound (constitution assertions)');
+  if (sel.minimum_pass_ratio != null) add(`- Minimum pass ratio: ${(sel.minimum_pass_ratio * 100).toFixed(0)}%`);
+  add();
+
+  add('## Split');
+  add();
+  add(`- **Split ID:** \`${card.split.id}\``);
+  add(`- **Strategy:** ${card.split.strategy}`);
+  add(`- **Seed:** ${card.split.seed}`);
+  add(`- **Subject leakage:** ${card.split.leakage_free ? 'None (verified)' : 'DETECTED'}`);
+  add();
+
+  add('| Partition | Records | % |');
+  add('|-----------|---------|---|');
+  const total = card.split.counts.total_records;
+  add(`| Train | ${card.split.counts.train} | ${(card.split.counts.train / total * 100).toFixed(1)}% |`);
+  add(`| Val | ${card.split.counts.val} | ${(card.split.counts.val / total * 100).toFixed(1)}% |`);
+  add(`| Test | ${card.split.counts.test} | ${(card.split.counts.test / total * 100).toFixed(1)}% |`);
+  add();
+
+  add('## Lane Balance');
+  add();
+  add('| Lane | Total | Train% | Val% | Test% |');
+  add('|------|-------|--------|------|-------|');
+  for (const [lane, b] of Object.entries(card.lane_balance).sort((a, b) => b[1].total - a[1].total)) {
+    add(`| ${lane} | ${b.total} | ${b.train_pct}% | ${b.val_pct}% | ${b.test_pct}% |`);
+  }
+  add();
+
+  add('## Quality Gates');
+  add();
+  add(`- **Constitution rules:** ${card.constitution.rule_count}`);
+  add(`- **Rubric dimensions:** ${card.rubric.dimension_count}`);
+  if (card.rubric.thresholds) {
+    add(`- **Pass threshold:** ${(card.rubric.thresholds.pass * 100).toFixed(0)}%`);
+  }
+  add();
+
+  add('## Provenance');
+  add();
+  add('This dataset was produced by [Style Dataset Lab](https://github.com/mcp-tool-shop-org/style-dataset-lab).');
+  add('Every included record has been human-reviewed, canon-bound, and verified against project constitution rules.');
+  add('Split strategy ensures no subject appears in multiple partitions.');
+  add();
+
+  return lines.join('\n');
+}

package/lib/comfyui.js

@@ -0,0 +1,109 @@
+/**
+ * ComfyUI HTTP API client — extracted from 5 generation scripts.
+ *
+ * All functions take comfyUrl as a parameter so projects can override
+ * the default localhost:8188 endpoint.
+ */
+
+import { readFile } from 'node:fs/promises';
+
+const DEFAULT_URL = 'http://127.0.0.1:8188';
+const MAX_POLL_MS = 600_000; // 10 minutes
+
+/**
+ * Check if ComfyUI is reachable.
+ * @param {string} [comfyUrl]
+ * @returns {Promise<boolean>}
+ */
+export async function comfyHealth(comfyUrl = DEFAULT_URL) {
+  try {
+    const res = await fetch(`${comfyUrl}/system_stats`);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Submit a workflow and poll until complete.
+ * @param {Object} workflow — ComfyUI prompt graph
+ * @param {string} [comfyUrl]
+ * @param {{ clientPrefix?: string, timeoutMs?: number }} [opts]
+ * @returns {Promise<Object>} — history entry
+ */
+export async function submitAndWait(workflow, comfyUrl = DEFAULT_URL, opts = {}) {
+  const { clientPrefix = 'sdl', timeoutMs = MAX_POLL_MS } = opts;
+  const clientId = `${clientPrefix}-${Date.now()}`;
+
+  const res = await fetch(`${comfyUrl}/prompt`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ prompt: workflow, client_id: clientId }),
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`ComfyUI submit failed: ${res.status} ${text}`);
+  }
+
+  const { prompt_id: promptId } = await res.json();
+
+  const start = Date.now();
+  while (true) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`ComfyUI poll timeout after ${timeoutMs / 1000}s for prompt ${promptId}`);
+    }
+    await new Promise(r => setTimeout(r, 1000));
+    const histRes = await fetch(`${comfyUrl}/history/${promptId}`);
+    if (!histRes.ok) continue;
+    const history = await histRes.json();
+    const entry = history[promptId];
+    if (!entry) continue;
+    if (entry.status?.completed) return entry;
+    if (entry.status?.status_str === 'error') {
+      throw new Error(`ComfyUI generation failed: ${JSON.stringify(entry.status)}`);
+    }
+  }
+}
+
+/**
+ * Download a generated image from ComfyUI.
+ * @param {string} filename
+ * @param {string} [subfolder]
+ * @param {string} [comfyUrl]
+ * @param {string} [type='output']
+ * @returns {Promise<Buffer>}
+ */
+export async function downloadImage(filename, subfolder, comfyUrl = DEFAULT_URL, type = 'output') {
+  const url = `${comfyUrl}/view?filename=${encodeURIComponent(filename)}&subfolder=${encodeURIComponent(subfolder || '')}&type=${type}`;
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Download failed: ${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+/**
+ * Upload an image to ComfyUI's input folder.
+ * @param {string} filePath — local file to upload
+ * @param {string} filename — name to assign in ComfyUI
+ * @param {string} [comfyUrl]
+ * @returns {Promise<string>} — assigned name from ComfyUI
+ */
+export async function uploadImage(filePath, filename, comfyUrl = DEFAULT_URL) {
+  const data = await readFile(filePath);
+  const formData = new FormData();
+  formData.append('image', new Blob([data], { type: 'image/png' }), filename);
+  formData.append('overwrite', 'true');
+
+  const res = await fetch(`${comfyUrl}/upload/image`, {
+    method: 'POST',
+    body: formData,
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Upload failed: ${res.status} ${text}`);
+  }
+
+  const result = await res.json();
+  return result.name;
+}

package/lib/config.js

@@ -0,0 +1,248 @@
+/**
+ * Per-project config loader.
+ *
+ * Loads JSON config files from a project root directory.
+ * Falls back to sensible defaults when files don't exist,
+ * so unmigrated projects (pre-v2.0) still work.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+function loadJsonFile(filePath) {
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Failed to parse ${filePath}: ${err.message}`);
+  }
+}
+
+/**
+ * Load project.json — project identity and generation defaults.
+ */
+export function loadProjectMeta(projectRoot) {
+  const data = loadJsonFile(join(projectRoot, 'project.json'));
+  if (!data) {
+    return {
+      name: 'unknown',
+      display_name: 'Unknown Project',
+      domain: 'generic',
+      version: '0.0.0',
+      defaults: {},
+    };
+  }
+  return data;
+}
+
+/**
+ * Load constitution.json — array of rule objects.
+ */
+export function loadConstitution(projectRoot) {
+  const data = loadJsonFile(join(projectRoot, 'constitution.json'));
+  if (!data) return { rules: [] };
+  if (Array.isArray(data)) return { rules: data };
+  if (!data.rules) throw new Error(`constitution.json must have a "rules" array`);
+  return data;
+}
+
+/**
+ * Load lanes.json — lane definitions with detection patterns.
+ */
+export function loadLanes(projectRoot) {
+  const data = loadJsonFile(join(projectRoot, 'lanes.json'));
+  if (!data) {
+    return { default_lane: 'default', lanes: [] };
+  }
+  if (!data.lanes) throw new Error(`lanes.json must have a "lanes" array`);
+  return data;
+}
+
+/**
+ * Load rubric.json — scoring dimensions, thresholds, failure modes.
+ */
+export function loadRubric(projectRoot) {
+  const data = loadJsonFile(join(projectRoot, 'rubric.json'));
+  if (!data) {
+    return {
+      dimensions: [],
+      thresholds: { pass: 0.7, partial: 0.5, fail_ceiling: 0.4 },
+      failure_to_rules: {},
+    };
+  }
+  return data;
+}
+
+/**
+ * Load terminology.json — group vocabulary and detection patterns.
+ */
+export function loadTerminology(projectRoot) {
+  const data = loadJsonFile(join(projectRoot, 'terminology.json'));
+  if (!data) {
+    return {
+      group_label: 'group',
+      groups: {},
+      cross_group_patterns: {},
+      edge_defaults: {},
+      prompt_fallbacks: {},
+    };
+  }
+  return data;
+}
+
+/**
+ * Load all project config files at once.
+ */
+export function loadProjectConfig(projectRoot) {
+  return {
+    meta: loadProjectMeta(projectRoot),
+    constitution: loadConstitution(projectRoot),
+    lanes: loadLanes(projectRoot),
+    rubric: loadRubric(projectRoot),
+    terminology: loadTerminology(projectRoot),
+  };
+}
+
+// ─── Profile Loaders ─────────────────────────────────────────────────
+
+const DEFAULT_SELECTION_PROFILE = {
+  require_judgment: true,
+  require_status: ['approved'],
+  require_canon_bound: true,
+  minimum_pass_ratio: 0.5,
+  rights_filter: null,
+  exclude_lanes: [],
+  max_per_subject: null,
+  max_per_lane: null,
+};
+
+const DEFAULT_SPLIT_PROFILE = {
+  profile_id: 'balanced-default',
+  strategy: 'subject-isolated',
+  train_ratio: 0.8,
+  val_ratio: 0.1,
+  test_ratio: 0.1,
+  lane_balance: true,
+  subject_isolation: true,
+  seed: 42,
+};
+
+const DEFAULT_EXPORT_PROFILE = {
+  profile_id: 'canonical-package',
+  include_images: true,
+  image_strategy: 'symlink',
+  include_splits: true,
+  include_card: true,
+  include_checksums: true,
+  metadata_fields: ['id', 'asset_path', 'provenance', 'judgment', 'canon', 'identity', 'lineage'],
+};
+
+/**
+ * Load a selection profile from project or return built-in default.
+ */
+export function loadSelectionProfile(projectRoot, profileId) {
+  if (!profileId) return { ...DEFAULT_SELECTION_PROFILE };
+  const data = loadJsonFile(join(projectRoot, 'selection-profiles', `${profileId}.json`));
+  if (!data) return { ...DEFAULT_SELECTION_PROFILE };
+  return { ...DEFAULT_SELECTION_PROFILE, ...data };
+}
+
+/**
+ * Load a split profile from project or return built-in default.
+ */
+export function loadSplitProfile(projectRoot, profileId) {
+  if (!profileId) return { ...DEFAULT_SPLIT_PROFILE };
+  const data = loadJsonFile(join(projectRoot, 'split-profiles', `${profileId}.json`));
+  if (!data) return { ...DEFAULT_SPLIT_PROFILE };
+  return { ...DEFAULT_SPLIT_PROFILE, ...data };
+}
+
+/**
+ * Load an export profile from project or return built-in default.
+ */
+export function loadExportProfile(projectRoot, profileId) {
+  if (!profileId) return { ...DEFAULT_EXPORT_PROFILE };
+  const data = loadJsonFile(join(projectRoot, 'export-profiles', `${profileId}.json`));
+  if (!data) return { ...DEFAULT_EXPORT_PROFILE };
+  return { ...DEFAULT_EXPORT_PROFILE, ...data };
+}
+
+// ─── Detection Functions ─────────────────────────────────────────────
+// Extracted from scripts/canon-bind.js for reuse in eligibility,
+// snapshot, and split modules.
+
+/**
+ * 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.
+ */
+export 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.
+ * Uses explicit id_detection_order and prompt_detection_order when provided
+ * to preserve the exact detection priority of the original implementation.
+ */
+export function detectGroup(id, prompt, termConfig) {
+  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;
+}

package/lib/deprecation.js

@@ -0,0 +1,14 @@
+/**
+ * Deprecation warning helper — fires once per flag per process.
+ */
+
+const warned = new Set();
+
+export function warnDeprecated(oldFlag, newFlag) {
+  const key = `${oldFlag}→${newFlag}`;
+  if (warned.has(key)) return;
+  warned.add(key);
+  process.stderr.write(
+    `\x1b[33m⚠ --${oldFlag} is deprecated and will be removed in v3.0. Use --${newFlag} instead.\x1b[0m\n`
+  );
+}

package/lib/eligibility.js

@@ -0,0 +1,110 @@
+/**
+ * Eligibility evaluation engine.
+ *
+ * Determines whether each record qualifies for inclusion in a dataset
+ * snapshot, with explicit reason traces for every decision.
+ */
+
+import { detectLane, detectGroup } from './config.js';
+
+/**
+ * Evaluate a single record against a selection profile.
+ * @param {Object} record — full record object
+ * @param {Object} profile — selection profile
+ * @param {Object} lanesConfig — from lanes.json
+ * @param {Object} termConfig — from terminology.json
+ * @returns {{ eligible: boolean, reasons: string[] }}
+ */
+export function evaluateEligibility(record, profile, lanesConfig, termConfig) {
+  const reasons = [];
+
+  // 1. Judgment required
+  if (profile.require_judgment) {
+    if (!record.judgment) {
+      reasons.push('no judgment (record has not been reviewed)');
+    }
+  }
+
+  // 2. Status filter
+  if (profile.require_status?.length > 0 && record.judgment) {
+    if (!profile.require_status.includes(record.judgment.status)) {
+      reasons.push(`status "${record.judgment.status}" not in [${profile.require_status.join(', ')}]`);
+    }
+  }
+
+  // 3. Canon bound
+  if (profile.require_canon_bound) {
+    if (!record.canon?.assertions || record.canon.assertions.length === 0) {
+      reasons.push('not canon-bound (no assertions)');
+    }
+  }
+
+  // 4. Minimum pass ratio
+  if (profile.minimum_pass_ratio != null && record.canon?.assertion_count > 0) {
+    const ratio = record.canon.pass_count / record.canon.assertion_count;
+    if (ratio < profile.minimum_pass_ratio) {
+      reasons.push(`pass ratio ${(ratio * 100).toFixed(0)}% below minimum ${(profile.minimum_pass_ratio * 100).toFixed(0)}%`);
+    }
+  }
+
+  // 5. Lane exclusion
+  if (profile.exclude_lanes?.length > 0) {
+    const prompt = record.provenance?.prompt || '';
+    const lane = detectLane(record.id, prompt, lanesConfig);
+    if (profile.exclude_lanes.includes(lane)) {
+      reasons.push(`lane "${lane}" is excluded`);
+    }
+  }
+
+  // 6. Rights filter
+  if (profile.rights_filter != null) {
+    const rights = record.rights_status || record.training_rights_status || null;
+    if (rights !== profile.rights_filter) {
+      reasons.push(`rights "${rights || 'unknown'}" does not match required "${profile.rights_filter}"`);
+    }
+  }
+
+  // 7. Tag exclusion
+  if (profile.exclude_tags?.length > 0 && record.dataset_tags) {
+    const excluded = record.dataset_tags.filter(t => profile.exclude_tags.includes(t));
+    if (excluded.length > 0) {
+      reasons.push(`has excluded tags: ${excluded.join(', ')}`);
+    }
+  }
+
+  return {
+    eligible: reasons.length === 0,
+    reasons,
+  };
+}
+
+/**
+ * Categorize exclusion reasons for a set of records.
+ * @param {Array<{record_id: string, reasons: string[]}>} excluded
+ * @returns {Object} — category → count mapping
+ */
+export function categorizeExclusions(excluded) {
+  const categories = {
+    no_judgment: 0,
+    wrong_status: 0,
+    not_canon_bound: 0,
+    low_pass_ratio: 0,
+    excluded_lane: 0,
+    rights_filter: 0,
+    excluded_tags: 0,
+  };
+
+  for (const { reasons } of excluded) {
+    for (const r of reasons) {
+      if (r.includes('no judgment')) categories.no_judgment++;
+      else if (r.includes('status')) categories.wrong_status++;
+      else if (r.includes('canon-bound')) categories.not_canon_bound++;
+      else if (r.includes('pass ratio')) categories.low_pass_ratio++;
+      else if (r.includes('lane')) categories.excluded_lane++;
+      else if (r.includes('rights')) categories.rights_filter++;
+      else if (r.includes('tags')) categories.excluded_tags++;
+    }
+  }
+
+  return categories;
+}