open-model-selector 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,469 @@
+import * as react from 'react';
+
+/** Union of all supported model type identifiers. */
+type ModelType = 'text' | 'image' | 'video' | 'inpaint' | 'embedding' | 'tts' | 'asr' | 'upscale';
+interface Deprecation {
+    /** ISO 8601 date string indicating when the model is/was deprecated */
+    date: string;
+}
+interface BaseModel {
+    id: string;
+    name: string;
+    provider: string;
+    created: number;
+    type: ModelType;
+    description?: string;
+    privacy?: 'private' | 'anonymized';
+    offline?: boolean;
+    betaModel?: boolean;
+    /** Whether the user has marked this model as a favorite.
+     *  CLIENT-SIDE OVERLAY — this field is NEVER returned by any API.
+     *  It is a UI-layer concern managed via localStorage in the ModelSelector component.
+     *  Normalizers MUST default this to `false`; the component hydrates the real value
+     *  from localStorage at render time. */
+    is_favorite?: boolean;
+    modelSource?: string;
+    traits?: string[];
+    /** Deprecation info if this model is scheduled for or has been deprecated. */
+    deprecation?: Deprecation;
+}
+
+interface TextPricing {
+    prompt?: number;
+    completion?: number;
+    cache_input?: number;
+    cache_write?: number;
+}
+/** Feature flags indicating what a text model supports (vision, reasoning, function calling, etc.). */
+interface TextCapabilities {
+    optimizedForCode?: boolean;
+    supportsVision?: boolean;
+    supportsReasoning?: boolean;
+    supportsFunctionCalling?: boolean;
+    supportsResponseSchema?: boolean;
+    supportsLogProbs?: boolean;
+    supportsAudioInput?: boolean;
+    supportsVideoInput?: boolean;
+    supportsWebSearch?: boolean;
+    quantization?: string;
+}
+/** Default sampling parameter values for a text model. */
+interface TextConstraints {
+    temperature?: {
+        default: number;
+    };
+    top_p?: {
+        default: number;
+    };
+}
+/** A text/chat completion model with context length, pricing, and optional capabilities. */
+interface TextModel extends BaseModel {
+    type: 'text';
+    context_length: number;
+    pricing: TextPricing;
+    capabilities?: TextCapabilities;
+    constraints?: TextConstraints;
+}
+
+interface ImagePricing {
+    generation?: number;
+    upscale_2x?: number;
+    upscale_4x?: number;
+    resolutions?: Record<string, number>;
+}
+/** Generation constraints for an image model (prompt limits, aspect ratios, resolutions, etc.). */
+interface ImageConstraints {
+    promptCharacterLimit?: number;
+    steps?: {
+        default: number;
+        max: number;
+    };
+    widthHeightDivisor?: number;
+    aspectRatios?: string[];
+    defaultAspectRatio?: string;
+    resolutions?: string[];
+    defaultResolution?: string;
+}
+interface ImageModel extends BaseModel {
+    type: 'image';
+    pricing: ImagePricing;
+    constraints?: ImageConstraints;
+    /** Whether web search is supported for this image model.
+     *  In the Venice API, this field lives at `model_spec.supportsWebSearch`
+     *  (a sibling of `model_spec.constraints`), NOT inside `model_spec.constraints`. */
+    supportsWebSearch?: boolean;
+}
+
+/** Generation constraints for a video model (aspect ratios, durations, audio support, etc.). */
+interface VideoConstraints {
+    model_type?: 'text-to-video' | 'image-to-video' | 'video';
+    aspect_ratios?: string[];
+    resolutions?: string[];
+    durations?: string[];
+    audio?: boolean;
+    audio_configurable?: boolean;
+    audio_input?: boolean;
+    video_input?: boolean;
+}
+/** A video generation model. Note: no pricing data — the Venice API omits it for video models. */
+interface VideoModel extends BaseModel {
+    type: 'video';
+    constraints?: VideoConstraints;
+    model_sets?: string[];
+}
+
+interface InpaintPricing {
+    generation?: number;
+}
+/** Generation constraints for an inpainting model (aspect ratios, image combining). */
+interface InpaintConstraints {
+    aspectRatios?: string[];
+    combineImages?: boolean;
+}
+/** An image inpainting/editing model with pricing and generation constraints. */
+interface InpaintModel extends BaseModel {
+    type: 'inpaint';
+    pricing: InpaintPricing;
+    constraints?: InpaintConstraints;
+}
+
+interface EmbeddingPricing {
+    input?: number;
+    output?: number;
+}
+/** A text embedding model with per-token pricing. */
+interface EmbeddingModel extends BaseModel {
+    type: 'embedding';
+    pricing: EmbeddingPricing;
+}
+
+interface TtsPricing {
+    input?: number;
+}
+/** A text-to-speech model with pricing and available voice options. */
+interface TtsModel extends BaseModel {
+    type: 'tts';
+    pricing: TtsPricing;
+    voices?: string[];
+}
+
+interface AsrPricing {
+    per_audio_second?: number;
+}
+/** An automatic speech recognition (speech-to-text) model with per-second pricing. */
+interface AsrModel extends BaseModel {
+    type: 'asr';
+    pricing: AsrPricing;
+}
+
+interface UpscalePricing {
+    generation?: number;
+}
+/** An image upscaling model with flat per-generation pricing. */
+interface UpscaleModel extends BaseModel {
+    type: 'upscale';
+    pricing: UpscalePricing;
+}
+
+/** Discriminated union of all supported model types. Use `model.type` to narrow. */
+type AnyModel = TextModel | ImageModel | VideoModel | InpaintModel | EmbeddingModel | TtsModel | AsrModel | UpscaleModel;
+
+/** Safely coerce an unknown value to a number. Returns undefined for non-numeric/NaN. */
+declare function toNum(v: unknown): number | undefined;
+/** Extract shared BaseModel fields from a raw API response object.
+ *  Venice nests most metadata under model_spec; other providers use top-level fields.
+ *  This helper checks both locations with model_spec taking priority for Venice-specific fields. */
+declare function extractBaseFields(raw: Record<string, unknown>): Omit<BaseModel, 'type'>;
+
+/** Known model ID patterns for heuristic type inference.
+ *  Used when the API response lacks an explicit `type` field (non-Venice providers).
+ *  Exported so consumers can inspect or extend. */
+declare const MODEL_ID_TYPE_PATTERNS: Array<[RegExp, ModelType]>;
+/** Infer model type from its ID using naming conventions.
+ *  Returns undefined if no pattern matches (caller should fall back to 'text'). */
+declare function inferTypeFromId(id: string): ModelType | undefined;
+
+/** Normalize a raw API response object into a TextModel. */
+declare function normalizeTextModel(raw: Record<string, unknown>): TextModel;
+
+/** Normalize a raw API response object into an ImageModel. */
+declare function normalizeImageModel(raw: Record<string, unknown>): ImageModel;
+
+/** Normalize a raw API response object into a VideoModel.
+ *  Note: Video models have NO pricing data from the Venice API. */
+declare function normalizeVideoModel(raw: Record<string, unknown>): VideoModel;
+
+/** Normalize a raw API response object into an InpaintModel. */
+declare function normalizeInpaintModel(raw: Record<string, unknown>): InpaintModel;
+
+/** Normalize a raw API response object into an EmbeddingModel.
+ *  Note: Venice embedding models have BOTH input and output pricing. */
+declare function normalizeEmbeddingModel(raw: Record<string, unknown>): EmbeddingModel;
+
+/** Normalize a raw API response object into a TtsModel. */
+declare function normalizeTtsModel(raw: Record<string, unknown>): TtsModel;
+
+/** Normalize a raw API response object into an AsrModel. */
+declare function normalizeAsrModel(raw: Record<string, unknown>): AsrModel;
+
+/** Normalize a raw API response object into an UpscaleModel. */
+declare function normalizeUpscaleModel(raw: Record<string, unknown>): UpscaleModel;
+
+/** Function that extracts the array of raw model objects from an API response body. */
+type ResponseExtractor = (body: Record<string, unknown> | unknown[]) => Record<string, unknown>[];
+/** Function that normalizes a single raw model object into an AnyModel. */
+type ModelNormalizer = (raw: Record<string, unknown>) => AnyModel;
+/** Default response extractor handling common API response shapes:
+ *  - Top-level array → return as-is
+ *  - `{ data: [...] }` (OpenAI standard) → return data
+ *  - `{ models: [...] }` → return models
+ *  - Fallback → empty array */
+declare function defaultResponseExtractor(body: Record<string, unknown> | unknown[]): Record<string, unknown>[];
+/** Default dispatching model normalizer.
+ *  Uses three-tier type resolution:
+ *  1. Explicit `raw.type` field (Venice, custom providers)
+ *  2. Heuristic inference from model ID patterns (OpenAI, OpenRouter, etc.)
+ *  3. Fallback to 'text' — safe default for most providers */
+declare function defaultModelNormalizer(raw: Record<string, unknown>): AnyModel;
+
+/** A fetch-compatible function signature. Used for SSR, testing, or proxy scenarios. */
+type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
+interface UseModelsProps {
+    baseUrl?: string;
+    apiKey?: string;
+    /** Filter results to a specific model type. If omitted, returns all types. */
+    type?: ModelType;
+    /**
+     * Query parameters to append to the /models endpoint URL.
+     *
+     * Venice.ai requires `{ type: 'all' }` to return non-text models.
+     * Other providers typically need no query params.
+     *
+     * @default {}
+     */
+    queryParams?: Record<string, string>;
+    fetcher?: FetchFn;
+    responseExtractor?: ResponseExtractor;
+    normalizer?: ModelNormalizer;
+}
+interface UseModelsResult {
+    models: AnyModel[];
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * Fetches and normalizes AI models from an OpenAI-compatible `/models` endpoint.
+ * Handles loading state, errors, abort/timeout, and optional client-side type filtering.
+ *
+ * @example
+ * ```ts
+ * const { models, loading, error } = useModels({ baseUrl: "/api/v1", type: "text" })
+ * ```
+ */
+declare function useModels(props: UseModelsProps): UseModelsResult;
+
+/** Sentinel value representing system default model selection */
+declare const SYSTEM_DEFAULT_VALUE: "system_default";
+/**
+ * Props for the ModelSelector component.
+ *
+ * The component can operate in two modes:
+ * - **Managed Mode**: Provide `baseUrl` (and optionally `apiKey`) to fetch models from an API
+ * - **Controlled Mode**: Provide a static `models` array directly
+ */
+interface ModelSelectorProps {
+    /**
+     * Static list of models to display. When a non-empty array is provided,
+     * the internal API fetch is disabled and only these models are shown.
+     */
+    models?: AnyModel[];
+    /** Base URL for the OpenAI-compatible API endpoint (e.g., "https://api.venice.ai/api/v1") */
+    baseUrl?: string;
+    /** API key for authentication. Warning: This is visible in browser DevTools. Consider using a backend proxy. */
+    apiKey?: string;
+    /** Filter results to a specific model type. If omitted, returns all types. */
+    type?: ModelType;
+    /**
+     * Query parameters appended to the /models endpoint URL as a query string.
+     * For Venice.ai, pass { type: 'text' } or { type: 'all' } to filter models server-side.
+     * @default {}
+     */
+    queryParams?: Record<string, string>;
+    /**
+     * Custom fetch function for SSR, testing, or proxy scenarios.
+     * If not provided, uses global fetch.
+     */
+    fetcher?: UseModelsProps['fetcher'];
+    /**
+     * Custom function to extract the raw model array from the API response body.
+     * @see UseModelsProps.responseExtractor
+     */
+    responseExtractor?: UseModelsProps['responseExtractor'];
+    /**
+     * Custom function to normalize each raw model object into an AnyModel.
+     * @see UseModelsProps.normalizer
+     */
+    normalizer?: UseModelsProps['normalizer'];
+    /** Currently selected model ID (controlled component pattern) */
+    value?: string;
+    /**
+     * Callback fired when a model is selected.
+     * Receives the model ID and the full model object (or `null` for the system-default sentinel).
+     * If omitted, selections are silently ignored (read-only / display-only usage).
+     */
+    onChange?: (modelId: string, model: AnyModel | null) => void;
+    /** Callback fired when a model is favorited/unfavorited. Only relevant if favorites are controlled. */
+    onToggleFavorite?: (modelId: string) => void;
+    /** Placeholder text shown when no model is selected. @default "Select model..." */
+    placeholder?: string;
+    /** Current sort order for models. If provided, component operates in controlled mode for sorting. */
+    sortOrder?: "name" | "created";
+    /** Callback fired when sort order changes. Only relevant if `sortOrder` is controlled. */
+    onSortChange?: (order: "name" | "created") => void;
+    /** Popover placement relative to the trigger. @default "bottom" */
+    side?: "top" | "bottom" | "left" | "right";
+    /** Additional CSS class name(s) to apply to the root element */
+    className?: string;
+    /**
+     * Custom localStorage key for persisting favorites in uncontrolled mode.
+     * @default "open-model-selector-favorites"
+     */
+    storageKey?: string;
+    /** Whether to show the "Use System Default" option. @default true */
+    showSystemDefault?: boolean;
+    /**
+     * Whether to show deprecated models. Default: true.
+     * When false, models with deprecation.date in the past are hidden.
+     * Models with future deprecation dates are always shown with a warning.
+     */
+    showDeprecated?: boolean;
+    /** When true, prevents opening the selector and dims the trigger button. */
+    disabled?: boolean;
+}
+/**
+ * A searchable, accessible model selector combobox for AI models.
+ * Supports managed mode (fetches from API) and controlled mode (static model list).
+ * Features include favorites, sorting, deprecation warnings, and screen-reader announcements.
+ *
+ * @example
+ * ```tsx
+ * <ModelSelector type="text" baseUrl="/api/v1" onChange={(id) => setModel(id)} />
+ * ```
+ */
+declare const ModelSelector: react.ForwardRefExoticComponent<ModelSelectorProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Pre-configured ModelSelector that only displays text/chat models.
+ *
+ * @example
+ * ```tsx
+ * <TextModelSelector baseUrl="/api/v1" onChange={(id) => setModel(id)} />
+ * ```
+ */
+declare const TextModelSelector: react.ForwardRefExoticComponent<Omit<ModelSelectorProps, "type"> & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Pre-configured ModelSelector that only displays image generation models.
+ *
+ * @example
+ * ```tsx
+ * <ImageModelSelector baseUrl="/api/v1" onChange={(id) => setModel(id)} />
+ * ```
+ */
+declare const ImageModelSelector: react.ForwardRefExoticComponent<Omit<ModelSelectorProps, "type"> & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Pre-configured ModelSelector that only displays video generation models.
+ *
+ * @example
+ * ```tsx
+ * <VideoModelSelector baseUrl="/api/v1" onChange={(id) => setModel(id)} />
+ * ```
+ */
+declare const VideoModelSelector: react.ForwardRefExoticComponent<Omit<ModelSelectorProps, "type"> & react.RefAttributes<HTMLDivElement>>;
+
+/** Check whether a deprecation date is in the past.
+ *  Date-only ISO 8601 strings ("2025-01-15") are parsed as UTC midnight per the
+ *  ES spec, but we normalize explicitly to avoid any cross-engine ambiguity.
+ *  Returns false for invalid / unparseable date strings. */
+declare function isDeprecated(dateStr: string): boolean;
+
+/**
+ * Formats a per-token price into a human-readable per-million-tokens string.
+ *
+ * Accepts the price as a per-token value (matching the OpenAI / OpenRouter
+ * convention) and multiplies by 1,000,000 to display the per-million rate.
+ *
+ * @param value - Price per token as a number or numeric string.
+ *   Accepts `undefined`, `null`, empty string, or `NaN` — all return `"—"`.
+ * @returns A formatted dollar string (e.g. `"$30.00"`).
+ *   - Returns `"—"` for missing, empty, or non-numeric input.
+ *   - Uses 2 decimal places when the per-million value is ≥ $0.01.
+ *   - Uses 6 decimal places when the per-million value is < $0.01
+ *     (to preserve precision for very cheap models).
+ *
+ * @example
+ * ```ts
+ * formatPrice(0.00003)    // "$30.00"   (per-token → per-million)
+ * formatPrice("0.000015") // "$15.00"
+ * formatPrice(1e-12)      // "$0.000001"
+ * formatPrice(undefined)  // "—"
+ * ```
+ *
+ */
+declare function formatPrice(value: string | number | undefined | null): string;
+/**
+ * Formats a token count into a compact human-readable string.
+ *
+ * @param tokens - Raw token count (e.g. `128000`, `1_000_000`).
+ * @returns A compact string like `"128k"` or `"1M"`.
+ *   - Values ≥ 1,000,000 are shown in millions (e.g. `"1M"`, `"1.5M"`).
+ *   - Values < 1,000 are shown as exact numbers (e.g. `500` → `"500"`).
+ *   - Values ≥ 1,000 and < 1,000,000 are divided by 1,000 and rounded to the nearest
+ *     integer (e.g. `8192` → `"8k"`, `1000` → `"1k"`).
+ *
+ * @example
+ * ```ts
+ * formatContextLength(128000)    // "128k"
+ * formatContextLength(1_000_000) // "1M"
+ * formatContextLength(1_500_000) // "1.5M"
+ * ```
+ *
+ */
+declare function formatContextLength(tokens: number): string;
+/**
+ * Format a flat USD price (per-generation, per-inpaint, per-upscale).
+ * Unlike formatPrice which handles per-token values, this formats absolute USD amounts.
+ * Examples: 0.04 → "$0.04", 0.18 → "$0.18", 0 → "$0.00"
+ */
+declare function formatFlatPrice(usd: number | undefined | null): string;
+/**
+ * Format a per-audio-second price.
+ * Examples: 0.01 → "$0.01 / sec", 0.006 → "$0.006 / sec"
+ */
+declare function formatAudioPrice(perSecondUsd: number | undefined | null): string;
+/**
+ * Format an array of duration strings into a range.
+ * Examples: ["5", "10", "30"] → "5s – 30s", ["10"] → "10s", [] → "—"
+ * Handles both numeric strings and strings that may already have units.
+ */
+declare function formatDuration(durations: string[] | undefined | null): string;
+/**
+ * Format an array of resolution strings into a comma-separated list.
+ * Examples: ["720p", "1080p", "4K"] → "720p, 1080p, 4K", [] → "—"
+ */
+declare function formatResolutions(resolutions: string[] | undefined | null): string;
+/**
+ * Format an array of aspect ratio strings into a comma-separated list.
+ * Examples: ["16:9", "9:16", "1:1"] → "16:9, 9:16, 1:1", [] → "—"
+ */
+declare function formatAspectRatios(ratios: string[] | undefined | null): string;
+
+/** Props for TextModelSelector — same as ModelSelectorProps but without `type`. */
+type TextModelSelectorProps = Omit<ModelSelectorProps, 'type'>;
+/** Props for ImageModelSelector — same as ModelSelectorProps but without `type`. */
+type ImageModelSelectorProps = Omit<ModelSelectorProps, 'type'>;
+/** Props for VideoModelSelector — same as ModelSelectorProps but without `type`. */
+type VideoModelSelectorProps = Omit<ModelSelectorProps, 'type'>;
+
+export { type AnyModel, type AsrModel, type AsrPricing, type BaseModel, type Deprecation, type EmbeddingModel, type EmbeddingPricing, type FetchFn, type ImageConstraints, type ImageModel, ImageModelSelector, type ImageModelSelectorProps, type ImagePricing, type InpaintConstraints, type InpaintModel, type InpaintPricing, MODEL_ID_TYPE_PATTERNS, type ModelNormalizer, ModelSelector, type ModelSelectorProps, type ModelType, type ResponseExtractor, SYSTEM_DEFAULT_VALUE, type TextCapabilities, type TextConstraints, type TextModel, TextModelSelector, type TextModelSelectorProps, type TextPricing, type TtsModel, type TtsPricing, type UpscaleModel, type UpscalePricing, type UseModelsProps, type UseModelsResult, type VideoConstraints, type VideoModel, VideoModelSelector, type VideoModelSelectorProps, defaultModelNormalizer, defaultResponseExtractor, extractBaseFields, formatAspectRatios, formatAudioPrice, formatContextLength, formatDuration, formatFlatPrice, formatPrice, formatResolutions, inferTypeFromId, isDeprecated, normalizeAsrModel, normalizeEmbeddingModel, normalizeImageModel, normalizeInpaintModel, normalizeTextModel, normalizeTtsModel, normalizeUpscaleModel, normalizeVideoModel, toNum, useModels };