@phuetz/code-buddy 1.6.1 → 2.0.0

package/dist/lora/lisa-avatar-bible.js

@@ -0,0 +1,275 @@
+/**
+ * Multi-avatar / multi-style bible for Lisa LoRAs.
+ *
+ * Modelled on Krea 2 character demos (ComfyUI Workflow Blog):
+ * https://www.youtube.com/watch?v=GQusMZgc1RE
+ *
+ * Architecture (same as the video thumbnail):
+ *   1 locked FACE identity (one LoRA / one trigger)
+ *   + several STYLE packs (studio, wet selfie, rainy street, neon, soft editorial…)
+ * so one avatar can appear in many looks without baking one outfit into the LoRA.
+ *
+ * Default avatar `lisa` is calqued on the dark-brunette muse shown in that video.
+ *
+ * @module lora/lisa-avatar-bible
+ */
+/** Built-in avatar ids. */
+export const AVATAR_IDS = ['lisa', 'lisa-classic'];
+/**
+ * Presentation styles — same woman, different fashion/lighting package.
+ * Matches the multi-panel showcase in GQusMZgc1RE.
+ */
+export const AVATAR_STYLE_IDS = [
+    'studio', // studio beauty, hands near face, wet hair strands
+    'wet-selfie', // raindrops, phone selfie, glowing skin
+    'street-rain', // long black coat, rainy city walk
+    'neon-skate', // cyber neon night, bold fashion
+    'soft-editorial', // soft white blouse, clean portrait
+    'tender',
+    'playful',
+    'bold',
+    'sparkly',
+    'calm',
+    'mika',
+    'portrait',
+];
+const SHARED_NEGATIVE = [
+    'blurry',
+    'deformed',
+    'extra fingers',
+    'mutated hands',
+    'bad anatomy',
+    'plastic skin',
+    'waxy face',
+    'duplicate face',
+    'different person',
+    'age change',
+    'male',
+    'child',
+    'watermark',
+    'text',
+    'logo',
+    'lowres',
+    'over-smoothed',
+    'cgi mannequin',
+].join(', ');
+/**
+ * Primary Lisa — calqued on the dark brunette muse from
+ * https://www.youtube.com/watch?v=GQusMZgc1RE thumbnail / results grid.
+ *
+ * Keep identity SHORT: long stacked prompts make sd_turbo invent multi-face glitches.
+ */
+export const AVATAR_LISA_BRUNETTE = {
+    id: 'lisa',
+    name: 'Lisa (Krea brunette muse)',
+    trigger: 'ohwx lisa',
+    source: 'https://www.youtube.com/watch?v=GQusMZgc1RE',
+    defaultStyle: 'studio',
+    identity: [
+        'ohwx lisa',
+        'one woman only, single face, locked identity',
+        'beautiful young woman mid-20s',
+        'olive warm skin, dewy natural glow',
+        'dark brown eyes, long dark wavy brunette hair',
+        'high cheekbones, full soft lips',
+        'photoreal portrait, 85mm lens',
+    ].join(', '),
+    styles: {
+        studio: 'studio beauty portrait, wet-look dark hair strands on face, hands gently near chin, soft glam key light, intimate eye contact, editorial fashion',
+        'wet-selfie': 'mirror-style selfie holding black smartphone, rain droplets on skin and hair, soft bathroom or window light, intimate candid, glowing wet skin',
+        'street-rain': 'walking rainy european city street, long black tailored coat, wet pavement reflections, full-body to three-quarter, cinematic overcast light, confident stride',
+        'neon-skate': 'night city neon lights, bold futuristic fashion, dynamic skateboard pose, vibrant pink cyan color splash, same locked face identity, high energy',
+        'soft-editorial': 'soft clean studio portrait, sheer white blouse, hair gently pulled back with loose waves, pearl drop earring, serene direct gaze, high-end beauty retouch natural',
+        tender: 'soft warm key light, intimate close portrait, gentle affectionate smile, looking at camera with quiet love, cozy atmosphere',
+        playful: 'playful mischievous half-smile, lively eyes, slight head tilt, candid lifestyle portrait, vibrant soft colors',
+        bold: 'confident soft-glam portrait, dramatic yet natural lighting, alluring direct gaze, elegant modern fashion, tasteful',
+        sparkly: 'joyful bright smile, celebratory energy, sparkling eyes, cheerful fashion, crisp daylight',
+        calm: 'serene calm expression, soft muted palette, peaceful lifestyle portrait, quiet morning light',
+        mika: 'dynamic energetic pose, adventure-ready dark jacket, outdoor city bokeh, confident grin, motion feel',
+        portrait: 'clean editorial portrait, natural skin micro-detail, sharp dark eyes, neutral seamless background, photoreal Krea finish',
+    },
+    scenes: [
+        'clean white studio seamless backdrop',
+        'soft bathroom window light with rain on glass',
+        'rainy paris street corner, cool blue hour reflections',
+        'neon-lit wet night avenue, cinematic teal-magenta',
+        'soft bokeh cafe interior, warm window light',
+        'sunlit flower market, colorful bokeh',
+        'quiet bookstore aisle, soft overhead light',
+        'golden hour balcony, soft sky',
+        'cozy bar evening, amber practical lights',
+        'home living room couch, lamp light',
+    ],
+    outfits: [
+        'black delicate spaghetti-strap top',
+        'long black tailored wool coat',
+        'sheer soft white blouse',
+        'white camisole top',
+        'glossy dark fashion set for night',
+        'simple black turtleneck',
+        'casual denim jacket over white tee',
+        'elegant dark silk blouse',
+        'soft cream knit sweater',
+        'minimal black slip dress with jacket',
+    ],
+    lightings: [
+        'soft beauty dish key light',
+        'wet-skin specular glow, soft fill',
+        'overcast rainy daylight',
+        'neon night practicals',
+        'golden hour rim light',
+        'studio softbox beauty lighting',
+        'cool blue morning light',
+        'warm practical lamp light',
+    ],
+    negative: SHARED_NEGATIVE +
+        ', oily skin, orange tan, blonde hair, light brown hair, freckles heavy, ' +
+        'multiple faces, double face, triple face, two heads, extra eyes, fused faces, ' +
+        'split face, collage, montage, mirrored face artifact',
+};
+/** Previous soft chestnut companion look (optional second avatar). */
+export const AVATAR_LISA_CLASSIC = {
+    id: 'lisa-classic',
+    name: 'Lisa classic (soft chestnut)',
+    trigger: 'ohwx lisa classic',
+    defaultStyle: 'portrait',
+    identity: [
+        'ohwx lisa classic',
+        'same woman every image, locked face identity',
+        'young French woman mid-20s, exclusive digital companion presence',
+        'soft oval face, high cheekbones, delicate jawline',
+        'warm honey-brown eyes, long dark lashes, gentle brows',
+        'straight-to-wavy medium-long chestnut brown hair with soft honey highlights',
+        'natural healthy skin with fine pores, soft glam makeup, no plastic sheen',
+        'subtle freckles across nose bridge, warm peach lips',
+        'slender elegant build, photoreal Krea-style rendering',
+        '85mm portrait lens, shallow depth of field',
+    ].join(', '),
+    styles: {
+        tender: 'soft warm key light, intimate close portrait, gentle affectionate smile, cozy atmosphere',
+        playful: 'playful mischievous half-smile, lively eyes, slight head tilt, candid lifestyle portrait',
+        bold: 'confident soft-glam portrait, dramatic yet natural lighting, alluring direct gaze',
+        sparkly: 'joyful bright smile, celebratory energy, sparkling eyes, daylight',
+        calm: 'serene calm expression, soft muted palette, quiet morning light',
+        mika: 'dynamic energetic pose, outdoor city bokeh, confident grin',
+        portrait: 'clean editorial portrait, natural skin micro-detail, sharp eyes, neutral background',
+        studio: 'studio softbox beauty portrait, centered face, eye contact',
+        'wet-selfie': 'soft selfie, natural indoor light, phone in hand',
+        'street-rain': 'city street walk, soft coat, overcast light',
+        'neon-skate': 'night city lights, casual bold fashion, energetic pose',
+        'soft-editorial': 'soft white blouse, clean studio, serene gaze',
+    },
+    scenes: [
+        'soft bokeh cafe interior, warm window light',
+        'rainy city street corner, cool blue hour reflections',
+        'clean white studio seamless backdrop',
+        'home living room couch, lamp light',
+        'paris balcony morning, soft sky',
+        'neon night street, cinematic teal-orange',
+    ],
+    outfits: [
+        'simple black turtleneck',
+        'soft cream knit sweater',
+        'light linen shirt',
+        'casual denim jacket over white tee',
+        'elegant dark silk blouse',
+        'soft pink blouse, delicate gold earrings',
+    ],
+    lightings: [
+        'soft north-window light',
+        'golden hour rim light',
+        'studio softbox beauty lighting',
+        'overcast daylight',
+        'warm practical lamp light',
+        'cool blue morning light',
+    ],
+    negative: SHARED_NEGATIVE,
+};
+const REGISTRY = {
+    lisa: AVATAR_LISA_BRUNETTE,
+    'lisa-classic': AVATAR_LISA_CLASSIC,
+};
+/** Env: CODEBUDDY_LISA_AVATAR=lisa|lisa-classic */
+export function resolveAvatarId(raw, env = process.env) {
+    const v = (raw ?? env.CODEBUDDY_LISA_AVATAR ?? 'lisa').trim().toLowerCase();
+    if (v === 'lisa-classic' || v === 'classic' || v === 'chestnut')
+        return 'lisa-classic';
+    return 'lisa';
+}
+export function getAvatarProfile(id) {
+    return REGISTRY[resolveAvatarId(id)] ?? AVATAR_LISA_BRUNETTE;
+}
+export function listAvatarProfiles() {
+    return AVATAR_IDS.map((id) => REGISTRY[id]);
+}
+export function listAvatarStyles(avatarId) {
+    const p = getAvatarProfile(avatarId);
+    return AVATAR_STYLE_IDS.filter((s) => Boolean(p.styles[s]));
+}
+export function resolveAvatarStyle(raw, avatarId) {
+    const p = getAvatarProfile(avatarId);
+    const v = (raw ?? '').trim().toLowerCase().replace(/_/g, '-');
+    if (!v)
+        return p.defaultStyle;
+    const hit = AVATAR_STYLE_IDS.find((s) => s === v || s.replace(/-/g, '') === v.replace(/-/g, ''));
+    if (hit && p.styles[hit])
+        return hit;
+    // aliases from speech / CLI
+    if (v === 'street' || v === 'rain' || v === 'manteau')
+        return 'street-rain';
+    if (v === 'wet' || v === 'selfie' || v === 'pluie')
+        return 'wet-selfie';
+    if (v === 'neon' || v === 'cyber' || v === 'skate')
+        return 'neon-skate';
+    if (v === 'soft' || v === 'editorial' || v === 'blouse')
+        return 'soft-editorial';
+    if (v === 'studio' || v === 'beauty')
+        return 'studio';
+    return p.defaultStyle;
+}
+// ─── Back-compat exports (previous single-bible API) ───────────────────────
+export const LISA_AVATAR_TRIGGER = AVATAR_LISA_BRUNETTE.trigger;
+export const LISA_AVATAR_IDENTITY = AVATAR_LISA_BRUNETTE.identity;
+export const LISA_AVATAR_NEGATIVE = AVATAR_LISA_BRUNETTE.negative;
+export const LISA_AVATAR_SCENES = AVATAR_LISA_BRUNETTE.scenes;
+export const LISA_AVATAR_OUTFITS = AVATAR_LISA_BRUNETTE.outfits;
+export const LISA_AVATAR_LIGHTINGS = AVATAR_LISA_BRUNETTE.lightings;
+export const LISA_AVATAR_MOOD_SCENES = AVATAR_LISA_BRUNETTE.styles;
+/**
+ * Build a generation prompt:
+ * trigger → locked identity → style pack → optional free scene → quality.
+ */
+export function buildLisaAvatarPrompt(options) {
+    const profile = getAvatarProfile(options.avatarId);
+    const style = resolveAvatarStyle(options.style ?? options.mood, profile.id);
+    const styleLine = profile.styles[style] ?? profile.styles[profile.defaultStyle] ?? '';
+    // identity already starts with trigger — do not duplicate
+    const identityOrShort = options.includeIdentity === false
+        ? `${profile.trigger}, photoreal portrait, single face, locked identity`
+        : profile.identity;
+    const parts = [
+        identityOrShort,
+        styleLine,
+        options.scene?.trim().slice(0, 220),
+        options.forWhom ? `looking at ${options.forWhom}` : 'looking at camera',
+        'high detail face, natural skin texture, no text, no watermark, no logo',
+    ];
+    return parts.filter(Boolean).join(', ');
+}
+/** Human-readable catalog for CLI / doctor. */
+export function formatAvatarCatalog() {
+    const lines = ['Lisa avatar catalog (multi-style, one LoRA face each)', '='.repeat(50), ''];
+    for (const p of listAvatarProfiles()) {
+        lines.push(`${p.id} — ${p.name}`);
+        lines.push(`  trigger: ${p.trigger}`);
+        lines.push(`  default style: ${p.defaultStyle}`);
+        lines.push(`  styles: ${listAvatarStyles(p.id).join(', ')}`);
+        if (p.source)
+            lines.push(`  source: ${p.source}`);
+        lines.push('');
+    }
+    lines.push('Env: CODEBUDDY_LISA_AVATAR=lisa|lisa-classic');
+    lines.push('Selfie: buddy lora selfie --style studio|wet-selfie|street-rain|neon-skate|soft-editorial');
+    return lines.join('\n');
+}
+//# sourceMappingURL=lisa-avatar-bible.js.map

package/dist/lora/local-plan.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Local Krea 2 LoRA training plan (1-click / AI-Toolkit / musubi style).
+ * Does not download multi-GB trainers; writes config + script the operator can run.
+ */
+import type { LoraLocalPlan } from './types.js';
+export declare function writeLocalTrainPlan(projectDirectory: string, options?: {
+    steps?: number;
+    triggerPhrase?: string;
+    resolution?: number;
+}): Promise<LoraLocalPlan>;

package/dist/lora/local-plan.js

@@ -0,0 +1,205 @@
+/**
+ * Local Krea 2 LoRA training plan (1-click / AI-Toolkit / musubi style).
+ * Does not download multi-GB trainers; writes config + script the operator can run.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { loadProjectMeta } from './dataset.js';
+export async function writeLocalTrainPlan(projectDirectory, options) {
+    const meta = await loadProjectMeta(projectDirectory);
+    const trigger = (options?.triggerPhrase ?? meta?.triggerPhrase ?? '').trim();
+    const steps = options?.steps ?? 1500;
+    const resolution = options?.resolution ?? 768;
+    const imagesDir = path.join(projectDirectory, 'images');
+    const outDir = path.join(projectDirectory, 'output');
+    await fs.mkdir(outDir, { recursive: true });
+    const config = {
+        job: 'extension',
+        config: {
+            name: meta?.name ?? path.basename(projectDirectory),
+            process: [
+                {
+                    type: 'sd_trainer',
+                    training_folder: outDir,
+                    device: 'cuda',
+                    trigger_word: trigger,
+                    network: { type: 'lora', linear: 32, linear_alpha: 32 },
+                    save: { dtype: 'bf16', save_every: 250, max_step_saves_to_keep: 4 },
+                    datasets: [
+                        {
+                            folder_path: imagesDir,
+                            caption_ext: 'txt',
+                            caption_dropout_rate: 0.05,
+                            resolution: [resolution],
+                        },
+                    ],
+                    train: {
+                        batch_size: 1,
+                        steps,
+                        gradient_accumulation: 1,
+                        train_unet: true,
+                        train_text_encoder: false,
+                        noise_scheduler: 'flowmatch',
+                        optimizer: 'adamw8bit',
+                        lr: 0.0001,
+                        dtype: 'bf16',
+                    },
+                    model: {
+                        name_or_path: 'krea/Krea-2-Raw',
+                        quantize: true,
+                        low_vram: true,
+                    },
+                    sample: {
+                        sampler: 'flowmatch',
+                        sample_every: 250,
+                        width: resolution,
+                        height: resolution,
+                        prompts: trigger
+                            ? [`${trigger} portrait, soft light`, `${trigger} looking at camera`]
+                            : ['portrait, soft light'],
+                    },
+                },
+            ],
+        },
+        meta: {
+            purpose: 'Krea 2 character/style LoRA — local plan generated by Code Buddy',
+            notes: [
+                'Base model id is a starting point; match the weights your AI-Toolkit / musubi build expects.',
+                '16GB VRAM: keep low_vram + quantize; 40–50 images; 1000–1500 steps typical for likeness.',
+                'Cloud alternative: buddy lora train cloud <project> (FAL_KEY).',
+            ],
+        },
+    };
+    const configPath = path.join(projectDirectory, 'ai-toolkit-krea2.json');
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    const scriptPath = path.join(projectDirectory, 'train-local.sh');
+    await fs.writeFile(scriptPath, buildLocalScript(projectDirectory, configPath), {
+        encoding: 'utf8',
+        mode: 0o755,
+    });
+    const readmePath = path.join(projectDirectory, 'LOCAL-TRAIN.md');
+    await fs.writeFile(readmePath, buildLocalReadme({ projectDirectory, configPath, scriptPath, steps, trigger }), 'utf8');
+    return {
+        projectDir: projectDirectory,
+        configPath,
+        readmePath,
+        scriptPath,
+        steps: [
+            `1. Dataset in ${imagesDir}`,
+            `2. Review config ${configPath}`,
+            `3. Install AI-Toolkit or musubi-tuner (see LOCAL-TRAIN.md / the Krea 2 LoRA video)`,
+            `4. Run: bash ${scriptPath}   # or open AI-Toolkit GUI and load the JSON`,
+            `5. Install weights: buddy lora install ${path.join(outDir, '*.safetensors')}`,
+        ],
+    };
+}
+function buildLocalScript(projectDir, configPath) {
+    return `#!/usr/bin/env bash
+# Local Krea 2 LoRA training helper (Code Buddy)
+# Mirrors the "1-click local" flow from Krea 2 LoRA tutorials — does NOT download multi-GB deps itself.
+set -euo pipefail
+PROJECT="${projectDir}"
+CONFIG="${configPath}"
+cd "$PROJECT"
+
+if command -v python3 >/dev/null 2>&1; then
+  PY=python3
+else
+  PY=python
+fi
+
+echo "== Code Buddy local LoRA plan =="
+echo "Project: $PROJECT"
+echo "Config:  $CONFIG"
+echo
+echo "This script looks for a local trainer; it will not auto-download multi-GB models."
+echo
+
+if [[ -n "\${AI_TOOLKIT_DIR:-}" && -f "$AI_TOOLKIT_DIR/run.py" ]]; then
+  echo "Using AI_TOOLKIT_DIR=$AI_TOOLKIT_DIR"
+  exec "$PY" "$AI_TOOLKIT_DIR/run.py" "$CONFIG"
+fi
+
+if [[ -d "$HOME/ai-toolkit" && -f "$HOME/ai-toolkit/run.py" ]]; then
+  echo "Using ~/ai-toolkit"
+  exec "$PY" "$HOME/ai-toolkit/run.py" "$CONFIG"
+fi
+
+if [[ -d "$HOME/DEV/ai-toolkit" && -f "$HOME/DEV/ai-toolkit/run.py" ]]; then
+  echo "Using ~/DEV/ai-toolkit"
+  exec "$PY" "$HOME/DEV/ai-toolkit/run.py" "$CONFIG"
+fi
+
+# Pinokio / portable installs sometimes expose a CLI
+if command -v ai-toolkit >/dev/null 2>&1; then
+  exec ai-toolkit train "$CONFIG"
+fi
+
+cat <<EOF
+No local AI-Toolkit found.
+
+Options:
+  A) Cloud (cheapest path in Code Buddy):
+       CODEBUDDY_LORA_TRAIN=true FAL_KEY=… buddy lora train cloud $(basename "$PROJECT") --steps 1000
+
+  B) Install AI-Toolkit (or follow the 1-click installer from the Krea 2 LoRA video), then:
+       export AI_TOOLKIT_DIR=/path/to/ai-toolkit
+       bash $PROJECT/train-local.sh
+
+  C) musubi-tuner: point it at images/ + config notes in LOCAL-TRAIN.md
+
+Config ready at:
+  $CONFIG
+EOF
+exit 2
+`;
+}
+function buildLocalReadme(args) {
+    return `# Local Krea 2 LoRA training
+
+Aligned with community “1-click local” + cheapest cloud tutorials (Krea 2 LoRA / AI-Toolkit / musubi).
+
+## Recommended settings (character)
+
+| Param | Value |
+|-------|--------|
+| Images | 40–50 in \`images/\` |
+| Steps | ${args.steps} (1000–1500 typical) |
+| Resolution | 768 (faster) or 1024 (detail) |
+| Trigger | \`${args.trigger || 'your_trigger'}\` |
+| Captions | optional \`.txt\` same-stem; else trigger |
+
+## Path A — Cloud (often cheapest / no VRAM)
+
+\`\`\`bash
+export FAL_KEY=…
+export CODEBUDDY_LORA_TRAIN=true
+buddy lora train cloud ${path.basename(args.projectDirectory)} --steps 1000
+# ~$0.003/step on fal (min 100 steps billed) → ~$3 for 1000 steps
+\`\`\`
+
+## Path B — Local GPU
+
+1. Install [AI-Toolkit](https://github.com/ostris/ai-toolkit) or musubi-tuner (or the 1-click installer from the video).
+2. Ensure base **Krea 2 Raw** weights are available as expected by your trainer.
+3. Run:
+
+\`\`\`bash
+export AI_TOOLKIT_DIR=/path/to/ai-toolkit
+bash ${args.scriptPath}
+\`\`\`
+
+Config: \`${args.configPath}\`
+
+16GB VRAM: keep low_vram/quantize; layer offload if needed (~64GB RAM).
+
+## After training
+
+\`\`\`bash
+buddy lora install ${path.join(args.projectDirectory, 'output', 'your.safetensors')} --name ${path.basename(args.projectDirectory)}
+\`\`\`
+
+Then use ComfyUI with Krea 2 + LoRA, or \`CODEBUDDY_IMAGE_PROVIDER=comfyui\`.
+`;
+}
+//# sourceMappingURL=local-plan.js.map

package/dist/lora/pack-dataset.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Pack images (+ captions) into a .zip for fal Krea 2 trainer.
+ */
+export declare function packDatasetZip(projectDirectory: string, outZipPath?: string): Promise<{
+    zipPath: string;
+    fileCount: number;
+}>;

package/dist/lora/pack-dataset.js

@@ -0,0 +1,39 @@
+/**
+ * Pack images (+ captions) into a .zip for fal Krea 2 trainer.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { listImages } from './dataset.js';
+export async function packDatasetZip(projectDirectory, outZipPath) {
+    const imagesDir = path.join(projectDirectory, 'images');
+    const images = await listImages(imagesDir);
+    if (images.length === 0) {
+        throw new Error(`No images to pack in ${imagesDir}`);
+    }
+    const zipPath = outZipPath ?? path.join(projectDirectory, 'dataset.zip');
+    const jszipModule = await import('jszip');
+    const JSZip = (jszipModule.default
+        ?? jszipModule);
+    const zip = new JSZip();
+    let fileCount = 0;
+    for (const img of images) {
+        const imgPath = path.join(imagesDir, img);
+        const buf = await fs.readFile(imgPath);
+        zip.file(img, buf);
+        fileCount += 1;
+        const stem = img.replace(/\.[^.]+$/, '');
+        const capPath = path.join(imagesDir, `${stem}.txt`);
+        try {
+            const cap = await fs.readFile(capPath);
+            zip.file(`${stem}.txt`, cap);
+            fileCount += 1;
+        }
+        catch {
+            /* optional caption */
+        }
+    }
+    const content = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+    await fs.writeFile(zipPath, content);
+    return { zipPath, fileCount };
+}
+//# sourceMappingURL=pack-dataset.js.map

package/dist/lora/quality-gate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Lightweight dataset quality gate (no heavy image libs).
+ * Flags tiny files (likely corrupt), exact byte duplicates (sha256), and
+ * near-identical sizes with identical first-chunk hashes as soft duplicates.
+ *
+ * @module lora/quality-gate
+ */
+export interface QualityIssue {
+    path: string;
+    kind: 'too_small' | 'duplicate' | 'unreadable';
+    detail: string;
+}
+export interface DatasetQualityReport {
+    ok: boolean;
+    imageCount: number;
+    issues: QualityIssue[];
+    warnings: string[];
+    /** Images that passed size + uniqueness checks. */
+    kept: string[];
+    /** Paths recommended for exclusion (duplicates / unreadable / too small). */
+    reject: string[];
+}
+/**
+ * Scan images/ under a LoRA project for simple quality problems.
+ * Pure filesystem heuristics — no pixel blur metrics (no sharp/opencv dep).
+ */
+export declare function assessDatasetQuality(projectDirectory: string, options?: {
+    minBytes?: number;
+}): Promise<DatasetQualityReport>;
+/** Soft OK: no hard errors (unreadable/too_small); duplicates only warn. */
+export declare function qualityGatePassed(report: DatasetQualityReport): boolean;

package/dist/lora/quality-gate.js

@@ -0,0 +1,90 @@
+/**
+ * Lightweight dataset quality gate (no heavy image libs).
+ * Flags tiny files (likely corrupt), exact byte duplicates (sha256), and
+ * near-identical sizes with identical first-chunk hashes as soft duplicates.
+ *
+ * @module lora/quality-gate
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { createHash } from 'crypto';
+import { listImages } from './dataset.js';
+const DEFAULT_MIN_BYTES = 8_000; // ~8 KB — empty/corrupt PNG stubs are smaller
+async function fileSha256(filePath) {
+    const buf = await fs.readFile(filePath);
+    return createHash('sha256').update(buf).digest('hex');
+}
+/**
+ * Scan images/ under a LoRA project for simple quality problems.
+ * Pure filesystem heuristics — no pixel blur metrics (no sharp/opencv dep).
+ */
+export async function assessDatasetQuality(projectDirectory, options) {
+    const imagesDir = path.join(projectDirectory, 'images');
+    const minBytes = options?.minBytes ?? DEFAULT_MIN_BYTES;
+    const names = await listImages(imagesDir);
+    const issues = [];
+    const warnings = [];
+    const kept = [];
+    const reject = [];
+    const seenHash = new Map();
+    for (const name of names) {
+        const full = path.join(imagesDir, name);
+        try {
+            const st = await fs.stat(full);
+            if (st.size < minBytes) {
+                issues.push({
+                    path: full,
+                    kind: 'too_small',
+                    detail: `${st.size} bytes < min ${minBytes} (likely corrupt or blank)`,
+                });
+                reject.push(full);
+                continue;
+            }
+            const hash = await fileSha256(full);
+            const prior = seenHash.get(hash);
+            if (prior) {
+                issues.push({
+                    path: full,
+                    kind: 'duplicate',
+                    detail: `exact duplicate of ${path.basename(prior)}`,
+                });
+                reject.push(full);
+                continue;
+            }
+            seenHash.set(hash, full);
+            kept.push(full);
+        }
+        catch (err) {
+            issues.push({
+                path: full,
+                kind: 'unreadable',
+                detail: err instanceof Error ? err.message : String(err),
+            });
+            reject.push(full);
+        }
+    }
+    if (kept.length < 15 && names.length >= 15) {
+        warnings.push(`Only ${kept.length} unique usable images after quality filter (need ~40 for Krea).`);
+    }
+    if (reject.length > 0) {
+        warnings.push(`${reject.length} image(s) flagged (too small / duplicate / unreadable).`);
+    }
+    const report = {
+        // Hard fail only on corrupt/unreadable; exact duplicates are reject-list warnings.
+        // `ok` is derived from the single shared predicate below to avoid drift.
+        ok: false,
+        imageCount: names.length,
+        issues,
+        warnings,
+        kept,
+        reject,
+    };
+    report.ok = qualityGatePassed(report);
+    return report;
+}
+/** Soft OK: no hard errors (unreadable/too_small); duplicates only warn. */
+export function qualityGatePassed(report) {
+    const hard = report.issues.filter((i) => i.kind === 'too_small' || i.kind === 'unreadable');
+    return hard.length === 0 && report.kept.length > 0;
+}
+//# sourceMappingURL=quality-gate.js.map