@shop-os/modelkit 0.1.7 → 0.1.9

package/dist/catalog.d.cts

@@ -0,0 +1,479 @@
+import { ImageModel, experimental_generateVideo } from 'ai';
+
+/**
+ * Canonical vocabulary shared by every adapter. Adapters translate these
+ * values to provider field names and casing; callers never do.
+ */
+
+/** The AI SDK video model spelling: a catalog id or a provider video model instance. */
+type VideoModel = Parameters<typeof experimental_generateVideo>[0]["model"];
+type AspectRatio = "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | "4:5" | "5:4" | "21:9" | "9:21" | "97:30" | "adaptive";
+type ImageSize = "512" | "1K" | "2K" | "4K";
+type VideoResolution = "360p" | "480p" | "720p" | "768p" | "1080p" | "2k" | "4k";
+/** "xhigh" and "max" exist only on gpt-image-2.5; gpt-image-2 rejects them at the provider. */
+type ImageQuality = "auto" | "low" | "medium" | "high" | "xhigh" | "max";
+type OutputFormat = "png" | "jpeg" | "webp";
+/**
+ * A media input. `label` is a caption the adapter emits as a text part right
+ * before the media where the provider takes interleaved content (Gemini image,
+ * Omni), so a prompt can address "Image 2" or "the brand logo" by name.
+ */
+type MediaRef = {
+    url: string;
+    label?: string;
+} | {
+    bytes: Uint8Array;
+    mime: string;
+    label?: string;
+};
+/** Caller-driven Topaz upscale controls; see the topaz row and TopazImageInput. */
+interface UpscaleOptions {
+    enhanceModel?: string;
+    subjectDetection?: string;
+    faceEnhancement?: boolean;
+    faceEnhancementCreativity?: number;
+    faceEnhancementStrength?: number;
+}
+type ModelType = "text" | "image" | "video" | "audio" | "upscale" | "bg-remove";
+type Lifecycle = "active" | "hidden" | "deprecated" | "retired";
+type AdapterId = "ai-sdk-text" | "google-image" | "openai-image" | "google-genai" | "ark" | "fal" | "replicate" | "prodia" | "higgsfield" | "xai-video";
+/** Gemini image safety threshold, per category, sent only when the caller opts in. */
+type ImageSafetySetting = {
+    category: string;
+    threshold: string;
+};
+interface ImageRequest {
+    model: string;
+    prompt: string;
+    references?: MediaRef[];
+    aspectRatio?: AspectRatio;
+    size?: ImageSize;
+    exactSize?: string;
+    quality?: ImageQuality;
+    seed?: number;
+    count?: number;
+    outputFormat?: OutputFormat;
+    /** Upscale factor for upscaler rows; adapters map it to the provider's field. */
+    scaleFactor?: number;
+    /** Gemini image safety thresholds. Off (provider default) unless supplied. */
+    safetySettings?: ImageSafetySetting[];
+    /** Sampling temperature where the provider exposes one for images (Gemini). */
+    temperature?: number;
+    /** Upscaler controls beyond `scaleFactor`/`outputFormat` (Topaz). */
+    upscale?: UpscaleOptions;
+}
+/**
+ * What a caller passes to generateImage. Same field names as the AI SDK's
+ * generateImage where the concept matches: `n`, `size` as `WxH`, `abortSignal`,
+ * `providerOptions`. The model is a catalog id or alias, or an AI SDK image
+ * model instance that runs through the SDK unchanged.
+ */
+interface ImageCallOptions extends Omit<ImageRequest, "model" | "size"> {
+    model: ImageModel;
+    /** Alias of `count`. */
+    n?: number;
+    /** Catalog tier or an exact `WxH` size (alias of `exactSize`). */
+    size?: ImageSize | `${number}x${number}`;
+    abortSignal?: AbortSignal;
+    /** Reaches the provider only for AI SDK model instances; catalog rows carry their own. */
+    providerOptions?: ProviderOptions;
+}
+interface VideoRequest {
+    model: string;
+    prompt: string;
+    firstFrame?: MediaRef;
+    lastFrame?: MediaRef;
+    sourceVideo?: MediaRef;
+    referenceImages?: MediaRef[];
+    referenceVideos?: MediaRef[];
+    referenceAudios?: MediaRef[];
+    aspectRatio?: AspectRatio;
+    resolution?: VideoResolution;
+    durationSeconds?: number;
+    generateAudio?: boolean;
+    seed?: number;
+    negativePrompt?: string;
+    cfgScale?: number;
+    promptExpansion?: "fast" | "balanced" | "quality";
+    /** Provider watermark toggle (Seedance). */
+    watermark?: boolean;
+    /** Provider-side safety checker toggle (fal MiniMax). Provider default when unset. */
+    safetyChecker?: boolean;
+    mode?: "standard" | "pro";
+}
+/**
+ * What a caller passes to generateVideo. `duration` is the AI SDK spelling of
+ * `durationSeconds`. An AI SDK video model instance runs through
+ * `experimental_generateVideo` and is exposed as a settled job.
+ */
+interface VideoCallOptions extends Omit<VideoRequest, "model"> {
+    model: VideoModel;
+    /** Alias of `durationSeconds`. */
+    duration?: number;
+    abortSignal?: AbortSignal;
+    /** Reaches the provider only for AI SDK model instances; catalog rows carry their own. */
+    providerOptions?: ProviderOptions;
+}
+interface AudioRequest {
+    model: string;
+    prompt: string;
+    /** Lyria: optional reference image. MMAudio: the video to score. */
+    references?: MediaRef[];
+    sourceVideo?: MediaRef;
+    negativePrompt?: string;
+    durationSeconds?: number;
+    seed?: number;
+    /** Music models: no vocals. */
+    instrumental?: boolean;
+    /** Cancellation; combined with CallContext.signal before dispatch. */
+    abortSignal?: AbortSignal;
+}
+interface AudioResult {
+    audio: {
+        bytes: Uint8Array;
+        mime: string;
+    } | {
+        url: string;
+        expiresAt?: Date;
+    };
+    /** Lyria returns lyrics as text parts next to the audio. */
+    text?: string;
+    usage: UsageEvent;
+    raw?: JsonValue;
+}
+/** An AI SDK file part ready for generateText/generateObject, e.g. a video for understanding. */
+interface MediaPart {
+    type: "file";
+    data: string | Uint8Array;
+    mediaType: string;
+    /** Set when the bytes were uploaded to a provider file store (Gemini Files API). Call `cleanup` after the request. */
+    cleanup?: () => Promise<void>;
+}
+type RequiredInput = "firstFrame" | "sourceVideo" | "references";
+type SupportedOption = "seed" | "quality" | "negativePrompt" | "cfgScale" | "generateAudio" | "promptExpansion" | "lastFrame" | "count" | "outputFormat" | "scaleFactor" | "safetySettings" | "temperature" | "upscale" | "watermark" | "safetyChecker" | "instrumental";
+interface ReferenceLimits {
+    images?: number;
+    videos?: number;
+    audios?: number;
+    total?: number;
+    /** Provider rejects a request whose only references are audio. */
+    audioOnly?: boolean;
+}
+interface ModelConstraints {
+    aspectRatios?: AspectRatio[];
+    sizes?: ImageSize[];
+    resolutions?: VideoResolution[];
+    durations?: {
+        min: number;
+        max: number;
+    } | number[];
+    /** Curated UI choices when `durations` is a range; `resolveOptions` ignores it. */
+    durationPresets?: number[];
+    /** Curated quality choices for rows whose `supports` includes "quality". */
+    qualityOptions?: string[];
+    /**
+     * Exact pixel size per aspect ratio for rows an app must size verbatim
+     * (gpt-image-2 keeps its historic WxH contract); callers pass it as `exactSize`.
+     */
+    exactSizes?: Record<string, string>;
+    references?: ReferenceLimits;
+    requires?: RequiredInput[];
+    supports?: SupportedOption[];
+    /** Ratio is dropped, with a warning, when one of these inputs is present. */
+    ratioIgnoredWith?: ("firstFrame" | "sourceVideo")[];
+}
+/** JSON-compatible value. Provider options and raw payloads carry these, never `unknown`. */
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+/**
+ * Options handed to the provider untouched, keyed by provider name like the AI SDK's
+ * providerOptions: { anthropic: { thinking: ... } }. Values are JSON without null.
+ */
+type ProviderOptionValue = string | number | boolean | ProviderOptionValue[] | {
+    [key: string]: ProviderOptionValue;
+};
+type ProviderOptions = {
+    [provider: string]: {
+        [key: string]: ProviderOptionValue;
+    };
+};
+type UsageUnit = "tokens" | "images" | "seconds" | "reported_cost_usd" | "compute_seconds";
+type UsageModality = "TEXT" | "IMAGE" | "VIDEO" | "AUDIO";
+type PricingKind = "token" | "image_size" | "video_per_second" | "flat";
+/** What a model picker shows for a row. Free of any surface-specific ids. */
+interface CatalogDisplay {
+    /** Vendor as the UI names it: "google", "openai", "meta", "bytedance", "xai", "kuaishou", ... */
+    provider: string;
+    /** One or two sentences for the picker card. */
+    description: string;
+    /** CDN URL of the vendor or model logo. */
+    logo?: string;
+    /** Chat picker cost bucket: 1 = cheapest tier (Haiku/Flash/mini), 2 = Sonnet class, 3 = Opus/Pro/frontier. */
+    costTier?: 1 | 2 | 3;
+    /** Chat picker highlight flag. */
+    recommended?: boolean;
+    /**
+     * Picker position: lower comes first; rows without one keep catalog order
+     * after the ordered ones. Set it to surface a new model at the top.
+     */
+    sortOrder?: number;
+}
+/** Capability flags a UI keys off. Absent means false / unknown. */
+interface CatalogCapabilities {
+    /** Image rows: generates from a prompt alone. */
+    imageGenerate?: boolean;
+    /** Image rows: edits or conditions on reference images. */
+    imageEdit?: boolean;
+    /** Video rows: takes an existing video as the thing to edit or extend. */
+    acceptsSourceVideo?: boolean;
+    /** Video rows: first/last frames and reference images are mutually exclusive inputs. */
+    framesExcludeReferences?: boolean;
+    /** Text rows. `reasoning`: the model streams reasoning the UI should surface. */
+    reasoning?: boolean;
+    vision?: boolean;
+    tools?: boolean;
+    structuredOutput?: boolean;
+    contextWindow?: number;
+}
+interface CatalogModel {
+    /** Canonical id. Equals the pricing key in pro-backend credit_pricing_* tables. */
+    id: string;
+    aliases: string[];
+    label: string;
+    type: ModelType;
+    adapter: AdapterId;
+    /** Id the provider expects, e.g. dola-seedream-5-0-pro-260628. */
+    providerModelId: string;
+    lifecycle: Lifecycle;
+    replacedBy?: string;
+    /**
+     * "catalog" = offered in product pickers (Creative Studio, chat, Space Builder);
+     * "internal" = callable by id only.
+     */
+    exposure: "catalog" | "internal";
+    constraints: ModelConstraints;
+    defaults: Partial<Omit<ImageRequest, "model" | "prompt"> & Omit<VideoRequest, "model" | "prompt"> & Omit<AudioRequest, "model" | "prompt"> & {
+        temperature?: number;
+    }>;
+    /** Provider options merged under the caller's; text rows carry their reasoning / thinking tuning here. */
+    providerOptions?: ProviderOptions;
+    /**
+     * `slug` and `providerLabel` keep an app's historic usage-event names for a
+     * row (e.g. cowork emits `image_gen_<slug>` from provider `<providerLabel>`);
+     * absent means the app derives them from the id and display.provider.
+     */
+    usage: {
+        unit: UsageUnit;
+        modality: UsageModality;
+        slug?: string;
+        providerLabel?: string;
+    };
+    pricingKind: PricingKind;
+    /** Required on every `active` row so a picker can render it without a hand-written catalog. */
+    display?: CatalogDisplay;
+    capabilities?: CatalogCapabilities;
+}
+interface Warning {
+    code: "ratio_coerced" | "ratio_dropped" | "size_coerced" | "resolution_coerced" | "duration_coerced" | "references_trimmed" | "option_ignored";
+    message: string;
+    field: string;
+    from?: unknown;
+    to?: unknown;
+}
+interface ImageBytes {
+    bytes: Uint8Array;
+    mime: string;
+}
+/** An image with the AI SDK `GeneratedFile` accessors next to the kit's `bytes`/`mime`. */
+interface GeneratedImage extends ImageBytes {
+    readonly uint8Array: Uint8Array;
+    readonly base64: string;
+    readonly mediaType: string;
+}
+/** What an adapter returns. */
+interface ImageResult {
+    images: ImageBytes[];
+    usage: UsageEvent;
+    raw?: unknown;
+    /** The provider URL the images were downloaded from, when the provider hands one back. */
+    outputUrl?: string;
+}
+/** What generateImage returns: the adapter result plus `image`, SDK accessors and warnings. */
+interface ImageCallResult extends ImageResult {
+    image: GeneratedImage;
+    images: GeneratedImage[];
+    warnings: Warning[];
+}
+interface VideoResult {
+    video: {
+        url: string;
+        expiresAt?: Date;
+    } | {
+        bytes: Uint8Array;
+        mime: string;
+    };
+    usage: UsageEvent;
+    raw?: unknown;
+}
+interface VideoCallJob extends VideoJob {
+    warnings: Warning[];
+}
+interface VideoJob {
+    jobId: string;
+    poll(): Promise<{
+        status: "pending" | "running" | "succeeded" | "failed";
+        raw?: unknown;
+    }>;
+    result(opts?: {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<VideoResult>;
+}
+interface UsageEvent {
+    /** Canonical catalog id, never the provider id. */
+    model: string;
+    provider: string;
+    modality: UsageModality;
+    unit: UsageUnit;
+    quantity: number;
+    imageSize?: ImageSize;
+    imageQuality?: ImageQuality;
+    resolution?: VideoResolution;
+    durationSeconds?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    reportedCostUsd?: number;
+    raw?: unknown;
+}
+type ProviderKeyName = "openai" | "anthropic" | "google" | "xai" | "perplexity" | "deepseek" | "moonshot" | "minimax" | "ark" | "fal" | "replicate" | "prodia" | "higgsfield" | "cloudflare";
+type ProviderKeys = Partial<Record<ProviderKeyName, string>> & {
+    /** Higgsfield needs the pair; both switch together. */
+    higgsfieldSecret?: string;
+    /** Bedrock runtime credentials for Anthropic models when routing.anthropic = "bedrock". */
+    aws?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        region: string;
+        sessionToken?: string;
+    };
+};
+interface Routing {
+    /** Text models: direct provider or the Cloudflare AI Gateway. */
+    text?: "direct" | "cloudflare";
+    /** Anthropic chat via Bedrock (us. prefixed ids) or the Anthropic API. */
+    anthropic?: "direct" | "bedrock";
+    /** fal from geo-blocked regions goes through the Cloudflare passthrough. */
+    fal?: "direct" | "cloudflare-passthrough";
+    cloudflare?: {
+        accountId: string;
+        gatewayId: string;
+    };
+}
+/** Regional or proxy endpoints for providers whose base url is configurable. */
+interface AdapterEndpoints {
+    /** Ark (Seedream images, Seedance videos). Defaults to the BytePlus ap-southeast endpoint. */
+    ark?: string;
+}
+interface ModelKitConfig {
+    keys: {
+        pro: ProviderKeys;
+        enterprise?: ProviderKeys;
+    };
+    routing?: Routing;
+    /** Provider base-url overrides; unset entries use each adapter's documented default. */
+    endpoints?: AdapterEndpoints;
+    /** Called once per completed provider call. */
+    onUsage?: (event: UsageEvent) => void | Promise<void>;
+    /** Extra or replacement catalog rows, merged by id. */
+    catalogOverride?: CatalogModel[];
+    fetch?: typeof fetch;
+    logger?: Pick<Console, "debug" | "info" | "warn" | "error">;
+}
+interface CallContext {
+    /** "enterprise" picks keys.enterprise when every key for the provider is set, else falls back to pro. */
+    tier?: "pro" | "enterprise";
+    signal?: AbortSignal;
+    onUnsupported?: "error" | "coerce";
+}
+
+declare class Catalog {
+    private readonly byId;
+    private readonly byAlias;
+    constructor(models: CatalogModel[]);
+    add(model: CatalogModel): void;
+    /** Resolves a canonical id or any historical alias. */
+    resolveId(idOrAlias: string): string | undefined;
+    get(idOrAlias: string): CatalogModel | undefined;
+    require(idOrAlias: string): CatalogModel;
+    list(filter?: {
+        type?: ModelType;
+        lifecycle?: Lifecycle[];
+    }): CatalogModel[];
+    /** Merge rows by id. Used for catalogOverride. */
+    withOverrides(rows: CatalogModel[]): Catalog;
+}
+
+/** Seeded from Cowork, Space Builder and trigger-workflows. See catalog/*.ts. */
+declare const MODELS: CatalogModel[];
+
+declare const IMAGE_MODELS: CatalogModel[];
+
+declare const VIDEO_MODELS: CatalogModel[];
+
+declare const TEXT_MODELS: CatalogModel[];
+
+declare const OTHER_MODELS: CatalogModel[];
+
+type OnUnsupported = "error" | "coerce";
+interface ResolveResult<T> {
+    request: T;
+    warnings: Warning[];
+}
+/** Nearest supported ratio in the same orientation bucket, else nearest overall, by log distance. */
+declare function nearestAspectRatio(requested: AspectRatio, supported: AspectRatio[]): AspectRatio;
+declare function resolveImageOptions(model: CatalogModel, request: ImageRequest, onUnsupported?: OnUnsupported): ResolveResult<ImageRequest>;
+declare function resolveVideoOptions(model: CatalogModel, request: VideoRequest, onUnsupported?: OnUnsupported): ResolveResult<VideoRequest>;
+declare function resolveAudioOptions(model: CatalogModel, request: AudioRequest, onUnsupported?: OnUnsupported): ResolveResult<AudioRequest>;
+
+/** Provider body or the lifted detail (Gemini blockReason, fal body.detail). */
+type ProviderErrorBody = string | JsonValue;
+type ModelKitErrorCode = "unknown_model" | "unsupported_option" | "missing_input" | "content_blocked" | "provider_rejected" | "timeout" | "auth" | "network" | "rate_limited";
+interface ModelKitErrorInit {
+    code: ModelKitErrorCode;
+    message: string;
+    provider?: string;
+    model?: string;
+    status?: number;
+    body?: ProviderErrorBody;
+    cause?: unknown;
+    retryable?: boolean;
+}
+declare class ModelKitError extends Error {
+    readonly code: ModelKitErrorCode;
+    readonly provider: string | undefined;
+    readonly model: string | undefined;
+    readonly status: number | undefined;
+    readonly body: ProviderErrorBody | undefined;
+    readonly retryable: boolean;
+    constructor(init: ModelKitErrorInit);
+}
+declare function isModelKitError(err: unknown): err is ModelKitError;
+
+/**
+ * Browser-safe catalog subpath (`@shop-os/modelkit/catalog`).
+ *
+ * Catalog rows, the option resolver and error types only. No adapters, no
+ * client, no key handling, no text helpers and no provider SDKs, so the
+ * bundle is safe to ship to browsers (Space Builder pickers, vibe-shared).
+ */
+
+/** Resolve caller options against a catalog row, dispatching on `model.type`. */
+declare function resolveOptions(model: CatalogModel, request: ImageRequest | VideoRequest | AudioRequest, onUnsupported?: OnUnsupported): ResolveResult<ImageRequest | VideoRequest | AudioRequest>;
+
+export { type AdapterEndpoints, type AdapterId, type AspectRatio, type AudioRequest, type AudioResult, type CallContext, Catalog, type CatalogCapabilities, type CatalogDisplay, type CatalogModel, type GeneratedImage, IMAGE_MODELS, type ImageBytes, type ImageCallOptions, type ImageCallResult, type ImageQuality, type ImageRequest, type ImageResult, type ImageSafetySetting, type ImageSize, type JsonObject, type JsonPrimitive, type JsonValue, type Lifecycle, MODELS, type MediaPart, type MediaRef, type ModelConstraints, type ModelKitConfig, ModelKitError, type ModelKitErrorCode, type ModelKitErrorInit, type ModelType, OTHER_MODELS, type OnUnsupported, type OutputFormat, type PricingKind, type ProviderErrorBody, type ProviderKeyName, type ProviderKeys, type ProviderOptionValue, type ProviderOptions, type ReferenceLimits, type RequiredInput, type ResolveResult, type Routing, type SupportedOption, TEXT_MODELS, type UpscaleOptions, type UsageEvent, type UsageModality, type UsageUnit, VIDEO_MODELS, type VideoCallJob, type VideoCallOptions, type VideoJob, type VideoModel, type VideoRequest, type VideoResolution, type VideoResult, type Warning, isModelKitError, nearestAspectRatio, resolveAudioOptions, resolveImageOptions, resolveOptions, resolveVideoOptions };