transloadit 4.7.6 → 4.8.0

package/src/cli/semanticIntents/imageGenerate.ts

@@ -0,0 +1,254 @@
+import { basename } from 'node:path'
+import type { IntentOptionDefinition, PreparedIntentInputs } from '../intentRuntime.ts'
+import type { SemanticIntentDescriptor, SemanticIntentPresentation } from './index.ts'
+import { parseOptionalEnumValue } from './parsing.ts'
+
+const defaultImageGenerateModel = 'google/nano-banana-2'
+const imageGenerateFormats = ['jpeg', 'jpg', 'png', 'gif', 'webp', 'svg'] as const
+
+const imageGenerateOptionDefinitions = [
+  {
+    name: 'prompt',
+    kind: 'string',
+    propertyName: 'prompt',
+    optionFlags: '--prompt',
+    description: 'The prompt describing the desired image content.',
+    required: true,
+    exampleValue: JSON.stringify('A red bicycle in a studio'),
+  },
+  {
+    name: 'model',
+    kind: 'string',
+    propertyName: 'model',
+    optionFlags: '--model',
+    description: `The AI model to use for image generation. Defaults to ${defaultImageGenerateModel}.`,
+    required: false,
+    exampleValue: defaultImageGenerateModel,
+  },
+  {
+    name: 'format',
+    kind: 'string',
+    propertyName: 'format',
+    optionFlags: '--format',
+    description: 'Format of the generated image.',
+    required: false,
+    exampleValue: 'jpg',
+  },
+  {
+    name: 'seed',
+    kind: 'number',
+    propertyName: 'seed',
+    optionFlags: '--seed',
+    description: 'Seed for the random number generator.',
+    required: false,
+  },
+  {
+    name: 'aspectRatio',
+    kind: 'string',
+    propertyName: 'aspectRatio',
+    optionFlags: '--aspect-ratio',
+    description: 'Aspect ratio of the generated image.',
+    required: false,
+  },
+  {
+    name: 'height',
+    kind: 'number',
+    propertyName: 'height',
+    optionFlags: '--height',
+    description: 'Height of the generated image.',
+    required: false,
+  },
+  {
+    name: 'width',
+    kind: 'number',
+    propertyName: 'width',
+    optionFlags: '--width',
+    description: 'Width of the generated image.',
+    required: false,
+  },
+  {
+    name: 'style',
+    kind: 'string',
+    propertyName: 'style',
+    optionFlags: '--style',
+    description: 'Style of the generated image.',
+    required: false,
+  },
+  {
+    name: 'numOutputs',
+    kind: 'number',
+    propertyName: 'numOutputs',
+    optionFlags: '--num-outputs',
+    description: 'Number of image variants to generate.',
+    required: false,
+  },
+] as const satisfies readonly IntentOptionDefinition[]
+
+const imageGenerateCommandPresentation = {
+  description: 'Generate images from text prompts',
+  details:
+    'Runs `/image/generate`. Without inputs, this is text-to-image. With one or more `--input` files, the inputs are bundled into a single assembly so the prompt can refer to them by filename.',
+  examples: [
+    [
+      'Generate an image from text',
+      'transloadit image generate --prompt "A red bicycle in a studio" --out output.png',
+    ],
+    [
+      'Guide generation with one input image',
+      'transloadit image generate --input subject.jpg --prompt "Place subject.jpg on a magazine cover" --out output.png',
+    ],
+    [
+      'Guide generation with multiple input images',
+      'transloadit image generate --input person1.jpg --input person2.jpg --input background.jpg --prompt "Place person1.jpg feeding person2.jpg in front of background.jpg" --out output.png',
+    ],
+  ] as Array<[string, string]>,
+} as const satisfies SemanticIntentPresentation
+
+function parseOptionalFormat(value: unknown): (typeof imageGenerateFormats)[number] | null {
+  return parseOptionalEnumValue({
+    flagName: '--format',
+    supportedValues: imageGenerateFormats,
+    value,
+  })
+}
+
+function parseRequiredPrompt(value: unknown): string {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error('image generate requires --prompt')
+  }
+
+  return value
+}
+
+function parseOptionalNumber(flagName: string, value: unknown): number | undefined {
+  if (value == null || value === '') {
+    return undefined
+  }
+
+  const numericValue = typeof value === 'number' ? value : Number(String(value).trim())
+  if (Number.isNaN(numericValue)) {
+    throw new Error(`${flagName} must be a number`)
+  }
+
+  return numericValue
+}
+
+function parseOptionalIntegerRange(
+  flagName: string,
+  value: unknown,
+  { max, min }: { max: number; min: number },
+): number | undefined {
+  const numericValue = parseOptionalNumber(flagName, value)
+  if (numericValue == null) {
+    return undefined
+  }
+
+  if (!Number.isInteger(numericValue) || numericValue < min || numericValue > max) {
+    throw new Error(`${flagName} must be an integer between ${min} and ${max}`)
+  }
+
+  return numericValue
+}
+
+function createImageGenerateStep(
+  rawValues: Record<string, unknown>,
+  context: { hasInputs: boolean },
+): Record<string, unknown> {
+  const step: Record<string, unknown> = {
+    robot: '/image/generate',
+    result: true,
+    model: defaultImageGenerateModel,
+    prompt: parseRequiredPrompt(rawValues.prompt),
+  }
+
+  if (context.hasInputs) {
+    step.use = {
+      steps: [':original'],
+      bundle_steps: true,
+    }
+  }
+
+  const model = rawValues.model
+  if (typeof model === 'string' && model.trim() !== '') {
+    step.model = model
+  }
+
+  const format = parseOptionalFormat(rawValues.format)
+  if (format != null) {
+    step.format = format
+  }
+
+  const seed = parseOptionalNumber('--seed', rawValues.seed)
+  if (seed != null) {
+    step.seed = seed
+  }
+
+  const aspectRatio = rawValues.aspectRatio
+  if (typeof aspectRatio === 'string' && aspectRatio.trim() !== '') {
+    step.aspect_ratio = aspectRatio
+  }
+
+  const height = parseOptionalNumber('--height', rawValues.height)
+  if (height != null) {
+    step.height = height
+  }
+
+  const width = parseOptionalNumber('--width', rawValues.width)
+  if (width != null) {
+    step.width = width
+  }
+
+  const style = rawValues.style
+  if (typeof style === 'string' && style.trim() !== '') {
+    step.style = style
+  }
+
+  const numOutputs = parseOptionalIntegerRange('--num-outputs', rawValues.numOutputs, {
+    min: 1,
+    max: 10,
+  })
+  if (numOutputs != null) {
+    step.num_outputs = numOutputs
+  }
+
+  return step
+}
+
+function ensureUniqueInputBasenames(preparedInputs: PreparedIntentInputs): PreparedIntentInputs {
+  const seenBasenames = new Map<string, string>()
+
+  for (const input of preparedInputs.inputs) {
+    const inputBasename = basename(input)
+    const previousInput = seenBasenames.get(inputBasename)
+    if (previousInput != null) {
+      throw new Error(
+        `image generate requires unique input basenames when prompts refer to files; found duplicate ${inputBasename} in ${previousInput} and ${input}`,
+      )
+    }
+
+    seenBasenames.set(inputBasename, input)
+  }
+
+  return preparedInputs
+}
+
+export const imageGenerateSemanticIntentDescriptor = {
+  createStep: createImageGenerateStep,
+  execution: {
+    kind: 'dynamic-step',
+    handler: 'image-generate',
+    resultStepName: 'generate',
+    fields: imageGenerateOptionDefinitions,
+  },
+  inputPolicy: {
+    kind: 'optional',
+    field: 'prompt',
+    attachUseWhenInputsProvided: false,
+  },
+  outputDescription: 'Write the result to this path',
+  async prepareInputs(preparedInputs) {
+    return await Promise.resolve(ensureUniqueInputBasenames(preparedInputs))
+  },
+  presentation: imageGenerateCommandPresentation,
+  runnerKind: 'bundled',
+} as const satisfies SemanticIntentDescriptor

package/src/cli/semanticIntents/index.ts

@@ -5,6 +5,7 @@ import type {
   PreparedIntentInputs,
 } from '../intentRuntime.ts'
 import { imageDescribeSemanticIntentDescriptor } from './imageDescribe.ts'
+import { imageGenerateSemanticIntentDescriptor } from './imageGenerate.ts'
 import {
   markdownDocxSemanticIntentDescriptor,
   markdownPdfSemanticIntentDescriptor,
@@ -17,7 +18,10 @@ export interface SemanticIntentPresentation {
 }
 
 export interface SemanticIntentDescriptor {
-  createStep: (rawValues: Record<string, unknown>) => Record<string, unknown>
+  createStep: (
+    rawValues: Record<string, unknown>,
+    context: { hasInputs: boolean },
+  ) => Record<string, unknown>
   execution: IntentDynamicStepExecutionDefinition
   inputPolicy: IntentInputPolicy
   outputDescription: string
@@ -31,6 +35,7 @@ export interface SemanticIntentDescriptor {
 
 const semanticIntentDescriptors: Record<string, SemanticIntentDescriptor> = {
   'image-describe': imageDescribeSemanticIntentDescriptor,
+  'image-generate': imageGenerateSemanticIntentDescriptor,
   'markdown-pdf': {
     ...markdownPdfSemanticIntentDescriptor,
   },

package/src/cli/semanticIntents/markdownPdf.ts

@@ -76,7 +76,7 @@ function createMarkdownConvertSemanticIntent({
   } satisfies SemanticIntentPresentation
 
   return {
-    createStep(rawValues) {
+    createStep(rawValues, _context) {
       return {
         robot: '/document/convert',
         use: ':original',

package/src/robots.ts

@@ -1,5 +1,5 @@
 import type { z } from 'zod'
-import { robotsMeta, robotsSchema } from './alphalib/types/robots/_index.ts'
+import { getRobotSchemaOptions, robotsMeta } from './alphalib/types/robots/_index.ts'
 
 export type RobotListOptions = {
   category?: string
@@ -219,7 +219,7 @@ const getRobotsMetaIndex = (): {
 
 const getRobotSchemaIndex = (): Map<string, z.ZodTypeAny> => {
   const index = new Map<string, z.ZodTypeAny>()
-  for (const option of robotsSchema.options) {
+  for (const option of getRobotSchemaOptions()) {
     const shape = getShape(option)
     const robotSchema = shape.robot
     if (!robotSchema) continue