@chai-ui/core 0.5.0 → 0.6.1

package/src/media-analyzer.ts

@@ -0,0 +1,182 @@
+/**
+ * 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, type GenerationEngine } from "./engine.js";
+import {
+  DEFAULT_MEDIA_ANALYSIS_PROMPT_LENGTH,
+  MEDIA_ANALYSIS_PROMPTS,
+  type MediaAnalysisPromptLength,
+} from "./media-analysis-prompts.js";
+import { routeModel, type ModelRoutingInput, type ModelRoutingResult } from "./model-routing.js";
+import { reasoningModelFor, type Reasoning } from "./reasoning.js";
+import type { DroppedMedia, ModelOption } from "./types.js";
+
+export interface MediaAnalyzerAttachment extends DroppedMedia {
+  id: string;
+}
+
+export interface MediaAnalyzerSubmitPayload {
+  attachments: MediaAnalyzerAttachment[];
+  modelId: string | null;
+  /** When true, the analyzer routes among `models` at submit instead of using `modelId`. */
+  autoSelectModel: boolean;
+  /** The models offered for the attached media's kind. */
+  models: ModelOption[];
+  /** `null` until a person actually picks one — see `MediaAnalyzer`'s `promptLength` prop for why this doesn't default to "concise". */
+  promptLength: MediaAnalysisPromptLength | null;
+}
+
+export interface MediaAnalyzerOptions {
+  /**
+   * Overrides the nearest `ChaiProvider`'s reasoning engine. With neither,
+   * a mock text engine answers, so a first render works with no key.
+   */
+  engine?: GenerationEngine;
+  /** The model when the person hasn't picked one. Defaults to the provider's reasoning model for the media's kind. */
+  model?: string;
+  onResult?: (prompt: string) => void;
+  onError?: (message: string) => void;
+  /** Auto-select: fires with the routed model so the trigger shows it. Wire it to `MediaAnalyzer`'s `onModelChange` state. */
+  onModelChange?: (modelId: string) => void;
+  /** Replaces the routing instruction (`buildModelRoutingPrompt`). */
+  routingPrompt?: (input: ModelRoutingInput) => string;
+  /** Fires when auto-select fell back to the first listed model (no reasoning model, a failed call, or an unlisted reply). Analysis still runs. */
+  onRoutingFallback?: (result: Extract<ModelRoutingResult, { status: "fallback" }>) => void;
+}
+
+export interface MediaAnalyzerState {
+  analyzing: boolean;
+  error: string | null;
+  prompt: string | null;
+}
+
+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: () => MediaAnalyzerOptions,
+  getProvided: () => Reasoning | undefined = () => undefined
+) {
+  let state: MediaAnalyzerState = { analyzing: false, error: null, prompt: null };
+  const listeners = new Set<() => void>();
+  const set = (next: Partial<MediaAnalyzerState>) => {
+    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: AbortController | null = null;
+
+  function submit(payload: MediaAnalyzerSubmitPayload) {
+    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: string | undefined) =>
+      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: () => void) {
+      listeners.add(listener);
+      return () => void listeners.delete(listener);
+    },
+    submit,
+    cancel,
+    reset,
+  };
+}
+
+export type MediaAnalyzerStore = ReturnType<typeof createMediaAnalyzerStore>;

package/src/reasoning.ts

@@ -0,0 +1,90 @@
+import { createOpenRouterEngine } from "./engines/openrouter.js";
+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 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: Partial<Record<MediaKind, string>> = {
+  video: "google/gemini-3.8-flash",
+  audio: "google/gemini-3.8-flash",
+};
+
+/** 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 function createReasoning(config: ReasoningConfig, engine: GenerationEngine): Reasoning {
+  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: ReasoningConfig): GenerationEngine {
+  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: { reasoningEngine?: GenerationEngine; reasoningModel?: string },
+  provided: Reasoning | undefined
+): Reasoning | undefined {
+  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: Reasoning, attachments: DroppedMedia[] = []): string {
+  for (const { kind } of attachments) {
+    const model = reasoning.modelByKind[kind];
+    if (model) return model;
+  }
+  return reasoning.model;
+}

package/src/suggested-models.ts

@@ -0,0 +1,121 @@
+import type { GenerationUseCase, MediaKind, ModelOption } from "./types.js";
+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: ModelOption[] = [
+  { 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: ModelOption[] = [
+  { 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: ModelOption[] = [
+  { 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: ModelOption[] = [
+  {
+    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: Partial<Record<MediaKind, ModelOption[]>> = {
+  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: GenerationUseCase | undefined): ModelOption[] {
+  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: ReadonlyMap<string, ModelOption> = new Map(
+  [...SUGGESTED_IMAGE_MODELS, ...SUGGESTED_TEXT_TO_VIDEO_MODELS, ...SUGGESTED_IMAGE_TO_VIDEO_MODELS, ...SUGGESTED_EDIT_MODELS].map((m) => [m.id, m])
+);

package/src/types.ts

@@ -91,6 +91,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
@@ -101,6 +108,12 @@ 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";