@howells/motif-sdk 4.0.0 → 5.0.0

package/README.md

@@ -10,7 +10,7 @@ npm install @howells/motif-sdk
 
 ## Run a Task
 
-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 google, openai, replicate, and fal. See [Image Layer](#image-layer-howellsmotif-sdkimage) below.
+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 { createMotif } from "@howells/motif-sdk";
@@ -32,6 +32,8 @@ console.log(result.value.model, result.value.files[0]?.url, result.value.cost);
 
 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.
+
 ## Plan Without Calling fal
 
 `plan(task, input, { dryRun: true })` resolves the Model and returns the endpoint, body and projected cost with no I/O and no key.
@@ -51,11 +53,42 @@ if (plan.isOk()) {
 }
 ```
 
+## Stream a Task
+
+`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.
+
+```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);
+}
+```
+
+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.
+
+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()`.
+
+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
 
-- `createMotif` - the Task client: one function per Task plus `run`, `plan`, `upload` and `deletePayloads`.
+- `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 google, openai, replicate, and fal.
+- `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.
@@ -64,7 +97,7 @@ if (plan.isOk()) {
 
 ## Common Types
 
-- `MotifClient`, `MotifClientConfig`, `TaskInput`, `TaskOutput`, `TaskPlan`, `TaskFile`
+- `MotifClient`, `MotifClientConfig`, `TaskInput`, `TaskOutput`, `TaskPlan`, `TaskFile`, `TaskStream`, `TaskStreamEvent`, `TaskStreamOptions`
 - `TaskId`, `Tier`, `TaskDefinition`, `RankedModel`, `TaskRequest`, `TaskResolution`, `ModelProfile`
 - `AspectRatio`, `Resolution`, `CustomImageSize`, `ImageSizeBounds`, `MotifError`
 
@@ -79,7 +112,7 @@ 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({
@@ -88,12 +121,11 @@ const generated = await img.generate({
   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({
   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()) {
@@ -110,7 +142,7 @@ 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 |
+| `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 |

package/dist/image.d.ts

@@ -28,10 +28,10 @@ declare class MotifError extends Error {
 //#region src/image/types.d.ts
 /**
  * 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. */
@@ -48,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`. */
@@ -293,9 +293,9 @@ export declare const PROVIDERS: Record<ImageProviderId, ImageProviderAdapter>;
  */
 export declare function getProviderAdapter(provider: ImageProviderId): ImageProviderAdapter;
 //#endregion
-//#region src/image/google.d.ts
-/** 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
 /** Env var read for the OpenAI API key when `apiKey` is not supplied in config. */