@goodandready/dsh-image-gen 0.11.10 → 0.11.12

package/lib/tools/character-sheet.js

@@ -0,0 +1,187 @@
+// 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: (result, renderCtx) =>
+            renderToolOutput(result, renderCtx, {
+              title: (res) => `Character Sheet (${res.layout || 'turnaround'}) — ${res.style || 'concept_art'}`,
+              subtitle: (res) => (res.views ? `Views: ${res.views.join(' | ')}` : ''),
+            }),
+        },
+        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,172 @@
+// 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: (result, renderCtx) =>
+            renderToolOutput(result, renderCtx, {
+              title: (res) => `3D Architecture Diagram — ${res.title || res.style || 'Isometric'}`,
+              subtitle: (res) => (res.detectedNodes?.length ? `Nodes: ${res.detectedNodes.slice(0, 4).join(', ')}` : ''),
+            }),
+        },
+        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

@@ -41,7 +41,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,
@@ -172,6 +172,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: {
@@ -182,7 +190,28 @@ export function registerGenerationTools(ctx, deps) {
             channel: { type: 'string' },
             provider: { type: 'string' },
             model: { type: 'string' },
-            _fallback: { type: 'string' },
+            _fallback: {
+              type: 'object',
+              additionalProperties: true,
+              properties: {
+                triggered: { type: 'boolean' },
+                primaryProvider: { type: 'string' },
+                providerUsed: { type: 'string' },
+                attempts: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    additionalProperties: true,
+                    properties: {
+                      provider: { type: 'string' },
+                      durationMs: { type: 'number' },
+                      success: { type: 'boolean' },
+                      error: { type: 'string' },
+                    },
+                  },
+                },
+              },
+            },
             path: { type: 'string' },
             url: { type: 'string' },
             width: { type: 'integer' },
@@ -231,7 +260,28 @@ export function registerGenerationTools(ctx, deps) {
                   cost: { type: 'number' },
                   fromCache: { type: 'boolean' },
                   qualityReport: { type: 'object', additionalProperties: true },
-                  _fallback: { type: 'string' },
+                  _fallback: {
+                    type: 'object',
+                    additionalProperties: true,
+                    properties: {
+                      triggered: { type: 'boolean' },
+                      primaryProvider: { type: 'string' },
+                      providerUsed: { type: 'string' },
+                      attempts: {
+                        type: 'array',
+                        items: {
+                          type: 'object',
+                          additionalProperties: true,
+                          properties: {
+                            provider: { type: 'string' },
+                            durationMs: { type: 'number' },
+                            success: { type: 'boolean' },
+                            error: { type: 'string' },
+                          },
+                        },
+                      },
+                    },
+                  },
                   provider: { type: 'string' },
                   model: { type: 'string' },
                   attachment: {
@@ -303,7 +353,24 @@ 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 {
+            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)
@@ -331,7 +398,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/ui-asset.js

@@ -91,6 +91,28 @@ export function registerUiAssetTools(ctx, deps) {
                 type: 'object',
                 additionalProperties: true,
               },
+            _fallback: {
+              type: 'object',
+              additionalProperties: true,
+              properties: {
+                triggered: { type: 'boolean' },
+                primaryProvider: { type: 'string' },
+                providerUsed: { type: 'string' },
+                attempts: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    additionalProperties: true,
+                    properties: {
+                      provider: { type: 'string' },
+                      durationMs: { type: 'number' },
+                      success: { type: 'boolean' },
+                      error: { type: 'string' },
+                    },
+                  },
+                },
+              },
+            },
             },
           },
           render(args, value) {