@goodandready/dsh-image-gen 0.11.11 → 0.11.13

package/lib/tools/character-sheet.js

@@ -0,0 +1,183 @@
+// character-sheet.js — generate_character_sheet tool (#181).
+// Generates multi-angle character model sheets and turnarounds with visual consistency.
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import path from 'node:path'
+import { mkdir, writeFile } from 'node:fs/promises'
+import {
+  ASPECT_RATIOS,
+  buildSidecar,
+  makeProviders,
+  toLosslessJson,
+  saveAttachmentSafe,
+} from '../providers.js'
+import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
+import { renderToolOutput } from '../attachment-helper.js'
+import {
+  CHARACTER_SHEET_LAYOUTS,
+  CHARACTER_SHEET_STYLES,
+  buildCharacterSheetPrompt,
+} from '../character-sheet-helpers.js'
+
+export function registerCharacterSheetTools(ctx, deps) {
+  const {
+    live,
+    slugify,
+    resolveApiKey,
+  } = deps
+
+  ctx.effect(() => {
+    ctx.tools.register(
+      defineTool({
+        name: 'generate_character_sheet',
+        description:
+          'Generate a multi-angle character model sheet or turnaround reference with high visual identity consistency. '
+          + 'Supports horizontal turnarounds (front, profile, 3/4, back), 1x3 triptychs, 2x2 grids, and facial emotion sheets across concept, anime, 3D, and comic styles.',
+        parameters: {
+          prompt: {
+            type: 'string',
+            description: 'Core character description (e.g. "female cyborg detective with neon violet hair, yellow trenchcoat, cybernetic arm").',
+          },
+          layout: {
+            type: 'string',
+            enum: ['turnaround', '1x3', '2x2', 'emotions'],
+            description: 'Layout arrangement: "turnaround" (4 sequential horizontal views), "1x3" (front, side, back), "2x2" (quad angles), or "emotions" (4 facial expressions). Default: turnaround.',
+          },
+          style: {
+            type: 'string',
+            enum: ['concept_art', 'anime', '3d_animation', 'pixel_art', 'realistic', 'comic'],
+            description: 'Artistic rendering style. Default: concept_art.',
+          },
+          negativePrompt: {
+            type: 'string',
+            description: 'Negative prompt directives to suppress unwanted elements.',
+          },
+          seed: {
+            type: 'integer',
+            description: 'RNG seed for reproducible character generation across sessions.',
+          },
+          provider: {
+            type: 'string',
+            description: 'Optional provider override (e.g. fal, replicate, local). Defaults to active provider.',
+          },
+        },
+        output: {
+          schema: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              prompt: { type: 'string' },
+              layout: { type: 'string' },
+              style: { type: 'string' },
+              aspectRatio: { type: 'string' },
+              views: {
+                type: 'array',
+                items: { type: 'string' },
+              },
+              seed: { type: 'integer' },
+              provider: { type: 'string' },
+              attachment: {
+                type: 'object',
+                additionalProperties: true,
+                properties: {
+                  attachmentId: { type: 'string' },
+                  url: { type: 'string' },
+                  mediaType: { type: 'string' },
+                  filename: { type: 'string' },
+                  byteSize: { type: 'integer' },
+                },
+              },
+            },
+          },
+          render: (_args, value) => renderToolOutput(value),
+        },
+        async execute(args, execCtx) {
+          const cfg = live.value
+          const activeProvider = args.provider || cfg.activeProvider || 'fal'
+          const seed = typeof args.seed === 'number' ? args.seed : Math.floor(Math.random() * 2147483647)
+
+          const sheetPlan = buildCharacterSheetPrompt({
+            prompt: args.prompt,
+            layout: args.layout,
+            style: args.style,
+            negativePrompt: args.negativePrompt,
+          })
+
+          const providers = makeProviders({
+            fetchImpl: fetch,
+            resolveKey: (id) => resolveApiKey(cfg, id),
+            cfg,
+          })
+
+          const fallbackChain = resolveFallbackChain(activeProvider, cfg)
+
+          const aspectPixels = ASPECT_RATIOS[sheetPlan.aspectRatio] || ASPECT_RATIOS['16:9']
+
+          const jobPayload = {
+            prompt: sheetPlan.prompt,
+            negativePrompt: sheetPlan.negativePrompt,
+            aspectRatio: sheetPlan.aspectRatio,
+            aspectPixels,
+            format: 'png',
+            seed,
+            quality: 'high',
+          }
+
+          const { result: genResult, provider: usedProvider } = await executeWithFallback(
+            fallbackChain,
+            providers,
+            jobPayload,
+            { signal: execCtx?.signal }
+          )
+
+          const timestamp = Date.now()
+          const safeSlug = slugify(args.prompt.slice(0, 30)) || 'character-sheet'
+          const filename = `character-sheet-${sheetPlan.layout}-${safeSlug}-${timestamp}.png`
+
+          let attachment = null
+          if (genResult.bytes) {
+            const outDir = path.resolve(process.cwd(), cfg.outputDir || 'output')
+            await mkdir(outDir, { recursive: true })
+            const diskPath = path.join(outDir, filename)
+            await writeFile(diskPath, Buffer.from(genResult.bytes))
+
+            attachment = await saveAttachmentSafe(
+              ctx,
+              Buffer.from(genResult.bytes),
+              'image/png',
+              filename,
+              diskPath
+            )
+          } else if (genResult.url) {
+            attachment = {
+              url: genResult.url,
+              mediaType: 'image/png',
+              filename,
+            }
+          }
+
+          const response = {
+            prompt: sheetPlan.prompt,
+            characterDescription: args.prompt,
+            layout: sheetPlan.layout,
+            style: sheetPlan.style,
+            aspectRatio: sheetPlan.aspectRatio,
+            views: sheetPlan.views,
+            seed,
+            provider: usedProvider,
+            attachment,
+          }
+
+          if (attachment?.attachmentId) {
+            response.attachmentId = attachment.attachmentId
+          }
+          if (attachment?.url) {
+            response.url = attachment.url
+          }
+
+          return response
+        },
+      })
+    )
+  }, 'dsh-image-gen: tool generate_character_sheet')
+}

package/lib/tools/diagram.js

@@ -0,0 +1,168 @@
+// diagram.js — beautify_diagram tool (#185).
+// Transforms raw Mermaid / Graphviz diagrams into high-end 3D isometric architectural illustrations.
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import path from 'node:path'
+import { mkdir, writeFile } from 'node:fs/promises'
+import {
+  ASPECT_RATIOS,
+  makeProviders,
+  saveAttachmentSafe,
+} from '../providers.js'
+import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
+import { renderToolOutput } from '../attachment-helper.js'
+import {
+  DIAGRAM_3D_STYLES,
+  buildDiagramIllustrationPrompt,
+} from '../diagram-helpers.js'
+
+export function registerDiagramTools(ctx, deps) {
+  const {
+    live,
+    slugify,
+    resolveApiKey,
+  } = deps
+
+  ctx.effect(() => {
+    ctx.tools.register(
+      defineTool({
+        name: 'beautify_diagram',
+        description:
+          'Transform raw Mermaid or Graphviz diagrams into stunning 3D isometric architectural illustrations '
+          + 'with glowing data pipes, glassmorphism cards, and pristine technical lighting for documentation and hero blocks.',
+        parameters: {
+          diagram: {
+            type: 'string',
+            description: 'Raw Mermaid diagram source code, Graphviz DOT text, or image path/attachment.',
+          },
+          style: {
+            type: 'string',
+            enum: ['isometric_3d', 'cyber_blueprint', 'clay_minimal', 'glossy_dark'],
+            description: '3D rendering aesthetic style. Default: isometric_3d.',
+          },
+          title: {
+            type: 'string',
+            description: 'Optional architecture title or headline to feature in the composition.',
+          },
+          aspect_ratio: {
+            type: 'string',
+            enum: ['16:9', '1:1', '4:3', '21:9'],
+            description: 'Aspect ratio for documentation header or hero banner (default: 16:9).',
+          },
+          seed: {
+            type: 'integer',
+            description: 'Optional seed for reproducible diagram generation.',
+          },
+          provider: {
+            type: 'string',
+            description: 'Optional provider override. Defaults to active provider.',
+          },
+        },
+        output: {
+          schema: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              title: { type: 'string' },
+              style: { type: 'string' },
+              aspectRatio: { type: 'string' },
+              detectedNodes: {
+                type: 'array',
+                items: { type: 'string' },
+              },
+              prompt: { type: 'string' },
+              seed: { type: 'integer' },
+              provider: { type: 'string' },
+              attachment: {
+                type: 'object',
+                additionalProperties: true,
+                properties: {
+                  attachmentId: { type: 'string' },
+                  url: { type: 'string' },
+                  mediaType: { type: 'string' },
+                  filename: { type: 'string' },
+                },
+              },
+            },
+          },
+          render: (_args, value) => renderToolOutput(value),
+        },
+        async execute(args, execCtx) {
+          const cfg = live?.value || (typeof live === 'function' ? live() : {})
+          const activeProvider = args.provider || cfg.activeProvider || 'fal'
+          const seed = typeof args.seed === 'number' ? args.seed : Math.floor(Math.random() * 2147483647)
+
+          const plan = buildDiagramIllustrationPrompt({
+            diagram: args.diagram,
+            style: args.style,
+            title: args.title,
+            aspectRatio: args.aspect_ratio || '16:9',
+          })
+
+          const providers = makeProviders({
+            fetchImpl: fetch,
+            resolveKey: (id) => resolveApiKey(cfg, id),
+            cfg,
+          })
+          const fallbackChain = resolveFallbackChain(activeProvider, cfg)
+          const aspectPixels = ASPECT_RATIOS[plan.aspectRatio] || ASPECT_RATIOS['16:9']
+
+          const jobPayload = {
+            prompt: plan.prompt,
+            negativePrompt: plan.negativePrompt,
+            aspectRatio: plan.aspectRatio,
+            aspectPixels,
+            format: 'png',
+            seed,
+            quality: 'high',
+          }
+
+          const { result: genResult, provider: usedProvider } = await executeWithFallback(
+            fallbackChain,
+            providers,
+            jobPayload,
+            { signal: execCtx?.signal }
+          )
+
+          const outDir = path.resolve(process.cwd(), cfg.outputDir || 'output')
+          await mkdir(outDir, { recursive: true })
+          const timestamp = Date.now()
+          const safeSlug = slugify(args.title || 'architecture-diagram') || 'diagram'
+          const filename = `diagram-3d-${safeSlug}-${timestamp}.png`
+
+          let attachment = null
+          if (genResult.bytes) {
+            const diskPath = path.join(outDir, filename)
+            await writeFile(diskPath, Buffer.from(genResult.bytes))
+            attachment = await saveAttachmentSafe(
+              ctx,
+              Buffer.from(genResult.bytes),
+              'image/png',
+              filename,
+              diskPath
+            )
+          } else if (genResult.url) {
+            attachment = {
+              url: genResult.url,
+              mediaType: 'image/png',
+              filename,
+            }
+          }
+
+          return {
+            title: args.title || 'System Architecture',
+            style: plan.style,
+            aspectRatio: plan.aspectRatio,
+            detectedNodes: plan.parsedNodes,
+            prompt: plan.prompt,
+            seed,
+            provider: usedProvider,
+            attachment,
+            url: attachment?.url,
+            attachmentId: attachment?.attachmentId,
+          }
+        },
+      })
+    )
+  }, 'dsh-image-gen: tool beautify_diagram')
+}

package/lib/tools/generation.js

@@ -1,22 +1,4 @@
 import { registerGenerationPackTool } from './generation-pack.js'
-
-/** Run an array of async task functions with a concurrency cap */
-async function asyncPool(tasks, concurrency = 3) {
-  const results = new Array(tasks.length)
-  let nextIdx = 0
-  async function worker() {
-    while (nextIdx < tasks.length) {
-      const idx = nextIdx++
-      results[idx] = await tasks[idx]()
-    }
-  }
-  const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, () => worker())
-  await Promise.all(workers)
-  return results
-}
-
-// generation — image-gen tools (generate_image, generate_image_pack). Extracted from apply() (#216).
-
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import path from 'node:path'
 import { mkdir, writeFile } from 'node:fs/promises'
@@ -41,7 +23,7 @@ import { calculateGenerationCost, recordSpend, assertBudgetAvailable } from '../
 import { trackAndAssertLoopGuard } from '../loop-guard.js'
 import { getCachedGeneration, setCachedGeneration } from '../generation-cache.js'
 import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
-import { getSessionAnchor, applyAnchorPromptHints } from '../anchor-helpers.js'
+import { getSessionAnchor, applyAnchorPromptHints, buildFaceConsistencyPrompt } from '../anchor-helpers.js'
 import { enhancePrompt } from '../prompt-enhancer.js'
 import {
   readHistory,
@@ -53,6 +35,22 @@ import {
   cachedResult,
 } from '../history.js'
 
+// generation — image-gen tools (generate_image, generate_image_pack). Extracted from apply() (#216).
+
+/** Run an array of async task functions with a concurrency cap */
+async function asyncPool(tasks, concurrency = 3) {
+  const results = new Array(tasks.length)
+  let nextIdx = 0
+  async function worker() {
+    while (nextIdx < tasks.length) {
+      const idx = nextIdx++
+      results[idx] = await tasks[idx]()
+    }
+  }
+  const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, () => worker())
+  await Promise.all(workers)
+  return results
+}
 
 export function registerGenerationTools(ctx, deps) {
   const {
@@ -172,6 +170,14 @@ export function registerGenerationTools(ctx, deps) {
           type: 'number',
           description: 'Optional strength of reference anchor influence (0.1 to 1.0).',
         },
+        face_reference: {
+          type: 'string',
+          description: 'Portrait reference image (URL, local path, or attachment id) for facial identity preservation via FaceID / IP-Adapter (#183).',
+        },
+        face_strength: {
+          type: 'number',
+          description: 'Facial identity similarity weight between 0.1 and 1.0 (default: 0.75).',
+        },
       },
       output: {
         schema: {
@@ -336,7 +342,7 @@ export function registerGenerationTools(ctx, deps) {
       // Subscriptions service is optional: without it, subscription providers
       // gracefully decline while other providers continue functioning.
         let subscriptionImages
-        try { subscriptionImages = ctx.get && ctx.get('subscriptionImages') } catch { subscriptionImages = undefined }
+        try { subscriptionImages = ctx.get && ctx.get('subscriptionImages') } catch (_err) { subscriptionImages = undefined }
 
         const source = args.source_image ? await resolveSource(ctx, exec, args.source_image) : undefined
         const mask = args.mask ? await resolveSource(ctx, exec, args.mask) : undefined
@@ -345,7 +351,25 @@ export function registerGenerationTools(ctx, deps) {
         const styleInfo = resolveStylePreset(effectiveStyle, args.negative_prompt, args.guidance_scale)
         let effectivePrompt = styleInfo.promptSuffix ? `${enhanced.prompt}, ${styleInfo.promptSuffix}` : enhanced.prompt
         const activeAnchor = getSessionAnchor(sessionId)
-        if (args.reference_image) {
+        let resolvedFaceRef
+        const faceRefInput = args.face_reference || (activeAnchor && (activeAnchor.mode === 'face' || activeAnchor.mode === 'character') ? activeAnchor.image : undefined)
+        if (faceRefInput) {
+          try {
+            resolvedFaceRef = await resolveSource(ctx, exec, faceRefInput)
+          } catch (_err) {
+            /* non-fatal: face_reference resolve fallback */
+            resolvedFaceRef = { url: faceRefInput }
+          }
+          const facePlan = buildFaceConsistencyPrompt({
+            prompt: effectivePrompt,
+            faceStrength: args.face_strength || activeAnchor?.strength,
+            characterName: activeAnchor?.label,
+          })
+          effectivePrompt = facePlan.prompt
+          if (facePlan.negativePrompt) {
+            effectiveNegative = effectiveNegative ? `${effectiveNegative}, ${facePlan.negativePrompt}` : facePlan.negativePrompt
+          }
+        } else if (args.reference_image) {
           effectivePrompt = `${effectivePrompt}, visual reference anchor`
         } else if (activeAnchor) {
           effectivePrompt = applyAnchorPromptHints(activeAnchor, effectivePrompt)
@@ -373,7 +397,7 @@ export function registerGenerationTools(ctx, deps) {
         assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
         const providers = makeProviders(
           { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg, subscriptionImages },
-          { prompt: effectivePrompt, size, format, seed: args.seed, signal: exec.signal, negativePrompt: effectiveNegative, guidanceScale: effectiveGuidance, source, mask, strength: args.strength, quality: args.quality, style: args.style, aspectPixels, aspectRatio: args.aspect_ratio },
+          { prompt: effectivePrompt, size, format, seed: args.seed, signal: exec.signal, negativePrompt: effectiveNegative, guidanceScale: effectiveGuidance, source, mask, strength: args.strength, quality: args.quality, style: args.style, aspectPixels, aspectRatio: args.aspect_ratio, faceReference: resolvedFaceRef },
         )
       // Subscription providers return {ok:false, reason} instead of throwing:
       // rejection reaches the model as text. Without this guard,

package/lib/tools/style-matrix.js

@@ -126,7 +126,7 @@ export function registerStyleMatrixTools(ctx, deps) {
 
           const provider = PROVIDER_KEYS.includes(cfg.provider) ? cfg.provider : 'fal'
           let subscriptionImages
-          try { subscriptionImages = ctx.get && ctx.get('subscriptionImages') } catch { subscriptionImages = undefined }
+          try { subscriptionImages = ctx.get && ctx.get('subscriptionImages') } catch (_err) { subscriptionImages = undefined }
 
           const chain = resolveFallbackChain(provider, cfg.fallbackProviders, PROVIDER_KEYS)
           const quadrantIds = ['A', 'B', 'C', 'D']

package/lib/tools/ui-asset.js

@@ -145,7 +145,7 @@ export function registerUiAssetTools(ctx, deps) {
 
           const provider = PROVIDER_KEYS.includes(cfg.provider) ? cfg.provider : 'fal'
           let subscriptionImages
-          try { subscriptionImages = ctx.get && ctx.get('subscriptionImages') } catch { subscriptionImages = undefined }
+          try { subscriptionImages = ctx.get && ctx.get('subscriptionImages') } catch (_err) { subscriptionImages = undefined }
 
           const providers = makeProviders(
             { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg, subscriptionImages },