@chai-ui/core 0.5.0 → 0.6.1

package/README.md

@@ -14,9 +14,10 @@
 
 The headless core behind CHAI's components: the data types, the
 Request → Run → Result model a submitted prompt flows through, and the
-pluggable generation engines that actually call models. No framework, no
-rendering — `@chai-ui/react` is one binding of this; a future non-React
-binding would depend on this package the same way.
+pluggable generation engines that actually call models, and the components'
+behavior as small framework-free stores. No framework, no rendering:
+`@chai-ui/react` wraps the stores in hooks, and a Vue binding will wrap the
+same stores.
 
 ## Layout
 
@@ -26,9 +27,38 @@ binding would depend on this package the same way.
 - `engines/fal.ts` — `createFalEngine`, media generation through Fal.ai (the default).
 - `engines/openrouter.ts` — `createOpenRouterEngine`, text/reasoning through OpenRouter (prompt enhancement, media analysis).
 - `media-analysis-prompts.ts` — the instruction text `MediaAnalyzer` sends, per media kind × prompt length.
+- `suggested-models.ts` — the suggested model lists per use case (Fal for generation, OpenRouter for analysis), each model with its verified aspect ratios and Fal input format; `suggestedModels(useCase)`.
+- `check-suggested-models.ts` — `checkSuggestedModels()`: checks those lists against Fal's and OpenRouter's catalogs as they are today. No key, no model run.
 - `model-routing.ts` — auto-select: `buildModelRoutingPrompt`, `parseModelRoutingReply`, and `routeModel`, which falls back to the first listed model instead of throwing.
+- `reasoning.ts` — the reasoning engine and models a `ChaiProvider` shares: `createReasoning`, `pickReasoning`, `reasoningModelFor` and the suggested defaults.
+- `composer.ts` — `createComposerStore`, what `useComposer` wraps: submit payload → runs, auto-select routing, Enhance, cancel, and image edit versions. Plus the Composer's shared types (`ComposerSubmitPayload`, `EditVersion`, …).
+- `media-analyzer.ts` — `createMediaAnalyzerStore`, what `useMediaAnalyzer` wraps.
 - `server/` — `createChaiHandler` and `toNodeHandler`, exported from `@chai-ui/core/server` (server-only).
 
+## Suggested models, and checking them
+
+The components fill their Model menus from the suggested lists when a
+builder passes none (see `@chai-ui/react`'s README). Each Fal model in them
+carries `falInput`, read from its Fal schema: where the image goes
+(`image_url`, `image_urls` or `start_image_url`) and how the aspect ratio
+is sent (`aspect_ratio`, or a named `image_size`). `buildFalRequestBody`
+uses it; for a model outside the lists it falls back to guessing from the
+id.
+
+The lists change only through package releases. `checkSuggestedModels()`
+compares them with the providers right now, from a browser or Node, with
+no key:
+
+```ts
+const { ok, checked, problems } = await checkSuggestedModels();
+```
+
+It reports a model that's gone or no longer active, a Fal model that no
+longer takes an aspect ratio or image field Chai sends or now requires a
+field Chai doesn't send, and an OpenRouter model that no longer accepts its
+media kind. Fal's catalog is read 10 models a page (`api.fal.ai/v1/models`),
+OpenRouter's from `openrouter.ai/api/v1/models`.
+
 ## The server route: `@chai-ui/core/server`
 
 The built-in engines never hold an API key. They call one route on your

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

@@ -0,0 +1,31 @@
+/** 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 declare function checkSuggestedModels(options?: {
+    fetchImpl?: typeof fetch;
+}): Promise<SuggestedModelsCheck>;
+//# sourceMappingURL=check-suggested-models.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"check-suggested-models.d.ts","sourceRoot":"","sources":["../src/check-suggested-models.ts"],"names":[],"mappings":"AAIA,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,KAAK,GAAG,YAAY,CAAC;IAC/B,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,EAAE,EAAE,OAAO,CAAC;IACZ,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,qBAAqB,EAAE,CAAC;CACnC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAQpH"}

package/dist/check-suggested-models.js

@@ -0,0 +1,123 @@
+import { SUGGESTED_ANALYSIS_MODELS, SUGGESTED_FAL_MODELS } from "./suggested-models.js";
+import { FAL_NAMED_IMAGE_SIZES } from "./engines/fal.js";
+/**
+ * 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 = {}) {
+    const fetchImpl = (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, model })));
+    const problems = [...(await checkFal(fal, fetchImpl)), ...(await checkOpenRouter(analysis, fetchImpl))];
+    return { ok: problems.length === 0, checked: fal.length + analysis.length, problems };
+}
+async function checkFal(models, fetchImpl) {
+    const query = models.map((m) => `endpoint_id=${encodeURIComponent(m.id)}`).join("&");
+    let found;
+    try {
+        // Fal answers 10 models a page, with a cursor for the next.
+        found = [];
+        let cursor;
+        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());
+            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.message}` }];
+    }
+    const problems = [];
+    const add = (modelId, problem) => 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, fetchImpl) {
+    let catalog;
+    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()).data ?? [];
+    }
+    catch (err) {
+        return [{ provider: "openrouter", modelId: "*", problem: `Couldn't reach OpenRouter's model list: ${err.message}` }];
+    }
+    const problems = [];
+    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;
+}
+/** The model's request schema, from its OpenAPI document, with a resolver for `$ref`s. */
+function inputSchema(openapi) {
+    const schemas = openapi?.components?.schemas ?? {};
+    const resolve = (s) => (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, resolve) {
+    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;
+}
+//# sourceMappingURL=check-suggested-models.js.map

package/dist/check-suggested-models.js.map

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

package/dist/composer.d.ts

@@ -0,0 +1,188 @@
+/**
+ * The Composer's behavior with no framework: turns a submit payload into
+ * `Request` → `Run` → `Result` (§6), fanning out across `engine.generate`
+ * calls and folding each one back into state as it settles. A small store
+ * (`getState` + `subscribe`) that `useComposer` (React) and the Vue
+ * composable wrap; the pure transitions live in `run.ts`.
+ */
+import { type GenerationEngine } from "./engine.js";
+import { type ModelRoutingInput, type ModelRoutingResult } from "./model-routing.js";
+import { type EditRegion } from "./region-edit.js";
+import { type Reasoning } from "./reasoning.js";
+import { type ResultStatus, type Run } from "./run.js";
+import type { DroppedMedia, GenerationUseCase, MediaKind, ModelOption } from "./types.js";
+export interface ComposerAttachment extends DroppedMedia {
+    id: string;
+}
+/**
+ * The selected generation use case, shown as a removable chip (reference:
+ * the mock's "Video"/"Image" chip) — deliberately independent of
+ * `attachments`: a use case can be picked from the attach menu with nothing
+ * attached yet (e.g. "Create video"). Composer never derives this from
+ * `attachments` itself (that's app-level policy, not a Composer opinion —
+ * the design). With none picked, `defaultUseCase` applies.
+ */
+export interface ComposerUseCase {
+    kind: MediaKind;
+    label: string;
+    /**
+     * An edit of the attached image rather than a new one: no aspect ratio,
+     * region chips when `regions` is set, and a submit needs only an image and
+     * either a prompt or a region. Images only for now.
+     */
+    edit?: boolean;
+}
+/** A plain text request — what a submit means when no use case is picked, unless the builder sets `defaultUseCase`. */
+export declare const TEXT_USE_CASE: ComposerUseCase;
+/** Editing the attached image, the attach menu's "Edit image". Pair it with `useComposer`'s `editImage` and an `EditCard`. */
+export declare const EDIT_IMAGE_USE_CASE: ComposerUseCase;
+/** One use case to run and the models picked for it. Empty `modelIds` means the engine's default model. */
+export interface ComposerSelection {
+    useCase: ComposerUseCase;
+    modelIds: string[];
+    /** The models offered for this use case: what auto-select routes among. */
+    models: ModelOption[];
+}
+/**
+ * Everything Composer itself tracks, assembled into one object at submit
+ * time — an honest snapshot of the component's own state, handed to
+ * `onSubmit` so a builder doesn't have to re-derive it from five
+ * separately-controlled props they already hold.
+ */
+export interface ComposerSubmitPayload {
+    value: string;
+    attachments: ComposerAttachment[];
+    /** The use case to run — the picked one, or `defaultUseCase` when none is picked. The first one with `multiSelectUseCases`. */
+    useCase: ComposerUseCase;
+    /** The first picked model, or null for the engine's default. */
+    modelId: string | null;
+    aspectRatio: string | null;
+    /** Everything to run: one entry per use case with its picked models. A single entry unless `multiSelectUseCases` is on. */
+    selections: ComposerSelection[];
+    /** When true, the model is chosen at submit (`useComposer` routes among each selection's `models`), not by the picks. */
+    autoSelectModel: boolean;
+    /** An edit's marked regions, each with its own instruction. Empty unless the use case is an edit. */
+    regions?: EditRegion[];
+}
+/**
+ * One version of the image being edited: the original, or the result of an
+ * edit. The composer's `edit.versions` builds these from its runs.
+ */
+export interface EditVersion {
+    id: string;
+    /** The image, once there is one. */
+    src?: string;
+    /** The image this version was edited from, shown under the progress spinner until `src` arrives. */
+    from?: string;
+    status: ResultStatus;
+    /** The regions this version was made with (none for the original). Shown faintly, for reference. */
+    regions: EditRegion[];
+    error?: string;
+}
+/** A result's `modelId` when nothing was picked: the engine runs its own default model. */
+export declare const DEFAULT_MODEL_ID = "default";
+export interface ComposerOptions {
+    /** The generation engine a submitted run actually calls. Defaults to `mockEngine`. */
+    engine?: GenerationEngine;
+    /**
+     * Engines per use-case kind, overriding `engine` for that kind — needed
+     * for multi-use-case select, since one Fal engine outputs one kind, e.g.
+     * `{ image: createFalEngine({ outputKind: "image" }), video: createFalEngine({ outputKind: "video" }) }`.
+     */
+    engineByKind?: Partial<Record<MediaKind, GenerationEngine>>;
+    /**
+     * The engine for text requests (a Composer with no use case picked, or a
+     * text use case). Defaults to `reasoningEngine`, and to a mock text engine
+     * when neither is set, so a text prompt always gets a reply.
+     */
+    textEngine?: GenerationEngine;
+    /** The model text requests use when none is picked. Defaults to the reasoning model for the attachments' kinds, then the text engine's own default. */
+    textModel?: string;
+    /**
+     * The reasoning engine Enhance calls — deliberately separate from
+     * `engine`: Fal's own text/vision access is itself an
+     * OpenRouter proxy, so defaulting Enhance to a Fal `engine` would
+     * silently double-proxy. Must return text. Set together with
+     * `reasoningModel` to override the nearest `ChaiProvider`'s pair; with
+     * neither set here nor a provider, `enhance` stays `undefined`, same
+     * shape as `Composer`'s own "omit `onEnhance` to hide the button" convention.
+     */
+    reasoningEngine?: GenerationEngine;
+    /** Set with `reasoningEngine` to override the provider's pair; used for every kind (§5.5). */
+    reasoningModel?: string;
+    /** Overrides the instruction wrapping a raw prompt for Enhance. Defaults to a generic still/video-aware rewrite instruction. */
+    enhancePrompt?: (value: string, mode?: GenerationUseCase) => string;
+    /**
+     * Auto-select: with `autoSelectModel` on in the payload, the reasoning
+     * model picks one model per use case at submit, then these fire with the
+     * pick so the Composer's trigger shows it. Wire them to the same state as
+     * Composer's `onModelChange` / `onModelIdsChange`.
+     */
+    onModelChange?: (modelId: string) => void;
+    onModelIdsChange?: (modelIds: string[]) => void;
+    /** Replaces the routing instruction (`buildModelRoutingPrompt`). */
+    routingPrompt?: (input: ModelRoutingInput) => string;
+    /**
+     * Fires when auto-select couldn't route and fell back to the first listed
+     * model: no reasoning model, a failed reasoning call (e.g. a bad key), or
+     * a reply naming no listed model. The request still runs.
+     */
+    onRoutingFallback?: (result: Extract<ModelRoutingResult, {
+        status: "fallback";
+    }>) => void;
+    /**
+     * The image to edit, when the Composer's use case is an edit (e.g.
+     * `EDIT_IMAGE_USE_CASE`) and an image is attached. While it's set, `edit`
+     * returns props for an `EditCard`, and each edit's results become new
+     * versions of the image. Changing it to another image starts over.
+     */
+    editImage?: DroppedMedia | null;
+    /** Replaces how an edit's prompt and regions become the model's prompt. Defaults to `buildRegionEditPrompt`, in the model's `regionFormat`. */
+    editPrompt?: (args: {
+        prompt: string;
+        regions: EditRegion[];
+        model?: ModelOption;
+    }) => string;
+    onRun?: (run: Run) => void;
+    onResult?: (run: Run, resultId: string) => void;
+    onError?: (run: Run, resultId: string) => void;
+}
+export interface ComposerState {
+    /** One run per use case submitted: a single run unless the Composer has `multiSelectUseCases` on. */
+    runs: Run[];
+    enhancing: boolean;
+    routing: boolean;
+    /** Edit mode. Each edit's runs are kept (not replaced by the next submit), since every result is a version of the image the person can page back to. */
+    editRuns: Run[];
+    regions: EditRegion[];
+    activeVersion: number;
+    /** The image the edit state belongs to. Another image starts over. */
+    editSource: string | null;
+    /** Numbers each image, so its original version has its own id and EditCard starts it clean. */
+    editImageCount: number;
+}
+/** Props for an `EditCard` (spread them in), and `regions` for `Composer`. */
+export interface ComposerEdit {
+    versions: EditVersion[];
+    activeVersion: number;
+    onActiveVersionChange: (index: number) => void;
+    regions: EditRegion[];
+    onRegionsChange: (regions: EditRegion[]) => void;
+}
+/**
+ * `getOptions` is read on every call, so options can change between
+ * renders; `getProvided` is the nearest provider's reasoning, if any.
+ */
+export declare function createComposerStore(getOptions: () => ComposerOptions, getProvided?: () => Reasoning | undefined): {
+    getState: () => ComposerState;
+    subscribe(listener: () => void): () => undefined;
+    submit: (payload: ComposerSubmitPayload) => void;
+    cancel: () => void;
+    enhance: (value: string) => Promise<string>;
+    edit: (s: ComposerState, editImage: DroppedMedia | null | undefined) => ComposerEdit | null;
+    reasoning: () => Reasoning | undefined;
+};
+export type ComposerStore = ReturnType<typeof createComposerStore>;
+/** One console warning per message per page load: auto-select is on with no reasoning model to route with. */
+export declare function warnNoReasoningOnce(consequence: string): void;
+//# sourceMappingURL=composer.d.ts.map

package/dist/composer.d.ts.map

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