@howells/motif-sdk 5.3.0 → 6.0.0

package/dist/index.d.cts

@@ -150,7 +150,7 @@ export declare const CREATIVE_TAXONOMY: {
     readonly experimental: true;
     readonly id: "illustration";
     readonly label: "Editorial illustration";
-    readonly model: "gpt2";
+    readonly model: "flare";
   }];
   readonly mood: readonly [{
     readonly clause: "soft natural daylight from a window out of frame, gentle falloff into the corners, low contrast, even diffused light with soft, held highlights";
@@ -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. */
@@ -1018,8 +1030,6 @@ interface TaskUnresolved {
 type TaskResolution = TaskResolved | TaskUnresolved;
 interface ModelProfile {
   readonly capabilities: ReadonlySet<Capability>;
-  /** Capabilities reachable only when this key variable is set. */
-  readonly keyedCapabilities: ReadonlyMap<Capability, string>;
   /** Key variables the Model needs for any request. */
   readonly keys: readonly string[];
   readonly maxReferences: number;
@@ -1027,6 +1037,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;
@@ -1122,8 +1138,6 @@ export declare function sumCosts(costs: readonly (number | null)[]): {
 interface MotifClientConfig {
   /** Falls back to FAL_KEY. */
   falKey?: string;
-  /** Falls back to OPENAI_API_KEY. Used only by Models routed through OpenAI. */
-  openAiKey?: string;
   /** Models pinned per Task, as `resolveTask` takes them. */
   pins?: TaskEnvironment["pins"];
   /** The one network seam. Defaults to global fetch. Retries and timeouts still apply. */
@@ -1170,6 +1184,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 +1218,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
@@ -1230,8 +1255,8 @@ interface TaskPlan {
   queued: boolean;
   /** Projected: before the call. */
   cost: ResolvedCost;
-  /** The provider carrying the request. "openai" only for a transparency route. */
-  provider: "fal" | "openai";
+  /** The provider carrying the request. */
+  provider: "fal";
 }
 interface TaskOutput extends Omit<TaskPlan, "body" | "cost" | "queued"> {
   files: TaskFile[];
@@ -1282,7 +1307,7 @@ interface MotifClient {
    */
   resume: (task: TaskId, input: TaskInput, requestId: string) => Promise<Result$1<TaskOutput, MotifError>>;
 }
-/** Create the Task client. Keys fall back to FAL_KEY and OPENAI_API_KEY. */
+/** 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
@@ -1328,13 +1353,10 @@ export declare function promptWarnings(prompt: string, context?: {
 export declare const motifEnvSchema: import("@howells/envy").EnvSchema<{
   readonly optional: {
     FAL_KEY: z.ZodString;
-    OPENAI_API_KEY: z.ZodString;
   };
 }>;
 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;
-/** The OpenAI key, used by direct OpenAI routes such as gpt2 transparency. */
-export declare function getOpenAiKeyFromEnv(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

@@ -150,7 +150,7 @@ export declare const CREATIVE_TAXONOMY: {
     readonly experimental: true;
     readonly id: "illustration";
     readonly label: "Editorial illustration";
-    readonly model: "gpt2";
+    readonly model: "flare";
   }];
   readonly mood: readonly [{
     readonly clause: "soft natural daylight from a window out of frame, gentle falloff into the corners, low contrast, even diffused light with soft, held highlights";
@@ -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. */
@@ -1018,8 +1030,6 @@ interface TaskUnresolved {
 type TaskResolution = TaskResolved | TaskUnresolved;
 interface ModelProfile {
   readonly capabilities: ReadonlySet<Capability>;
-  /** Capabilities reachable only when this key variable is set. */
-  readonly keyedCapabilities: ReadonlyMap<Capability, string>;
   /** Key variables the Model needs for any request. */
   readonly keys: readonly string[];
   readonly maxReferences: number;
@@ -1027,6 +1037,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;
@@ -1122,8 +1138,6 @@ export declare function sumCosts(costs: readonly (number | null)[]): {
 interface MotifClientConfig {
   /** Falls back to FAL_KEY. */
   falKey?: string;
-  /** Falls back to OPENAI_API_KEY. Used only by Models routed through OpenAI. */
-  openAiKey?: string;
   /** Models pinned per Task, as `resolveTask` takes them. */
   pins?: TaskEnvironment["pins"];
   /** The one network seam. Defaults to global fetch. Retries and timeouts still apply. */
@@ -1170,6 +1184,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 +1218,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
@@ -1230,8 +1255,8 @@ interface TaskPlan {
   queued: boolean;
   /** Projected: before the call. */
   cost: ResolvedCost;
-  /** The provider carrying the request. "openai" only for a transparency route. */
-  provider: "fal" | "openai";
+  /** The provider carrying the request. */
+  provider: "fal";
 }
 interface TaskOutput extends Omit<TaskPlan, "body" | "cost" | "queued"> {
   files: TaskFile[];
@@ -1282,7 +1307,7 @@ interface MotifClient {
    */
   resume: (task: TaskId, input: TaskInput, requestId: string) => Promise<Result$1<TaskOutput, MotifError>>;
 }
-/** Create the Task client. Keys fall back to FAL_KEY and OPENAI_API_KEY. */
+/** 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
@@ -1328,13 +1353,10 @@ export declare function promptWarnings(prompt: string, context?: {
 export declare const motifEnvSchema: import("@howells/envy").EnvSchema<{
   readonly optional: {
     FAL_KEY: z.ZodString;
-    OPENAI_API_KEY: z.ZodString;
   };
 }>;
 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;
-/** The OpenAI key, used by direct OpenAI routes such as gpt2 transparency. */
-export declare function getOpenAiKeyFromEnv(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 };