@openpets/fal 1.0.1

package/README.md

@@ -0,0 +1,73 @@
+# FAL AI Image & Video Generation
+
+FAL AI image and video generation plugin for OpenCode - text-to-image, image-to-image, text-to-video, and image-to-video using Flux, Stable Diffusion, Kling, and more.
+
+## Features
+
+- **Text-to-Image**: Generate images from text descriptions using Flux, Stable Diffusion, and other models
+- **Image-to-Image**: Transform existing images with style transfer, editing, and variations
+- **Text-to-Video**: Create videos from text prompts using Kling, Runway Gen-3, and more
+- **Image-to-Video**: Animate static images with camera movements and effects
+
+## Installation
+
+```bash
+npm install openpets/fal
+```
+
+## Setup
+
+1. Get your FAL AI API key from [https://fal.ai](https://fal.ai)
+2. Create a `.env` file in the plugin directory:
+
+```bash
+FAL_KEY=your-api-key-here
+```
+
+## Usage
+
+### Generate an image
+
+```bash
+opencode run "generate an image of a sunset over the ocean"
+```
+
+### Transform an image
+
+```bash
+opencode run "transform this image into watercolor style"
+```
+
+### Generate a video
+
+```bash
+opencode run "generate a video of clouds drifting across the sky"
+```
+
+### Animate an image
+
+```bash
+opencode run "animate this image with a camera pan"
+```
+
+## Available Tools
+
+- `fal-generate-image`: Generate images using FAL AI text-to-image models
+- `fal-transform-image`: Transform images using FAL AI image-to-image models
+- `fal-generate-video`: Generate videos using FAL AI text-to-video models
+- `fal-animate-image`: Animate static images using FAL AI image-to-video models
+
+## Testing
+
+Run individual test scripts:
+
+```bash
+npm run test:generate-image
+npm run test:transform-image
+npm run test:generate-video
+npm run test:animate-image
+```
+
+## License
+
+MIT

package/client.ts

@@ -0,0 +1,397 @@
+import { fal } from "@fal-ai/client"
+import { BaseAIClient, AIImageResult, AIVideoResult } from "@/core/ai-client-base"
+import { createLogger } from "@/core/logger"
+import * as fs from "fs"
+import * as path from "path"
+
+const logger = createLogger("fal-client")
+
+export interface FalImageGenerationOptions {
+  prompt: string
+  model?: string
+  seed?: number
+  image_size?: "square_hd" | "square" | "portrait_4_3" | "portrait_16_9" | "landscape_4_3" | "landscape_16_9"
+  num_images?: number
+  num_inference_steps?: number
+  guidance_scale?: number
+  negative_prompt?: string
+  enable_safety_checker?: boolean
+  input_image?: string
+}
+
+export interface FalVideoGenerationOptions {
+  prompt: string
+  model?: string
+  seed?: number
+  duration?: number
+  fps?: number
+  aspect_ratio?: "16:9" | "9:16" | "1:1"
+  num_videos?: number
+  input_image?: string
+  enable_safety_checker?: boolean
+}
+
+export class FalClient extends BaseAIClient {
+  private configured: boolean = false
+
+  constructor(apiKey?: string) {
+    super({
+      apiKey: apiKey || process.env.FAL_KEY || "",
+      baseUrl: "https://fal.run",
+      debug: false
+    })
+  }
+
+  get providerName(): string {
+    return "fal"
+  }
+
+  private ensureConfigured() {
+    this.ensureApiKey("FAL_KEY")
+
+    if (!this.configured) {
+      fal.config({
+        credentials: this.apiKey
+      })
+      this.configured = true
+    }
+  }
+
+  private async uploadFileIfNeeded(filePath: string): Promise<string> {
+    if (filePath.startsWith("http://") || filePath.startsWith("https://")) {
+      logger.info("🌐 Using existing URL (no upload needed)", { url: filePath })
+      return filePath
+    }
+
+    if (filePath.startsWith("data:")) {
+      logger.info("📊 Using data URI (no upload needed)")
+      return filePath
+    }
+
+    this.ensureConfigured()
+
+    const resolvedPath = path.resolve(filePath)
+
+    if (!fs.existsSync(resolvedPath)) {
+      logger.error("❌ FILE NOT FOUND", {
+        original_path: filePath,
+        resolved_path: resolvedPath
+      })
+      throw new Error(`File not found: ${resolvedPath}`)
+    }
+
+    const fileStats = fs.statSync(resolvedPath)
+    logger.info("📤 UPLOADING FILE TO FAL STORAGE", {
+      original_path: filePath,
+      resolved_path: resolvedPath,
+      file_size_bytes: fileStats.size,
+      file_size_kb: Math.round(fileStats.size / 1024)
+    })
+
+    const fileBuffer = fs.readFileSync(resolvedPath)
+    const fileName = path.basename(resolvedPath)
+    const mimeType = this.getMimeType(fileName)
+
+    logger.debug("Creating file blob", {
+      fileName,
+      mimeType,
+      buffer_size: fileBuffer.length
+    })
+
+    const blob = new Blob([fileBuffer], {
+      type: mimeType
+    })
+
+    const file = new File([blob], fileName, {
+      type: mimeType
+    })
+
+    const url = await fal.storage.upload(file)
+
+    logger.info("✅ FILE UPLOADED SUCCESSFULLY TO FAL", {
+      uploaded_url: url,
+      url_length: url.length,
+      original_filename: fileName
+    })
+
+    return url
+  }
+
+  private getMimeType(fileName: string): string {
+    const ext = path.extname(fileName).toLowerCase()
+    const mimeTypes: Record<string, string> = {
+      '.jpg': 'image/jpeg',
+      '.jpeg': 'image/jpeg',
+      '.png': 'image/png',
+      '.gif': 'image/gif',
+      '.webp': 'image/webp',
+      '.mp4': 'video/mp4',
+      '.mov': 'video/quicktime',
+      '.avi': 'video/x-msvideo'
+    }
+    return mimeTypes[ext] || 'application/octet-stream'
+  }
+
+  async generateImage(options: FalImageGenerationOptions): Promise<AIImageResult> {
+    try {
+      this.ensureConfigured()
+
+      const model = options.model || "fal-ai/flux/dev"
+
+      const input: any = {
+        prompt: options.prompt,
+      }
+
+      if (options.seed !== undefined) input.seed = options.seed
+      if (options.image_size) input.image_size = options.image_size
+      if (options.num_images) input.num_images = options.num_images
+      if (options.num_inference_steps) input.num_inference_steps = options.num_inference_steps
+      if (options.guidance_scale) input.guidance_scale = options.guidance_scale
+      if (options.negative_prompt) input.negative_prompt = options.negative_prompt
+      if (options.enable_safety_checker !== undefined) input.enable_safety_checker = options.enable_safety_checker
+
+      if (options.input_image) {
+        logger.info("🖼️  PROCESSING INPUT IMAGE", {
+          input_image_path: options.input_image,
+          model: model
+        })
+        const imageUrl = await this.uploadFileIfNeeded(options.input_image)
+
+        if (model.includes('nano-banana')) {
+          input.image_urls = [imageUrl]
+          logger.info("✅ INPUT IMAGE READY (nano-banana mode)", {
+            image_urls: [imageUrl],
+            total_images: 1
+          })
+        } else {
+          input.image_url = imageUrl
+          logger.info("✅ INPUT IMAGE READY (standard mode)", {
+            image_url: imageUrl,
+            url_length: imageUrl.length
+          })
+        }
+      } else {
+        logger.warn("⚠️  NO INPUT IMAGE PROVIDED - generating from text only")
+      }
+
+      logger.info("📤 SENDING REQUEST TO FAL API", {
+        model,
+        has_input_image: !!(input.image_url || input.image_urls),
+        input_params: {
+          has_prompt: !!input.prompt,
+          image_size: input.image_size,
+          num_images: input.num_images,
+          has_image_url: !!input.image_url,
+          has_image_urls: !!input.image_urls,
+          seed: input.seed
+        },
+        full_input: JSON.stringify(input, null, 2)
+      })
+
+      const result: any = await fal.subscribe(model, {
+        input,
+        logs: false,
+      })
+
+      logger.info("📥 RAW FAL RESPONSE", {
+        has_data: !!result.data,
+        data_keys: result.data ? Object.keys(result.data) : [],
+        has_images: result.data?.images ? true : false,
+        images_count: result.data?.images?.length || 0,
+        requestId: result.requestId,
+        full_response: JSON.stringify(result, null, 2).substring(0, 1000)
+      })
+
+      const credits = this.extractCreditsFromResponse(result)
+
+      if (result.data && result.data.images) {
+        const generatedImages = result.data.images.map((img: any) => ({
+          url: img.url,
+          width: img.width,
+          height: img.height,
+          contentType: img.content_type
+        }))
+
+        logger.info("✅ FAL API RESPONSE RECEIVED", {
+          num_images_generated: generatedImages.length,
+          dimensions: generatedImages.map(img => `${img.width}x${img.height}`),
+          request_id: result.requestId,
+          inference_time: result.data.timings?.inference || 0,
+          seed_used: result.data.seed
+        })
+
+        if (options.input_image) {
+          logger.info("📊 IMAGE-TO-IMAGE TRANSFORMATION COMPLETE", {
+            original_image: options.input_image,
+            requested_size: options.image_size,
+            output_dimensions: generatedImages.map(img => `${img.width}x${img.height}`).join(", ")
+          })
+        }
+
+        return {
+          success: true,
+          images: generatedImages,
+          requestId: result.requestId,
+          metadata: {
+            model,
+            provider: this.providerName,
+            prompt: options.prompt,
+            seed: result.data.seed || options.seed || 0,
+            inferenceTime: result.data.timings?.inference || 0
+          },
+          credits
+        }
+      } else {
+        logger.warn("⚠️ NO IMAGES IN FAL RESPONSE", {
+          has_data: !!result.data,
+          data_keys: result.data ? Object.keys(result.data) : [],
+          has_images_field: 'images' in (result.data || {}),
+          result_keys: Object.keys(result || {}),
+          full_response: JSON.stringify(result, null, 2).substring(0, 2000)
+        })
+        return {
+          success: false,
+          error: "No images returned from FAL API",
+          requestId: result.requestId
+        }
+      }
+    } catch (error: any) {
+      const errorDetails = {
+        message: error.message || "Unknown error occurred",
+        name: error.name,
+        statusCode: error.status || error.statusCode,
+        body: error.body,
+        requestId: error.request_id,
+        model: options.model || "fal-ai/flux/dev",
+        promptLength: options.prompt?.length || 0,
+        stack: error.stack
+      }
+
+      const verboseError = `FAL API Error: ${errorDetails.message}\n` +
+        `  Model: ${errorDetails.model}\n` +
+        `  Prompt Length: ${errorDetails.promptLength} characters\n` +
+        (errorDetails.statusCode ? `  Status Code: ${errorDetails.statusCode}\n` : '') +
+        (errorDetails.requestId ? `  Request ID: ${errorDetails.requestId}\n` : '') +
+        (errorDetails.body ? `  Response Body: ${JSON.stringify(errorDetails.body)}\n` : '') +
+        (errorDetails.stack ? `  Stack: ${errorDetails.stack.split('\n').slice(0, 3).join('\n')}` : '')
+
+      this.log(verboseError, "error")
+
+      return {
+        success: false,
+        error: verboseError
+      }
+    }
+  }
+
+  async generateAndOpenImage(options: FalImageGenerationOptions, openInViewer: boolean = true): Promise<AIImageResult & { localPath?: string }> {
+    const result = await this.generateImage(options)
+    return this.downloadAndOpen(result, "image", "png", openInViewer)
+  }
+
+  async generateVideo(options: FalVideoGenerationOptions): Promise<AIVideoResult> {
+    try {
+      this.ensureConfigured()
+
+      const model = options.model || "fal-ai/veo3.1/image-to-video"
+
+      const input: any = {
+        prompt: options.prompt,
+      }
+
+      if (options.seed !== undefined) input.seed = options.seed
+      if (options.duration) input.duration = options.duration
+      if (options.fps) input.fps = options.fps
+      if (options.aspect_ratio) input.aspect_ratio = options.aspect_ratio
+      if (options.num_videos) input.num_videos = options.num_videos
+      if (options.enable_safety_checker !== undefined) input.enable_safety_checker = options.enable_safety_checker
+
+      if (options.input_image) {
+        const imageUrl = await this.uploadFileIfNeeded(options.input_image)
+        input.image_url = imageUrl
+        this.log(`Using input image for video: ${imageUrl}`, "debug")
+      }
+
+      this.log(`Generating video with model: ${model}`, "debug")
+
+      const result: any = await fal.subscribe(model, {
+        input,
+        logs: false,
+      })
+
+      const credits = this.extractCreditsFromResponse(result)
+
+      if (result.data && result.data.video) {
+        return {
+          success: true,
+          videos: [{
+            url: result.data.video.url,
+            width: result.data.video.width || 720,
+            height: result.data.video.height || 1280,
+            duration: result.data.video.duration || options.duration || 5,
+            contentType: result.data.video.content_type || "video/mp4"
+          }],
+          requestId: result.requestId,
+          metadata: {
+            model,
+            provider: this.providerName,
+            prompt: options.prompt,
+            seed: result.data.seed || options.seed || 0,
+            inferenceTime: result.data.timings?.inference || 0
+          },
+          credits
+        }
+      } else {
+        return {
+          success: false,
+          error: "No video returned from FAL API",
+          requestId: result.requestId
+        }
+      }
+    } catch (error: any) {
+      const errorDetails = {
+        message: error.message || "Unknown error occurred",
+        name: error.name,
+        statusCode: error.status || error.statusCode,
+        body: error.body,
+        requestId: error.request_id,
+        model: options.model || "fal-ai/kling-video-v1",
+        promptLength: options.prompt?.length || 0,
+        duration: options.duration,
+        fps: options.fps,
+        aspectRatio: options.aspect_ratio,
+        hasInputImage: !!options.input_image,
+        inputImageUrl: options.input_image ? options.input_image.substring(0, 50) + '...' : undefined,
+        stack: error.stack
+      }
+
+      const verboseError = `FAL Video API Error: ${errorDetails.message}\n` +
+        `  Model: ${errorDetails.model}\n` +
+        `  Prompt Length: ${errorDetails.promptLength} characters\n` +
+        `  Duration: ${errorDetails.duration || 'default'}s\n` +
+        `  FPS: ${errorDetails.fps || 'default'}\n` +
+        `  Aspect Ratio: ${errorDetails.aspectRatio || 'default'}\n` +
+        (errorDetails.hasInputImage ? `  Input Image: ${errorDetails.inputImageUrl}\n` : '') +
+        (errorDetails.statusCode ? `  Status Code: ${errorDetails.statusCode}\n` : '') +
+        (errorDetails.requestId ? `  Request ID: ${errorDetails.requestId}\n` : '') +
+        (errorDetails.body ? `  Response Body: ${JSON.stringify(errorDetails.body)}\n` : '') +
+        (errorDetails.stack ? `  Stack: ${errorDetails.stack.split('\n').slice(0, 3).join('\n')}` : '')
+
+      this.log(verboseError, "error")
+
+      return {
+        success: false,
+        error: verboseError
+      }
+    }
+  }
+
+  async generateAndOpenVideo(options: FalVideoGenerationOptions, openInViewer: boolean = true): Promise<AIVideoResult & { localPath?: string }> {
+    const result = await this.generateVideo(options)
+    return this.downloadAndOpen(result, "video", "mp4", openInViewer)
+  }
+}
+
+export function createFalClient(apiKey?: string): FalClient {
+  return new FalClient(apiKey)
+}

package/commands.json

@@ -0,0 +1,219 @@
+{
+  "name": "@openpets/fal",
+  "version": "1.0.1",
+  "description": "FAL AI image and video generation plugin for OpenCode - text-to-image, image-to-image, text-to-video, and image-to-video using Flux, Stable Diffusion, Kling, and more",
+  "tools": [
+    {
+      "name": "fal-generate-image",
+      "description": "Generate an image using FAL AI text-to-image models (Flux, Stable Diffusion, etc.)",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "prompt": {
+            "type": "string",
+            "description": "Text description of the image to generate"
+          },
+          "model": {
+            "type": "string",
+            "optional": true,
+            "description": "Model to use (default: fal-ai/flux/dev). Options: fal-ai/flux/dev, fal-ai/flux/schnell, fal-ai/stable-diffusion-v3"
+          },
+          "image_size": {
+            "type": "string",
+            "enum": [
+              "square_hd",
+              "square",
+              "portrait_4_3",
+              "portrait_16_9",
+              "landscape_4_3",
+              "landscape_16_9"
+            ],
+            "optional": true,
+            "description": "Image aspect ratio (default: square)"
+          },
+          "num_images": {
+            "type": "number",
+            "optional": true,
+            "description": "Number of images to generate (default: 1)"
+          },
+          "seed": {
+            "type": "number",
+            "optional": true,
+            "description": "Random seed for reproducibility"
+          },
+          "num_inference_steps": {
+            "type": "number",
+            "optional": true,
+            "description": "Number of inference steps (more = higher quality, slower)"
+          },
+          "guidance_scale": {
+            "type": "number",
+            "optional": true,
+            "description": "How closely to follow the prompt (7.5 is typical)"
+          },
+          "negative_prompt": {
+            "type": "string",
+            "optional": true,
+            "description": "What to avoid in the image"
+          },
+          "enable_safety_checker": {
+            "type": "boolean",
+            "optional": true,
+            "description": "Enable content safety checker (default: true)"
+          }
+        }
+      }
+    },
+    {
+      "name": "fal-transform-image",
+      "description": "Transform an existing image using FAL AI image-to-image models (style transfer, editing, variations)",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "input_image": {
+            "type": "string",
+            "description": "Path or URL to input image to transform"
+          },
+          "prompt": {
+            "type": "string",
+            "description": "Description of how to transform the image"
+          },
+          "model": {
+            "type": "string",
+            "optional": true,
+            "description": "Model to use (default: fal-ai/flux/dev)"
+          },
+          "image_size": {
+            "type": "string",
+            "enum": [
+              "square_hd",
+              "square",
+              "portrait_4_3",
+              "portrait_16_9",
+              "landscape_4_3",
+              "landscape_16_9"
+            ],
+            "optional": true,
+            "description": "Output image aspect ratio"
+          },
+          "num_images": {
+            "type": "number",
+            "optional": true,
+            "description": "Number of variations to generate (default: 1)"
+          },
+          "seed": {
+            "type": "number",
+            "optional": true,
+            "description": "Random seed for reproducibility"
+          },
+          "guidance_scale": {
+            "type": "number",
+            "optional": true,
+            "description": "How closely to follow the prompt"
+          },
+          "negative_prompt": {
+            "type": "string",
+            "optional": true,
+            "description": "What to avoid in the transformation"
+          }
+        }
+      }
+    },
+    {
+      "name": "fal-generate-video",
+      "description": "Generate a video using FAL AI text-to-video models (Kling, Runway Gen-3, etc.)",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "prompt": {
+            "type": "string",
+            "description": "Text description of the video to generate"
+          },
+          "model": {
+            "type": "string",
+            "optional": true,
+            "description": "Model to use (default: fal-ai/kling-video-v1). Options: fal-ai/kling-video-v1, fal-ai/runway-gen3"
+          },
+          "duration": {
+            "type": "number",
+            "optional": true,
+            "description": "Video duration in seconds (default: 5)"
+          },
+          "fps": {
+            "type": "number",
+            "optional": true,
+            "description": "Frames per second (default: 24)"
+          },
+          "aspect_ratio": {
+            "type": "string",
+            "enum": [
+              "16:9",
+              "9:16",
+              "1:1"
+            ],
+            "optional": true,
+            "description": "Video aspect ratio (default: 16:9)"
+          },
+          "num_videos": {
+            "type": "number",
+            "optional": true,
+            "description": "Number of videos to generate (default: 1)"
+          },
+          "seed": {
+            "type": "number",
+            "optional": true,
+            "description": "Random seed for reproducibility"
+          }
+        }
+      }
+    },
+    {
+      "name": "fal-animate-image",
+      "description": "Animate a static image using FAL AI image-to-video models",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "input_image": {
+            "type": "string",
+            "description": "Path or URL to input image to animate"
+          },
+          "prompt": {
+            "type": "string",
+            "description": "Description of how the image should move/animate"
+          },
+          "model": {
+            "type": "string",
+            "optional": true,
+            "description": "Model to use (default: fal-ai/veo3.1/image-to-video)"
+          },
+          "duration": {
+            "type": "number",
+            "optional": true,
+            "description": "Video duration in seconds (default: 5)"
+          },
+          "fps": {
+            "type": "number",
+            "optional": true,
+            "description": "Frames per second (default: 24)"
+          },
+          "aspect_ratio": {
+            "type": "string",
+            "enum": [
+              "16:9",
+              "9:16",
+              "1:1"
+            ],
+            "optional": true,
+            "description": "Video aspect ratio"
+          },
+          "seed": {
+            "type": "number",
+            "optional": true,
+            "description": "Random seed for reproducibility"
+          }
+        }
+      }
+    }
+  ],
+  "generatedAt": "2026-02-03T18:38:06.215Z"
+}

package/index.ts

@@ -0,0 +1,177 @@
+import { z, createPlugin, type ToolDefinition, loadEnv, createLogger } from "openpets-sdk"
+import { createFalClient, type FalImageGenerationOptions, type FalVideoGenerationOptions } from "./client"
+
+export const FalPlugin = async () => {
+  const logger = createLogger("fal-plugin")
+
+  const env = loadEnv('fal')
+  const FAL_KEY = env.FAL_KEY
+
+  if (!FAL_KEY) {
+    logger.error("Missing required FAL environment variable")
+    throw new Error("FAL_KEY environment variable is required. Set it in .env file or pet configuration.")
+  }
+
+  logger.info("Initializing FAL plugin", { hasApiKey: !!FAL_KEY })
+
+  const falClient = createFalClient(FAL_KEY)
+
+  const tools: ToolDefinition[] = [
+    {
+      name: "fal-generate-image",
+      description: "Generate an image using FAL AI text-to-image models (Flux, Stable Diffusion, etc.)",
+      schema: z.object({
+        prompt: z.string().describe("Text description of the image to generate"),
+        model: z.string().optional().describe("Model to use (default: fal-ai/flux/dev). Options: fal-ai/flux/dev, fal-ai/flux/schnell, fal-ai/stable-diffusion-v3"),
+        image_size: z.enum(["square_hd", "square", "portrait_4_3", "portrait_16_9", "landscape_4_3", "landscape_16_9"]).optional().describe("Image aspect ratio (default: square)"),
+        num_images: z.number().optional().describe("Number of images to generate (default: 1)"),
+        seed: z.number().optional().describe("Random seed for reproducibility"),
+        num_inference_steps: z.number().optional().describe("Number of inference steps (more = higher quality, slower)"),
+        guidance_scale: z.number().optional().describe("How closely to follow the prompt (7.5 is typical)"),
+        negative_prompt: z.string().optional().describe("What to avoid in the image"),
+        enable_safety_checker: z.boolean().optional().describe("Enable content safety checker (default: true)")
+      }),
+      async execute(args) {
+        logger.info("Generating image", { prompt: args.prompt.substring(0, 50), model: args.model })
+
+        const result = await falClient.generateAndOpenImage({
+          prompt: args.prompt,
+          model: args.model,
+          image_size: args.image_size,
+          num_images: args.num_images,
+          seed: args.seed,
+          num_inference_steps: args.num_inference_steps,
+          guidance_scale: args.guidance_scale,
+          negative_prompt: args.negative_prompt,
+          enable_safety_checker: args.enable_safety_checker
+        })
+
+        return JSON.stringify({
+          success: result.success,
+          message: result.success ? "Image generated successfully" : "Image generation failed",
+          images: result.images?.map(img => img.url) || [],
+          localPath: result.localPath,
+          metadata: result.metadata,
+          requestId: result.requestId,
+          credits: result.credits,
+          error: result.error
+        }, null, 2)
+      }
+    },
+    {
+      name: "fal-transform-image",
+      description: "Transform an existing image using FAL AI image-to-image models (style transfer, editing, variations)",
+      schema: z.object({
+        input_image: z.string().describe("Path or URL to input image to transform"),
+        prompt: z.string().describe("Description of how to transform the image"),
+        model: z.string().optional().describe("Model to use (default: fal-ai/flux/dev)"),
+        image_size: z.enum(["square_hd", "square", "portrait_4_3", "portrait_16_9", "landscape_4_3", "landscape_16_9"]).optional().describe("Output image aspect ratio"),
+        num_images: z.number().optional().describe("Number of variations to generate (default: 1)"),
+        seed: z.number().optional().describe("Random seed for reproducibility"),
+        guidance_scale: z.number().optional().describe("How closely to follow the prompt"),
+        negative_prompt: z.string().optional().describe("What to avoid in the transformation")
+      }),
+      async execute(args) {
+        logger.info("Transforming image", { inputImage: args.input_image, prompt: args.prompt.substring(0, 50) })
+
+        const result = await falClient.generateAndOpenImage({
+          input_image: args.input_image,
+          prompt: args.prompt,
+          model: args.model,
+          image_size: args.image_size,
+          num_images: args.num_images,
+          seed: args.seed,
+          guidance_scale: args.guidance_scale,
+          negative_prompt: args.negative_prompt
+        })
+
+        return JSON.stringify({
+          success: result.success,
+          message: result.success ? "Image transformed successfully" : "Image transformation failed",
+          images: result.images?.map(img => img.url) || [],
+          localPath: result.localPath,
+          metadata: result.metadata,
+          requestId: result.requestId,
+          credits: result.credits,
+          error: result.error
+        }, null, 2)
+      }
+    },
+    {
+      name: "fal-generate-video",
+      description: "Generate a video using FAL AI text-to-video models (Kling, Runway Gen-3, etc.)",
+      schema: z.object({
+        prompt: z.string().describe("Text description of the video to generate"),
+        model: z.string().optional().describe("Model to use (default: fal-ai/kling-video-v1). Options: fal-ai/kling-video-v1, fal-ai/runway-gen3"),
+        duration: z.number().optional().describe("Video duration in seconds (default: 5)"),
+        fps: z.number().optional().describe("Frames per second (default: 24)"),
+        aspect_ratio: z.enum(["16:9", "9:16", "1:1"]).optional().describe("Video aspect ratio (default: 16:9)"),
+        num_videos: z.number().optional().describe("Number of videos to generate (default: 1)"),
+        seed: z.number().optional().describe("Random seed for reproducibility")
+      }),
+      async execute(args) {
+        logger.info("Generating video", { prompt: args.prompt.substring(0, 50), duration: args.duration })
+
+        const result = await falClient.generateAndOpenVideo({
+          prompt: args.prompt,
+          model: args.model,
+          duration: args.duration,
+          fps: args.fps,
+          aspect_ratio: args.aspect_ratio,
+          num_videos: args.num_videos,
+          seed: args.seed
+        })
+
+        return JSON.stringify({
+          success: result.success,
+          message: result.success ? "Video generated successfully" : "Video generation failed",
+          videos: result.videos?.map(vid => vid.url) || [],
+          localPath: result.localPath,
+          metadata: result.metadata,
+          requestId: result.requestId,
+          credits: result.credits,
+          error: result.error
+        }, null, 2)
+      }
+    },
+    {
+      name: "fal-animate-image",
+      description: "Animate a static image using FAL AI image-to-video models",
+      schema: z.object({
+        input_image: z.string().describe("Path or URL to input image to animate"),
+        prompt: z.string().describe("Description of how the image should move/animate"),
+        model: z.string().optional().describe("Model to use (default: fal-ai/veo3.1/image-to-video)"),
+        duration: z.number().optional().describe("Video duration in seconds (default: 5)"),
+        fps: z.number().optional().describe("Frames per second (default: 24)"),
+        aspect_ratio: z.enum(["16:9", "9:16", "1:1"]).optional().describe("Video aspect ratio"),
+        seed: z.number().optional().describe("Random seed for reproducibility")
+      }),
+      async execute(args) {
+        logger.info("Animating image", { inputImage: args.input_image, prompt: args.prompt.substring(0, 50) })
+
+        const result = await falClient.generateAndOpenVideo({
+          input_image: args.input_image,
+          prompt: args.prompt,
+          model: args.model,
+          duration: args.duration,
+          fps: args.fps,
+          aspect_ratio: args.aspect_ratio,
+          seed: args.seed
+        })
+
+        return JSON.stringify({
+          success: result.success,
+          message: result.success ? "Image animated successfully" : "Image animation failed",
+          videos: result.videos?.map(vid => vid.url) || [],
+          localPath: result.localPath,
+          metadata: result.metadata,
+          requestId: result.requestId,
+          credits: result.credits,
+          error: result.error
+        }, null, 2)
+      }
+    }
+  ]
+
+  return createPlugin(tools)
+}

package/package.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://pets.studio/config.json",
+  "name": "@openpets/fal",
+  "version": "1.0.1",
+  "title": "FAL",
+  "subtitle": "Flux, Stable Diffusion, Kling Video & More",
+  "description": "FAL AI image and video generation plugin for OpenCode - text-to-image, image-to-image, text-to-video, and image-to-video using Flux, Stable Diffusion, Kling, and more",
+  "categories": [
+    "ai",
+    "image-generation",
+    "video-generation",
+    "creative"
+  ],
+  "homepage": "https://fal.ai",
+  "faq": [
+    {
+      "question": "How do I get a FAL AI API key?",
+      "answer": "Visit https://fal.ai, create an account, and generate an API key from your dashboard."
+    },
+    {
+      "question": "What image models are supported?",
+      "answer": "The plugin supports Flux, Stable Diffusion, and other popular text-to-image and image-to-image models available on FAL AI."
+    },
+    {
+      "question": "What video models are supported?",
+      "answer": "The plugin supports Kling, Runway Gen-3, and other text-to-video and image-to-video models available on FAL AI."
+    },
+    {
+      "question": "How much does it cost to generate images and videos?",
+      "answer": "Pricing varies by model. Check https://fal.ai/pricing for current rates. You'll need credits in your FAL AI account."
+    }
+  ],
+  "main": "index.ts",
+  "types": "index.ts",
+  "keywords": [
+    "opencode",
+    "plugin",
+    "fal",
+    "ai",
+    "image-generation",
+    "video-generation",
+    "flux",
+    "stable-diffusion",
+    "kling-video",
+    "text-to-image",
+    "image-to-image",
+    "text-to-video",
+    "image-to-video"
+  ],
+  "envVariables": {
+    "required": [
+      {
+        "name": "FAL_KEY",
+        "description": "FAL AI API key for image and video generation",
+        "provider": "FAL AI",
+        "priority": 1,
+        "example": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    ]
+  },
+  "queries": [
+    "generate an image of a sunset over the ocean",
+    "transform this image into watercolor style",
+    "generate a video of clouds drifting across the sky",
+    "animate this image with a camera pan"
+  ],
+  "scenarios": {
+    "text-to-image-basic": [
+      "use fal-generate-image to create a cat sitting on a windowsill",
+      "use fal-generate-image with square_hd size for a landscape with mountains",
+      "use fal-generate-image to make a portrait of a robot"
+    ],
+    "image-transformation": [
+      "use fal-transform-image to convert photo to watercolor style",
+      "use fal-transform-image to add cyberpunk effects to image",
+      "use fal-transform-image to change day photo to night"
+    ],
+    "video-generation": [
+      "use fal-generate-video to create ocean waves crashing on beach",
+      "use fal-generate-video with 16:9 aspect for rotating product",
+      "use fal-generate-video at 30 fps for smooth fireworks animation"
+    ],
+    "image-animation": [
+      "use fal-animate-image to add camera pan to landscape photo",
+      "use fal-animate-image with zoom motion for city skyline",
+      "use fal-animate-image to create parallax effect in forest scene"
+    ]
+  },
+  "scripts": {
+    "build": "pets build",
+    "build:tsc": "tsc",
+    "quickstart": "opencode run \"list available fal commands\"",
+    "test:generate-image": "opencode run \"Generate an image using FAL AI text-to-image models (Flux, Stable Diffusion, etc.)\"",
+    "test:transform-image": "opencode run \"Transform an existing image using FAL AI image-to-image models (style transfer, editing, variations)\"",
+    "test:generate-video": "opencode run \"Generate a video using FAL AI text-to-video models (Kling, Runway Gen-3, etc.)\"",
+    "test:animate-image": "opencode run \"Animate a static image using FAL AI image-to-video models\"",
+    "test:all": "echo \"Run individual test scripts to test specific tools\""
+  },
+  "type": "module",
+  "dependencies": {
+    "openpets-sdk": "^1.0.0",
+    "@fal-ai/client": "^1.7.2",
+    "dotenv": "^16.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.ts",
+    "index.js",
+    "client.ts",
+    "client.js",
+    "*.d.ts",
+    "lib/**/*",
+    "src/**/*",
+    "commands.json",
+    "public/**/*",
+    "README.md",
+    "prompts/**/*"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/raggle-ai/pets/pets/fal"
+  }
+}

package/src/custom.ts

@@ -0,0 +1,162 @@
+
+// const falClient = createFalClient(FAL_KEY)
+
+// // Define write operation patterns for read-only mode filtering
+// const WRITE_PATTERNS = ['generate', 'transform', 'animate']
+
+// const apiTools: ToolDefinition[] = [
+//   {
+//     name: "fal-generate-image",
+//     description: "Generate an image using FAL AI text-to-image models (Flux, Stable Diffusion, etc.)",
+//     schema: z.object({
+//       prompt: z.string().describe("Text description of the image to generate"),
+//       model: z.string().optional().describe("Model to use (default: fal-ai/flux/dev). Options: fal-ai/flux/dev, fal-ai/flux/schnell, fal-ai/stable-diffusion-v3"),
+//       image_size: z.enum(["square_hd", "square", "portrait_4_3", "portrait_16_9", "landscape_4_3", "landscape_16_9"]).optional().describe("Image aspect ratio (default: square)"),
+//       num_images: z.number().optional().describe("Number of images to generate (default: 1)"),
+//       seed: z.number().optional().describe("Random seed for reproducibility"),
+//       num_inference_steps: z.number().optional().describe("Number of inference steps (more = higher quality, slower)"),
+//       guidance_scale: z.number().optional().describe("How closely to follow the prompt (7.5 is typical)"),
+//       negative_prompt: z.string().optional().describe("What to avoid in the image"),
+//       enable_safety_checker: z.boolean().optional().describe("Enable content safety checker (default: true)")
+//     }),
+//     async execute(args) {
+//       logger.info("Generating image", { prompt: args.prompt.substring(0, 50), model: args.model })
+
+//       const result = await falClient.generateAndOpenImage({
+//         prompt: args.prompt,
+//         model: args.model,
+//         image_size: args.image_size,
+//         num_images: args.num_images,
+//         seed: args.seed,
+//         num_inference_steps: args.num_inference_steps,
+//         guidance_scale: args.guidance_scale,
+//         negative_prompt: args.negative_prompt,
+//         enable_safety_checker: args.enable_safety_checker
+//       })
+
+//       return JSON.stringify({
+//         success: result.success,
+//         message: result.success ? "Image generated successfully" : "Image generation failed",
+//         images: result.images?.map(img => img.url) || [],
+//         localPath: result.localPath,
+//         metadata: result.metadata,
+//         requestId: result.requestId,
+//         credits: result.credits,
+//         error: result.error
+//       }, null, 2)
+//     }
+//   },
+//   {
+//     name: "fal-transform-image",
+//     description: "Transform an existing image using FAL AI image-to-image models (style transfer, editing, variations)",
+//     schema: z.object({
+//       input_image: z.string().describe("Path or URL to input image to transform"),
+//       prompt: z.string().describe("Description of how to transform the image"),
+//       model: z.string().optional().describe("Model to use (default: fal-ai/flux/dev)"),
+//       image_size: z.enum(["square_hd", "square", "portrait_4_3", "portrait_16_9", "landscape_4_3", "landscape_16_9"]).optional().describe("Output image aspect ratio"),
+//       num_images: z.number().optional().describe("Number of variations to generate (default: 1)"),
+//       seed: z.number().optional().describe("Random seed for reproducibility"),
+//       guidance_scale: z.number().optional().describe("How closely to follow the prompt"),
+//       negative_prompt: z.string().optional().describe("What to avoid in the transformation")
+//     }),
+//     async execute(args) {
+//       logger.info("Transforming image", { inputImage: args.input_image, prompt: args.prompt.substring(0, 50) })
+
+//       const result = await falClient.generateAndOpenImage({
+//         input_image: args.input_image,
+//         prompt: args.prompt,
+//         model: args.model,
+//         image_size: args.image_size,
+//         num_images: args.num_images,
+//         seed: args.seed,
+//         guidance_scale: args.guidance_scale,
+//         negative_prompt: args.negative_prompt
+//       })
+
+//       return JSON.stringify({
+//         success: result.success,
+//         message: result.success ? "Image transformed successfully" : "Image transformation failed",
+//         images: result.images?.map(img => img.url) || [],
+//         localPath: result.localPath,
+//         metadata: result.metadata,
+//         requestId: result.requestId,
+//         credits: result.credits,
+//         error: result.error
+//       }, null, 2)
+//     }
+//   },
+//   {
+//     name: "fal-generate-video",
+//     description: "Generate a video using FAL AI text-to-video models (Kling, Runway Gen-3, etc.)",
+//     schema: z.object({
+//       prompt: z.string().describe("Text description of the video to generate"),
+//       model: z.string().optional().describe("Model to use (default: fal-ai/kling-video-v1). Options: fal-ai/kling-video-v1, fal-ai/runway-gen3"),
+//       duration: z.number().optional().describe("Video duration in seconds (default: 5)"),
+//       fps: z.number().optional().describe("Frames per second (default: 24)"),
+//       aspect_ratio: z.enum(["16:9", "9:16", "1:1"]).optional().describe("Video aspect ratio (default: 16:9)"),
+//       num_videos: z.number().optional().describe("Number of videos to generate (default: 1)"),
+//       seed: z.number().optional().describe("Random seed for reproducibility")
+//     }),
+//     async execute(args) {
+//       logger.info("Generating video", { prompt: args.prompt.substring(0, 50), duration: args.duration })
+
+//       const result = await falClient.generateAndOpenVideo({
+//         prompt: args.prompt,
+//         model: args.model,
+//         duration: args.duration,
+//         fps: args.fps,
+//         aspect_ratio: args.aspect_ratio,
+//         num_videos: args.num_videos,
+//         seed: args.seed
+//       })
+
+//       return JSON.stringify({
+//         success: result.success,
+//         message: result.success ? "Video generated successfully" : "Video generation failed",
+//         videos: result.videos?.map(vid => vid.url) || [],
+//         localPath: result.localPath,
+//         metadata: result.metadata,
+//         requestId: result.requestId,
+//         credits: result.credits,
+//         error: result.error
+//       }, null, 2)
+//     }
+//   },
+//   {
+//     name: "fal-animate-image",
+//     description: "Animate a static image using FAL AI image-to-video models",
+//     schema: z.object({
+//       input_image: z.string().describe("Path or URL to input image to animate"),
+//       prompt: z.string().describe("Description of how the image should move/animate"),
+//       model: z.string().optional().describe("Model to use (default: fal-ai/veo3.1/image-to-video)"),
+//       duration: z.number().optional().describe("Video duration in seconds (default: 5)"),
+//       fps: z.number().optional().describe("Frames per second (default: 24)"),
+//       aspect_ratio: z.enum(["16:9", "9:16", "1:1"]).optional().describe("Video aspect ratio"),
+//       seed: z.number().optional().describe("Random seed for reproducibility")
+//     }),
+//     async execute(args) {
+//       logger.info("Animating image", { inputImage: args.input_image, prompt: args.prompt.substring(0, 50) })
+
+//       const result = await falClient.generateAndOpenVideo({
+//         input_image: args.input_image,
+//         prompt: args.prompt,
+//         model: args.model,
+//         duration: args.duration,
+//         fps: args.fps,
+//         aspect_ratio: args.aspect_ratio,
+//         seed: args.seed
+//       })
+
+//       return JSON.stringify({
+//         success: result.success,
+//         message: result.success ? "Image animated successfully" : "Image animation failed",
+//         videos: result.videos?.map(vid => vid.url) || [],
+//         localPath: result.localPath,
+//         metadata: result.metadata,
+//         requestId: result.requestId,
+//         credits: result.credits,
+//         error: result.error
+//       }, null, 2)
+//     }
+//   }
+// ]