@howells/motif-sdk 5.3.0 → 5.4.0

package/dist/index.d.cts

@@ -246,7 +246,8 @@ export declare function enrichPrompt(options: EnrichPromptOptions): CreativeProm
 /** ─── 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";
-type ImageOutputFormat = "jpeg" | "png" | "webp";
+/** `gif` is an animation and `svg` a vector image, on the Models that make them. */
+type ImageOutputFormat = "jpeg" | "png" | "webp" | "gif" | "svg";
 interface CustomImageSize {
   height: number;
   width: number;
@@ -325,25 +326,31 @@ export declare const ACCOUNT_LOCKED = "ACCOUNT_LOCKED";
  */
 export declare function isFalAccountLocked(status: number, body: string): boolean;
 //#endregion
-//#region src/tasks.d.ts
+//#region src/image-benchmarks.d.ts
 /**
- * The Task registry: every job Motif does, with the Models that can do it
- * ranked best-first and tagged with the Tier each belongs to.
- *
- * Rankings are data so a default change is visible in a pull request. A Task
- * ranked from the bench's human comparisons says `rankedFrom: "bench"`; every
- * other Task is hand-ranked from published quality numbers and fal price, and
- * says so. Today no Task is bench-ranked: the bench holds two human ratings,
- * both on one model, which is not an order.
- *
- * Model ids are the short aliases `-m` and `TaskInput.model` accept. `resolveTask` in `./resolve` is the only place a Model is
- * chosen from these lists.
- *
- * A Task can have modes: a variant of the job a caller names explicitly, such
- * as erasing text rather than an object. A ranked entry with a `mode` is only
- * chosen when the request names that mode; an entry without one only when it
- * names none. A Model can appear once per mode.
+ * 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
+ * benchmarked; `evaluatedModel` names what was measured.
  */
+type ImageBenchmarkTask = "text-to-image" | "image-edit-single-image";
+interface ArenaScore {
+  readonly elo: number;
+  readonly rank: number;
+  /** The reported plus-or-minus interval, in Elo points. */
+  readonly uncertainty: number;
+  /** Exact leaderboard label, including a setting where one was reported. */
+  readonly evaluatedModel: string;
+  readonly preliminary?: true;
+  readonly votes?: number;
+}
+/** Scores are comparable only on the same board and snapshot. */
+interface ImageModelBenchmark extends ArenaScore {
+  readonly source: string;
+  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];
@@ -351,12 +358,14 @@ export declare const DEFAULT_TIER: Tier;
 /** Where a Task's order came from. */
 type RankedFrom = "bench" | "hand";
 /** Something a request needs that not every Model can honour. */
-type Capability = "aspect" | "count" | "image" | "mask" | "negativePrompt" | "outputFormat" | "references" | "resolution" | "rig" | "seed" | "transparency" | "video";
+type Capability = "aspect" | "count" | "image" | "markup" | "mask" | "negativePrompt" | "outputFormat" | "references" | "resolution" | "rig" | "seed" | "transparency" | "video";
 interface RankedModel {
   /** A Model id, as accepted by `-m` or `TaskInput.model`. */
   readonly model: string;
   /** The Tier this Model is offered at. */
   readonly tier: Tier;
+  /** Published evidence for this Task; null means this route is unscored. */
+  readonly benchmark?: ImageModelBenchmark | null;
   /** The mode this entry serves. Absent for the Task's plain job. */
   readonly mode?: string;
   /** Capabilities this Model has for this Task beyond its registry profile. */
@@ -964,6 +973,8 @@ interface TaskRequest {
   readonly references?: number;
   /** A mask image is passed in. */
   readonly mask?: boolean;
+  /** A markup image is passed in. */
+  readonly markup?: boolean;
   /** An aspect ratio is asked for, e.g. `"3:2"`. */
   readonly aspect?: string;
   /** A resolution tier is asked for, e.g. `"1K"`. */
@@ -972,7 +983,8 @@ interface TaskRequest {
   readonly count?: number;
   readonly seed?: boolean;
   readonly negativePrompt?: boolean;
-  readonly outputFormat?: boolean;
+  /** An output format is asked for, e.g. `"gif"`. */
+  readonly outputFormat?: string;
   /** A rigged mesh wanted. */
   readonly rig?: boolean;
   /** The kind of Source passed in. Absent for a text-only request. */
@@ -1027,6 +1039,12 @@ interface ModelProfile {
   readonly aspects?: readonly string[];
   /** Resolutions the Model accepts. Absent means any. */
   readonly resolutions?: readonly string[];
+  /** Output formats the Model returns, for a text request and an edit.
+   * Absent means any. */
+  readonly outputFormats?: {
+    readonly edit: readonly string[];
+    readonly text: readonly string[];
+  };
 }
 /** The profile for a Model id, or undefined when no registry knows it. */
 export declare function modelProfile(model: string): ModelProfile | undefined;
@@ -1170,6 +1188,12 @@ interface TaskInput {
   prompt?: string;
   /** Mask image: https URL or data URL. */
   mask?: string;
+  /**
+   * Markup image: https URL or data URL. A transparent PNG of annotations
+   * (circles, arrows, notes) the size of the image being edited, guiding its
+   * edit. generate with references and vary take it; it can't join a mask.
+   */
+  markup?: string;
   /** Reference images: https URLs or data URLs. restyle and try-on take exactly one. */
   references?: readonly string[];
   aspect?: AspectRatio;
@@ -1198,10 +1222,15 @@ interface TaskInput {
   ephemeral?: boolean;
   /**
    * Called on each poll of fal's queue with its status ("queued",
-   * "processing", "completed", "failed") and, while queued, the place in line. Passing
-   * it runs a fal generation through the queue, since only the queue reports.
+   * "processing", "completed", "failed") and, while queued, the place in line. When fal has
+   * written new log lines since the last poll, they come as the third argument
+   * (new lines only). Passing it runs a fal generation through the queue, since
+   * only the queue reports.
    */
-  onProgress?: (status: JobStatus["status"], queuePosition?: number) => void;
+  onProgress?: (status: JobStatus["status"], queuePosition?: number, logs?: readonly {
+    message: string;
+    timestamp: string;
+  }[]) => void;
   /**
    * Called once, as soon as fal's queue accepts the run, with its request id
    * and before any wait. Keep it to `resume` the same job after a restart

package/dist/index.d.ts

@@ -246,7 +246,8 @@ export declare function enrichPrompt(options: EnrichPromptOptions): CreativeProm
 /** ─── 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";
-type ImageOutputFormat = "jpeg" | "png" | "webp";
+/** `gif` is an animation and `svg` a vector image, on the Models that make them. */
+type ImageOutputFormat = "jpeg" | "png" | "webp" | "gif" | "svg";
 interface CustomImageSize {
   height: number;
   width: number;
@@ -325,25 +326,31 @@ export declare const ACCOUNT_LOCKED = "ACCOUNT_LOCKED";
  */
 export declare function isFalAccountLocked(status: number, body: string): boolean;
 //#endregion
-//#region src/tasks.d.ts
+//#region src/image-benchmarks.d.ts
 /**
- * The Task registry: every job Motif does, with the Models that can do it
- * ranked best-first and tagged with the Tier each belongs to.
- *
- * Rankings are data so a default change is visible in a pull request. A Task
- * ranked from the bench's human comparisons says `rankedFrom: "bench"`; every
- * other Task is hand-ranked from published quality numbers and fal price, and
- * says so. Today no Task is bench-ranked: the bench holds two human ratings,
- * both on one model, which is not an order.
- *
- * Model ids are the short aliases `-m` and `TaskInput.model` accept. `resolveTask` in `./resolve` is the only place a Model is
- * chosen from these lists.
- *
- * A Task can have modes: a variant of the job a caller names explicitly, such
- * as erasing text rather than an object. A ranked entry with a `mode` is only
- * chosen when the request names that mode; an entry without one only when it
- * names none. A Model can appear once per mode.
+ * 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
+ * benchmarked; `evaluatedModel` names what was measured.
  */
+type ImageBenchmarkTask = "text-to-image" | "image-edit-single-image";
+interface ArenaScore {
+  readonly elo: number;
+  readonly rank: number;
+  /** The reported plus-or-minus interval, in Elo points. */
+  readonly uncertainty: number;
+  /** Exact leaderboard label, including a setting where one was reported. */
+  readonly evaluatedModel: string;
+  readonly preliminary?: true;
+  readonly votes?: number;
+}
+/** Scores are comparable only on the same board and snapshot. */
+interface ImageModelBenchmark extends ArenaScore {
+  readonly source: string;
+  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];
@@ -351,12 +358,14 @@ export declare const DEFAULT_TIER: Tier;
 /** Where a Task's order came from. */
 type RankedFrom = "bench" | "hand";
 /** Something a request needs that not every Model can honour. */
-type Capability = "aspect" | "count" | "image" | "mask" | "negativePrompt" | "outputFormat" | "references" | "resolution" | "rig" | "seed" | "transparency" | "video";
+type Capability = "aspect" | "count" | "image" | "markup" | "mask" | "negativePrompt" | "outputFormat" | "references" | "resolution" | "rig" | "seed" | "transparency" | "video";
 interface RankedModel {
   /** A Model id, as accepted by `-m` or `TaskInput.model`. */
   readonly model: string;
   /** The Tier this Model is offered at. */
   readonly tier: Tier;
+  /** Published evidence for this Task; null means this route is unscored. */
+  readonly benchmark?: ImageModelBenchmark | null;
   /** The mode this entry serves. Absent for the Task's plain job. */
   readonly mode?: string;
   /** Capabilities this Model has for this Task beyond its registry profile. */
@@ -964,6 +973,8 @@ interface TaskRequest {
   readonly references?: number;
   /** A mask image is passed in. */
   readonly mask?: boolean;
+  /** A markup image is passed in. */
+  readonly markup?: boolean;
   /** An aspect ratio is asked for, e.g. `"3:2"`. */
   readonly aspect?: string;
   /** A resolution tier is asked for, e.g. `"1K"`. */
@@ -972,7 +983,8 @@ interface TaskRequest {
   readonly count?: number;
   readonly seed?: boolean;
   readonly negativePrompt?: boolean;
-  readonly outputFormat?: boolean;
+  /** An output format is asked for, e.g. `"gif"`. */
+  readonly outputFormat?: string;
   /** A rigged mesh wanted. */
   readonly rig?: boolean;
   /** The kind of Source passed in. Absent for a text-only request. */
@@ -1027,6 +1039,12 @@ interface ModelProfile {
   readonly aspects?: readonly string[];
   /** Resolutions the Model accepts. Absent means any. */
   readonly resolutions?: readonly string[];
+  /** Output formats the Model returns, for a text request and an edit.
+   * Absent means any. */
+  readonly outputFormats?: {
+    readonly edit: readonly string[];
+    readonly text: readonly string[];
+  };
 }
 /** The profile for a Model id, or undefined when no registry knows it. */
 export declare function modelProfile(model: string): ModelProfile | undefined;
@@ -1170,6 +1188,12 @@ interface TaskInput {
   prompt?: string;
   /** Mask image: https URL or data URL. */
   mask?: string;
+  /**
+   * Markup image: https URL or data URL. A transparent PNG of annotations
+   * (circles, arrows, notes) the size of the image being edited, guiding its
+   * edit. generate with references and vary take it; it can't join a mask.
+   */
+  markup?: string;
   /** Reference images: https URLs or data URLs. restyle and try-on take exactly one. */
   references?: readonly string[];
   aspect?: AspectRatio;
@@ -1198,10 +1222,15 @@ interface TaskInput {
   ephemeral?: boolean;
   /**
    * Called on each poll of fal's queue with its status ("queued",
-   * "processing", "completed", "failed") and, while queued, the place in line. Passing
-   * it runs a fal generation through the queue, since only the queue reports.
+   * "processing", "completed", "failed") and, while queued, the place in line. When fal has
+   * written new log lines since the last poll, they come as the third argument
+   * (new lines only). Passing it runs a fal generation through the queue, since
+   * only the queue reports.
    */
-  onProgress?: (status: JobStatus["status"], queuePosition?: number) => void;
+  onProgress?: (status: JobStatus["status"], queuePosition?: number, logs?: readonly {
+    message: string;
+    timestamp: string;
+  }[]) => void;
   /**
    * Called once, as soon as fal's queue accepts the run, with its request id
    * and before any wait. Keep it to `resume` the same job after a restart