@howells/motif-sdk 6.0.0 → 7.1.0

package/README.md

@@ -34,7 +34,7 @@ Every Task function returns `Result<TaskOutput, MotifError>` from `neverthrow` a
 
 ## Curated Models and Tiers
 
-The Task client curates 24 generation Models, with separate rankings for generation and editing. Both follow Arena, read 29 October 2026. `TASKS.generate` and `TASKS.vary` expose the current choices, Tiers and evidence in `basis` and `rankedAt`. A generation with `references` uses the editing ranking.
+The Task client curates 23 generation Models, with separate rankings for generation and editing. Both follow Arena, read 29 October 2026. `TASKS.generate` and `TASKS.vary` expose the current choices, Tiers and evidence in `basis` and `rankedAt`. Sunburst and Flare run GPT Image 2.6; Arena has not scored 2.6 yet, so their benchmarks are the GPT Image 2.5 scores, and each carries a `note` saying so. A generation with `references` uses the editing ranking.
 
 | Tier                 | Generation default | Editing default   |
 | -------------------- | ------------------ | ----------------- |
@@ -42,11 +42,11 @@ The Task client curates 24 generation Models, with separate rankings for generat
 | `balanced` (default) | Nano Banana 2.1    | Grok Image 2      |
 | `fast`               | Nano Banana 2 Lite | Grok              |
 
-These are the first choices when the request's capabilities and available keys permit them. Explicit Models, Looks and pins take precedence. Selected specialists remain for typography, transparency, control and inexpensive drafts. Archived predecessors remain available through explicit Models, pins and existing Looks, including `flux2-dev` for streaming.
+These are the first choices when the request's capabilities and available keys permit them. Explicit Models, Looks and pins take precedence. Selected specialists remain for typography, transparency, control and inexpensive drafts.
 
 Nano Banana 2.1 (`banana21`) supports up to 14 References and 1K/2K/4K output, with no 0.5K output. Its balanced placement uses preliminary Arena evidence. Sunburst and Flare run GPT Image 2.6 on fal and default to `quality: "max"`; `params: { quality: "high" }` with an explicit `model` overrides it. Both also return an animated GIF (`outputFormat: "gif"`, with `params.frame_count` and `params.frame_duration_ms`) or, from text, an SVG (`outputFormat: "svg"`), and take `markup`: a transparent PNG of arrows, circles and notes the size of the image being edited, which guides a vary or an edit with References. Asking for a format or markup limits the choice to Models that support it. The direct provider image layer described below has its own adapter capabilities and chooses no Model.
 
-Token-billed Task plans, including Sunburst, Flare, Nano Banana 2.1, Banana Lite and MAI 2.5, report `cost: { usd: null, basis: "unknown" }`; a published representative price is not an exact total. The [curation audit](https://github.com/howells/motif/blob/main/docs/research/image-model-curation-2026-10-07.md) records the current rankings, specialist roles and provider coverage gaps.
+Token-billed Task plans, including Sunburst, Flare, Nano Banana 2.1, Banana Lite and MAI 2.5, report `cost: { usd: null, basis: "unknown" }`; a published representative price is not an exact total.
 
 Pass `onProgress(status, queuePosition)` to hear fal's queue state while a run waits: `"queued"` with its place in line, then `"processing"`, then `"completed"` (or `"failed"`). Passing it sends the run through fal's queue, since only the queue reports state. Models without streaming report state, not a percentage.
 
@@ -73,7 +73,7 @@ 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 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.
+`stream(task, input, options?)` opens a direct inference stream on the resolved route. Streaming is explicitly supported for GPT Image 1.5, including its edit route. Other routes return `STREAMING_UNSUPPORTED` before any provider request; Motif never substitutes another model or retries a stream.
 
 ```ts
 const controller = new AbortController();
@@ -100,7 +100,7 @@ Events use `images`, `progress` or `provider` types. Images carry the same `Task
 
 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.
+For a local checkout, `node packages/motif-sdk/examples/stream.mjs` prints the resolved request without a provider call. Adding `--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
 

package/dist/image.d.ts

@@ -1,11 +1,25 @@
+/**
+ * `@howells/motif-sdk/image` — provider-agnostic image generation + editing.
+ *
+ * ESM-only subpath export, built on the Vercel AI SDK image interface
+ * (`generateImage`, `@ai-sdk/*`). The caller names the provider and model;
+ * reuses the SDK's Result convention (`Result<T, MotifError>` — no
+ * thrown exceptions). Gemini is reached through OpenRouter.
+ *
+ * @example
+ * ```ts
+ * import { createMotifImage } from "@howells/motif-sdk/image";
+ *
+ * const img = createMotifImage({ defaultProvider: "openrouter" });
+ * const r = await img.generate({ model: "gemini-3.1-flash-image", prompt: "a bare concrete wall" });
+ * if (r.isOk()) console.log(r.value.images[0].mediaType, r.value.cost);
+ * ```
+ */
 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.
  *
@@ -24,8 +38,6 @@ declare class MotifError extends Error {
   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
 /**
  * Image provider id. All four Phase 1b adapters are implemented
  * (`openrouter`, `openai`, `replicate`, `fal`); the type keeps an open union tail so
@@ -240,8 +252,6 @@ interface MotifImageClient {
    */
   bestOfN: (opts: BestOfNOptions) => Promise<Result<BestOfNResult, MotifError>>;
 }
-//#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, fetch?: FalFetch) => ImageModel;
 /** Internal dependency-injection seam (default: real `generateImage` + adapters). */
@@ -249,8 +259,6 @@ interface MotifImageDeps {
   generateImage?: typeof generateImage;
   resolveModel?: ResolveImageModel;
 }
-//#endregion
-//#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 resolve keys and meter spend.
@@ -292,24 +300,14 @@ export declare const PROVIDERS: Record<ImageProviderId, ImageProviderAdapter>;
  * provider (callers catch this into a `Result.err`).
  */
 export declare function getProviderAdapter(provider: ImageProviderId): ImageProviderAdapter;
-//#endregion
-//#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. */
 export declare const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
-//#endregion
-//#region src/image/replicate.d.ts
 /** 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
 /** Env var read for the fal key when `apiKey` is not supplied in config. */
 export declare const FAL_API_KEY_ENV = "FAL_KEY";
-//#endregion
-//#region src/image/cost.d.ts
 /**
  * Extract a provider-reported total cost from a `generateImage` result's
  * `providerMetadata`, if the provider surfaces a numeric `cost`. The shape is
@@ -323,8 +321,6 @@ export declare function providerPricePerImageUsd(provider: ImageProviderId, mode
  * then the static table (× image count), then unknown.
  */
 export declare function costForImages(provider: ImageProviderId, modelId: string, providerMetadata: unknown, imageCount: number): ImageCost;
-//#endregion
-//#region src/image/index.d.ts
 /**
  * Create a provider-agnostic image client.
  *
@@ -333,5 +329,4 @@ export declare function costForImages(provider: ImageProviderId, modelId: string
  *   and the built-in provider adapters; tests inject fakes here to run offline.
  */
 export declare function createMotifImage(config?: MotifImageConfig, deps?: MotifImageDeps): MotifImageClient;
-//#endregion
 export type { BestOfNOptions, BestOfNResult, EditImageOptions, GenerateImageOptions, ImageCost, ImageCostSource, ImageJudge, ImageProviderAdapter, ImageProviderId, MotifImageClient, MotifImageConfig, MotifImageFile, MotifImageResult };