@howells/motif-sdk 0.8.0 → 0.10.0

package/README.md

@@ -123,6 +123,83 @@ The package exports public types for generation, processing, queue, metadata, an
 - `ModelConfig`, `AspectRatio`, `Resolution`, `ImageSize`, `ImageQuality`, `BackgroundMode`, `ThinkingLevel`
 - `FalToolConfig`, `FalToolId`, `FalToolRequest`, `FalToolRunOptions`
 
+## Image Layer (`@howells/motif-sdk/image`)
+
+A provider-agnostic image generation + editing layer, additive to the fal-specific `MotifServer` surface above. It is an ESM-only subpath export, built on the Vercel AI SDK image interface (`ai`'s `generateImage`).
+
+```bash
+npm install @howells/motif-sdk
+```
+
+```ts
+import { createMotifImage } from "@howells/motif-sdk/image";
+
+const img = createMotifImage({ defaultProvider: "google" });
+
+// text -> image
+const generated = await img.generate({
+  tier: "fast",
+  prompt: "a plain room, bare concrete wall",
+  aspectRatio: "1:1",
+});
+
+// multi-image edit (images + instruction, optional mask -> image out)
+const edited = await img.edit({
+  tier: "balanced",
+  images: [roomBytes, tileBytes],
+  instruction: "Apply the oak texture from image 2 onto the wall in image 1.",
+  mask: surfaceMaskBytes,
+});
+
+if (edited.isOk()) {
+  edited.value.images; // MotifImageFile[]
+  edited.value.cost; // { usd, source: "provider-metadata" | "table" | "unknown" }
+  edited.value.provider; // resolved ImageProviderId
+  edited.value.model; // resolved model id
+}
+```
+
+Both `generate()` and `edit()` return `Result<MotifImageResult, MotifError>`, matching the rest of the SDK — no throws, check `isOk()` / `isErr()`.
+
+Four providers are implemented, each reading its own API key from the environment (or a `MotifImageConfig` override):
+
+| Provider | Env var | Notes |
+| --- | --- | --- |
+| `google` | `GOOGLE_GENERATIVE_AI_API_KEY` | Default provider; Gemini gen + edit |
+| `openai` | `OPENAI_API_KEY` | gpt-image-1 |
+| `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 }`.
+
+### Best-of-N with an injectable judge
+
+`bestOfN()` generates `n` candidates in parallel and picks a winner. It reuses the same options as `generate()` (text→image) or `edit()` (pass `images` for the edit path), plus `n` and an optional `judge`. When a `seed` is given each candidate uses `seed + index`, so the N vary. The judge is a caller-provided function — the layer takes no text-client dependency, so it pairs well with `@howells/ai`'s vision client but does not require it. Omit the judge and candidate 0 wins.
+
+```ts
+const best = await img.bestOfN({
+  prompt: "a plain room, bare concrete wall",
+  n: 4,
+  seed: 100, // candidates get seeds 100, 101, 102, 103
+  // Caller-provided judge: receives the successful candidates + context,
+  // returns the winning index. Wire in @howells/ai here if you want a vision judge.
+  judge: async (candidates, context) => {
+    // ...score candidates[i].images[0] against context.prompt...
+    return { index: 0, reason: "sharpest wall texture" };
+  },
+});
+
+if (best.isOk()) {
+  best.value.best; // the winning MotifImageResult
+  best.value.chosenIndex; // its index within candidates
+  best.value.reason; // the judge's rationale, if any
+  best.value.candidates; // every successful candidate (generation order)
+  best.value.totalCostUsd; // summed USD across all candidates generated
+}
+```
+
+If some candidates fail, the judge sees only the survivors; if all `n` fail, `bestOfN()` returns `Result.err`.
+
 ## Testing
 
 ```bash

package/dist/image.d.ts

@@ -1,4 +1,4 @@
-import { ImageModel, generateImage } from 'ai';
+import { generateImage, ImageModel } from 'ai';
 import { Result } from 'neverthrow';
 
 declare class MotifError extends Error {
@@ -78,25 +78,53 @@ interface GenerateImageOptions {
     model?: string;
     /** Provider override for this call. */
     provider?: ImageProviderId;
-    /** Aspect ratio, e.g. `"1:1"`. */
+    /**
+     * Aspect ratio, e.g. `"1:1"`. An alternative to {@link size}; pass one or the
+     * other. If both are passed the provider decides which to honor and typically
+     * surfaces a warning (see {@link MotifImageResult.warnings}).
+     */
     aspectRatio?: `${number}:${number}`;
-    /** Explicit pixel size, e.g. `"1024x1024"`. */
+    /**
+     * Explicit pixel size, e.g. `"1024x1024"`. An alternative to
+     * {@link aspectRatio}; pass one or the other. If both are passed the provider
+     * decides which to honor and typically surfaces a warning (see
+     * {@link MotifImageResult.warnings}).
+     */
     size?: `${number}x${number}`;
     /** Number of images to generate. */
     n?: number;
+    /** Seed for reproducible generation, where the provider supports it. */
+    seed?: number;
+    /** Abort signal to cancel the in-flight request. */
+    signal?: AbortSignal;
     /**
      * Provider-specific options, passed straight through to the underlying model
      * as body parameters. Outer key = provider name, inner key = option name.
+     * Values must be JSON-representable; a non-JSON value (undefined, function,
+     * bigint, symbol) makes the call fail with a `MotifError`.
      */
     providerOptions?: Record<string, Record<string, unknown>>;
 }
 /** Options for a multi-image edit (images in → image out), with an optional mask. */
 interface EditImageOptions {
-    /** Input images. Each is raw bytes, a base64 string, or a data URL. */
+    /**
+     * Input images. Each entry is raw bytes (`Uint8Array`) or a string. A string
+     * may be base64, a `data:` URL, OR a remote `http(s)://` URL. Remote URLs are
+     * FETCHED by the provider — and on some providers (e.g. OpenAI) that fetch
+     * happens from the local process running this SDK. Callers that accept
+     * untrusted URLs should fetch and validate the bytes themselves before
+     * passing them here (SSRF / local-network exposure otherwise).
+     */
     images: (Uint8Array | string)[];
     /** Natural-language edit instruction. */
     instruction: string;
-    /** Optional mask (bytes, base64, or data URL) constraining the edited region. */
+    /**
+     * Optional mask constraining the edited region. Same accepted forms as
+     * {@link EditImageOptions.images} (bytes, base64, `data:` URL, or a remote
+     * `http(s)://` URL that the provider fetches — see the images note on
+     * untrusted URLs). When multiple images are passed, the mask applies to
+     * `images[0]`.
+     */
     mask?: Uint8Array | string;
     /** Quality/latency tier. Ignored when `model` is set. */
     tier?: ImageTier;
@@ -106,6 +134,10 @@ interface EditImageOptions {
     provider?: ImageProviderId;
     /** Number of images to generate. */
     n?: number;
+    /** Seed for reproducible generation, where the provider supports it. */
+    seed?: number;
+    /** Abort signal to cancel the in-flight request. */
+    signal?: AbortSignal;
     /** Provider-specific options (see {@link GenerateImageOptions.providerOptions}). */
     providerOptions?: Record<string, Record<string, unknown>>;
 }
@@ -127,6 +159,56 @@ interface MotifImageResult {
     model: string;
     /** Provider correlation id, where the provider surfaces one. */
     requestId?: string;
+    /**
+     * Degraded-success warnings from the provider (a requested setting was
+     * ignored or adjusted — e.g. passing both `size` and `aspectRatio`). Each is a
+     * readable string. Omitted entirely when the provider returned none.
+     */
+    warnings?: readonly string[];
+}
+/**
+ * Picks the winning candidate for a {@link MotifImageClient.bestOfN} call.
+ *
+ * Receives the successful candidates (index-aligned to
+ * {@link BestOfNResult.candidates}) and the request context, and returns the
+ * chosen index (plus an optional human-readable reason). May be sync or async.
+ * The judge is caller-provided so the image layer stays decoupled from any text
+ * client — it pairs well with `@howells/ai`'s vision client, but that dependency
+ * is not required.
+ */
+type ImageJudge = (candidates: readonly MotifImageResult[], context: {
+    readonly prompt?: string;
+    readonly instruction?: string;
+}) => Promise<{
+    index: number;
+    reason?: string;
+}> | {
+    index: number;
+    reason?: string;
+};
+/**
+ * Options for a best-of-N generation. Extends either {@link GenerateImageOptions}
+ * (text→image) or {@link EditImageOptions} (multi-image edit) — the presence of
+ * `images` selects the edit path — with the candidate count and an optional judge.
+ */
+type BestOfNOptions = (GenerateImageOptions | EditImageOptions) & {
+    /** How many candidates to generate (>= 1). */
+    n: number;
+    /** Chooses the winner. Omit → candidate 0 wins. */
+    judge?: ImageJudge;
+};
+/** Result of a {@link MotifImageClient.bestOfN} call. */
+interface BestOfNResult {
+    /** The winning candidate (its single-image {@link MotifImageResult}). */
+    best: MotifImageResult;
+    /** The index of `best` within `candidates`. */
+    chosenIndex: number;
+    /** Judge's rationale, if it returned one. */
+    reason?: string;
+    /** All successful candidates, in generation order. */
+    candidates: readonly MotifImageResult[];
+    /** Total USD across all candidates that were generated (successes only). */
+    totalCostUsd: number;
 }
 /** The provider-agnostic image client. Every method returns a Result — no throws. */
 interface MotifImageClient {
@@ -134,6 +216,30 @@ interface MotifImageClient {
     generate: (opts: GenerateImageOptions) => Promise<Result<MotifImageResult, MotifError>>;
     /** Multi-image edit (with optional mask). */
     edit: (opts: EditImageOptions) => Promise<Result<MotifImageResult, MotifError>>;
+    /**
+     * Generate N candidates (in parallel) and pick the best via an optional
+     * injectable judge. Discriminates generate vs edit by the presence of
+     * `images`. Returns the winner plus all successful candidates and total spend.
+     */
+    bestOfN: (opts: BestOfNOptions) => Promise<Result<BestOfNResult, MotifError>>;
+}
+
+/**
+ * Internal dependency-injection seam for the image layer.
+ *
+ * These types are INTERNAL: they are consumed by `createMotifImage`'s `deps`
+ * parameter and by the offline tests, but they are deliberately NOT re-exported
+ * from the public `@howells/motif-sdk/image` subpath, so they never appear in
+ * `dist/image.d.ts`. Import them from `./deps` inside the package (and from
+ * `../src/image/deps` in tests).
+ */
+
+/** A model resolver: builds an AI SDK `ImageModel` for a (provider, model, key). */
+type ResolveImageModel = (provider: ImageProviderId, modelId: string, apiKey?: string) => ImageModel;
+/** Internal dependency-injection seam (default: real `generateImage` + adapters). */
+interface MotifImageDeps {
+    generateImage?: typeof generateImage;
+    resolveModel?: ResolveImageModel;
 }
 
 /**
@@ -164,7 +270,18 @@ interface ImageProviderAdapter {
      * network I/O.
      */
     readonly resolveModel: (modelId: string, apiKey?: string) => ImageModel;
-    /** Static per-model USD/image table (best-effort; cited per adapter). */
+    /**
+     * Static per-model USD/**image** table (best-effort; cited per adapter). This
+     * is multiplied by the returned image count to form the call total.
+     *
+     * Cost contract: if an adapter instead surfaces a cost on
+     * `result.providerMetadata` (the preferred source; see
+     * {@link costFromProviderMetadata}), that value MUST already be the **call
+     * total** across all `n` images — NOT a per-image figure. `priceUsdByModel`
+     * is per-image; `providerMetadata.cost` is the whole call. These two paths
+     * intentionally differ, so an adapter must not populate a per-image number
+     * into `providerMetadata.cost`.
+     */
     readonly priceUsdByModel: Readonly<Record<string, number>>;
 }
 /**
@@ -297,13 +414,6 @@ declare function costForImages(provider: ImageProviderId, modelId: string, provi
  * ```
  */
 
-/** A model resolver: builds an AI SDK `ImageModel` for a (provider, model, key). */
-type ResolveImageModel = (provider: ImageProviderId, modelId: string, apiKey?: string) => ImageModel;
-/** Internal dependency-injection seam (default: real `generateImage` + adapters). */
-interface MotifImageDeps {
-    generateImage?: typeof generateImage;
-    resolveModel?: ResolveImageModel;
-}
 /**
  * Create a provider-agnostic image client.
  *
@@ -313,4 +423,4 @@ interface MotifImageDeps {
  */
 declare function createMotifImage(config?: MotifImageConfig, deps?: MotifImageDeps): MotifImageClient;
 
-export { type EditImageOptions, FAL_API_KEY_ENV, FAL_TIER_MODELS, GOOGLE_API_KEY_ENV, GOOGLE_TIER_MODELS, type GenerateImageOptions, type ImageCost, type ImageCostSource, type ImageProviderAdapter, type ImageProviderId, type ImageTier, type MotifImageClient, type MotifImageConfig, type MotifImageDeps, type MotifImageFile, type MotifImageResult, OPENAI_API_KEY_ENV, OPENAI_TIER_MODELS, PROVIDERS, REPLICATE_API_KEY_ENV, REPLICATE_TIER_MODELS, type ResolveImageModel, costForImages, costFromProviderMetadata, createMotifImage, getProviderAdapter };
+export { type BestOfNOptions, type BestOfNResult, type EditImageOptions, FAL_API_KEY_ENV, FAL_TIER_MODELS, GOOGLE_API_KEY_ENV, GOOGLE_TIER_MODELS, type GenerateImageOptions, type ImageCost, type ImageCostSource, type ImageJudge, type ImageProviderAdapter, type ImageProviderId, type ImageTier, type MotifImageClient, type MotifImageConfig, type MotifImageFile, type MotifImageResult, OPENAI_API_KEY_ENV, OPENAI_TIER_MODELS, PROVIDERS, REPLICATE_API_KEY_ENV, REPLICATE_TIER_MODELS, costForImages, costFromProviderMetadata, createMotifImage, getProviderAdapter };

package/dist/image.js

@@ -1503,6 +1503,8 @@ function createMotifImage(config = {}, deps = {}) {
         ...opts.n === void 0 ? {} : { n: opts.n },
         ...opts.size === void 0 ? {} : { size: opts.size },
         ...opts.aspectRatio === void 0 ? {} : { aspectRatio: opts.aspectRatio },
+        ...opts.seed === void 0 ? {} : { seed: opts.seed },
+        ...opts.signal === void 0 ? {} : { abortSignal: opts.signal },
         ...opts.providerOptions === void 0 ? {} : { providerOptions: toProviderOptions(opts.providerOptions) }
       });
       return ok2(toMotifImageResult(result, provider, modelId));
@@ -1523,6 +1525,8 @@ function createMotifImage(config = {}, deps = {}) {
           ...opts.mask === void 0 ? {} : { mask: opts.mask }
         },
         ...opts.n === void 0 ? {} : { n: opts.n },
+        ...opts.seed === void 0 ? {} : { seed: opts.seed },
+        ...opts.signal === void 0 ? {} : { abortSignal: opts.signal },
         ...opts.providerOptions === void 0 ? {} : { providerOptions: toProviderOptions(opts.providerOptions) }
       });
       return ok2(toMotifImageResult(result, provider, modelId));
@@ -1530,7 +1534,91 @@ function createMotifImage(config = {}, deps = {}) {
       return err2(toMotifError(error));
     }
   }
-  return { generate, edit };
+  async function bestOfN(opts) {
+    return await runBestOfN(opts, generate, edit);
+  }
+  return { generate, edit, bestOfN };
+}
+async function runCandidate(opts, index, generate, edit) {
+  const candidateSeed = opts.seed === void 0 ? void 0 : opts.seed + index;
+  const overrides = {
+    n: 1,
+    ...candidateSeed === void 0 ? {} : { seed: candidateSeed }
+  };
+  if ("images" in opts) {
+    return await edit({ ...opts, ...overrides });
+  }
+  return await generate({ ...opts, ...overrides });
+}
+async function selectWinner(opts, candidates) {
+  const { judge } = opts;
+  if (judge === void 0) {
+    return ok2({ chosenIndex: 0 });
+  }
+  const context = "images" in opts ? { instruction: opts.instruction } : { prompt: opts.prompt };
+  const decision = await judge(candidates, context);
+  if (!Number.isInteger(decision.index) || decision.index < 0 || decision.index >= candidates.length) {
+    return err2(
+      new MotifError(
+        `bestOfN judge returned an out-of-range index ${decision.index} (expected 0..${candidates.length - 1})`,
+        0
+      )
+    );
+  }
+  return ok2({
+    chosenIndex: decision.index,
+    ...decision.reason === void 0 ? {} : { reason: decision.reason }
+  });
+}
+async function runBestOfN(opts, generate, edit) {
+  try {
+    const { n } = opts;
+    if (!Number.isInteger(n) || n < 1) {
+      return err2(
+        new MotifError(`bestOfN requires an integer n >= 1 (got ${n})`, 0)
+      );
+    }
+    const results = await Promise.all(
+      Array.from({ length: n }, (_unused, index) => index).map(
+        async (index) => await runCandidate(opts, index, generate, edit)
+      )
+    );
+    const candidates = [];
+    let firstError;
+    for (const result of results) {
+      if (result.isOk()) {
+        candidates.push(result.value);
+      } else {
+        firstError ??= result.error;
+      }
+    }
+    if (candidates.length === 0) {
+      return err2(
+        firstError ?? new MotifError(`all ${n} bestOfN candidates failed`, 0)
+      );
+    }
+    const winner = await selectWinner(opts, candidates);
+    if (winner.isErr()) {
+      return err2(winner.error);
+    }
+    const { chosenIndex, reason } = winner.value;
+    const best = candidates[chosenIndex];
+    if (best === void 0) {
+      return err2(new MotifError("bestOfN failed to resolve a winner", 0));
+    }
+    const totalCostUsd = Number(
+      candidates.reduce((sum, candidate) => sum + candidate.cost.usd, 0).toFixed(6)
+    );
+    return ok2({
+      best,
+      chosenIndex,
+      ...reason === void 0 ? {} : { reason },
+      candidates,
+      totalCostUsd
+    });
+  } catch (error) {
+    return err2(toMotifError(error));
+  }
 }
 function defaultResolveModel(provider, modelId, apiKey) {
   return getProviderAdapter(provider).resolveModel(modelId, apiKey);
@@ -1555,14 +1643,26 @@ function toMotifImageResult(result, provider, model) {
     images.length
   );
   const requestId = extractRequestId(result);
+  const warnings = result.warnings.map(renderWarning);
   return {
     images,
     cost,
     provider,
     model,
-    ...requestId === void 0 ? {} : { requestId }
+    ...requestId === void 0 ? {} : { requestId },
+    ...warnings.length === 0 ? {} : { warnings }
   };
 }
+function renderWarning(warning) {
+  if (warning.type === "unsupported" || warning.type === "compatibility") {
+    const label = warning.type === "unsupported" ? "unsupported feature" : "compatibility mode for feature";
+    return warning.details === void 0 ? `${label} "${warning.feature}"` : `${label} "${warning.feature}": ${warning.details}`;
+  }
+  if (warning.type === "deprecated") {
+    return `deprecated setting "${warning.setting}": ${warning.message}`;
+  }
+  return warning.message;
+}
 function isRecord3(value) {
   return typeof value === "object" && value !== null;
 }
@@ -1601,13 +1701,13 @@ function toProviderOptions(input) {
   for (const [namespace, options] of Object.entries(input)) {
     const inner = {};
     for (const [key, value] of Object.entries(options)) {
-      inner[key] = toJsonValue(value);
+      inner[key] = toJsonValue(value, `providerOptions.${namespace}.${key}`);
     }
     out[namespace] = inner;
   }
   return out;
 }
-function toJsonValue(value) {
+function toJsonValue(value, path) {
   if (value === null) {
     return null;
   }
@@ -1617,18 +1717,21 @@ function toJsonValue(value) {
   if (typeof value === "object") {
     if (Array.isArray(value)) {
       const arr = [];
-      for (const item of value) {
-        arr.push(toJsonValue(item));
+      for (const [index, item] of value.entries()) {
+        arr.push(toJsonValue(item, `${path}[${index}]`));
       }
       return arr;
     }
     const obj = {};
     for (const [key, entry] of Object.entries(value)) {
-      obj[key] = toJsonValue(entry);
+      obj[key] = toJsonValue(entry, `${path}.${key}`);
     }
     return obj;
   }
-  return null;
+  throw new MotifError(
+    `providerOptions value at ${path} is not JSON-representable (type: ${typeof value})`,
+    0
+  );
 }
 function toMotifError(error) {
   if (error instanceof MotifError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/motif-sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Public Node SDK for Motif fal.ai generation, editing, utility tools, and model metadata.",
   "keywords": [
     "fal",
@@ -61,8 +61,8 @@
     "vitest": "^4.1.10"
   },
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
+    "dev": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsup --watch",
     "lint": "howells-check .",
     "lint:fix": "howells-fix .",
     "typecheck": "tsc --noEmit",