@howells/motif-sdk 7.0.0 → 7.2.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 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`. 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   |
 | -------------------- | ------------------ | ----------------- |

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 };

package/dist/image.js

@@ -3,7 +3,7 @@ import { err, ok } from "neverthrow";
 import { createFal } from "@ai-sdk/fal";
 import { createOpenAI } from "@ai-sdk/openai";
 import { createReplicate } from "@ai-sdk/replicate";
-//#region src/errors.ts
+// src/errors.ts
 /**
 * `MotifError` and its coercion helper.
 *
@@ -49,8 +49,7 @@ function falHttpError(status, body, requestId) {
 	if (isFalAccountLocked(status, body)) return new MotifError(`fal account is locked because it is out of credit (fal said: ${body})`, status, ACCOUNT_LOCKED, requestId);
 	return new MotifError(`Request failed: ${status} ${body}`, status, void 0, requestId);
 }
-//#endregion
-//#region src/models.ts
+// src/models.ts
 const AA_IMAGE_LEADERBOARD_SNAPSHOT = "2026-10-07";
 const AA_IMAGE_SOURCES = ["https://artificialanalysis.ai/image/leaderboard/text-to-image", "https://artificialanalysis.ai/image/leaderboard/editing"];
 const FAL_PRICING_CHECKED_AT = "2026-05-12";
@@ -120,7 +119,7 @@ const MODELS = {
 			"xhigh",
 			"max"
 		],
-		supportsResolution: false,
+		supportsResolution: true,
 		supportsSyncMode: true,
 		type: "generation",
 		useQueue: true
@@ -187,7 +186,7 @@ const MODELS = {
 			"xhigh",
 			"max"
 		],
-		supportsResolution: false,
+		supportsResolution: true,
 		supportsSyncMode: true,
 		type: "generation",
 		useQueue: true
@@ -1219,8 +1218,7 @@ const MODELS = {
 	"ideogram3-transparent",
 	"recraft41"
 ].filter((id) => MODELS[id]?.supportsEdit === true);
-//#endregion
-//#region src/capabilities.ts
+// src/capabilities.ts
 /** Generation options a model can refuse, with the registry test for each. */
 const OPTION_CAPABILITIES = {
 	aspect: (config) => (config.sizeMode ?? "aspect_ratio") !== "none",
@@ -1377,8 +1375,7 @@ Object.keys(OPTION_CAPABILITIES).filter(isModelOption);
 		}
 	]
 }).look;
-//#endregion
-//#region src/tool-registry/analysis.ts
+// src/tool-registry/analysis.ts
 const ANALYSIS_TOOLS = {
 	"got-ocr": {
 		category: "analysis",
@@ -1492,8 +1489,7 @@ const ANALYSIS_TOOLS = {
 		task: "vision moderation"
 	}
 };
-//#endregion
-//#region src/tool-registry/assets.ts
+// src/tool-registry/assets.ts
 const ASSET_TOOLS = {
 	"hunyuan3d-v3": {
 		category: "3d",
@@ -1811,8 +1807,7 @@ const ASSET_TOOLS = {
 		task: "single-image 3D reconstruction"
 	}
 };
-//#endregion
-//#region src/tool-registry/background.ts
+// src/tool-registry/background.ts
 const BACKGROUND_TOOLS = {
 	"ben-v2": {
 		category: "background",
@@ -2187,8 +2182,7 @@ const BACKGROUND_TOOLS = {
 		task: "video enhancement"
 	}
 };
-//#endregion
-//#region src/tool-registry/editing.ts
+// src/tool-registry/editing.ts
 const EDITING_TOOLS = {
 	"bria-eraser": {
 		category: "erase",
@@ -2459,8 +2453,7 @@ const EDITING_TOOLS = {
 		task: "virtual garment try-on"
 	}
 };
-//#endregion
-//#region src/tool-registry/structure.ts
+// src/tool-registry/structure.ts
 const STRUCTURE_TOOLS = {
 	"depth-anything": {
 		category: "preprocess",
@@ -2852,8 +2845,7 @@ const STRUCTURE_TOOLS = {
 		task: "depth preprocessing"
 	}
 };
-//#endregion
-//#region src/tools.ts
+// src/tools.ts
 const FAL_TOOLS = {
 	...ANALYSIS_TOOLS,
 	...ASSET_TOOLS,
@@ -2862,8 +2854,7 @@ const FAL_TOOLS = {
 	...STRUCTURE_TOOLS
 };
 Object.keys(FAL_TOOLS);
-//#endregion
-//#region src/image/fetch.ts
+// src/image/fetch.ts
 function urlOf(input) {
 	if (typeof input === "string") return input;
 	return input instanceof URL ? input.href : input.url;
@@ -2873,8 +2864,7 @@ function toProviderFetch(fetch) {
 	if (fetch === void 0) return {};
 	return { fetch: async (input, init) => await fetch(urlOf(input), init ?? {}) };
 }
-//#endregion
-//#region src/image/fal.ts
+// src/image/fal.ts
 /**
 * fal provider adapter.
 *
@@ -2960,8 +2950,7 @@ const falAdapter = {
 	resolveModel: resolveModel$3,
 	priceUsdByModel: FAL_IMAGE_PRICE_USD
 };
-//#endregion
-//#region src/image/openai.ts
+// src/image/openai.ts
 /**
 * OpenAI (gpt-image) provider adapter.
 *
@@ -3007,8 +2996,7 @@ const openaiAdapter = {
 	resolveModel: resolveModel$2,
 	priceUsdByModel: OPENAI_IMAGE_PRICE_USD
 };
-//#endregion
-//#region src/image/openrouter.ts
+// src/image/openrouter.ts
 /** Env var read for the OpenRouter API key when `apiKey` is not supplied in config. */
 const OPENROUTER_API_KEY_ENV = "OPENROUTER_API_KEY";
 const OPENROUTER_IMAGES_URL = "https://openrouter.ai/api/v1/images";
@@ -3171,8 +3159,7 @@ const openrouterAdapter = {
 	resolveModel: resolveModel$1,
 	priceUsdByModel: OPENROUTER_IMAGE_PRICE_USD
 };
-//#endregion
-//#region src/image/replicate.ts
+// src/image/replicate.ts
 /**
 * Replicate provider adapter.
 *
@@ -3207,8 +3194,7 @@ function resolveModel(modelId, apiKey, fetch) {
 		...toProviderFetch(fetch)
 	}).image(modelId);
 }
-//#endregion
-//#region src/image/provider.ts
+// src/image/provider.ts
 /**
 * The provider registry. Every id in {@link ImageProviderId}'s closed part maps
 * to its adapter; the open union tail means a lookup can still miss, so access
@@ -3234,8 +3220,7 @@ function getProviderAdapter(provider) {
 	if (adapter === void 0) throw new MotifError(`Unsupported image provider: ${provider}`, 0);
 	return adapter;
 }
-//#endregion
-//#region src/image/cost.ts
+// src/image/cost.ts
 /**
 * Per-call cost tracking for the image layer.
 *
@@ -3305,8 +3290,7 @@ function costForCalls(provider, modelId, callMetadata, imageCount) {
 		source: "unknown"
 	};
 }
-//#endregion
-//#region src/image/index.ts
+// src/image/index.ts
 /**
 * `@howells/motif-sdk/image` — provider-agnostic image generation + editing.
 *
@@ -3578,5 +3562,4 @@ function toMotifError(error) {
 	if (isFalAccountLocked(status, body)) return falHttpError(status, body);
 	return new MotifError(message, status, code);
 }
-//#endregion
 export { FAL_API_KEY_ENV, OPENAI_API_KEY_ENV, OPENROUTER_API_KEY_ENV, PROVIDERS, REPLICATE_API_KEY_ENV, costForImages, costFromProviderMetadata, createMotifImage, getProviderAdapter, providerPricePerImageUsd };