@snaptrude/plugin-core 0.2.6 → 0.2.8

package/src/api/documentation/aiInspiration.ts

@@ -0,0 +1,871 @@
+import * as z from "zod"
+import type { PluginApiReturn } from "../../types"
+
+const JsonPrimitive = z.union([z.string(), z.number(), z.boolean(), z.null()])
+type JsonValue =
+  | z.infer<typeof JsonPrimitive>
+  | JsonValue[]
+  | { [key: string]: JsonValue }
+const JsonValue: z.ZodType<JsonValue> = z.lazy(() =>
+  z.union([JsonPrimitive, z.array(JsonValue), z.record(z.string(), JsonValue)]),
+)
+
+export const PluginAIInspirationRunMode = z.enum(["blocking", "job"])
+export type PluginAIInspirationRunMode = z.infer<
+  typeof PluginAIInspirationRunMode
+>
+
+export const PluginAIInspirationOutputKind = z.enum([
+  "source",
+  "image",
+  "video",
+])
+export type PluginAIInspirationOutputKind = z.infer<
+  typeof PluginAIInspirationOutputKind
+>
+
+export const PluginAIInspirationModelOutput = z.enum(["image", "video"])
+export type PluginAIInspirationModelOutput = z.infer<
+  typeof PluginAIInspirationModelOutput
+>
+
+export const PluginAIInspirationRuntimeProvider = z.enum(["gpt", "fal"])
+export type PluginAIInspirationRuntimeProvider = z.infer<
+  typeof PluginAIInspirationRuntimeProvider
+>
+
+export const PluginAIInspirationPromptStrategy = z.enum([
+  "gpt-image",
+  "fal-image",
+  "fal-video",
+])
+export type PluginAIInspirationPromptStrategy = z.infer<
+  typeof PluginAIInspirationPromptStrategy
+>
+
+export const PluginAIInspirationShapeKind = z.enum(["image", "view", "video"])
+export type PluginAIInspirationShapeKind = z.infer<
+  typeof PluginAIInspirationShapeKind
+>
+
+export const PluginAIInspirationVideoMode = z.enum([
+  "animate",
+  "references",
+  "keyframes",
+])
+export type PluginAIInspirationVideoMode = z.infer<
+  typeof PluginAIInspirationVideoMode
+>
+
+export const PluginAIInspirationVideoMotion = z.enum([
+  "auto",
+  "slow-dolly",
+  "subtle-orbit",
+  "reveal",
+])
+export type PluginAIInspirationVideoMotion = z.infer<
+  typeof PluginAIInspirationVideoMotion
+>
+
+export const PluginAIInspirationVideoDuration = z.enum(["4s", "6s", "8s"])
+export type PluginAIInspirationVideoDuration = z.infer<
+  typeof PluginAIInspirationVideoDuration
+>
+
+export const PluginAIInspirationJobStatus = z.enum([
+  "queued",
+  "running",
+  "completed",
+  "failed",
+  "cancelled",
+])
+export type PluginAIInspirationJobStatus = z.infer<
+  typeof PluginAIInspirationJobStatus
+>
+
+export const PluginAIInspirationWorkflowRunState = z.enum([
+  "current",
+  "stale",
+  "running",
+  "failed",
+  "superseded",
+])
+export type PluginAIInspirationWorkflowRunState = z.infer<
+  typeof PluginAIInspirationWorkflowRunState
+>
+
+export const PluginAIInspirationRegionHint = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  w: z.number().finite().positive(),
+  h: z.number().finite().positive(),
+})
+export type PluginAIInspirationRegionHint = z.infer<
+  typeof PluginAIInspirationRegionHint
+>
+
+export const PluginAIInspirationPoint = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+})
+export type PluginAIInspirationPoint = z.infer<typeof PluginAIInspirationPoint>
+
+export const PluginAIInspirationTextAnnotation = z.object({
+  text: z.string().min(1),
+  x: z.number().finite().optional(),
+  y: z.number().finite().optional(),
+})
+export type PluginAIInspirationTextAnnotation = z.infer<
+  typeof PluginAIInspirationTextAnnotation
+>
+
+export const PluginAIInspirationSketchGuidance = z.object({
+  visualShapeIds: z.array(z.string()).optional(),
+  textAnnotations: z.array(PluginAIInspirationTextAnnotation).optional(),
+})
+export type PluginAIInspirationSketchGuidance = z.infer<
+  typeof PluginAIInspirationSketchGuidance
+>
+
+export const PluginAIInspirationSiteOptions = z.object({
+  includeSatellite: z.boolean().optional(),
+  includeStreetView: z.boolean().optional(),
+  includeAerial: z.boolean().optional(),
+  aerialBearing: z.number().finite().optional(),
+  aerialPitch: z.number().finite().optional(),
+  selectedDiagramIds: z.array(z.string()).optional(),
+  location: z
+    .object({
+      lat: z.number().finite(),
+      lng: z.number().finite(),
+    })
+    .optional(),
+})
+export type PluginAIInspirationSiteOptions = z.infer<
+  typeof PluginAIInspirationSiteOptions
+>
+
+export const PluginAIInspirationAppliedPreset = z.object({
+  source: z.enum(["curated", "user"]),
+  presetId: z.string().min(1),
+  name: z.string().min(1),
+  savedPresetKind: z.enum(["prompt", "style"]).optional(),
+  stylePrompt: z.string().optional(),
+  modelId: z.string().optional(),
+  referenceImages: z
+    .array(
+      z.object({
+        url: z.string().min(1),
+        label: z.string().optional(),
+        weight: z.number().finite().optional(),
+      }),
+    )
+    .optional(),
+  siteDefaults: z
+    .object({
+      includeSatellite: z.boolean().optional(),
+      includeStreetView: z.boolean().optional(),
+      includeAerial: z.boolean().optional(),
+    })
+    .optional(),
+})
+export type PluginAIInspirationAppliedPreset = z.infer<
+  typeof PluginAIInspirationAppliedPreset
+>
+
+export const PluginAIInspirationVideoOptions = z.object({
+  mode: PluginAIInspirationVideoMode.optional(),
+  endFrameShapeId: z.string().optional(),
+  motion: PluginAIInspirationVideoMotion.optional(),
+  duration: PluginAIInspirationVideoDuration.optional(),
+})
+export type PluginAIInspirationVideoOptions = z.infer<
+  typeof PluginAIInspirationVideoOptions
+>
+
+export const PluginAIInspirationModel = z.object({
+  id: z.string(),
+  label: z.string(),
+  supportsMultiImage: z.boolean(),
+  output: PluginAIInspirationModelOutput,
+  isDefault: z.boolean().optional(),
+})
+export type PluginAIInspirationModel = z.infer<typeof PluginAIInspirationModel>
+
+export const PluginAIInspirationModelCapability = z.object({
+  id: z.string(),
+  output: PluginAIInspirationModelOutput,
+  provider: PluginAIInspirationRuntimeProvider,
+  supportsRegionEdit: z.boolean(),
+  supportsReferenceImages: z.boolean(),
+  supportsStylePresets: z.boolean(),
+  supportsSiteContext: z.boolean(),
+  supportsSketchGuidance: z.boolean(),
+  supportsKeyframes: z.boolean(),
+  maxExtraImages: z.number().int().nonnegative(),
+  promptStrategy: PluginAIInspirationPromptStrategy,
+})
+export type PluginAIInspirationModelCapability = z.infer<
+  typeof PluginAIInspirationModelCapability
+>
+
+export const PluginAIInspirationListModelsResult = z.object({
+  defaultModelId: z.string(),
+  models: z.array(PluginAIInspirationModel),
+})
+export type PluginAIInspirationListModelsResult = z.infer<
+  typeof PluginAIInspirationListModelsResult
+>
+
+export const PluginAIInspirationGetModelCapabilitiesArgs = z.object({
+  modelId: z.string().min(1),
+})
+export type PluginAIInspirationGetModelCapabilitiesArgs = z.infer<
+  typeof PluginAIInspirationGetModelCapabilitiesArgs
+>
+
+export const PluginAIInspirationGetModelCapabilitiesResult = z.object({
+  capability: PluginAIInspirationModelCapability,
+})
+export type PluginAIInspirationGetModelCapabilitiesResult = z.infer<
+  typeof PluginAIInspirationGetModelCapabilitiesResult
+>
+
+export const PluginAIInspirationShapeRef = z.object({
+  shapeId: z.string(),
+  assetId: z.string().optional(),
+  kind: PluginAIInspirationShapeKind,
+  name: z.string().optional(),
+  width: z.number().finite().optional(),
+  height: z.number().finite().optional(),
+  outputType: PluginAIInspirationOutputKind.optional(),
+  sourceUrl: z.string().optional(),
+})
+export type PluginAIInspirationShapeRef = z.infer<
+  typeof PluginAIInspirationShapeRef
+>
+
+export const PluginAIInspirationListSourcesArgs = z.object({
+  includeGenerated: z.boolean().optional(),
+  includeSourceUrl: z.boolean().optional(),
+})
+export type PluginAIInspirationListSourcesArgs = z.infer<
+  typeof PluginAIInspirationListSourcesArgs
+>
+
+export const PluginAIInspirationListSourcesResult = z.object({
+  sources: z.array(PluginAIInspirationShapeRef),
+})
+export type PluginAIInspirationListSourcesResult = z.infer<
+  typeof PluginAIInspirationListSourcesResult
+>
+
+export const PluginAIInspirationGetSelectionResult = z.object({
+  selectedShapeIds: z.array(z.string()),
+  sources: z.array(PluginAIInspirationShapeRef),
+})
+export type PluginAIInspirationGetSelectionResult = z.infer<
+  typeof PluginAIInspirationGetSelectionResult
+>
+
+export const PluginAIInspirationPresetReferenceImage = z.object({
+  url: z.string(),
+  label: z.string().optional(),
+  weight: z.number().finite().optional(),
+})
+export type PluginAIInspirationPresetReferenceImage = z.infer<
+  typeof PluginAIInspirationPresetReferenceImage
+>
+
+export const PluginAIInspirationPreset = z.object({
+  id: z.string(),
+  name: z.string(),
+  source: z.enum(["curated", "user"]),
+  modelId: z.string(),
+  categoryId: z.string().optional(),
+  categoryLabel: z.string().optional(),
+  description: z.string().optional(),
+  previewImageUrl: z.string().optional(),
+  prompt: z.string().optional(),
+  stylePrompt: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  referenceImages: z.array(PluginAIInspirationPresetReferenceImage).optional(),
+  siteDefaults: PluginAIInspirationAppliedPreset.shape.siteDefaults.optional(),
+})
+export type PluginAIInspirationPreset = z.infer<
+  typeof PluginAIInspirationPreset
+>
+
+export const PluginAIInspirationPresetCategory = z.object({
+  id: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+})
+export type PluginAIInspirationPresetCategory = z.infer<
+  typeof PluginAIInspirationPresetCategory
+>
+
+export const PluginAIInspirationGetPresetCatalogResult = z.object({
+  categories: z.array(PluginAIInspirationPresetCategory),
+  presets: z.array(PluginAIInspirationPreset),
+})
+export type PluginAIInspirationGetPresetCatalogResult = z.infer<
+  typeof PluginAIInspirationGetPresetCatalogResult
+>
+
+export const PluginAIInspirationOutput = z.object({
+  outputType: z.enum(["image", "video"]),
+  shapeId: z.string(),
+  assetId: z.string(),
+  outputUrl: z.string().optional(),
+  position: PluginAIInspirationPoint.optional(),
+})
+export type PluginAIInspirationOutput = z.infer<
+  typeof PluginAIInspirationOutput
+>
+
+export const PluginAIInspirationDebugSummary = z.record(z.string(), JsonValue)
+export type PluginAIInspirationDebugSummary = z.infer<
+  typeof PluginAIInspirationDebugSummary
+>
+
+export const PluginAIInspirationRunMetadata = z.object({
+  geometryFidelity: z.string().optional(),
+  debugSummary: PluginAIInspirationDebugSummary.optional(),
+  streetViewComposite: z
+    .object({
+      used: z.boolean(),
+      renderMode: z.enum(["prompt_refs_default", "masked_composite_pilot"]),
+      backgroundLabel: z.string().optional(),
+    })
+    .optional(),
+})
+export type PluginAIInspirationRunMetadata = z.infer<
+  typeof PluginAIInspirationRunMetadata
+>
+
+export const PluginAIInspirationGenerateArgs = z.object({
+  sourceShapeId: z.string().min(1),
+  prompt: z.string().min(1).max(8000),
+  modelId: z.string().optional(),
+  referenceShapeIds: z.array(z.string()).max(12).optional(),
+  referenceStrength: z.enum(["low", "medium", "high"]).optional(),
+  appliedPreset: PluginAIInspirationAppliedPreset.optional(),
+  site: PluginAIInspirationSiteOptions.optional(),
+  regionHint: PluginAIInspirationRegionHint.optional(),
+  sketchGuidance: PluginAIInspirationSketchGuidance.optional(),
+  video: PluginAIInspirationVideoOptions.optional(),
+  runMode: PluginAIInspirationRunMode.optional(),
+})
+export type PluginAIInspirationGenerateArgs = z.infer<
+  typeof PluginAIInspirationGenerateArgs
+>
+
+export const PluginAIInspirationRunResult = z.object({
+  jobId: z.string().optional(),
+  output: PluginAIInspirationOutput.optional(),
+  outputs: z.array(PluginAIInspirationOutput).optional(),
+  metadata: PluginAIInspirationRunMetadata.optional(),
+})
+export type PluginAIInspirationRunResult = z.infer<
+  typeof PluginAIInspirationRunResult
+>
+
+export const PluginAIInspirationRefineArgs = z.object({
+  sourceShapeId: z.string().min(1),
+  upscaleFactor: z
+    .union([z.literal(1.5), z.literal(2), z.literal(4)])
+    .optional(),
+  runMode: PluginAIInspirationRunMode.optional(),
+})
+export type PluginAIInspirationRefineArgs = z.infer<
+  typeof PluginAIInspirationRefineArgs
+>
+
+export const PluginAIInspirationJobProgress = z.object({
+  currentStep: z.number().int().nonnegative().optional(),
+  totalSteps: z.number().int().nonnegative().optional(),
+  message: z.string().optional(),
+})
+export type PluginAIInspirationJobProgress = z.infer<
+  typeof PluginAIInspirationJobProgress
+>
+
+export const PluginAIInspirationJob = z.object({
+  jobId: z.string(),
+  status: PluginAIInspirationJobStatus,
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  completedAt: z.number().optional(),
+  method: z.string(),
+  progress: PluginAIInspirationJobProgress.optional(),
+  result: PluginAIInspirationRunResult.optional(),
+  error: z.string().optional(),
+})
+export type PluginAIInspirationJob = z.infer<typeof PluginAIInspirationJob>
+
+export const PluginAIInspirationJobArgs = z.object({
+  jobId: z.string().min(1),
+})
+export type PluginAIInspirationJobArgs = z.infer<
+  typeof PluginAIInspirationJobArgs
+>
+
+export const PluginAIInspirationGetJobResult = z.object({
+  job: PluginAIInspirationJob,
+})
+export type PluginAIInspirationGetJobResult = z.infer<
+  typeof PluginAIInspirationGetJobResult
+>
+
+export const PluginAIInspirationCancelJobResult = z.object({
+  job: PluginAIInspirationJob,
+})
+export type PluginAIInspirationCancelJobResult = z.infer<
+  typeof PluginAIInspirationCancelJobResult
+>
+
+export const PluginAIInspirationListJobsResult = z.object({
+  jobs: z.array(PluginAIInspirationJob),
+})
+export type PluginAIInspirationListJobsResult = z.infer<
+  typeof PluginAIInspirationListJobsResult
+>
+
+export const PluginAIInspirationWorkflowVideoConfig = z.object({
+  mode: z.string().optional(),
+  motion: z.string().optional(),
+  duration: z.string().optional(),
+  endFrameShapeId: z.string().optional(),
+})
+export type PluginAIInspirationWorkflowVideoConfig = z.infer<
+  typeof PluginAIInspirationWorkflowVideoConfig
+>
+
+export const PluginAIInspirationGenerationInputSnapshot = z.object({
+  version: z.literal(1),
+  meta: z.record(z.string(), JsonValue),
+  regionHint: PluginAIInspirationRegionHint.optional(),
+  sketchGuidance: z.record(z.string(), JsonValue).optional(),
+  sourceCameraHeading: z.number().finite().optional(),
+})
+export type PluginAIInspirationGenerationInputSnapshot = z.infer<
+  typeof PluginAIInspirationGenerationInputSnapshot
+>
+
+export const PluginAIInspirationWorkflowOperation = z.object({
+  type: z.enum(["generate-image", "refine", "generate-video"]),
+  label: z.string(),
+  prompt: z.string().optional(),
+  modelId: z.string().optional(),
+  presetId: z.string().optional(),
+  presetName: z.string().optional(),
+  refineFactor: z.number().finite().optional(),
+  sourceRole: z.enum(["primary", "end-frame"]).optional(),
+  video: PluginAIInspirationWorkflowVideoConfig.optional(),
+  generationInput: PluginAIInspirationGenerationInputSnapshot.optional(),
+})
+export type PluginAIInspirationWorkflowOperation = z.infer<
+  typeof PluginAIInspirationWorkflowOperation
+>
+
+export const PluginAIInspirationWorkflowNode = z.object({
+  id: z.string(),
+  shapeId: z.string(),
+  assetId: z.string().optional(),
+  kind: PluginAIInspirationOutputKind,
+  state: z.string(),
+  runState: PluginAIInspirationWorkflowRunState.optional(),
+  staleReason: z.string().optional(),
+  incomingEdgeIds: z.array(z.string()),
+  outgoingEdgeIds: z.array(z.string()),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+})
+export type PluginAIInspirationWorkflowNode = z.infer<
+  typeof PluginAIInspirationWorkflowNode
+>
+
+export const PluginAIInspirationWorkflowEdge = z.object({
+  id: z.string(),
+  sourceNodeId: z.string(),
+  targetNodeId: z.string(),
+  arrowShapeId: z.string().optional(),
+  operation: PluginAIInspirationWorkflowOperation,
+  state: z.string(),
+  runState: PluginAIInspirationWorkflowRunState.optional(),
+  staleReason: z.string().optional(),
+  supersededByEdgeId: z.string().optional(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+})
+export type PluginAIInspirationWorkflowEdge = z.infer<
+  typeof PluginAIInspirationWorkflowEdge
+>
+
+export const PluginAIInspirationWorkflow = z.object({
+  id: z.string(),
+  rootNodeIds: z.array(z.string()),
+  nodeIds: z.array(z.string()),
+  edgeIds: z.array(z.string()),
+  nodes: z.record(z.string(), PluginAIInspirationWorkflowNode),
+  edges: z.record(z.string(), PluginAIInspirationWorkflowEdge),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+})
+export type PluginAIInspirationWorkflow = z.infer<
+  typeof PluginAIInspirationWorkflow
+>
+
+export const PluginAIInspirationGetWorkflowForShapeArgs = z.object({
+  shapeId: z.string().min(1),
+})
+export type PluginAIInspirationGetWorkflowForShapeArgs = z.infer<
+  typeof PluginAIInspirationGetWorkflowForShapeArgs
+>
+
+export const PluginAIInspirationGetWorkflowForShapeResult = z.object({
+  workflow: PluginAIInspirationWorkflow.nullable(),
+  node: PluginAIInspirationWorkflowNode.nullable(),
+})
+export type PluginAIInspirationGetWorkflowForShapeResult = z.infer<
+  typeof PluginAIInspirationGetWorkflowForShapeResult
+>
+
+export const PluginAIInspirationRerunPlanResult = z.discriminatedUnion(
+  "status",
+  [
+    z.object({
+      status: z.literal("ready"),
+      workflowId: z.string(),
+      sourceNode: PluginAIInspirationWorkflowNode,
+      edgeIds: z.array(z.string()),
+      edges: z.array(PluginAIInspirationWorkflowEdge),
+      recipe: z.lazy(() => PluginAIInspirationRecipe),
+      needsEndFrame: z.boolean(),
+      defaultEndFrameShapeId: z.string().nullable(),
+    }),
+    z.object({
+      status: z.literal("unavailable"),
+      reason: z.enum([
+        "not-in-workflow",
+        "source-only",
+        "running",
+        "missing-input",
+      ]),
+    }),
+  ],
+)
+export type PluginAIInspirationRerunPlanResult = z.infer<
+  typeof PluginAIInspirationRerunPlanResult
+>
+
+export const PluginAIInspirationRerunSelectedBranchArgs = z.object({
+  shapeId: z.string().min(1),
+  endFrameShapeId: z.string().optional(),
+  runMode: PluginAIInspirationRunMode.optional(),
+})
+export type PluginAIInspirationRerunSelectedBranchArgs = z.infer<
+  typeof PluginAIInspirationRerunSelectedBranchArgs
+>
+
+export const PluginAIInspirationRecipeSlot = z.object({
+  id: z.string(),
+  type: z.enum(["source-image", "end-frame"]),
+  label: z.string(),
+  required: z.boolean(),
+})
+export type PluginAIInspirationRecipeSlot = z.infer<
+  typeof PluginAIInspirationRecipeSlot
+>
+
+export const PluginAIInspirationRecipeStep = z.object({
+  id: z.string(),
+  operation: PluginAIInspirationWorkflowOperation,
+  outputKind: z.enum(["image", "video"]),
+})
+export type PluginAIInspirationRecipeStep = z.infer<
+  typeof PluginAIInspirationRecipeStep
+>
+
+export const PluginAIInspirationRecipeDraft = z.object({
+  name: z.string(),
+  summary: z.string(),
+  slots: z.array(PluginAIInspirationRecipeSlot),
+  steps: z.array(PluginAIInspirationRecipeStep).min(1).max(20),
+  outputKind: z.enum(["image", "video"]),
+  thumbnailUrl: z.string().optional(),
+})
+export type PluginAIInspirationRecipeDraft = z.infer<
+  typeof PluginAIInspirationRecipeDraft
+>
+
+export const PluginAIInspirationRecipe: z.ZodType<
+  PluginAIInspirationRecipeDraft & {
+    version: 1
+    id: string
+    fingerprint?: string
+    createdAt: number
+    updatedAt: number
+  }
+> = PluginAIInspirationRecipeDraft.extend({
+  version: z.literal(1),
+  id: z.string(),
+  fingerprint: z.string().optional(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+})
+export type PluginAIInspirationRecipe = z.infer<
+  typeof PluginAIInspirationRecipe
+>
+
+export const PluginAIInspirationExtractionResult = z.discriminatedUnion(
+  "status",
+  [
+    z.object({
+      status: z.literal("ready"),
+      draft: PluginAIInspirationRecipeDraft,
+    }),
+    z.object({
+      status: z.literal("unavailable"),
+      reason: z.enum([
+        "not-in-workflow",
+        "source-only",
+        "missing-workflow",
+        "missing-node",
+        "missing-input",
+        "invalid-workflow",
+      ]),
+    }),
+  ],
+)
+export type PluginAIInspirationExtractionResult = z.infer<
+  typeof PluginAIInspirationExtractionResult
+>
+
+export const PluginAIInspirationListRecipesResult = z.object({
+  recipes: z.array(PluginAIInspirationRecipe),
+})
+export type PluginAIInspirationListRecipesResult = z.infer<
+  typeof PluginAIInspirationListRecipesResult
+>
+
+export const PluginAIInspirationSaveRecipeArgs = z.object({
+  draft: PluginAIInspirationRecipeDraft,
+  name: z.string().min(1),
+})
+export type PluginAIInspirationSaveRecipeArgs = z.infer<
+  typeof PluginAIInspirationSaveRecipeArgs
+>
+
+export const PluginAIInspirationSaveRecipeResult = z.discriminatedUnion(
+  "status",
+  [
+    z.object({ status: z.literal("saved"), recipe: PluginAIInspirationRecipe }),
+    z.object({
+      status: z.literal("duplicate"),
+      recipe: PluginAIInspirationRecipe,
+    }),
+    z.object({ status: z.literal("invalid-name"), recipe: z.null() }),
+    z.object({ status: z.literal("failed"), recipe: z.null() }),
+  ],
+)
+export type PluginAIInspirationSaveRecipeResult = z.infer<
+  typeof PluginAIInspirationSaveRecipeResult
+>
+
+export const PluginAIInspirationDeleteRecipeArgs = z.object({
+  recipeId: z.string().min(1),
+})
+export type PluginAIInspirationDeleteRecipeArgs = z.infer<
+  typeof PluginAIInspirationDeleteRecipeArgs
+>
+
+export const PluginAIInspirationDeleteRecipeResult = z.object({
+  deleted: z.boolean(),
+})
+export type PluginAIInspirationDeleteRecipeResult = z.infer<
+  typeof PluginAIInspirationDeleteRecipeResult
+>
+
+export const PluginAIInspirationExtractRecipeFromShapeArgs = z.object({
+  shapeId: z.string().min(1),
+})
+export type PluginAIInspirationExtractRecipeFromShapeArgs = z.infer<
+  typeof PluginAIInspirationExtractRecipeFromShapeArgs
+>
+
+export const PluginAIInspirationRunRecipeArgs = z.object({
+  recipeId: z.string().optional(),
+  recipe: PluginAIInspirationRecipe.optional(),
+  slotShapeIds: z.record(z.string(), z.string()),
+  runMode: PluginAIInspirationRunMode.optional(),
+})
+export type PluginAIInspirationRunRecipeArgs = z.infer<
+  typeof PluginAIInspirationRunRecipeArgs
+>
+
+/**
+ * Present-mode AI Inspiration APIs.
+ *
+ * These APIs operate on Present canvas shape IDs and inherit the current user's
+ * AI quota. They create outputs on the Present canvas; pure backend generation
+ * without canvas output is intentionally out of scope.
+ *
+ * Accessed via `snaptrude.documentation.aiInspiration`.
+ */
+export abstract class PluginDocumentationAIInspirationApi {
+  constructor() {}
+
+  /**
+   * List AI Inspiration models that can be used for generation.
+   *
+   * @returns The default model ID and available model descriptors.
+   */
+  public abstract listModels(): PluginApiReturn<PluginAIInspirationListModelsResult>
+
+  /**
+   * Get capability flags for a model.
+   *
+   * @param args - Object containing `modelId`.
+   * @returns Capability flags such as reference, site-context, region, and keyframe support.
+   */
+  public abstract getModelCapabilities(
+    args: PluginAIInspirationGetModelCapabilitiesArgs,
+  ): PluginApiReturn<PluginAIInspirationGetModelCapabilitiesResult>
+
+  /**
+   * List image/view/video sources on the current Present page.
+   *
+   * @param args - Optional filters. Set `includeGenerated` to include AI outputs.
+   * @returns Serializable shape references using Present canvas shape IDs.
+   */
+  public abstract listSources(
+    args: PluginAIInspirationListSourcesArgs,
+  ): PluginApiReturn<PluginAIInspirationListSourcesResult>
+
+  /**
+   * Get selected Present canvas shapes that AI Inspiration can use.
+   *
+   * @returns Selected shape IDs and resolved source references.
+   */
+  public abstract getSelection(): PluginApiReturn<PluginAIInspirationGetSelectionResult>
+
+  /**
+   * Get the curated AI Inspiration preset catalog.
+   *
+   * @returns Preset categories and presets.
+   */
+  public abstract getPresetCatalog(): PluginApiReturn<PluginAIInspirationGetPresetCatalogResult>
+
+  /**
+   * Generate an image or video from a Present canvas source.
+   *
+   * @param args - Generation options including source, prompt, model, references, site context,
+   * region guidance, sketch guidance, and video options.
+   * @returns A canvas output in blocking mode or a job ID in job mode.
+   */
+  public abstract generate(
+    args: PluginAIInspirationGenerateArgs,
+  ): PluginApiReturn<PluginAIInspirationRunResult>
+
+  /**
+   * Refine/upscale an AI Inspiration source image.
+   *
+   * @param args - Source shape, optional upscale factor, and run mode.
+   * @returns A canvas output in blocking mode or a job ID in job mode.
+   */
+  public abstract refine(
+    args: PluginAIInspirationRefineArgs,
+  ): PluginApiReturn<PluginAIInspirationRunResult>
+
+  /** Get a transient AI Inspiration job by ID. */
+  public abstract getJob(
+    args: PluginAIInspirationJobArgs,
+  ): PluginApiReturn<PluginAIInspirationGetJobResult>
+
+  /** Cancel a transient AI Inspiration job. */
+  public abstract cancelJob(
+    args: PluginAIInspirationJobArgs,
+  ): PluginApiReturn<PluginAIInspirationCancelJobResult>
+
+  /** List transient AI Inspiration jobs created in the current host session. */
+  public abstract listJobs(): PluginApiReturn<PluginAIInspirationListJobsResult>
+
+  /**
+   * Get the sanitized workflow graph containing a Present shape.
+   *
+   * @param args - Object containing `shapeId`.
+   * @returns The workflow and matching node, or `null` values when the shape is not in a workflow.
+   */
+  public abstract getWorkflowForShape(
+    args: PluginAIInspirationGetWorkflowForShapeArgs,
+  ): PluginApiReturn<PluginAIInspirationGetWorkflowForShapeResult>
+
+  /**
+   * Build a rerun plan for the selected workflow branch ending at a shape.
+   *
+   * @param args - Object containing `shapeId`.
+   * @returns Ready plan data or an unavailable reason.
+   */
+  public abstract getSelectedBranchRerunPlan(
+    args: PluginAIInspirationGetWorkflowForShapeArgs,
+  ): PluginApiReturn<PluginAIInspirationRerunPlanResult>
+
+  /**
+   * Rerun the selected workflow branch and supersede the previous branch.
+   *
+   * @param args - Selected shape, optional end frame shape, and run mode.
+   * @returns New canvas outputs in blocking mode or a job ID in job mode.
+   */
+  public abstract rerunSelectedBranch(
+    args: PluginAIInspirationRerunSelectedBranchArgs,
+  ): PluginApiReturn<PluginAIInspirationRunResult>
+
+  /**
+   * Extract a reusable recipe draft from the workflow path ending at a shape.
+   *
+   * @param args - Object containing `shapeId`.
+   * @returns A recipe draft or an unavailable reason.
+   */
+  public abstract extractRecipeFromShape(
+    args: PluginAIInspirationExtractRecipeFromShapeArgs,
+  ): PluginApiReturn<PluginAIInspirationExtractionResult>
+
+  /**
+   * List project-level AI Inspiration recipes stored in Present document metadata.
+   *
+   * @returns Saved project recipes.
+   */
+  public abstract listRecipes(): PluginApiReturn<PluginAIInspirationListRecipesResult>
+
+  /**
+   * Save a project-level AI Inspiration recipe.
+   *
+   * @param args - Recipe draft and desired name.
+   * @returns Saved, duplicate, invalid-name, or failed status.
+   */
+  public abstract saveRecipe(
+    args: PluginAIInspirationSaveRecipeArgs,
+  ): PluginApiReturn<PluginAIInspirationSaveRecipeResult>
+
+  /**
+   * Delete a project-level AI Inspiration recipe.
+   *
+   * @param args - Object containing `recipeId`.
+   * @returns Whether a recipe was deleted.
+   */
+  public abstract deleteRecipe(
+    args: PluginAIInspirationDeleteRecipeArgs,
+  ): PluginApiReturn<PluginAIInspirationDeleteRecipeResult>
+
+  /**
+   * Run a saved or inline recipe against Present canvas slot shapes.
+   *
+   * @param args - Saved `recipeId` or inline `recipe`, slot shape IDs, and run mode.
+   * @returns Canvas outputs in blocking mode or a job ID in job mode.
+   */
+  public abstract runRecipe(
+    args: PluginAIInspirationRunRecipeArgs,
+  ): PluginApiReturn<PluginAIInspirationRunResult>
+}