@chai-ui/core 0.5.0 → 0.6.1

package/dist/media-analyzer.js

@@ -0,0 +1,124 @@
+/**
+ * The Media Analyzer's behavior with no framework: sends the attached media
+ * and the instruction for its kind and prompt length
+ * (`MEDIA_ANALYSIS_PROMPTS`) to the reasoning engine, and keeps the
+ * generated prompt, which fills in as the text streams. A small store
+ * (`getState` + `subscribe`) that `useMediaAnalyzer` (React) and the Vue
+ * composable wrap.
+ */
+import { warnNoReasoningOnce } from "./composer.js";
+import { createMockEngine, isAbortError, normalizeGenerationError } from "./engine.js";
+import { DEFAULT_MEDIA_ANALYSIS_PROMPT_LENGTH, MEDIA_ANALYSIS_PROMPTS, } from "./media-analysis-prompts.js";
+import { routeModel } from "./model-routing.js";
+import { reasoningModelFor } from "./reasoning.js";
+const mockTextEngine = createMockEngine({ outputKind: "text" });
+/**
+ * `getOptions` is read on every call, so options can change between
+ * renders; `getProvided` is the nearest provider's reasoning, if any.
+ */
+export function createMediaAnalyzerStore(getOptions, getProvided = () => undefined) {
+    let state = { analyzing: false, error: null, prompt: null };
+    const listeners = new Set();
+    const set = (next) => {
+        state = { ...state, ...next };
+        for (const l of listeners)
+            l();
+    };
+    // Each submit gets an id; a late reply from an earlier submit is dropped,
+    // and its call aborted.
+    let callId = 0;
+    let controller = null;
+    function submit(payload) {
+        const opts = getOptions();
+        const reasoning = getProvided();
+        const id = ++callId;
+        controller?.abort();
+        const { signal } = (controller = new AbortController());
+        set({ error: null, prompt: null });
+        const kind = payload.attachments[0]?.kind;
+        if (kind !== "image" && kind !== "video" && kind !== "audio") {
+            const message = "Attach an image, video, or audio file to analyze.";
+            set({ error: message });
+            opts.onError?.(message);
+            return;
+        }
+        const engine = opts.engine ?? reasoning?.engine ?? mockTextEngine;
+        const defaultModel = opts.model ?? (reasoning ? reasoningModelFor(reasoning, payload.attachments) : undefined);
+        const instruction = MEDIA_ANALYSIS_PROMPTS[kind][payload.promptLength ?? DEFAULT_MEDIA_ANALYSIS_PROMPT_LENGTH];
+        const current = () => id === callId;
+        const autoSelect = payload.autoSelectModel && payload.models.length > 0;
+        const analyze = (modelId) => engine
+            .generate({
+            modelId,
+            prompt: instruction,
+            attachments: payload.attachments,
+            onText: (text) => current() && set({ prompt: text }),
+            signal,
+        })
+            .then(({ src }) => {
+            if (!current())
+                return;
+            set({ prompt: src });
+            getOptions().onResult?.(src);
+        }, (err) => {
+            if (!current() || isAbortError(err))
+                return;
+            const { message } = normalizeGenerationError(err);
+            set({ error: message });
+            getOptions().onError?.(message);
+        })
+            .finally(() => current() && set({ analyzing: false }));
+        set({ analyzing: true });
+        if (!autoSelect) {
+            void analyze(payload.modelId ?? defaultModel);
+            return;
+        }
+        // Auto-select: the reasoning model looks at the media and picks the
+        // analysis model first. A routing problem falls back, never blocks.
+        void routeModel({
+            prompt: "",
+            outputKind: "text",
+            attachmentKinds: payload.attachments.map((a) => a.kind),
+            attachments: payload.attachments,
+            models: payload.models,
+            engine: opts.engine ?? reasoning?.engine,
+            model: defaultModel,
+            routingPrompt: opts.routingPrompt,
+            signal,
+        }).then((routed) => {
+            if (!current() || signal.aborted)
+                return;
+            const latest = getOptions();
+            if (routed.status === "fallback") {
+                if (routed.reason === "no-reasoning")
+                    warnNoReasoningOnce("analysis runs on the first listed model");
+                latest.onRoutingFallback?.(routed);
+            }
+            latest.onModelChange?.(routed.modelId);
+            return analyze(routed.modelId);
+        });
+    }
+    /** Stops the analysis in flight (cancelling at the provider where it can), keeping any text that already streamed in. */
+    function cancel() {
+        callId += 1;
+        controller?.abort();
+        controller = null;
+        set({ analyzing: false });
+    }
+    /** Stops anything in flight and clears the prompt and error, e.g. when the person changes their media. */
+    function reset() {
+        cancel();
+        set({ error: null, prompt: null });
+    }
+    return {
+        getState: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => void listeners.delete(listener);
+        },
+        submit,
+        cancel,
+        reset,
+    };
+}
+//# sourceMappingURL=media-analyzer.js.map

package/dist/media-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-analyzer.js","sourceRoot":"","sources":["../src/media-analyzer.ts"],"names":[],"mappings":"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"}

package/dist/reasoning.d.ts

@@ -0,0 +1,59 @@
+import type { GenerationEngine } from "./engine.js";
+import type { DroppedMedia, MediaKind } from "./types.js";
+/**
+ * The suggested reasoning model for text and images: prompt enhancement,
+ * auto-select routing and image analysis. A default, not a requirement —
+ * pass any model id `reasoningEngine` can run.
+ */
+export declare const DEFAULT_REASONING_MODEL = "anthropic/claude-opus-5";
+/**
+ * Suggested per-kind overrides for media Claude can't read. Gemini takes
+ * video and audio directly. For a cheaper option, swap in
+ * `"qwen/qwen3.8-omni-flash"`, which takes both too.
+ */
+export declare const DEFAULT_REASONING_MODEL_BY_KIND: Partial<Record<MediaKind, string>>;
+/** The reasoning engine and models every CHAI component shares. */
+export interface Reasoning {
+    engine: GenerationEngine;
+    /** The model for text and any attachment kind without its own entry in `modelByKind`. */
+    model: string;
+    modelByKind: Partial<Record<MediaKind, string>>;
+}
+/** What a `ChaiProvider` takes, in any framework. */
+export interface ReasoningConfig {
+    /** Text, image and routing model. Defaults to `DEFAULT_REASONING_MODEL`. */
+    reasoningModel?: string;
+    /**
+     * Per-attachment-kind models, merged over `DEFAULT_REASONING_MODEL_BY_KIND`
+     * one kind at a time, e.g. `{ video: "qwen/qwen3.8-omni-flash" }` keeps
+     * the default for audio. Map a kind to `reasoningModel`'s value to use
+     * one model for everything.
+     */
+    reasoningModelByKind?: Partial<Record<MediaKind, string>>;
+    /**
+     * The engine the reasoning models run on. Defaults to OpenRouter,
+     * independent of the generation engine: Fal's own LLM access is an
+     * OpenRouter proxy, so defaulting to it would double-proxy.
+     */
+    reasoningEngine?: GenerationEngine;
+}
+/** A provider's `Reasoning`, from its config and the engine it holds (`config.reasoningEngine`, else one OpenRouter engine it created once). */
+export declare function createReasoning(config: ReasoningConfig, engine: GenerationEngine): Reasoning;
+/** The reasoning engine a provider uses: the one passed, else OpenRouter's. */
+export declare function reasoningEngineFor(config: ReasoningConfig): GenerationEngine;
+/**
+ * A hook's or composable's own pair wins, but only as a pair: half of one
+ * never mixes with half of the provider's (e.g. a hook engine with the
+ * provider's model). Half a pair means no reasoning.
+ */
+export declare function pickReasoning(own: {
+    reasoningEngine?: GenerationEngine;
+    reasoningModel?: string;
+}, provided: Reasoning | undefined): Reasoning | undefined;
+/**
+ * The reasoning model for a call with these attachments: the first
+ * attachment whose kind has its own model wins (a clip plus a still goes
+ * to the model that can read the clip), else `reasoning.model`.
+ */
+export declare function reasoningModelFor(reasoning: Reasoning, attachments?: DroppedMedia[]): string;
+//# sourceMappingURL=reasoning.d.ts.map

package/dist/reasoning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning.d.ts","sourceRoot":"","sources":["../src/reasoning.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,4BAA4B,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAG9E,CAAC;AAEF,mEAAmE;AACnE,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,gBAAgB,CAAC;IACzB,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD;AAED,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D;;;;OAIG;IACH,eAAe,CAAC,EAAE,gBAAgB,CAAC;CACpC;AAED,gJAAgJ;AAChJ,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAQ5F;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE;IAAE,eAAe,CAAC,EAAE,gBAAgB,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,EACpE,QAAQ,EAAE,SAAS,GAAG,SAAS,GAC9B,SAAS,GAAG,SAAS,CAIvB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,SAAS,EAAE,WAAW,GAAE,YAAY,EAAO,GAAG,MAAM,CAMhG"}

package/dist/reasoning.js

@@ -0,0 +1,55 @@
+import { createOpenRouterEngine } from "./engines/openrouter.js";
+/**
+ * The suggested reasoning model for text and images: prompt enhancement,
+ * auto-select routing and image analysis. A default, not a requirement —
+ * pass any model id `reasoningEngine` can run.
+ */
+export const DEFAULT_REASONING_MODEL = "anthropic/claude-opus-5";
+/**
+ * Suggested per-kind overrides for media Claude can't read. Gemini takes
+ * video and audio directly. For a cheaper option, swap in
+ * `"qwen/qwen3.8-omni-flash"`, which takes both too.
+ */
+export const DEFAULT_REASONING_MODEL_BY_KIND = {
+    video: "google/gemini-3.8-flash",
+    audio: "google/gemini-3.8-flash",
+};
+/** A provider's `Reasoning`, from its config and the engine it holds (`config.reasoningEngine`, else one OpenRouter engine it created once). */
+export function createReasoning(config, engine) {
+    const byKind = config.reasoningModelByKind ?? {};
+    const overrides = Object.fromEntries(Object.entries(byKind).filter(([, v]) => v !== undefined));
+    return {
+        engine,
+        model: config.reasoningModel ?? DEFAULT_REASONING_MODEL,
+        modelByKind: { ...DEFAULT_REASONING_MODEL_BY_KIND, ...overrides },
+    };
+}
+/** The reasoning engine a provider uses: the one passed, else OpenRouter's. */
+export function reasoningEngineFor(config) {
+    return config.reasoningEngine ?? createOpenRouterEngine();
+}
+/**
+ * A hook's or composable's own pair wins, but only as a pair: half of one
+ * never mixes with half of the provider's (e.g. a hook engine with the
+ * provider's model). Half a pair means no reasoning.
+ */
+export function pickReasoning(own, provided) {
+    const { reasoningEngine, reasoningModel } = own;
+    if (!reasoningEngine && !reasoningModel)
+        return provided;
+    return reasoningEngine && reasoningModel ? { engine: reasoningEngine, model: reasoningModel, modelByKind: {} } : undefined;
+}
+/**
+ * The reasoning model for a call with these attachments: the first
+ * attachment whose kind has its own model wins (a clip plus a still goes
+ * to the model that can read the clip), else `reasoning.model`.
+ */
+export function reasoningModelFor(reasoning, attachments = []) {
+    for (const { kind } of attachments) {
+        const model = reasoning.modelByKind[kind];
+        if (model)
+            return model;
+    }
+    return reasoning.model;
+}
+//# sourceMappingURL=reasoning.js.map

package/dist/reasoning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning.js","sourceRoot":"","sources":["../src/reasoning.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAIjE;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,yBAAyB,CAAC;AAEjE;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAuC;IACjF,KAAK,EAAE,yBAAyB;IAChC,KAAK,EAAE,yBAAyB;CACjC,CAAC;AA6BF,gJAAgJ;AAChJ,MAAM,UAAU,eAAe,CAAC,MAAuB,EAAE,MAAwB;IAC/E,MAAM,MAAM,GAAG,MAAM,CAAC,oBAAoB,IAAI,EAAE,CAAC;IACjD,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC;IAChG,OAAO;QACL,MAAM;QACN,KAAK,EAAE,MAAM,CAAC,cAAc,IAAI,uBAAuB;QACvD,WAAW,EAAE,EAAE,GAAG,+BAA+B,EAAE,GAAG,SAAS,EAAE;KAClE,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB,CAAC,MAAuB;IACxD,OAAO,MAAM,CAAC,eAAe,IAAI,sBAAsB,EAAE,CAAC;AAC5D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAoE,EACpE,QAA+B;IAE/B,MAAM,EAAE,eAAe,EAAE,cAAc,EAAE,GAAG,GAAG,CAAC;IAChD,IAAI,CAAC,eAAe,IAAI,CAAC,cAAc;QAAE,OAAO,QAAQ,CAAC;IACzD,OAAO,eAAe,IAAI,cAAc,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7H,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAoB,EAAE,cAA8B,EAAE;IACtF,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,SAAS,CAAC,KAAK,CAAC;AACzB,CAAC"}

package/dist/suggested-models.d.ts

@@ -0,0 +1,23 @@
+import type { GenerationUseCase, MediaKind, ModelOption } from "./types.js";
+/** Create image, from a prompt. */
+export declare const SUGGESTED_IMAGE_MODELS: ModelOption[];
+/** Create video, from a prompt alone. */
+export declare const SUGGESTED_TEXT_TO_VIDEO_MODELS: ModelOption[];
+/** Create video, starting from an attached image. The video follows the image's shape, so none lists aspect ratios. */
+export declare const SUGGESTED_IMAGE_TO_VIDEO_MODELS: ModelOption[];
+/**
+ * Edit an image. Flux 3 Image reads marked regions as boxes; the others get
+ * them described in words. An edit keeps the image's shape, so no aspect
+ * ratios.
+ */
+export declare const SUGGESTED_EDIT_MODELS: ModelOption[];
+/**
+ * MediaAnalyzer's models per media kind, on OpenRouter. The first in each
+ * is `ChaiProvider`'s default reasoning model for that kind.
+ */
+export declare const SUGGESTED_ANALYSIS_MODELS: Partial<Record<MediaKind, ModelOption[]>>;
+/** The suggested Fal models for a generation use case, or none (text requests use the reasoning model). */
+export declare function suggestedModels(useCase: GenerationUseCase | undefined): ModelOption[];
+/** Every suggested Fal model, by id: how the Fal engine knows each one's inputs. */
+export declare const SUGGESTED_FAL_MODELS: ReadonlyMap<string, ModelOption>;
+//# sourceMappingURL=suggested-models.d.ts.map

package/dist/suggested-models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggested-models.d.ts","sourceRoot":"","sources":["../src/suggested-models.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAuB5E,mCAAmC;AACnC,eAAO,MAAM,sBAAsB,EAAE,WAAW,EAa/C,CAAC;AAEF,yCAAyC;AACzC,eAAO,MAAM,8BAA8B,EAAE,WAAW,EAKvD,CAAC;AAEF,uHAAuH;AACvH,eAAO,MAAM,+BAA+B,EAAE,WAAW,EAKxD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,EAY9C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,EAAE,CAAC,CAqB/E,CAAC;AAEF,2GAA2G;AAC3G,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,WAAW,EAAE,CAarF;AAED,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAEjE,CAAC"}

package/dist/suggested-models.js

@@ -0,0 +1,110 @@
+import { DEFAULT_MAX_REGIONS } from "./region-edit.js";
+/**
+ * Suggested models, so builders don't have to write model lists. Composer
+ * and MediaAnalyzer use them when no `models` is passed; passing `models`
+ * still replaces them. The first model in each list is the default pick.
+ *
+ * Generation runs on Fal (the default engine), analysis on OpenRouter (the
+ * reasoning engine). Every entry was checked against the provider's own
+ * catalog: Fal's model schemas (`api.fal.ai/v1/models?expand=openapi-3.0`)
+ * for the aspect ratios and the image field, OpenRouter's model list for
+ * the input kinds. They change only through package releases; run
+ * `checkSuggestedModels()` to see whether a provider has changed since.
+ *
+ * Checked 2026-10-06.
+ */
+const NANO_BANANA_RATIOS = ["21:9", "16:9", "3:2", "4:3", "5:4", "1:1", "4:5", "3:4", "2:3", "9:16"];
+const FLUX_3_RATIOS = ["21:9", "2:1", "16:9", "3:2", "7:5", "4:3", "5:4", "1:1", "4:5", "3:4", "5:7", "2:3", "9:16", "1:2"];
+/** The ratios a named `image_size` covers (FLUX.1, GPT Image 2). */
+const IMAGE_SIZE_RATIOS = ["1:1", "4:3", "16:9", "3:4", "9:16"];
+/** Create image, from a prompt. */
+export const SUGGESTED_IMAGE_MODELS = [
+    { id: "fal-ai/nano-banana-pro", label: "Nano Banana Pro", provider: "Google", speed: "standard", aspectRatios: NANO_BANANA_RATIOS, falInput: { aspectRatio: "aspect_ratio" } },
+    {
+        id: "fal-ai/nano-banana-2",
+        label: "Nano Banana 2",
+        provider: "Google",
+        speed: "fast",
+        aspectRatios: [...NANO_BANANA_RATIOS, "4:1", "1:4", "8:1", "1:8"],
+        falInput: { aspectRatio: "aspect_ratio" },
+    },
+    { id: "blackforestlabs/flux-3/text-to-image", label: "Flux 3 Image", provider: "Black Forest Labs", speed: "standard", aspectRatios: FLUX_3_RATIOS, falInput: { aspectRatio: "aspect_ratio" } },
+    { id: "openai/gpt-image-2", label: "GPT Image 2", provider: "OpenAI", speed: "slow", aspectRatios: IMAGE_SIZE_RATIOS, falInput: { aspectRatio: "image_size" } },
+    { id: "fal-ai/flux/schnell", label: "FLUX.1 schnell", provider: "Black Forest Labs", speed: "fast", aspectRatios: IMAGE_SIZE_RATIOS, falInput: { aspectRatio: "image_size" } },
+];
+/** Create video, from a prompt alone. */
+export const SUGGESTED_TEXT_TO_VIDEO_MODELS = [
+    { id: "minimax/h3-max/text-to-video", label: "MiniMax H3 Max", provider: "MiniMax", speed: "slow", aspectRatios: ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"], falInput: { aspectRatio: "aspect_ratio" } },
+    { id: "bytedance/seedance-2.5/text-to-video", label: "Seedance 2.5", provider: "ByteDance", speed: "slow", aspectRatios: ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"], falInput: { aspectRatio: "aspect_ratio" } },
+    { id: "fal-ai/kling-video/v3/pro/text-to-video", label: "Kling v3 Pro", provider: "Kling", speed: "slow", aspectRatios: ["16:9", "9:16", "1:1"], falInput: { aspectRatio: "aspect_ratio" } },
+    { id: "fal-ai/veo3.1/fast", label: "Veo 3.1 Fast", provider: "Google", speed: "standard", aspectRatios: ["16:9", "9:16"], falInput: { aspectRatio: "aspect_ratio" } },
+];
+/** Create video, starting from an attached image. The video follows the image's shape, so none lists aspect ratios. */
+export const SUGGESTED_IMAGE_TO_VIDEO_MODELS = [
+    { id: "fal-ai/kling-video/v3/pro/image-to-video", label: "Kling v3 Pro", provider: "Kling", speed: "slow", falInput: { image: "start_image_url" } },
+    { id: "minimax/h3-max/image-to-video", label: "MiniMax H3 Max", provider: "MiniMax", speed: "slow", falInput: { image: "image_url" } },
+    { id: "bytedance/seedance-2.5/image-to-video", label: "Seedance 2.5", provider: "ByteDance", speed: "slow", falInput: { image: "image_url" } },
+    { id: "fal-ai/veo3.1/fast/image-to-video", label: "Veo 3.1 Fast", provider: "Google", speed: "standard", falInput: { image: "image_url" } },
+];
+/**
+ * Edit an image. Flux 3 Image reads marked regions as boxes; the others get
+ * them described in words. An edit keeps the image's shape, so no aspect
+ * ratios.
+ */
+export const SUGGESTED_EDIT_MODELS = [
+    {
+        id: "blackforestlabs/flux-3/edit-image",
+        label: "Flux 3 Image",
+        provider: "Black Forest Labs",
+        speed: "standard",
+        regionFormat: "flux-3-boxes",
+        maxRegions: DEFAULT_MAX_REGIONS,
+        falInput: { image: "image_urls" },
+    },
+    { id: "fal-ai/nano-banana-pro/edit", label: "Nano Banana Pro", provider: "Google", speed: "standard", falInput: { image: "image_urls" } },
+    { id: "openai/gpt-image-2/edit", label: "GPT Image 2", provider: "OpenAI", speed: "slow", falInput: { image: "image_urls" } },
+];
+/**
+ * MediaAnalyzer's models per media kind, on OpenRouter. The first in each
+ * is `ChaiProvider`'s default reasoning model for that kind.
+ */
+export const SUGGESTED_ANALYSIS_MODELS = {
+    image: [
+        { id: "anthropic/claude-opus-5", label: "Claude Opus 5", provider: "Anthropic", speed: "standard" },
+        { id: "openai/gpt-5.2", label: "GPT-5.2", provider: "OpenAI", speed: "standard" },
+        { id: "google/gemini-3.5-flash", label: "Gemini 3.5 Flash", provider: "Google", speed: "fast" },
+        { id: "meta-llama/llama-4-maverick", label: "Llama 4 Maverick", provider: "Meta", speed: "standard" },
+        { id: "x-ai/grok-4.5", label: "Grok 4.5", provider: "xAI", speed: "standard" },
+    ],
+    video: [
+        { id: "google/gemini-3.8-flash", label: "Gemini 3.8 Flash", provider: "Google", speed: "fast" },
+        { id: "google/gemini-3.5-flash", label: "Gemini 3.5 Flash", provider: "Google", speed: "fast" },
+        { id: "amazon/nova-2-lite-v1", label: "Nova 2 Lite", provider: "Amazon", speed: "fast" },
+        { id: "bytedance-seed/seed-2.0-lite", label: "Seed 2.0 Lite", provider: "ByteDance", speed: "fast" },
+        { id: "moonshotai/kimi-k3", label: "Kimi K3", provider: "Moonshot", speed: "standard" },
+    ],
+    audio: [
+        { id: "google/gemini-3.8-flash", label: "Gemini 3.8 Flash", provider: "Google", speed: "fast" },
+        { id: "openai/gpt-audio", label: "GPT Audio", provider: "OpenAI", speed: "standard" },
+        { id: "mistralai/voxtral-small-24b-2507", label: "Voxtral Small 24B", provider: "Mistral", speed: "standard" },
+        { id: "xiaomi/mimo-v2.5", label: "MiMo V2.5", provider: "Xiaomi", speed: "standard" },
+    ],
+};
+/** The suggested Fal models for a generation use case, or none (text requests use the reasoning model). */
+export function suggestedModels(useCase) {
+    switch (useCase) {
+        case "text-to-image":
+            return SUGGESTED_IMAGE_MODELS;
+        case "text-to-video":
+            return SUGGESTED_TEXT_TO_VIDEO_MODELS;
+        case "image-to-video":
+            return SUGGESTED_IMAGE_TO_VIDEO_MODELS;
+        case "image-edit":
+            return SUGGESTED_EDIT_MODELS;
+        default:
+            return [];
+    }
+}
+/** Every suggested Fal model, by id: how the Fal engine knows each one's inputs. */
+export const SUGGESTED_FAL_MODELS = new Map([...SUGGESTED_IMAGE_MODELS, ...SUGGESTED_TEXT_TO_VIDEO_MODELS, ...SUGGESTED_IMAGE_TO_VIDEO_MODELS, ...SUGGESTED_EDIT_MODELS].map((m) => [m.id, m]));
+//# sourceMappingURL=suggested-models.js.map

package/dist/suggested-models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggested-models.js","sourceRoot":"","sources":["../src/suggested-models.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AAEH,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AACrG,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;AAC5H,oEAAoE;AACpE,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAEhE,mCAAmC;AACnC,MAAM,CAAC,MAAM,sBAAsB,GAAkB;IACnD,EAAE,EAAE,EAAE,wBAAwB,EAAE,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,kBAAkB,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,cAAc,EAAE,EAAE;IAC9K;QACE,EAAE,EAAE,sBAAsB;QAC1B,KAAK,EAAE,eAAe;QACtB,QAAQ,EAAE,QAAQ;QAClB,KAAK,EAAE,MAAM;QACb,YAAY,EAAE,CAAC,GAAG,kBAAkB,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC;QACjE,QAAQ,EAAE,EAAE,WAAW,EAAE,cAAc,EAAE;KAC1C;IACD,EAAE,EAAE,EAAE,sCAAsC,EAAE,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,mBAAmB,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,cAAc,EAAE,EAAE;IAC/L,EAAE,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,iBAAiB,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE,EAAE;IAC/J,EAAE,EAAE,EAAE,qBAAqB,EAAE,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,iBAAiB,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE,EAAE;CAC/K,CAAC;AAEF,yCAAyC;AACzC,MAAM,CAAC,MAAM,8BAA8B,GAAkB;IAC3D,EAAE,EAAE,EAAE,8BAA8B,EAAE,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,cAAc,EAAE,EAAE;IAC3M,EAAE,EAAE,EAAE,sCAAsC,EAAE,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,cAAc,EAAE,EAAE;IACnN,EAAE,EAAE,EAAE,yCAAyC,EAAE,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,cAAc,EAAE,EAAE;IAC5L,EAAE,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,cAAc,EAAE,EAAE;CACtK,CAAC;AAEF,uHAAuH;AACvH,MAAM,CAAC,MAAM,+BAA+B,GAAkB;IAC5D,EAAE,EAAE,EAAE,0CAA0C,EAAE,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,EAAE;IACnJ,EAAE,EAAE,EAAE,+BAA+B,EAAE,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE;IACtI,EAAE,EAAE,EAAE,uCAAuC,EAAE,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE;IAC9I,EAAE,EAAE,EAAE,mCAAmC,EAAE,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE;CAC5I,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAkB;IAClD;QACE,EAAE,EAAE,mCAAmC;QACvC,KAAK,EAAE,cAAc;QACrB,QAAQ,EAAE,mBAAmB;QAC7B,KAAK,EAAE,UAAU;QACjB,YAAY,EAAE,cAAc;QAC5B,UAAU,EAAE,mBAAmB;QAC/B,QAAQ,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE;KAClC;IACD,EAAE,EAAE,EAAE,6BAA6B,EAAE,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE;IACzI,EAAE,EAAE,EAAE,yBAAyB,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE;CAC9H,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAA8C;IAClF,KAAK,EAAE;QACL,EAAE,EAAE,EAAE,yBAAyB,EAAE,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,EAAE;QACnG,EAAE,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE;QACjF,EAAE,EAAE,EAAE,yBAAyB,EAAE,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE;QAC/F,EAAE,EAAE,EAAE,6BAA6B,EAAE,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE;QACrG,EAAE,EAAE,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE;KAC/E;IACD,KAAK,EAAE;QACL,EAAE,EAAE,EAAE,yBAAyB,EAAE,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE;QAC/F,EAAE,EAAE,EAAE,yBAAyB,EAAE,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE;QAC/F,EAAE,EAAE,EAAE,uBAAuB,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE;QACxF,EAAE,EAAE,EAAE,8BAA8B,EAAE,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE;QACpG,EAAE,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE;KACxF;IACD,KAAK,EAAE;QACL,EAAE,EAAE,EAAE,yBAAyB,EAAE,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE;QAC/F,EAAE,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE;QACrF,EAAE,EAAE,EAAE,kCAAkC,EAAE,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE;QAC9G,EAAE,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE;KACtF;CACF,CAAC;AAEF,2GAA2G;AAC3G,MAAM,UAAU,eAAe,CAAC,OAAsC;IACpE,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,eAAe;YAClB,OAAO,sBAAsB,CAAC;QAChC,KAAK,eAAe;YAClB,OAAO,8BAA8B,CAAC;QACxC,KAAK,gBAAgB;YACnB,OAAO,+BAA+B,CAAC;QACzC,KAAK,YAAY;YACf,OAAO,qBAAqB,CAAC;QAC/B;YACE,OAAO,EAAE,CAAC;IACd,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,MAAM,oBAAoB,GAAqC,IAAI,GAAG,CAC3E,CAAC,GAAG,sBAAsB,EAAE,GAAG,8BAA8B,EAAE,GAAG,+BAA+B,EAAE,GAAG,qBAAqB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CACnJ,CAAC"}

package/dist/types.d.ts

@@ -87,6 +87,13 @@ export interface ModelOption {
     regionFormat?: RegionFormat;
     /** For image-edit models: the most regions one edit takes. `EditCard` disables "New region" at this many. */
     maxRegions?: number;
+    /**
+     * How a Fal model takes its inputs, from its Fal schema: which field the
+     * attached image goes in, and whether the aspect ratio is sent as
+     * `aspect_ratio` or as a named `image_size`. The suggested lists carry it;
+     * without it the Fal engine guesses from the id.
+     */
+    falInput?: FalInputFormat;
     /**
      * The output aspect ratios the model takes, e.g. `["1:1", "16:9", "9:16"]`.
      * Composer's Aspect ratio menu offers only ratios the selected models
@@ -96,6 +103,11 @@ export interface ModelOption {
      */
     aspectRatios?: string[];
 }
+/** See `ModelOption.falInput`. */
+export interface FalInputFormat {
+    image?: "image_url" | "image_urls" | "start_image_url";
+    aspectRatio?: "aspect_ratio" | "image_size";
+}
 /** How an edit's regions reach the model — see `ModelOption.regionFormat`. */
 export type RegionFormat = "flux-3-boxes" | "text";
 /**

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,SAAS,CAAC;IAChB,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,oFAAoF;AACpF,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;CACf;AAED,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IACpC;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,6GAA6G;IAC7G,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,MAAM,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,eAAe,GACf,YAAY,GACZ,eAAe,GACf,gBAAgB,GAChB,YAAY,GACZ,QAAQ,GACR,cAAc,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,SAAS,CAAC;IAChB,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,oFAAoF;AACpF,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;CACf;AAED,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IACpC;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,6GAA6G;IAC7G,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,WAAW,GAAG,YAAY,GAAG,iBAAiB,CAAC;IACvD,WAAW,CAAC,EAAE,cAAc,GAAG,YAAY,CAAC;CAC7C;AAED,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,MAAM,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,eAAe,GACf,YAAY,GACZ,eAAe,GACf,gBAAgB,GAChB,YAAY,GACZ,QAAQ,GACR,cAAc,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chai-ui/core",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "CHAI UI headless core — the Request/Run/Result data model and pluggable generation engines (Fal.ai, OpenRouter, mock). No framework, no rendering.",
   "license": "MIT",
   "author": "kazarazat",

package/src/check-suggested-models.ts

@@ -0,0 +1,147 @@
+import type { MediaKind, ModelOption } from "./types.js";
+import { SUGGESTED_ANALYSIS_MODELS, SUGGESTED_FAL_MODELS } from "./suggested-models.js";
+import { FAL_NAMED_IMAGE_SIZES } from "./engines/fal.js";
+
+/** One way a provider no longer matches a suggested model. */
+export interface SuggestedModelProblem {
+  provider: "fal" | "openrouter";
+  /** The model's id, or `"*"` when the provider couldn't be reached at all. */
+  modelId: string;
+  problem: string;
+}
+
+export interface SuggestedModelsCheck {
+  /** True when every suggested model still matches its provider. */
+  ok: boolean;
+  /** How many models were checked. */
+  checked: number;
+  problems: SuggestedModelProblem[];
+}
+
+/**
+ * Checks the suggested model lists against Fal and OpenRouter as they are
+ * today: each model still exists and is active; for Fal, it still takes
+ * the aspect ratios and image field Chai sends, and needs no other field
+ * Chai doesn't send; for OpenRouter, it still accepts the media kind it's
+ * listed for. Run it while setting up your engine. It needs no API key,
+ * runs no model and costs nothing; both catalogs are public and allow
+ * calls from a browser.
+ *
+ * The lists themselves only change through package releases. A problem
+ * here means a provider changed since: pick another model, or update the
+ * package once a release catches up.
+ */
+export async function checkSuggestedModels(options: { fetchImpl?: typeof fetch } = {}): Promise<SuggestedModelsCheck> {
+  const fetchImpl: typeof fetch = (input, init) => (options.fetchImpl ?? fetch)(input, init);
+  const fal = [...SUGGESTED_FAL_MODELS.values()];
+  const analysis = Object.entries(SUGGESTED_ANALYSIS_MODELS).flatMap(([kind, models]) =>
+    (models ?? []).map((model) => ({ kind: kind as MediaKind, model }))
+  );
+  const problems = [...(await checkFal(fal, fetchImpl)), ...(await checkOpenRouter(analysis, fetchImpl))];
+  return { ok: problems.length === 0, checked: fal.length + analysis.length, problems };
+}
+
+type Schema = { properties?: Record<string, Schema>; required?: string[]; enum?: unknown[]; const?: unknown; default?: unknown; anyOf?: Schema[]; allOf?: Schema[]; $ref?: string };
+
+async function checkFal(models: ModelOption[], fetchImpl: typeof fetch): Promise<SuggestedModelProblem[]> {
+  const query = models.map((m) => `endpoint_id=${encodeURIComponent(m.id)}`).join("&");
+  let found: { endpoint_id: string; metadata?: { status?: string }; openapi?: OpenApi }[];
+  try {
+    // Fal answers 10 models a page, with a cursor for the next.
+    found = [];
+    let cursor: string | undefined;
+    do {
+      const res = await fetchImpl(
+        `https://api.fal.ai/v1/models?expand=openapi-3.0&${query}${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`
+      );
+      if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+      const page = (await res.json()) as { models?: typeof found; has_more?: boolean; next_cursor?: string };
+      found.push(...(page.models ?? []));
+      cursor = page.has_more ? page.next_cursor : undefined;
+    } while (cursor);
+  } catch (err) {
+    return [{ provider: "fal", modelId: "*", problem: `Couldn't reach Fal's model catalog: ${(err as Error).message}` }];
+  }
+
+  const problems: SuggestedModelProblem[] = [];
+  const add = (modelId: string, problem: string) => problems.push({ provider: "fal", modelId, problem });
+  for (const model of models) {
+    const entry = found.find((f) => f.endpoint_id === model.id);
+    if (!entry) {
+      add(model.id, "Not in Fal's catalog any more.");
+      continue;
+    }
+    if (entry.metadata?.status && entry.metadata.status !== "active") add(model.id, `Fal lists it as "${entry.metadata.status}".`);
+    const input = inputSchema(entry.openapi);
+    if (!input) continue;
+    const props = input.schema.properties ?? {};
+
+    const imageField = model.falInput?.image;
+    if (imageField && !props[imageField]) add(model.id, `No longer takes "${imageField}" for the image.`);
+
+    const ratioField = model.falInput?.aspectRatio;
+    if (model.aspectRatios && ratioField) {
+      const accepted = enumOf(props[ratioField], input.resolve);
+      if (!props[ratioField]) add(model.id, `No longer takes "${ratioField}".`);
+      else if (accepted) {
+        const wanted = ratioField === "image_size" ? model.aspectRatios.map((r) => FAL_NAMED_IMAGE_SIZES[r] ?? r) : model.aspectRatios;
+        const missing = wanted.filter((v) => !accepted.includes(v));
+        if (missing.length > 0) add(model.id, `No longer takes these ${ratioField} values: ${missing.join(", ")}.`);
+      }
+    }
+
+    const sent = new Set(["prompt", imageField ?? "", ratioField ?? ""]);
+    for (const name of input.schema.required ?? []) {
+      if (!sent.has(name) && props[name]?.default === undefined) add(model.id, `Now requires "${name}", which Chai doesn't send.`);
+    }
+  }
+  return problems;
+}
+
+async function checkOpenRouter(
+  models: { kind: MediaKind; model: ModelOption }[],
+  fetchImpl: typeof fetch
+): Promise<SuggestedModelProblem[]> {
+  let catalog: { id: string; architecture?: { input_modalities?: string[] } }[];
+  try {
+    const res = await fetchImpl("https://openrouter.ai/api/v1/models");
+    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+    catalog = ((await res.json()) as { data?: typeof catalog }).data ?? [];
+  } catch (err) {
+    return [{ provider: "openrouter", modelId: "*", problem: `Couldn't reach OpenRouter's model list: ${(err as Error).message}` }];
+  }
+  const problems: SuggestedModelProblem[] = [];
+  for (const { kind, model } of models) {
+    const entry = catalog.find((c) => c.id === model.id);
+    if (!entry) problems.push({ provider: "openrouter", modelId: model.id, problem: "Not in OpenRouter's catalog any more." });
+    else if (!entry.architecture?.input_modalities?.includes(kind))
+      problems.push({ provider: "openrouter", modelId: model.id, problem: `No longer accepts ${kind}.` });
+  }
+  return problems;
+}
+
+type OpenApi = {
+  paths?: Record<string, { post?: { requestBody?: { content?: Record<string, { schema?: Schema }> } } }>;
+  components?: { schemas?: Record<string, Schema> };
+};
+
+/** The model's request schema, from its OpenAPI document, with a resolver for `$ref`s. */
+function inputSchema(openapi: OpenApi | undefined): { schema: Schema; resolve: (s: Schema) => Schema } | null {
+  const schemas = openapi?.components?.schemas ?? {};
+  const resolve = (s: Schema): Schema => (s.$ref ? (schemas[s.$ref.split("/").pop()!] ?? s) : s);
+  for (const path of Object.values(openapi?.paths ?? {})) {
+    const body = path.post?.requestBody?.content?.["application/json"]?.schema;
+    if (body) return { schema: resolve(body), resolve };
+  }
+  return null;
+}
+
+/** The allowed values of a field, wherever its schema keeps them. */
+function enumOf(field: Schema | undefined, resolve: (s: Schema) => Schema): unknown[] | null {
+  if (!field) return null;
+  for (const s of [field, ...(field.anyOf ?? []), ...(field.allOf ?? [])].map(resolve)) {
+    if (s.enum) return s.enum;
+    if (s.const !== undefined) return [s.const];
+  }
+  return null;
+}