@howells/motif-sdk 0.9.0 → 0.10.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

@@ -166,12 +166,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>>;
 }
 
 /**
@@ -373,4 +423,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

@@ -1534,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);

package/package.json

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