@framers/agentos 0.1.113 → 0.1.114

package/dist/core/images/imageToBuffer.js

@@ -0,0 +1,95 @@
+/**
+ * @file imageToBuffer.ts
+ * Shared utility for normalising heterogeneous image inputs into a `Buffer`.
+ *
+ * Image editing, upscaling, and variation APIs accept images in multiple
+ * formats (base64 data URLs, raw base64 strings, `Buffer` instances, local
+ * file paths, and remote HTTP/HTTPS URLs).  This helper unifies them into
+ * a single `Buffer` so that downstream provider code never has to worry
+ * about the input shape.
+ */
+import * as fs from 'node:fs/promises';
+/**
+ * Converts an image input from any of the supported formats into a `Buffer`.
+ *
+ * Supported input formats:
+ * - **`Buffer`** — returned as-is.
+ * - **Base64 data URL** — e.g. `data:image/png;base64,iVBOR...`.  The base64
+ *   payload is extracted and decoded.
+ * - **Raw base64 string** — a string that does not look like a URL or file
+ *   path is assumed to be raw base64 data.
+ * - **`file://` URL** — resolved to a local filesystem path and read.
+ * - **HTTP/HTTPS URL** — fetched via `globalThis.fetch` and buffered.
+ * - **Local file path** — any other string is treated as an absolute or
+ *   relative filesystem path and read with `fs.readFile`.
+ *
+ * @param input - The image in any supported format.
+ * @returns A `Buffer` containing the raw image bytes.
+ *
+ * @throws {TypeError} When `input` is neither a string nor a Buffer.
+ * @throws {Error} When a remote URL fetch fails or the file cannot be read.
+ *
+ * @example
+ * ```ts
+ * const buf1 = await imageToBuffer('data:image/png;base64,iVBOR...');
+ * const buf2 = await imageToBuffer(fs.readFileSync('photo.png'));
+ * const buf3 = await imageToBuffer('https://example.com/photo.png');
+ * const buf4 = await imageToBuffer('/absolute/path/to/image.jpg');
+ * ```
+ */
+export async function imageToBuffer(input) {
+    // Already a Buffer — nothing to do.
+    if (Buffer.isBuffer(input)) {
+        return input;
+    }
+    if (typeof input !== 'string') {
+        throw new TypeError('imageToBuffer: expected a string (base64, URL, or file path) or Buffer.');
+    }
+    const trimmed = input.trim();
+    // Base64 data URL (e.g. "data:image/png;base64,iVBOR...")
+    if (trimmed.startsWith('data:')) {
+        const commaIdx = trimmed.indexOf(',');
+        if (commaIdx === -1) {
+            throw new Error('imageToBuffer: malformed data URL — missing comma separator.');
+        }
+        // Everything after the comma is the base64 payload.
+        return Buffer.from(trimmed.slice(commaIdx + 1), 'base64');
+    }
+    // file:// URL — convert to local path and read.
+    if (trimmed.startsWith('file://')) {
+        const filePath = new URL(trimmed).pathname;
+        return fs.readFile(filePath);
+    }
+    // Remote HTTP(S) URL — fetch and buffer.
+    if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) {
+        const response = await globalThis.fetch(trimmed);
+        if (!response.ok) {
+            throw new Error(`imageToBuffer: failed to fetch image from ${trimmed} (${response.status} ${response.statusText}).`);
+        }
+        return Buffer.from(await response.arrayBuffer());
+    }
+    // Heuristic: if the string contains path separators or a file extension,
+    // treat it as a filesystem path.  Otherwise assume raw base64.
+    const looksLikePath = trimmed.includes('/') || trimmed.includes('\\') || /\.\w{2,5}$/.test(trimmed);
+    if (looksLikePath) {
+        return fs.readFile(trimmed);
+    }
+    // Fallback: raw base64 string (no data URL prefix).
+    return Buffer.from(trimmed, 'base64');
+}
+/**
+ * Converts a Node.js `Buffer` into a DOM-compatible `BlobPart`.
+ *
+ * Recent TypeScript DOM typings require `BlobPart` byte views to be backed by a
+ * concrete `ArrayBuffer`, while `Buffer` is typed as `ArrayBufferLike`. Returning
+ * a plain `Uint8Array` avoids that mismatch for multipart image uploads.
+ *
+ * @param input - Raw image bytes stored in a Node.js `Buffer`.
+ * @returns An `ArrayBuffer` safe to pass into `new Blob([...])`.
+ */
+export function bufferToBlobPart(input) {
+    const bytes = new ArrayBuffer(input.byteLength);
+    new Uint8Array(bytes).set(input);
+    return bytes;
+}
+//# sourceMappingURL=imageToBuffer.js.map

package/dist/core/images/imageToBuffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageToBuffer.js","sourceRoot":"","sources":["../../../src/core/images/imageToBuffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAsB;IACxD,oCAAoC;IACpC,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,SAAS,CAAC,yEAAyE,CAAC,CAAC;IACjG,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAE7B,0DAA0D;IAC1D,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;QAClF,CAAC;QACD,oDAAoD;QACpD,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC5D,CAAC;IAED,gDAAgD;IAChD,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC;QAC3C,OAAO,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAED,yCAAyC;IACzC,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACpE,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CACb,6CAA6C,OAAO,KAAK,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,IAAI,CACpG,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,yEAAyE;IACzE,+DAA+D;IAC/D,MAAM,aAAa,GACjB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAChF,IAAI,aAAa,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAED,oDAAoD;IACpD,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAChD,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACjC,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/images/index.d.ts

@@ -1,10 +1,14 @@
 import type { IImageProvider } from './IImageProvider.js';
 export * from './IImageProvider.js';
+export * from './imageToBuffer.js';
+export * from './ImageOperationError.js';
 export * from './providers/OpenAIImageProvider.js';
 export * from './providers/OpenRouterImageProvider.js';
 export * from './providers/ReplicateImageProvider.js';
 export * from './providers/StabilityImageProvider.js';
 export * from './providers/StableDiffusionLocalProvider.js';
+export * from './providers/FluxImageProvider.js';
+export * from './providers/FalImageProvider.js';
 export type ImageProviderFactory = () => IImageProvider;
 export declare function registerImageProviderFactory(providerId: string, factory: ImageProviderFactory): void;
 export declare function unregisterImageProviderFactory(providerId: string): void;

package/dist/core/images/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/images/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAO1D,cAAc,qBAAqB,CAAC;AACpC,cAAc,oCAAoC,CAAC;AACnD,cAAc,wCAAwC,CAAC;AACvD,cAAc,uCAAuC,CAAC;AACtD,cAAc,uCAAuC,CAAC;AACtD,cAAc,6CAA6C,CAAC;AAE5D,MAAM,MAAM,oBAAoB,GAAG,MAAM,cAAc,CAAC;AAUxD,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAEpG;AAED,wBAAgB,8BAA8B,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAEvE;AAED,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,wBAAgB,0BAA0B,IAAI,MAAM,EAAE,CAErD;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAMtE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/images/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAS1D,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oCAAoC,CAAC;AACnD,cAAc,wCAAwC,CAAC;AACvD,cAAc,uCAAuC,CAAC;AACtD,cAAc,uCAAuC,CAAC;AACtD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAEhD,MAAM,MAAM,oBAAoB,GAAG,MAAM,cAAc,CAAC;AAYxD,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAEpG;AAED,wBAAgB,8BAA8B,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAEvE;AAED,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,wBAAgB,0BAA0B,IAAI,MAAM,EAAE,CAErD;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAMtE"}

package/dist/core/images/index.js

@@ -3,18 +3,26 @@ import { OpenRouterImageProvider } from './providers/OpenRouterImageProvider.js'
 import { ReplicateImageProvider } from './providers/ReplicateImageProvider.js';
 import { StabilityImageProvider } from './providers/StabilityImageProvider.js';
 import { StableDiffusionLocalProvider } from './providers/StableDiffusionLocalProvider.js';
+import { FluxImageProvider } from './providers/FluxImageProvider.js';
+import { FalImageProvider } from './providers/FalImageProvider.js';
 export * from './IImageProvider.js';
+export * from './imageToBuffer.js';
+export * from './ImageOperationError.js';
 export * from './providers/OpenAIImageProvider.js';
 export * from './providers/OpenRouterImageProvider.js';
 export * from './providers/ReplicateImageProvider.js';
 export * from './providers/StabilityImageProvider.js';
 export * from './providers/StableDiffusionLocalProvider.js';
+export * from './providers/FluxImageProvider.js';
+export * from './providers/FalImageProvider.js';
 const imageProviderFactories = new Map([
     ['openai', () => new OpenAIImageProvider()],
     ['openrouter', () => new OpenRouterImageProvider()],
     ['stability', () => new StabilityImageProvider()],
     ['replicate', () => new ReplicateImageProvider()],
     ['stable-diffusion-local', () => new StableDiffusionLocalProvider()],
+    ['bfl', () => new FluxImageProvider()],
+    ['fal', () => new FalImageProvider()],
 ]);
 export function registerImageProviderFactory(providerId, factory) {
     imageProviderFactories.set(providerId.toLowerCase(), factory);

package/dist/core/images/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/images/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,4BAA4B,EAAE,MAAM,6CAA6C,CAAC;AAE3F,cAAc,qBAAqB,CAAC;AACpC,cAAc,oCAAoC,CAAC;AACnD,cAAc,wCAAwC,CAAC;AACvD,cAAc,uCAAuC,CAAC;AACtD,cAAc,uCAAuC,CAAC;AACtD,cAAc,6CAA6C,CAAC;AAI5D,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAA+B;IACnE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,mBAAmB,EAAE,CAAC;IAC3C,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,uBAAuB,EAAE,CAAC;IACnD,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,sBAAsB,EAAE,CAAC;IACjD,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,sBAAsB,EAAE,CAAC;IACjD,CAAC,wBAAwB,EAAE,GAAG,EAAE,CAAC,IAAI,4BAA4B,EAAE,CAAC;CACrE,CAAC,CAAC;AAEH,MAAM,UAAU,4BAA4B,CAAC,UAAkB,EAAE,OAA6B;IAC5F,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,UAAkB;IAC/D,sBAAsB,CAAC,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,UAAkB;IACxD,OAAO,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,0BAA0B;IACxC,OAAO,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,MAAM,OAAO,GAAG,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;IACrE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,mDAAmD,UAAU,IAAI,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,OAAO,EAAE,CAAC;AACnB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/images/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,4BAA4B,EAAE,MAAM,6CAA6C,CAAC;AAC3F,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAEnE,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oCAAoC,CAAC;AACnD,cAAc,wCAAwC,CAAC;AACvD,cAAc,uCAAuC,CAAC;AACtD,cAAc,uCAAuC,CAAC;AACtD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAIhD,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAA+B;IACnE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,mBAAmB,EAAE,CAAC;IAC3C,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,uBAAuB,EAAE,CAAC;IACnD,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,sBAAsB,EAAE,CAAC;IACjD,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,sBAAsB,EAAE,CAAC;IACjD,CAAC,wBAAwB,EAAE,GAAG,EAAE,CAAC,IAAI,4BAA4B,EAAE,CAAC;IACpE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,iBAAiB,EAAE,CAAC;IACtC,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,gBAAgB,EAAE,CAAC;CACtC,CAAC,CAAC;AAEH,MAAM,UAAU,4BAA4B,CAAC,UAAkB,EAAE,OAA6B;IAC5F,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,UAAkB;IAC/D,sBAAsB,CAAC,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,UAAkB;IACxD,OAAO,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,0BAA0B;IACxC,OAAO,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,MAAM,OAAO,GAAG,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;IACrE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,mDAAmD,UAAU,IAAI,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,OAAO,EAAE,CAAC;AACnB,CAAC"}

package/dist/core/images/providers/FalImageProvider.d.ts

@@ -0,0 +1,208 @@
+/**
+ * @module core/images/providers/FalImageProvider
+ *
+ * Image generation provider for the Fal.ai platform, a popular serverless
+ * GPU host that offers fast inference for Flux and other diffusion models.
+ *
+ * ## Supported models
+ *
+ * | Model ID                    | Description                                  |
+ * |-----------------------------|----------------------------------------------|
+ * | `fal-ai/flux/dev`           | Flux Dev — fast iteration, open weights      |
+ * | `fal-ai/flux-pro`           | Flux Pro — highest quality                   |
+ * | `fal-ai/flux/schnell`       | Flux Schnell — optimised for speed           |
+ *
+ * ## API flow (queue-based)
+ *
+ * 1. **Submit** — `POST https://queue.fal.run/{model}` with prompt/params.
+ *    Returns `{ request_id }` immediately.
+ * 2. **Poll** — `GET https://queue.fal.run/{model}/requests/{request_id}/status`
+ *    until `status === 'COMPLETED'` and `images` array is populated.
+ *
+ * ## Authentication
+ *
+ * Requires a `FAL_API_KEY` environment variable. The key is sent as
+ * `Authorization: Key ${FAL_API_KEY}`.
+ *
+ * @see {@link IImageProvider} for the provider interface contract.
+ * @see {@link FluxImageProvider} for direct BFL API access.
+ * @see {@link ReplicateImageProvider} for Flux via Replicate.
+ */
+import { type IImageProvider, type ImageGenerationRequest, type ImageGenerationResult, type ImageModelInfo } from '../IImageProvider.js';
+/**
+ * Configuration for the Fal.ai image provider.
+ *
+ * @example
+ * ```typescript
+ * const config: FalImageProviderConfig = {
+ *   apiKey: process.env.FAL_API_KEY!,
+ *   defaultModelId: 'fal-ai/flux/dev',
+ * };
+ * ```
+ */
+export interface FalImageProviderConfig {
+    /**
+     * Fal.ai API key. Sent as `Authorization: Key ${apiKey}`.
+     * Obtain from https://fal.ai/dashboard/keys
+     */
+    apiKey: string;
+    /**
+     * Base URL for the Fal.ai queue API. Override for testing or proxy setups.
+     * @default 'https://queue.fal.run'
+     */
+    baseURL?: string;
+    /**
+     * Default model to use when the request doesn't specify one.
+     * @default 'fal-ai/flux/dev'
+     */
+    defaultModelId?: string;
+    /**
+     * Milliseconds between status polls while waiting for generation.
+     * @default 1000
+     */
+    pollIntervalMs?: number;
+    /**
+     * Maximum milliseconds to wait for generation before timing out.
+     * @default 120000
+     */
+    timeoutMs?: number;
+}
+/**
+ * Provider-specific options for Fal.ai image generation.
+ *
+ * Pass via `request.providerOptions.fal` when calling
+ * {@link FalImageProvider.generateImage}.
+ *
+ * @example
+ * ```typescript
+ * const result = await provider.generateImage({
+ *   modelId: 'fal-ai/flux/dev',
+ *   prompt: 'A sunset over mountains',
+ *   providerOptions: {
+ *     fal: { num_images: 2, seed: 42 },
+ *   },
+ * });
+ * ```
+ */
+export interface FalImageProviderOptions {
+    /** Number of images to generate. Default: 1. */
+    num_images?: number;
+    /** Image size string (e.g. 'landscape_16_9', 'square_hd', 'portrait_4_3'). */
+    image_size?: string;
+    /** Random seed for reproducible generation. */
+    seed?: number;
+    /** Number of inference steps. */
+    num_inference_steps?: number;
+    /** Guidance scale for classifier-free guidance. */
+    guidance_scale?: number;
+    /** Whether to enable the safety checker. Default: true. */
+    enable_safety_checker?: boolean;
+}
+/**
+ * Image generation provider connecting to the Fal.ai serverless platform.
+ *
+ * Implements the queue-based submit-then-poll pattern: a generation request
+ * returns a request ID immediately, and the provider polls the status
+ * endpoint until completion or timeout.
+ *
+ * @implements {IImageProvider}
+ *
+ * @example
+ * ```typescript
+ * const provider = new FalImageProvider();
+ * await provider.initialize({ apiKey: process.env.FAL_API_KEY! });
+ *
+ * const result = await provider.generateImage({
+ *   modelId: 'fal-ai/flux/dev',
+ *   prompt: 'A photorealistic astronaut riding a horse on Mars',
+ * });
+ * console.log(result.images[0].url);
+ * ```
+ */
+export declare class FalImageProvider implements IImageProvider {
+    /** @inheritdoc */
+    readonly providerId = "fal";
+    /** @inheritdoc */
+    isInitialized: boolean;
+    /** @inheritdoc */
+    defaultModelId?: string;
+    /** Internal resolved configuration. */
+    private _config;
+    /**
+     * Initialize the provider with API credentials and optional configuration.
+     *
+     * @param config - Configuration object. Must include `apiKey`.
+     * @throws {Error} If `apiKey` is missing or empty.
+     *
+     * @example
+     * ```typescript
+     * await provider.initialize({ apiKey: 'fal_xxx' });
+     * ```
+     */
+    initialize(config: Record<string, unknown>): Promise<void>;
+    /**
+     * Generate an image using the Fal.ai queue API.
+     *
+     * Submits the generation task to the queue, then polls the status
+     * endpoint until the result is ready or the timeout is reached.
+     *
+     * @param request - Image generation request with prompt and optional params.
+     * @returns The generated image result with URL(s).
+     *
+     * @throws {Error} If the provider is not initialized.
+     * @throws {Error} If the API returns an error or times out.
+     *
+     * @example
+     * ```typescript
+     * const result = await provider.generateImage({
+     *   modelId: 'fal-ai/flux/dev',
+     *   prompt: 'A serene Japanese garden in autumn',
+     *   n: 2,
+     * });
+     * ```
+     */
+    generateImage(request: ImageGenerationRequest): Promise<ImageGenerationResult>;
+    /**
+     * List available Flux models on the Fal.ai platform.
+     *
+     * @returns Static list of known Fal.ai model identifiers.
+     */
+    listAvailableModels(): Promise<ImageModelInfo[]>;
+    /**
+     * Submit a generation task to the Fal.ai queue.
+     *
+     * @param model - Full model path (e.g. 'fal-ai/flux/dev').
+     * @param body - Request body with prompt and generation params.
+     * @returns The request_id for status polling.
+     *
+     * @throws {Error} If the submission request fails.
+     * @internal
+     */
+    private _submitTask;
+    /**
+     * Poll the Fal.ai status endpoint until the task completes or times out.
+     *
+     * @param model - Full model path.
+     * @param requestId - The request ID from submission.
+     *
+     * @throws {Error} If the generation fails or times out.
+     * @internal
+     */
+    private _pollStatus;
+    /**
+     * Fetch the completed generation result from the Fal.ai result endpoint.
+     *
+     * Called after polling confirms the task is COMPLETED. The result
+     * endpoint is separate from the status endpoint because Fal.ai
+     * returns the full payload (including image URLs) only here.
+     *
+     * @param model - Full model path.
+     * @param requestId - The request ID from submission.
+     * @returns The generation result with image URLs.
+     *
+     * @throws {Error} If the result fetch fails.
+     * @internal
+     */
+    private _fetchResult;
+}
+//# sourceMappingURL=FalImageProvider.d.ts.map

package/dist/core/images/providers/FalImageProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FalImageProvider.d.ts","sourceRoot":"","sources":["../../../../src/core/images/providers/FalImageProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EAGpB,MAAM,sBAAsB,CAAC;AAM9B;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoDD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,uBAAuB;IACtC,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAqBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAiB,YAAW,cAAc;IACrD,kBAAkB;IAClB,SAAgB,UAAU,SAAS;IAEnC,kBAAkB;IACX,aAAa,UAAS;IAE7B,kBAAkB;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;IAE/B,uCAAuC;IACvC,OAAO,CAAC,OAAO,CAA0H;IAEzI;;;;;;;;;;OAUG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BhE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,aAAa,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAmEpF;;;;OAIG;IACG,mBAAmB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAYtD;;;;;;;;;OASG;YACW,WAAW;IAyBzB;;;;;;;;OAQG;YACW,WAAW;IAkCzB;;;;;;;;;;;;;OAaG;YACW,YAAY;CAgB3B"}

package/dist/core/images/providers/FalImageProvider.js

@@ -0,0 +1,301 @@
+/**
+ * @module core/images/providers/FalImageProvider
+ *
+ * Image generation provider for the Fal.ai platform, a popular serverless
+ * GPU host that offers fast inference for Flux and other diffusion models.
+ *
+ * ## Supported models
+ *
+ * | Model ID                    | Description                                  |
+ * |-----------------------------|----------------------------------------------|
+ * | `fal-ai/flux/dev`           | Flux Dev — fast iteration, open weights      |
+ * | `fal-ai/flux-pro`           | Flux Pro — highest quality                   |
+ * | `fal-ai/flux/schnell`       | Flux Schnell — optimised for speed           |
+ *
+ * ## API flow (queue-based)
+ *
+ * 1. **Submit** — `POST https://queue.fal.run/{model}` with prompt/params.
+ *    Returns `{ request_id }` immediately.
+ * 2. **Poll** — `GET https://queue.fal.run/{model}/requests/{request_id}/status`
+ *    until `status === 'COMPLETED'` and `images` array is populated.
+ *
+ * ## Authentication
+ *
+ * Requires a `FAL_API_KEY` environment variable. The key is sent as
+ * `Authorization: Key ${FAL_API_KEY}`.
+ *
+ * @see {@link IImageProvider} for the provider interface contract.
+ * @see {@link FluxImageProvider} for direct BFL API access.
+ * @see {@link ReplicateImageProvider} for Flux via Replicate.
+ */
+import { parseImageSize, } from '../IImageProvider.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Sleep for the specified number of milliseconds.
+ * Used between poll requests to avoid rate-limiting.
+ * @param ms - Duration in milliseconds.
+ * @returns Resolves after the delay.
+ * @internal
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Image generation provider connecting to the Fal.ai serverless platform.
+ *
+ * Implements the queue-based submit-then-poll pattern: a generation request
+ * returns a request ID immediately, and the provider polls the status
+ * endpoint until completion or timeout.
+ *
+ * @implements {IImageProvider}
+ *
+ * @example
+ * ```typescript
+ * const provider = new FalImageProvider();
+ * await provider.initialize({ apiKey: process.env.FAL_API_KEY! });
+ *
+ * const result = await provider.generateImage({
+ *   modelId: 'fal-ai/flux/dev',
+ *   prompt: 'A photorealistic astronaut riding a horse on Mars',
+ * });
+ * console.log(result.images[0].url);
+ * ```
+ */
+export class FalImageProvider {
+    constructor() {
+        /** @inheritdoc */
+        this.providerId = 'fal';
+        /** @inheritdoc */
+        this.isInitialized = false;
+    }
+    /**
+     * Initialize the provider with API credentials and optional configuration.
+     *
+     * @param config - Configuration object. Must include `apiKey`.
+     * @throws {Error} If `apiKey` is missing or empty.
+     *
+     * @example
+     * ```typescript
+     * await provider.initialize({ apiKey: 'fal_xxx' });
+     * ```
+     */
+    async initialize(config) {
+        const apiKey = typeof config.apiKey === 'string' ? config.apiKey.trim() : '';
+        if (!apiKey) {
+            throw new Error('Fal.ai image provider requires apiKey (FAL_API_KEY).');
+        }
+        this._config = {
+            apiKey,
+            baseURL: typeof config.baseURL === 'string' && config.baseURL.trim()
+                ? config.baseURL.trim()
+                : 'https://queue.fal.run',
+            defaultModelId: typeof config.defaultModelId === 'string' && config.defaultModelId.trim()
+                ? config.defaultModelId.trim()
+                : 'fal-ai/flux/dev',
+            pollIntervalMs: typeof config.pollIntervalMs === 'number' && config.pollIntervalMs > 0
+                ? config.pollIntervalMs
+                : 1000,
+            timeoutMs: typeof config.timeoutMs === 'number' && config.timeoutMs > 0
+                ? config.timeoutMs
+                : 120000,
+        };
+        this.defaultModelId = this._config.defaultModelId;
+        this.isInitialized = true;
+    }
+    /**
+     * Generate an image using the Fal.ai queue API.
+     *
+     * Submits the generation task to the queue, then polls the status
+     * endpoint until the result is ready or the timeout is reached.
+     *
+     * @param request - Image generation request with prompt and optional params.
+     * @returns The generated image result with URL(s).
+     *
+     * @throws {Error} If the provider is not initialized.
+     * @throws {Error} If the API returns an error or times out.
+     *
+     * @example
+     * ```typescript
+     * const result = await provider.generateImage({
+     *   modelId: 'fal-ai/flux/dev',
+     *   prompt: 'A serene Japanese garden in autumn',
+     *   n: 2,
+     * });
+     * ```
+     */
+    async generateImage(request) {
+        if (!this.isInitialized) {
+            throw new Error('Fal.ai image provider is not initialized. Call initialize() first.');
+        }
+        const model = request.modelId || this.defaultModelId || 'fal-ai/flux/dev';
+        // Extract Fal-specific options from the provider options bag.
+        const providerOpts = request.providerOptions?.fal;
+        // Build the request body matching Fal.ai's API schema.
+        const body = {
+            prompt: request.prompt,
+        };
+        // Map standard request fields to Fal.ai parameters.
+        // Fal.ai uses `image_size` which can be a named preset or dimensions.
+        const { width, height } = parseImageSize(request.size);
+        if (providerOpts?.image_size) {
+            body.image_size = providerOpts.image_size;
+        }
+        else if (width && height) {
+            // Fal.ai accepts object-style dimensions for some models
+            body.image_size = { width, height };
+        }
+        if (request.n)
+            body.num_images = request.n;
+        if (providerOpts?.num_images !== undefined)
+            body.num_images = providerOpts.num_images;
+        if (request.seed !== undefined)
+            body.seed = request.seed;
+        if (providerOpts?.seed !== undefined)
+            body.seed = providerOpts.seed;
+        if (providerOpts?.num_inference_steps !== undefined)
+            body.num_inference_steps = providerOpts.num_inference_steps;
+        if (providerOpts?.guidance_scale !== undefined)
+            body.guidance_scale = providerOpts.guidance_scale;
+        if (providerOpts?.enable_safety_checker !== undefined)
+            body.enable_safety_checker = providerOpts.enable_safety_checker;
+        // Step 1: Submit to the queue
+        const requestId = await this._submitTask(model, body);
+        // Step 2: Poll until complete
+        await this._pollStatus(model, requestId);
+        // Step 3: Fetch the result
+        const result = await this._fetchResult(model, requestId);
+        if (!result.images || result.images.length === 0) {
+            throw new Error('Fal.ai generation completed but returned no images.');
+        }
+        const images = result.images.map((img) => ({
+            url: img.url,
+            mimeType: img.content_type,
+            providerMetadata: {
+                width: img.width,
+                height: img.height,
+                seed: result.seed,
+            },
+        }));
+        return {
+            created: Math.floor(Date.now() / 1000),
+            modelId: model,
+            providerId: this.providerId,
+            images,
+            usage: {
+                totalImages: images.length,
+            },
+        };
+    }
+    /**
+     * List available Flux models on the Fal.ai platform.
+     *
+     * @returns Static list of known Fal.ai model identifiers.
+     */
+    async listAvailableModels() {
+        return [
+            { providerId: this.providerId, modelId: 'fal-ai/flux/dev', displayName: 'Flux Dev (Fal.ai)' },
+            { providerId: this.providerId, modelId: 'fal-ai/flux-pro', displayName: 'Flux Pro (Fal.ai)' },
+            { providerId: this.providerId, modelId: 'fal-ai/flux/schnell', displayName: 'Flux Schnell (Fal.ai)' },
+        ];
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Submit a generation task to the Fal.ai queue.
+     *
+     * @param model - Full model path (e.g. 'fal-ai/flux/dev').
+     * @param body - Request body with prompt and generation params.
+     * @returns The request_id for status polling.
+     *
+     * @throws {Error} If the submission request fails.
+     * @internal
+     */
+    async _submitTask(model, body) {
+        const url = `${this._config.baseURL}/${model}`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Key ${this._config.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Fal.ai image generation submission failed (${response.status}): ${errorText}`);
+        }
+        const data = (await response.json());
+        if (!data.request_id) {
+            throw new Error('Fal.ai submission response missing request_id.');
+        }
+        return data.request_id;
+    }
+    /**
+     * Poll the Fal.ai status endpoint until the task completes or times out.
+     *
+     * @param model - Full model path.
+     * @param requestId - The request ID from submission.
+     *
+     * @throws {Error} If the generation fails or times out.
+     * @internal
+     */
+    async _pollStatus(model, requestId) {
+        const startedAt = Date.now();
+        while (Date.now() - startedAt < this._config.timeoutMs) {
+            const url = `${this._config.baseURL}/${model}/requests/${requestId}/status`;
+            const response = await fetch(url, {
+                headers: {
+                    Authorization: `Key ${this._config.apiKey}`,
+                },
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`Fal.ai status polling failed (${response.status}): ${errorText}`);
+            }
+            const data = (await response.json());
+            if (data.status === 'COMPLETED') {
+                return;
+            }
+            if (data.status === 'FAILED') {
+                throw new Error(`Fal.ai image generation failed for request ${requestId}.`);
+            }
+            // 'IN_QUEUE' or 'IN_PROGRESS' — wait before next poll
+            await sleep(this._config.pollIntervalMs);
+        }
+        throw new Error(`Fal.ai image generation timed out after ${this._config.timeoutMs}ms for request ${requestId}.`);
+    }
+    /**
+     * Fetch the completed generation result from the Fal.ai result endpoint.
+     *
+     * Called after polling confirms the task is COMPLETED. The result
+     * endpoint is separate from the status endpoint because Fal.ai
+     * returns the full payload (including image URLs) only here.
+     *
+     * @param model - Full model path.
+     * @param requestId - The request ID from submission.
+     * @returns The generation result with image URLs.
+     *
+     * @throws {Error} If the result fetch fails.
+     * @internal
+     */
+    async _fetchResult(model, requestId) {
+        const url = `${this._config.baseURL}/${model}/requests/${requestId}`;
+        const response = await fetch(url, {
+            headers: {
+                Authorization: `Key ${this._config.apiKey}`,
+            },
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Fal.ai result fetch failed (${response.status}): ${errorText}`);
+        }
+        return (await response.json());
+    }
+}
+//# sourceMappingURL=FalImageProvider.js.map