@howells/motif-sdk 6.0.0 → 7.1.0

package/dist/index.d.cts

@@ -1,6 +1,18 @@
+/**
+ * Motif SDK: task-first image work over fal.ai.
+ *
+ * Callers name a task and a tier; Motif picks the model. The per-model registry
+ * and the fal client stay internal.
+ *
+ * @example
+ * ```typescript
+ * import { createMotif } from "@howells/motif-sdk";
+ *
+ * const motif = createMotif();
+ * ```
+ */
 import { Result, Result as Result$1, ResultAsync, err, ok } from "neverthrow";
 import { z } from "zod";
-//#region src/creative.d.ts
 /**
  * Creative direction fields applied to prompts in Motif's canonical order.
  *
@@ -117,7 +129,7 @@ export declare const CREATIVE_TAXONOMY: {
     readonly description: "Natural, unposed documentary portraits of people. Pair with a mood for the light.";
     readonly id: "portrait";
     readonly label: "Documentary portrait";
-    readonly model: "seedream45";
+    readonly model: "seedream5";
   }, {
     readonly acceptsMood: false;
     readonly aspect: "1:1";
@@ -241,8 +253,6 @@ export declare function validateCreativeDirection(creative: CreativeDirection |
  * are joined with `". "` and closed with a period. With no clauses the sanitized prompt is returned unchanged.
  */
 export declare function enrichPrompt(options: EnrichPromptOptions): CreativePromptResult;
-//#endregion
-//#region src/types.d.ts
 /** ─── Model Types ─────────────────────────────────────────────── */
 type AspectRatio = "auto" | "8:1" | "4:1" | "21:9" | "16:9" | "3:2" | "4:3" | "5:4" | "1:1" | "4:5" | "3:4" | "2:3" | "9:16" | "1:4" | "1:8";
 type Resolution = "0.5K" | "1K" | "2K" | "4K";
@@ -275,8 +285,6 @@ interface JobStatus {
 /** ─── Configuration ──────────────────────────────────────────── */
 /** The network seam: a `fetch`-shaped function. */
 type FalFetch = (url: string, init: RequestInit) => Promise<Response>;
-//#endregion
-//#region src/aspects.d.ts
 /** Ordered by popularity: square first, then common ratios */
 export declare const ASPECT_RATIOS: AspectRatio[];
 export declare const RESOLUTIONS: Resolution[];
@@ -296,8 +304,6 @@ export declare const FORMAT_PRESETS: Record<string, {
   aspect: AspectRatio;
   resolution?: Resolution;
 }>;
-//#endregion
-//#region src/errors.d.ts
 /**
  * `MotifError` and its coercion helper.
  *
@@ -325,8 +331,6 @@ export declare const ACCOUNT_LOCKED = "ACCOUNT_LOCKED";
  * account has run out of credit. Retrying cannot help, and the key is valid.
  */
 export declare function isFalAccountLocked(status: number, body: string): boolean;
-//#endregion
-//#region src/image-benchmarks.d.ts
 /**
  * Arena image scores captured for MOT-72 on October 29, 2026. Flare and
  * Sunburst route to GPT Image 2.6 but keep 2.5's scores until 2.6 is
@@ -340,6 +344,8 @@ interface ArenaScore {
   readonly uncertainty: number;
   /** Exact leaderboard label, including a setting where one was reported. */
   readonly evaluatedModel: string;
+  /** Set when the score was measured on a different version than Motif runs. */
+  readonly note?: string;
   readonly preliminary?: true;
   readonly votes?: number;
 }
@@ -349,8 +355,6 @@ interface ImageModelBenchmark extends ArenaScore {
   readonly snapshotDate: string;
   readonly task: ImageBenchmarkTask;
 }
-//#endregion
-//#region src/tasks.d.ts
 export declare const TIERS: readonly ["fast", "balanced", "quality"];
 /** How far a Task trades cost and speed for quality. */
 type Tier = (typeof TIERS)[number];
@@ -533,7 +537,7 @@ export declare const TASKS: {
     readonly summary: "Remove an object, person, text or clutter from an image and fill the gap.";
   };
   readonly generate: {
-    readonly basis: "Order follows Arena text-to-image (https://arena.ai/leaderboard/image/text-to-image), read 2026-10-29 (MOT-72). Sunburst and Flare lead quality at the benchmarked max setting. Balanced starts with Nano Banana 2.1 on preliminary Arena evidence, then Grok Image 2 and Muse Image. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Fast keeps Nano Banana 2 Lite, budget Grok and Seedream 5 Lite, and FLUX.2 Turbo. Design, transparency and tuned Look routes are capability exceptions. Generation with References uses the separate editing ranking. Older routes are explicit/pin/Look-only.";
+    readonly basis: "Order follows Arena text-to-image (https://arena.ai/leaderboard/image/text-to-image), read 2026-10-29. Sunburst and Flare lead quality at the benchmarked max setting. Balanced starts with Nano Banana 2.1 on preliminary Arena evidence, then Grok Image 2 and Muse Image. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Fast keeps Nano Banana 2 Lite, budget Grok and Seedream 5 Lite, and FLUX.2 Turbo. Design, transparency and tuned Look routes are capability exceptions. Generation with References uses the separate editing ranking. Older routes are explicit/pin/Look-only.";
     readonly models: readonly RankedModel[];
     readonly notFor: "Variations of an image you already have (vary), or a consistent set of images (series run).";
     readonly rankedAt: "2026-10-29";
@@ -946,7 +950,7 @@ export declare const TASKS: {
     readonly summary: "Trace a raster image to a clean SVG.";
   };
   readonly vary: {
-    readonly basis: "Order follows Arena image edit, single image (https://arena.ai/leaderboard/image/image-edit/single-image), read 2026-10-29 (MOT-72). Editing order differs from generation: Grok Image 2 leads balanced, ahead of Nano Banana 2.1, and Seedream 5 Pro outranks GPT Image 1.5. Arena scores Krea 3 only at its Ultra setting, which costs $0.27 to $0.35 an edit and ignores the requested size, so krea3, which runs fal's default setting, is ranked as unscored. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Sunburst and Flare use max quality. vary reuses a previously chosen Model when explicitly supplied, including retained legacy routes.";
+    readonly basis: "Order follows Arena image edit, single image (https://arena.ai/leaderboard/image/image-edit/single-image), read 2026-10-29. Editing order differs from generation: Grok Image 2 leads balanced, ahead of Nano Banana 2.1, and Seedream 5 Pro outranks GPT Image 1.5. Arena scores Krea 3 only at its Ultra setting, which costs $0.27 to $0.35 an edit and ignores the requested size, so krea3, which runs fal's default setting, is ranked as unscored. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Sunburst and Flare use max quality. vary reuses a previously chosen Model when explicitly supplied, including retained legacy routes.";
     readonly models: readonly RankedModel[];
     readonly notFor: "A specific change to an image described in words (generate with a reference), or a set of different scenes in one style (series run).";
     readonly rankedAt: "2026-10-29";
@@ -958,8 +962,6 @@ export declare const TASKS: {
 type TaskId = keyof typeof TASKS;
 export declare const TASK_IDS: readonly TaskId[];
 export declare function isTaskId(value: string): value is TaskId;
-//#endregion
-//#region src/resolve.d.ts
 /** What the request needs. Only the fields that narrow the choice. */
 interface TaskRequest {
   /** Explicit Model id, e.g. from `--model`. Overrides everything. */
@@ -1029,6 +1031,8 @@ interface TaskUnresolved {
 }
 type TaskResolution = TaskResolved | TaskUnresolved;
 interface ModelProfile {
+  /** The Model's display name, e.g. "GPT Image 2.6 Sunburst". */
+  readonly name: string;
   readonly capabilities: ReadonlySet<Capability>;
   /** Key variables the Model needs for any request. */
   readonly keys: readonly string[];
@@ -1059,8 +1063,6 @@ export declare function resolveTask(task: TaskId, request: TaskRequest, environm
  * nothing there.
  */
 export declare function tierChangesChoice(task: TaskId, request: Omit<TaskRequest, "tier">, environment: TaskEnvironment): boolean;
-//#endregion
-//#region src/task-stream.d.ts
 interface TaskStreamOptions {
   signal?: AbortSignal;
   /** Overall deadline covering connection and consumption, in milliseconds. */
@@ -1091,8 +1093,6 @@ interface TaskStream {
   /** Stops local consumption; does not guarantee provider cancellation or refund. */
   abort: () => void;
 }
-//#endregion
-//#region src/tool-cost.d.ts
 /** Pixel dimensions of one file an endpoint returned. */
 interface OutputDimensions {
   height?: number;
@@ -1133,8 +1133,6 @@ export declare function sumCosts(costs: readonly (number | null)[]): {
   known: number;
   unknown: number;
 };
-//#endregion
-//#region src/task-client.d.ts
 interface MotifClientConfig {
   /** Falls back to FAL_KEY. */
   falKey?: string;
@@ -1309,11 +1307,7 @@ interface MotifClient {
 }
 /** Create the Task client. The key falls back to FAL_KEY. */
 export declare function createMotif(config?: MotifClientConfig): MotifClient;
-//#endregion
-//#region src/task-plan-shared.d.ts
 export declare const INVALID_OPTION = "INVALID_OPTION";
-//#endregion
-//#region src/prompt-warnings.d.ts
 /**
  * Advisory checks on a user-written prompt.
  *
@@ -1348,8 +1342,6 @@ interface PromptWarning {
 export declare function promptWarnings(prompt: string, context?: {
   editing?: boolean;
 }): PromptWarning[];
-//#endregion
-//#region src/env.d.ts
 export declare const motifEnvSchema: import("@howells/envy").EnvSchema<{
   readonly optional: {
     FAL_KEY: z.ZodString;
@@ -1358,5 +1350,4 @@ export declare const motifEnvSchema: import("@howells/envy").EnvSchema<{
 type MotifEnv = ReturnType<typeof motifEnvSchema.parse>;
 export declare function parseMotifEnv(input?: Record<string, unknown>): MotifEnv;
 export declare function getFalKeyFromEnv(input?: Record<string, unknown>): string | undefined;
-//#endregion
 export { type AspectRatio, type Blocker, type Capability, type ChosenBy, type CreativeDirection, type CreativeField, type CreativeOption, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, type EnrichPromptOptions, type FalFetch, type ImageSizeBounds, type LookId, type LookOption, type ModelProfile, type MoodId, type MotifClient, type MotifClientConfig, type MotifEnv, type OutputDimensions, type PlanOptions, type PromptWarning, type PromptWarningRule, type RankedFrom, type RankedModel, type Resolution, type ResolvedCost, type Result, type ResultAsync, type TaskDefinition, type TaskEnvironment, type TaskFile, type TaskFunction, type TaskId, type TaskInput, type TaskMode, type TaskOutput, type TaskPlan, type TaskRequest, type TaskResolution, type TaskResolved, type TaskStream, type TaskStreamEvent, type TaskStreamOptions, type TaskUnresolved, type Tier, type Unblocker, err, ok };

package/dist/index.d.ts

@@ -1,6 +1,18 @@
+/**
+ * Motif SDK: task-first image work over fal.ai.
+ *
+ * Callers name a task and a tier; Motif picks the model. The per-model registry
+ * and the fal client stay internal.
+ *
+ * @example
+ * ```typescript
+ * import { createMotif } from "@howells/motif-sdk";
+ *
+ * const motif = createMotif();
+ * ```
+ */
 import { Result, Result as Result$1, ResultAsync, err, ok } from "neverthrow";
 import { z } from "zod";
-//#region src/creative.d.ts
 /**
  * Creative direction fields applied to prompts in Motif's canonical order.
  *
@@ -117,7 +129,7 @@ export declare const CREATIVE_TAXONOMY: {
     readonly description: "Natural, unposed documentary portraits of people. Pair with a mood for the light.";
     readonly id: "portrait";
     readonly label: "Documentary portrait";
-    readonly model: "seedream45";
+    readonly model: "seedream5";
   }, {
     readonly acceptsMood: false;
     readonly aspect: "1:1";
@@ -241,8 +253,6 @@ export declare function validateCreativeDirection(creative: CreativeDirection |
  * are joined with `". "` and closed with a period. With no clauses the sanitized prompt is returned unchanged.
  */
 export declare function enrichPrompt(options: EnrichPromptOptions): CreativePromptResult;
-//#endregion
-//#region src/types.d.ts
 /** ─── Model Types ─────────────────────────────────────────────── */
 type AspectRatio = "auto" | "8:1" | "4:1" | "21:9" | "16:9" | "3:2" | "4:3" | "5:4" | "1:1" | "4:5" | "3:4" | "2:3" | "9:16" | "1:4" | "1:8";
 type Resolution = "0.5K" | "1K" | "2K" | "4K";
@@ -275,8 +285,6 @@ interface JobStatus {
 /** ─── Configuration ──────────────────────────────────────────── */
 /** The network seam: a `fetch`-shaped function. */
 type FalFetch = (url: string, init: RequestInit) => Promise<Response>;
-//#endregion
-//#region src/aspects.d.ts
 /** Ordered by popularity: square first, then common ratios */
 export declare const ASPECT_RATIOS: AspectRatio[];
 export declare const RESOLUTIONS: Resolution[];
@@ -296,8 +304,6 @@ export declare const FORMAT_PRESETS: Record<string, {
   aspect: AspectRatio;
   resolution?: Resolution;
 }>;
-//#endregion
-//#region src/errors.d.ts
 /**
  * `MotifError` and its coercion helper.
  *
@@ -325,8 +331,6 @@ export declare const ACCOUNT_LOCKED = "ACCOUNT_LOCKED";
  * account has run out of credit. Retrying cannot help, and the key is valid.
  */
 export declare function isFalAccountLocked(status: number, body: string): boolean;
-//#endregion
-//#region src/image-benchmarks.d.ts
 /**
  * Arena image scores captured for MOT-72 on October 29, 2026. Flare and
  * Sunburst route to GPT Image 2.6 but keep 2.5's scores until 2.6 is
@@ -340,6 +344,8 @@ interface ArenaScore {
   readonly uncertainty: number;
   /** Exact leaderboard label, including a setting where one was reported. */
   readonly evaluatedModel: string;
+  /** Set when the score was measured on a different version than Motif runs. */
+  readonly note?: string;
   readonly preliminary?: true;
   readonly votes?: number;
 }
@@ -349,8 +355,6 @@ interface ImageModelBenchmark extends ArenaScore {
   readonly snapshotDate: string;
   readonly task: ImageBenchmarkTask;
 }
-//#endregion
-//#region src/tasks.d.ts
 export declare const TIERS: readonly ["fast", "balanced", "quality"];
 /** How far a Task trades cost and speed for quality. */
 type Tier = (typeof TIERS)[number];
@@ -533,7 +537,7 @@ export declare const TASKS: {
     readonly summary: "Remove an object, person, text or clutter from an image and fill the gap.";
   };
   readonly generate: {
-    readonly basis: "Order follows Arena text-to-image (https://arena.ai/leaderboard/image/text-to-image), read 2026-10-29 (MOT-72). Sunburst and Flare lead quality at the benchmarked max setting. Balanced starts with Nano Banana 2.1 on preliminary Arena evidence, then Grok Image 2 and Muse Image. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Fast keeps Nano Banana 2 Lite, budget Grok and Seedream 5 Lite, and FLUX.2 Turbo. Design, transparency and tuned Look routes are capability exceptions. Generation with References uses the separate editing ranking. Older routes are explicit/pin/Look-only.";
+    readonly basis: "Order follows Arena text-to-image (https://arena.ai/leaderboard/image/text-to-image), read 2026-10-29. Sunburst and Flare lead quality at the benchmarked max setting. Balanced starts with Nano Banana 2.1 on preliminary Arena evidence, then Grok Image 2 and Muse Image. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Fast keeps Nano Banana 2 Lite, budget Grok and Seedream 5 Lite, and FLUX.2 Turbo. Design, transparency and tuned Look routes are capability exceptions. Generation with References uses the separate editing ranking. Older routes are explicit/pin/Look-only.";
     readonly models: readonly RankedModel[];
     readonly notFor: "Variations of an image you already have (vary), or a consistent set of images (series run).";
     readonly rankedAt: "2026-10-29";
@@ -946,7 +950,7 @@ export declare const TASKS: {
     readonly summary: "Trace a raster image to a clean SVG.";
   };
   readonly vary: {
-    readonly basis: "Order follows Arena image edit, single image (https://arena.ai/leaderboard/image/image-edit/single-image), read 2026-10-29 (MOT-72). Editing order differs from generation: Grok Image 2 leads balanced, ahead of Nano Banana 2.1, and Seedream 5 Pro outranks GPT Image 1.5. Arena scores Krea 3 only at its Ultra setting, which costs $0.27 to $0.35 an edit and ignores the requested size, so krea3, which runs fal's default setting, is ranked as unscored. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Sunburst and Flare use max quality. vary reuses a previously chosen Model when explicitly supplied, including retained legacy routes.";
+    readonly basis: "Order follows Arena image edit, single image (https://arena.ai/leaderboard/image/image-edit/single-image), read 2026-10-29. Editing order differs from generation: Grok Image 2 leads balanced, ahead of Nano Banana 2.1, and Seedream 5 Pro outranks GPT Image 1.5. Arena scores Krea 3 only at its Ultra setting, which costs $0.27 to $0.35 an edit and ignores the requested size, so krea3, which runs fal's default setting, is ranked as unscored. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Sunburst and Flare use max quality. vary reuses a previously chosen Model when explicitly supplied, including retained legacy routes.";
     readonly models: readonly RankedModel[];
     readonly notFor: "A specific change to an image described in words (generate with a reference), or a set of different scenes in one style (series run).";
     readonly rankedAt: "2026-10-29";
@@ -958,8 +962,6 @@ export declare const TASKS: {
 type TaskId = keyof typeof TASKS;
 export declare const TASK_IDS: readonly TaskId[];
 export declare function isTaskId(value: string): value is TaskId;
-//#endregion
-//#region src/resolve.d.ts
 /** What the request needs. Only the fields that narrow the choice. */
 interface TaskRequest {
   /** Explicit Model id, e.g. from `--model`. Overrides everything. */
@@ -1029,6 +1031,8 @@ interface TaskUnresolved {
 }
 type TaskResolution = TaskResolved | TaskUnresolved;
 interface ModelProfile {
+  /** The Model's display name, e.g. "GPT Image 2.6 Sunburst". */
+  readonly name: string;
   readonly capabilities: ReadonlySet<Capability>;
   /** Key variables the Model needs for any request. */
   readonly keys: readonly string[];
@@ -1059,8 +1063,6 @@ export declare function resolveTask(task: TaskId, request: TaskRequest, environm
  * nothing there.
  */
 export declare function tierChangesChoice(task: TaskId, request: Omit<TaskRequest, "tier">, environment: TaskEnvironment): boolean;
-//#endregion
-//#region src/task-stream.d.ts
 interface TaskStreamOptions {
   signal?: AbortSignal;
   /** Overall deadline covering connection and consumption, in milliseconds. */
@@ -1091,8 +1093,6 @@ interface TaskStream {
   /** Stops local consumption; does not guarantee provider cancellation or refund. */
   abort: () => void;
 }
-//#endregion
-//#region src/tool-cost.d.ts
 /** Pixel dimensions of one file an endpoint returned. */
 interface OutputDimensions {
   height?: number;
@@ -1133,8 +1133,6 @@ export declare function sumCosts(costs: readonly (number | null)[]): {
   known: number;
   unknown: number;
 };
-//#endregion
-//#region src/task-client.d.ts
 interface MotifClientConfig {
   /** Falls back to FAL_KEY. */
   falKey?: string;
@@ -1309,11 +1307,7 @@ interface MotifClient {
 }
 /** Create the Task client. The key falls back to FAL_KEY. */
 export declare function createMotif(config?: MotifClientConfig): MotifClient;
-//#endregion
-//#region src/task-plan-shared.d.ts
 export declare const INVALID_OPTION = "INVALID_OPTION";
-//#endregion
-//#region src/prompt-warnings.d.ts
 /**
  * Advisory checks on a user-written prompt.
  *
@@ -1348,8 +1342,6 @@ interface PromptWarning {
 export declare function promptWarnings(prompt: string, context?: {
   editing?: boolean;
 }): PromptWarning[];
-//#endregion
-//#region src/env.d.ts
 export declare const motifEnvSchema: import("@howells/envy").EnvSchema<{
   readonly optional: {
     FAL_KEY: z.ZodString;
@@ -1358,5 +1350,4 @@ export declare const motifEnvSchema: import("@howells/envy").EnvSchema<{
 type MotifEnv = ReturnType<typeof motifEnvSchema.parse>;
 export declare function parseMotifEnv(input?: Record<string, unknown>): MotifEnv;
 export declare function getFalKeyFromEnv(input?: Record<string, unknown>): string | undefined;
-//#endregion
 export { type AspectRatio, type Blocker, type Capability, type ChosenBy, type CreativeDirection, type CreativeField, type CreativeOption, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, type EnrichPromptOptions, type FalFetch, type ImageSizeBounds, type LookId, type LookOption, type ModelProfile, type MoodId, type MotifClient, type MotifClientConfig, type MotifEnv, type OutputDimensions, type PlanOptions, type PromptWarning, type PromptWarningRule, type RankedFrom, type RankedModel, type Resolution, type ResolvedCost, type Result, type ResultAsync, type TaskDefinition, type TaskEnvironment, type TaskFile, type TaskFunction, type TaskId, type TaskInput, type TaskMode, type TaskOutput, type TaskPlan, type TaskRequest, type TaskResolution, type TaskResolved, type TaskStream, type TaskStreamEvent, type TaskStreamOptions, type TaskUnresolved, type Tier, type Unblocker, err, ok };