@howells/motif-sdk 2.0.0 → 5.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @howells/motif-sdk
 
-Public Node SDK for Motif fal.ai generation, editing, utility tools, and model metadata.
+Public Node SDK for Motif: Task-first image, video and utility work on fal.ai, plus a provider-agnostic image layer.
 
 ## Install
 
@@ -8,129 +8,102 @@ Public Node SDK for Motif fal.ai generation, editing, utility tools, and model m
 npm install @howells/motif-sdk
 ```
 
-## Generate Images
+## Run a Task
 
-The primary image API is `createMotifImage` (`@howells/motif-sdk/image`) — provider-agnostic generate/edit across google, openai, replicate, and fal. See [Image Layer](#image-layer-howellsmotif-sdkimage) below.
-
-The examples in this section use the low-level `FalClient`, the fal-native client for fal-specific capabilities (queue, upload, upscale, background removal, video, and utility tools).
+The Task client, `createMotif`, is the fal surface: name a Task and, optionally, a Tier, and Motif chooses the Model, builds its request and runs it on fal. `createMotifImage` (`@howells/motif-sdk/image`) is the provider-agnostic generate/edit layer across openrouter, openai, replicate, and fal. See [Image Layer](#image-layer-howellsmotif-sdkimage) below.
 
 ```ts
-import { FalClient } from "@howells/motif-sdk";
+import { createMotif } from "@howells/motif-sdk";
 
-const motif = new FalClient({
-  apiKey: process.env.FAL_KEY!,
-  retries: 3,
-  timeout: 120_000,
-});
+const motif = createMotif(); // reads FAL_KEY
 
 const result = await motif.generate({
-  model: "banana2",
   prompt: "editorial product photo",
   resolution: "2K",
-  enableGoogleSearch: true,
-  ephemeral: true,
+  tier: "quality",
 });
 
 if (result.isErr()) {
   throw result.error;
 }
 
-console.log(result.value.images[0]?.url);
+console.log(result.value.model, result.value.files[0]?.url, result.value.cost);
 ```
 
-Every async SDK method returns `Result<T, MotifError>` from `neverthrow`. Methods do not throw for fal request failures; check `isErr()` / `isOk()`.
+Every Task function returns `Result<TaskOutput, MotifError>` from `neverthrow` and does not throw for fal request failures; check `isErr()` / `isOk()`.
+
+Pass `onProgress(status, queuePosition)` to hear fal's queue state while a run waits: `"queued"` with its place in line, then `"in_progress"`, then `"completed"`. Passing it sends the run through fal's queue, since only the queue reports state. Models without streaming report state, not a percentage.
 
-## Dry-Run Request Bodies
+## Plan Without Calling fal
 
-Use `buildGenerateBody` or `motif.buildRequestBody()` when you need the exact fal endpoint and request body without making an API call.
+`plan(task, input, { dryRun: true })` resolves the Model and returns the endpoint, body and projected cost with no I/O and no key.
 
 ```ts
-import { buildGenerateBody } from "@howells/motif-sdk";
-
-const preview = buildGenerateBody({
-  model: "gpt2",
-  prompt: "change the wall color",
-  editImageUrls: ["https://example.com/interior.png"],
-  imageSize: "1536x1024",
-  maskImageUrl: "https://example.com/wall-mask.png",
-  quality: "auto",
-  syncMode: true,
-});
+const plan = motif.plan(
+  "erase",
+  {
+    image: "https://example.com/room.png",
+    prompt: "the chair",
+  },
+  { dryRun: true }
+);
 
-console.log(preview.endpoint);
-console.log(preview.body);
+if (plan.isOk()) {
+  console.log(plan.value.model, plan.value.cost);
+}
 ```
 
-## Queue, Upload, and Cleanup
+## Stream a Task
 
-```ts
-const job = await motif.submitGeneration({
-  model: "gpt2",
-  prompt: "gallery poster",
-});
+`stream(task, input, options?)` opens a direct inference stream on the resolved route. Streaming is explicitly supported for GPT Image 2, GPT Image 1.5 and FLUX.2 Dev, including their edit routes. Other routes return `STREAMING_UNSUPPORTED` before any provider request; Motif never substitutes another model or retries a stream.
 
-if (job.isOk()) {
-  const status = await motif.getJobStatus(
-    job.value.endpoint,
-    job.value.requestId
-  );
-  const completed = await motif.getJobResult(
-    job.value.endpoint,
-    job.value.requestId
-  );
+```ts
+const controller = new AbortController();
+const opened = await motif.stream(
+  "generate",
+  {
+    model: "gpt2",
+    prompt: "editorial product photo",
+    references: ["https://example.com/reference.png"],
+  },
+  { signal: controller.signal, timeout: 300_000 }
+);
+
+if (opened.isErr()) throw opened.error;
+for await (const result of opened.value.events) {
+  if (result.isErr()) throw result.error;
+  const event = result.value;
+  if (event.type === "images") render(event.files);
+  if (event.type === "progress") showProgress(event.progress, event.message);
 }
-
-const uploaded = await motif.uploadToFalCdn(fileBytes, {
-  contentType: "image/png",
-  fileName: "reference.png",
-});
-
-const deleted = await motif.deletePayloads("fal-request-id");
 ```
 
-## Utility Tools and Video
+Events use `images`, `progress` or `provider` types. Images carry the same `TaskFile` URL shape as ordinary Task outputs, including data URIs. Progress fractions are normalised only when explicitly between zero and one. The raw provider payload remains available as `raw` or `data`, and SSE event/id metadata is preserved. Preview images depend on the model; an images event is not labelled preview or final, and transport EOF does not prove generation success.
 
-```ts
-const mask = await motif.runTool({
-  tool: "sam3-image",
-  input: "https://example.com/input.png",
-  options: { prompt: "shoe", max_masks: 2 },
-});
+The handle exposes `plan`, optional `requestId` and `abort()`. Consume its events once. Abort, iterator exit and the overall deadline close local consumption; this does not guarantee cancellation of provider work or a refund. There is no queue submission, reconnection or retry. `plan()` remains a normal execution plan, so its `queued` flag describes `run()`, not `stream()`.
 
-const videoJob = await motif.submitVideo({
-  imageUrl: "https://example.com/frame.png",
-  prompt: "slow cinematic push-in",
-  duration: 5,
-  generateAudio: false,
-});
-```
+For a local checkout, `node packages/motif-sdk/examples/stream.mjs --dry-run` prints the resolved request without a provider call. Running it without `--dry-run` spends provider credits; it requires `FAL_KEY` and a built SDK. The runner is a repository example, not a packaged public API.
 
 ## Main Exports
 
-- `createMotifImage` (`@howells/motif-sdk/image`) - the primary image API: provider-agnostic generate/edit/best-of-N across google, openai, replicate, and fal.
-- `FalClient` - low-level fal-native client for generation, queue jobs, upload, utility tools, and payload deletion.
-- `buildGenerateBody` - Pure fal request normalization for dry runs and tests.
-- `MODELS`, `GENERATION_MODELS`, `UTILITY_MODELS`, `VIDEO_MODELS` - Motif model aliases, fal endpoints, capabilities, pricing, and benchmarks.
-- `FAL_TOOLS`, `FAL_TOOL_IDS`, `buildFalToolRequest`, `isFalToolId` - Normalized fal utility endpoints such as SAM, depth, upscaling, moderation, and background removal.
-- `ASPECT_RATIOS`, `RESOLUTIONS`, `FORMAT_PRESETS`, `aspectToGptSize`, `aspectToFalImageSize` - Shared sizing metadata and normalization helpers.
-- `IMAGE_TEXT_TO_IMAGE_TOP_20`, `IMAGE_EDITING_TOP_20`, `VIDEO_TEXT_TO_VIDEO_TOP_15`, `VIDEO_IMAGE_TO_VIDEO_TOP_15` - Bundled Artificial Analysis snapshots.
-- `estimateCost`, `estimateVideoCost` - Local cost estimates used by CLI dry runs and SDK previews.
-- `getFalKeyFromEnv` - `@howells/envy` backed `FAL_KEY` parsing.
+- `createMotif` - the Task client: one function per Task plus `run`, `stream`, `plan`, `upload` and `deletePayloads`.
+- `TASKS`, `TASK_IDS`, `TIERS`, `resolveTask`, `modelProfile`, `tierChangesChoice` - the Task registry and Model resolution.
+- `createMotifImage` (`@howells/motif-sdk/image`) - provider-agnostic generate/edit/best-of-N across openrouter, openai, replicate, and fal.
+- `ASPECT_RATIOS`, `RESOLUTIONS`, `FORMAT_PRESETS` - shared sizing metadata.
+- `LOOKS`, `CREATIVE_TAXONOMY`, `enrichPrompt`, `validateCreativeDirection` - house looks and moods.
+- `formatCost`, `sumCosts` - cost formatting and totals.
+- `getFalKeyFromEnv`, `getOpenAiKeyFromEnv` - `@howells/envy` backed key parsing.
 - Re-exported `neverthrow` helpers: `ok`, `err`, `Result`, `ResultAsync`.
 
 ## Common Types
 
-The package exports public types for generation, processing, queue, metadata, and utility tools:
-
-- `GenerateOptions`, `MotifResponse`, `MotifImage`
-- `UpscaleOptions`, `RemoveBackgroundOptions`, `VideoOptions`, `VideoResponse`
-- `QueuedJob`, `JobStatus`, `FalClientConfig`
-- `ModelConfig`, `AspectRatio`, `Resolution`, `ImageSize`, `ImageQuality`, `BackgroundMode`, `ThinkingLevel`
-- `FalToolConfig`, `FalToolId`, `FalToolRequest`, `FalToolRunOptions`
+- `MotifClient`, `MotifClientConfig`, `TaskInput`, `TaskOutput`, `TaskPlan`, `TaskFile`, `TaskStream`, `TaskStreamEvent`, `TaskStreamOptions`
+- `TaskId`, `Tier`, `TaskDefinition`, `RankedModel`, `TaskRequest`, `TaskResolution`, `ModelProfile`
+- `AspectRatio`, `Resolution`, `CustomImageSize`, `ImageSizeBounds`, `MotifError`
 
 ## Image Layer (`@howells/motif-sdk/image`)
 
-The primary, provider-agnostic image generation + editing layer — the recommended way to generate and edit images. The fal-specific `FalClient` surface above stays for fal-native extras. It is an ESM-only subpath export, built on the Vercel AI SDK image interface (`ai`'s `generateImage`).
+The provider-agnostic image generation + editing layer, for callers who choose the provider and model themselves. It is an ESM-only subpath export, built on the Vercel AI SDK image interface (`ai`'s `generateImage`).
 
 ```bash
 npm install @howells/motif-sdk
@@ -139,21 +112,20 @@ npm install @howells/motif-sdk
 ```ts
 import { createMotifImage } from "@howells/motif-sdk/image";
 
-const img = createMotifImage({ defaultProvider: "google" });
+const img = createMotifImage({ defaultProvider: "openrouter" });
 
 // text -> image
 const generated = await img.generate({
-  tier: "fast",
+  model: "gemini-3.1-flash-image-preview",
   prompt: "a plain room, bare concrete wall",
   aspectRatio: "1:1",
 });
 
-// multi-image edit (images + instruction, optional mask -> image out)
+// multi-image edit (images + instruction -> image out; masks need the openai provider)
 const edited = await img.edit({
-  tier: "balanced",
+  model: "gemini-3.1-flash-image-preview",
   images: [roomBytes, tileBytes],
   instruction: "Apply the oak texture from image 2 onto the wall in image 1.",
-  mask: surfaceMaskBytes,
 });
 
 if (edited.isOk()) {
@@ -170,14 +142,14 @@ Four providers are implemented, each reading its own API key from the environmen
 
 | Provider | Env var | Notes |
 | --- | --- | --- |
-| `google` | `GOOGLE_GENERATIVE_AI_API_KEY` | Default provider; Gemini gen + edit |
-| `openai` | `OPENAI_API_KEY` | GPT Image 2.5 Flare (fast/balanced), Sunburst (quality/hero) |
+| `openrouter` | `OPENROUTER_API_KEY` | Default provider; Gemini gen + edit through OpenRouter (`google/*`), no masks |
+| `openai` | `OPENAI_API_KEY` | GPT Image 2.5 Flare and Sunburst |
 | `replicate` | `REPLICATE_API_TOKEN` | flux-1.1-pro-ultra |
 | `fal` | `FAL_KEY` | fal-hosted adapter |
 
-`generate()` and `edit()` accept `tier` (`"fast" | "balanced" | "quality" | "hero"`) to resolve a model per provider, or an explicit `model` id. Every result carries a normalized per-call `cost: { usd, source }`.
+`generate()` and `edit()` take a provider model id; Task resolution chooses which model to pass, not the image layer. Every result carries a normalized per-call `cost: { usd, source }`.
 
-For OpenAI, `fast` and `balanced` (the default tier) select `gpt-image-2.5-flare`; `quality` and `hero` select `gpt-image-2.5-sunburst`. This updates the previous OpenAI tier default of `gpt-image-1`; pass that explicit model to retain it. Both new models support generation and multi-image editing:
+Both `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst` support generation and multi-image editing:
 
 ```ts
 const image = createMotifImage({ defaultProvider: "openai" });
@@ -192,7 +164,7 @@ const refined = await image.edit({
 });
 ```
 
-These models use token-based billing. Motif has no static per-image estimate for them, so `cost` is `{ usd: 0, source: "unknown" }` unless the provider supplies a cost; this does not mean generation is free. See the official [Flare](https://developers.openai.com/api/docs/models/gpt-image-2.5-flare) and [Sunburst](https://developers.openai.com/api/docs/models/gpt-image-2.5-sunburst) model pages. The installed OpenAI adapter accepts `low`, `medium`, `high`, and `auto` quality; the new `xhigh` and `max` settings require a future adapter update. The fal-backed CLI and `FalClient` expose these models as `flare` and `sunburst`. Fal supports `xhigh` and `max`, up to 16 edit references, masks and transparent backgrounds. Fal generation estimates are `null` (metered), including `estimateCost()` and queued jobs.
+These models use token-based billing. Motif has no static per-image estimate for them, so `cost` is `{ usd: 0, source: "unknown" }` unless the provider supplies a cost; this does not mean generation is free. See the official [Flare](https://developers.openai.com/api/docs/models/gpt-image-2.5-flare) and [Sunburst](https://developers.openai.com/api/docs/models/gpt-image-2.5-sunburst) model pages. The installed OpenAI adapter accepts `low`, `medium`, `high`, and `auto` quality; the new `xhigh` and `max` settings require a future adapter update. The Task client and the CLI reach these models on fal as `flare` and `sunburst`. Fal supports `xhigh` and `max`, up to 16 edit references, masks and transparent backgrounds. Fal generation estimates are `null` (metered).
 
 ### Best-of-N with an injectable judge
 

package/dist/image.d.ts

@@ -1,5 +1,10 @@
 import { ImageModel, generateImage } from "ai";
 import { Result } from "neverthrow";
+//#region src/types.d.ts
+/** ─── Configuration ──────────────────────────────────────────── */
+/** The network seam: a `fetch`-shaped function. */
+type FalFetch = (url: string, init: RequestInit) => Promise<Response>;
+//#endregion
 //#region src/errors.d.ts
 /**
  * `MotifError` and its coercion helper.
@@ -15,21 +20,18 @@ declare class MotifError extends Error {
   /** fal's request-correlation id (from the `x-fal-request-id` header or the
    * error body). Ties a failure back to fal's dashboard/support. */
   readonly requestId?: string;
-  constructor(message: string, status: number, code?: string, requestId?: string);
+  /** Structured context for the failure, e.g. the refused field. */
+  readonly details?: Record<string, unknown>;
+  constructor(message: string, status: number, code?: string, requestId?: string, details?: Record<string, unknown>);
 }
 //#endregion
 //#region src/image/types.d.ts
-/**
- * Quality/latency tier. Resolves through a provider-aware tier→model map when no
- * explicit `model` id is given. `balanced` is the default when a tier is omitted.
- */
-type ImageTier = "fast" | "balanced" | "quality" | "hero";
 /**
  * Image provider id. All four Phase 1b adapters are implemented
- * (`google`, `openai`, `replicate`, `fal`); the type keeps an open union tail so
+ * (`openrouter`, `openai`, `replicate`, `fal`); the type keeps an open union tail so
  * further adapters can slot in without a breaking type change.
  */
-type ImageProviderId = "google" | "openai" | "replicate" | "fal" | (string & Record<never, never>);
+type ImageProviderId = "openrouter" | "openai" | "replicate" | "fal" | (string & Record<never, never>);
 /** Source that produced a normalized per-call cost. */
 type ImageCostSource = "provider-metadata" | "table" | "unknown";
 /** Normalized per-call spend attached to every result. */
@@ -46,10 +48,10 @@ interface ImageCost {
  * credential `apiToken`, not `apiKey`.
  */
 interface MotifImageConfig {
-  /** Provider used when a call does not specify one. Defaults to `google`. */
+  /** Provider used when a call does not specify one. Defaults to `openrouter`. */
   defaultProvider?: ImageProviderId;
-  /** Google provider overrides. `apiKey` falls back to `GOOGLE_GENERATIVE_AI_API_KEY`. */
-  google?: {
+  /** OpenRouter provider overrides. `apiKey` falls back to `OPENROUTER_API_KEY`. */
+  openrouter?: {
     apiKey?: string;
   };
   /** OpenAI provider overrides. `apiKey` falls back to `OPENAI_API_KEY`. */
@@ -63,6 +65,13 @@ interface MotifImageConfig {
   replicate?: {
     apiToken?: string;
   };
+  /**
+   * Replaces global fetch for every provider request. Remote image URLs passed
+   * to `edit` are still downloaded by the AI SDK with global fetch.
+   */
+  fetch?: FalFetch;
+  /** Retries per call for retryable provider failures. AI SDK default: 2. */
+  maxRetries?: number;
   /** fal provider overrides. `apiKey` falls back to `FAL_KEY`. */
   fal?: {
     apiKey?: string;
@@ -72,10 +81,8 @@ interface MotifImageConfig {
 interface GenerateImageOptions {
   /** The text prompt. */
   prompt: string;
-  /** Quality/latency tier. Ignored when `model` is set. */
-  tier?: ImageTier;
-  /** Explicit provider model id. Overrides `tier`. */
-  model?: string;
+  /** Provider model id. Task resolution chooses it; the image layer never does. */
+  model: string;
   /** Provider override for this call. */
   provider?: ImageProviderId;
   /**
@@ -132,10 +139,8 @@ interface EditImageOptions {
    * `images[0]`.
    */
   mask?: Uint8Array | string;
-  /** Quality/latency tier. Ignored when `model` is set. */
-  tier?: ImageTier;
-  /** Explicit provider model id. Overrides `tier`. */
-  model?: string;
+  /** Provider model id. Task resolution chooses it; the image layer never does. */
+  model: string;
   /** Provider override for this call. */
   provider?: ImageProviderId;
   /** Number of images to generate. */
@@ -238,7 +243,7 @@ interface MotifImageClient {
 //#endregion
 //#region src/image/deps.d.ts
 /** A model resolver: builds an AI SDK `ImageModel` for a (provider, model, key). */
-type ResolveImageModel = (provider: ImageProviderId, modelId: string, apiKey?: string) => ImageModel;
+type ResolveImageModel = (provider: ImageProviderId, modelId: string, apiKey?: string, fetch?: FalFetch) => ImageModel;
 /** Internal dependency-injection seam (default: real `generateImage` + adapters). */
 interface MotifImageDeps {
   generateImage?: typeof generateImage;
@@ -248,14 +253,11 @@ interface MotifImageDeps {
 //#region src/image/provider.d.ts
 /**
  * A single image provider. A thin wrapper over the provider's `@ai-sdk/*` image
- * model, plus the metadata the layer needs to route by tier, resolve keys, and
- * meter spend.
+ * model, plus the metadata the layer needs to resolve keys and meter spend.
  */
 interface ImageProviderAdapter {
   /** Provider id, matching the key it is registered under in {@link PROVIDERS}. */
   readonly id: ImageProviderId;
-  /** Tier → model id map, used when a call does not pass an explicit `model`. */
-  readonly tierModels: Readonly<Record<ImageTier, string>>;
   /** Env var read for the API key when no key is supplied in config. */
   readonly apiKeyEnv: string;
   /**
@@ -264,7 +266,7 @@ interface ImageProviderAdapter {
    * (callers translate this into a `Result.err`). Building a model performs no
    * network I/O.
    */
-  readonly resolveModel: (modelId: string, apiKey?: string) => ImageModel;
+  readonly resolveModel: (modelId: string, apiKey?: string, fetch?: FalFetch) => ImageModel;
   /**
    * Static per-model USD/**image** table (best-effort; cited per adapter). This
    * is multiplied by the returned image count to form the call total.
@@ -291,40 +293,19 @@ export declare const PROVIDERS: Record<ImageProviderId, ImageProviderAdapter>;
  */
 export declare function getProviderAdapter(provider: ImageProviderId): ImageProviderAdapter;
 //#endregion
-//#region src/image/google.d.ts
-/**
- * Tier → Gemini image model id.
- *
- * Seeded from Material Desk's `RENDER_IMAGE_MODEL_BY_QUALITY` (the driving
- * consumer, see the design doc). `gemini-2.5-flash-image` is the proven-reachable
- * floor; the preview ids may require allowlist/tier access.
- */
-export declare const GOOGLE_TIER_MODELS: Readonly<Record<ImageTier, string>>;
-/** Env var read for the Google API key when `apiKey` is not supplied in config. */
-export declare const GOOGLE_API_KEY_ENV = "GOOGLE_GENERATIVE_AI_API_KEY";
+//#region src/image/openrouter.d.ts
+/** Env var read for the OpenRouter API key when `apiKey` is not supplied in config. */
+export declare const OPENROUTER_API_KEY_ENV = "OPENROUTER_API_KEY";
 //#endregion
 //#region src/image/openai.d.ts
-/**
- * Flare favors speed for everyday generation; Sunburst favors editing precision.
- * Explicit model ids still override tiers, including older GPT Image models.
- */
-export declare const OPENAI_TIER_MODELS: Readonly<Record<ImageTier, string>>;
 /** Env var read for the OpenAI API key when `apiKey` is not supplied in config. */
 export declare const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
 //#endregion
 //#region src/image/replicate.d.ts
-/** Tier → Replicate model id (all tiers → FLUX 1.1 Pro Ultra for now). */
-export declare const REPLICATE_TIER_MODELS: Readonly<Record<ImageTier, string>>;
 /** Env var read for the Replicate API token when `apiToken` is not in config. */
 export declare const REPLICATE_API_KEY_ENV = "REPLICATE_API_TOKEN";
 //#endregion
 //#region src/image/fal.d.ts
-/**
- * Tier → fal model id. For fal, explicit `model:` endpoint ids are the primary
- * path (any fal endpoint resolves via passthrough); this tier map is a
- * convenience covering the two most common (FLUX Pro Ultra + gpt-image).
- */
-export declare const FAL_TIER_MODELS: Readonly<Record<ImageTier, string>>;
 /** Env var read for the fal key when `apiKey` is not supplied in config. */
 export declare const FAL_API_KEY_ENV = "FAL_KEY";
 //#endregion
@@ -335,6 +316,8 @@ export declare const FAL_API_KEY_ENV = "FAL_KEY";
  * `{ [provider]: { ...; cost?: number } }`. Returns undefined otherwise.
  */
 export declare function costFromProviderMetadata(providerMetadata: unknown): number | undefined;
+/** Static per-image USD for a (provider, model), or undefined if unknown. */
+export declare function providerPricePerImageUsd(provider: ImageProviderId, modelId: string): number | undefined;
 /**
  * Normalized per-call cost for a generation. Prefers a provider-metadata cost,
  * then the static table (× image count), then unknown.
@@ -351,4 +334,4 @@ export declare function costForImages(provider: ImageProviderId, modelId: string
  */
 export declare function createMotifImage(config?: MotifImageConfig, deps?: MotifImageDeps): MotifImageClient;
 //#endregion
-export type { BestOfNOptions, BestOfNResult, EditImageOptions, GenerateImageOptions, ImageCost, ImageCostSource, ImageJudge, ImageProviderAdapter, ImageProviderId, ImageTier, MotifImageClient, MotifImageConfig, MotifImageFile, MotifImageResult };
+export type { BestOfNOptions, BestOfNResult, EditImageOptions, GenerateImageOptions, ImageCost, ImageCostSource, ImageJudge, ImageProviderAdapter, ImageProviderId, MotifImageClient, MotifImageConfig, MotifImageFile, MotifImageResult };