@howells/motif-sdk 0.9.0 → 0.11.0

package/README.md

@@ -172,6 +172,34 @@ Four providers are implemented, each reading its own API key from the environmen
 
 `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

@@ -97,6 +97,12 @@ interface GenerateImageOptions {
     seed?: number;
     /** Abort signal to cancel the in-flight request. */
     signal?: AbortSignal;
+    /**
+     * Extra HTTP headers forwarded to the provider request. Fal's non-retained IO
+     * (paired with FalClient.deletePayloads) is
+     * `headers: { "X-Fal-Store-IO": "0" }`.
+     */
+    headers?: Record<string, string>;
     /**
      * Provider-specific options, passed straight through to the underlying model
      * as body parameters. Outer key = provider name, inner key = option name.
@@ -138,6 +144,12 @@ interface EditImageOptions {
     seed?: number;
     /** Abort signal to cancel the in-flight request. */
     signal?: AbortSignal;
+    /**
+     * Extra HTTP headers forwarded to the provider request. Fal's non-retained IO
+     * (paired with FalClient.deletePayloads) is
+     * `headers: { "X-Fal-Store-IO": "0" }`.
+     */
+    headers?: Record<string, string>;
     /** Provider-specific options (see {@link GenerateImageOptions.providerOptions}). */
     providerOptions?: Record<string, Record<string, unknown>>;
 }
@@ -166,12 +178,62 @@ interface MotifImageResult {
      */
     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 {
     /** Text→image generation. */
     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>>;
 }
 
 /**
@@ -318,7 +380,11 @@ declare const REPLICATE_API_KEY_ENV = "REPLICATE_API_TOKEN";
  *   });
  */
 
-/** Tier → fal model id. */
+/**
+ * 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).
+ */
 declare const FAL_TIER_MODELS: Readonly<Record<ImageTier, string>>;
 /** Env var read for the fal key when `apiKey` is not supplied in config. */
 declare const FAL_API_KEY_ENV = "FAL_KEY";
@@ -373,4 +439,4 @@ declare function costForImages(provider: ImageProviderId, modelId: string, provi
  */
 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 MotifImageFile, type MotifImageResult, OPENAI_API_KEY_ENV, OPENAI_TIER_MODELS, PROVIDERS, REPLICATE_API_KEY_ENV, REPLICATE_TIER_MODELS, 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

@@ -1291,8 +1291,58 @@ var FAL_TIER_MODELS = {
 };
 var FAL_API_KEY_ENV = "FAL_KEY";
 var FAL_IMAGE_PRICE_USD = {
+  // FLUX family.
   [FAL_FLUX_MODEL]: MODELS.flux?.pricePerImageUsd ?? 0.06,
-  [FAL_GPT_IMAGE_MODEL]: MODELS.gpt?.pricePerImageUsd ?? 0.133
+  // MODELS.flux
+  "fal-ai/flux/schnell": MODELS["flux-fast"]?.pricePerImageUsd ?? 3e-3,
+  // MODELS["flux-fast"]
+  // FLUX.2 family.
+  "fal-ai/flux-2-max": MODELS["flux2-max"]?.pricePerImageUsd ?? 0.07,
+  // MODELS["flux2-max"]
+  "fal-ai/flux-2-pro": MODELS["flux2-pro"]?.pricePerImageUsd ?? 0.03,
+  // MODELS["flux2-pro"]
+  "fal-ai/flux-2-flex": MODELS["flux2-flex"]?.pricePerImageUsd ?? 0.05,
+  // MODELS["flux2-flex"]
+  "fal-ai/flux-2": MODELS["flux2-dev"]?.pricePerImageUsd ?? 0.012,
+  // MODELS["flux2-dev"]
+  "fal-ai/flux-2/turbo": MODELS["flux2-turbo"]?.pricePerImageUsd ?? 8e-3,
+  // MODELS["flux2-turbo"]
+  // gpt-image (fal adds overhead vs OpenAI-direct — see design doc §10).
+  [FAL_GPT_IMAGE_MODEL]: MODELS.gpt?.pricePerImageUsd ?? 0.133,
+  // MODELS.gpt
+  "openai/gpt-image-2": MODELS.gpt2?.pricePerImageUsd ?? 0.211,
+  // MODELS.gpt2
+  // Nano Banana (Gemini image) family.
+  "fal-ai/nano-banana-2": MODELS.banana2?.pricePerImageUsd ?? 0.08,
+  // MODELS.banana2
+  "fal-ai/nano-banana-pro": MODELS.banana?.pricePerImageUsd ?? 0.15,
+  // MODELS.banana
+  "fal-ai/gemini-25-flash-image": MODELS.gemini?.pricePerImageUsd ?? 0.0398,
+  // MODELS.gemini
+  "fal-ai/gemini-3-pro-image-preview": MODELS.gemini3?.pricePerImageUsd ?? 0.15,
+  // MODELS.gemini3
+  // Seedream family.
+  "fal-ai/bytedance/seedream/v4/text-to-image": MODELS.seedream4?.pricePerImageUsd ?? 0.03,
+  // MODELS.seedream4
+  "fal-ai/bytedance/seedream/v4.5/text-to-image": MODELS.seedream45?.pricePerImageUsd ?? 0.04,
+  // MODELS.seedream45
+  "bytedance/seedream/v5/pro/text-to-image": MODELS.seedream5?.pricePerImageUsd ?? 0.0675,
+  // MODELS.seedream5
+  "fal-ai/bytedance/seedream/v5/lite/text-to-image": MODELS["seedream5-lite"]?.pricePerImageUsd ?? 0.035,
+  // MODELS["seedream5-lite"]
+  // Other priced fal generation endpoints.
+  "fal-ai/recraft-v3": MODELS.recraft?.pricePerImageUsd ?? 0.04,
+  // MODELS.recraft
+  "fal-ai/recraft/v4/text-to-image": MODELS.recraft4?.pricePerImageUsd ?? 0.04,
+  // MODELS.recraft4
+  "fal-ai/ideogram/v3": MODELS.ideogram?.pricePerImageUsd ?? 0.03,
+  // MODELS.ideogram
+  "ideogram/v4": MODELS.ideogram4?.pricePerImageUsd ?? 0.03,
+  // MODELS.ideogram4
+  "xai/grok-imagine-image": MODELS["grok-image"]?.pricePerImageUsd ?? 0.02,
+  // MODELS["grok-image"]
+  "fal-ai/qwen-image": MODELS.qwen?.pricePerImageUsd ?? 0.02
+  // MODELS.qwen
 };
 function resolveModel(modelId, apiKey) {
   const key = apiKey ?? process.env[FAL_API_KEY_ENV];
@@ -1505,6 +1555,7 @@ function createMotifImage(config = {}, deps = {}) {
         ...opts.aspectRatio === void 0 ? {} : { aspectRatio: opts.aspectRatio },
         ...opts.seed === void 0 ? {} : { seed: opts.seed },
         ...opts.signal === void 0 ? {} : { abortSignal: opts.signal },
+        ...opts.headers === void 0 ? {} : { headers: opts.headers },
         ...opts.providerOptions === void 0 ? {} : { providerOptions: toProviderOptions(opts.providerOptions) }
       });
       return ok2(toMotifImageResult(result, provider, modelId));
@@ -1527,6 +1578,7 @@ function createMotifImage(config = {}, deps = {}) {
         ...opts.n === void 0 ? {} : { n: opts.n },
         ...opts.seed === void 0 ? {} : { seed: opts.seed },
         ...opts.signal === void 0 ? {} : { abortSignal: opts.signal },
+        ...opts.headers === void 0 ? {} : { headers: opts.headers },
         ...opts.providerOptions === void 0 ? {} : { providerOptions: toProviderOptions(opts.providerOptions) }
       });
       return ok2(toMotifImageResult(result, provider, modelId));
@@ -1534,7 +1586,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);
@@ -1655,7 +1791,8 @@ function toMotifError(error) {
   }
   const message = error instanceof Error ? error.message : String(error);
   const code = error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : void 0;
-  return new MotifError(message, 0, code);
+  const status = error instanceof Error && "statusCode" in error && typeof error.statusCode === "number" ? error.statusCode : 0;
+  return new MotifError(message, status, code);
 }
 export {
   FAL_API_KEY_ENV,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/motif-sdk",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Public Node SDK for Motif fal.ai generation, editing, utility tools, and model metadata.",
   "keywords": [
     "fal",