@llumiverse/common/lib/types/types.d.ts

Public types, enums and options used by Llumiverse API.

import type { BedrockOptions } from './options/bedrock.js';
import type { TextFallbackOptions } from './options/fallback.js';
import type { GroqOptions } from './options/groq.js';
import type { OpenAiOptions } from './options/openai.js';
import type { VertexAIOptions } from './options/vertexai.js';
export declare enum Providers {
    openai = "openai",
    openai_compatible = "openai_compatible",
    azure_openai = "azure_openai",
    azure_foundry = "azure_foundry",
    huggingface_ie = "huggingface_ie",
    replicate = "replicate",
    bedrock = "bedrock",
    vertexai = "vertexai",
    togetherai = "togetherai",
    mistralai = "mistralai",
    groq = "groq",
    watsonx = "watsonx",
    xai = "xai",
    anthropic = "anthropic"
}
export interface ProviderParams {
    id: Providers;
    name: string;
    requiresApiKey: boolean;
    requiresEndpointUrl: boolean;
    endpointPlaceholder?: string;
    supportSearch?: boolean;
}
export declare const ProviderList: Record<Providers, ProviderParams>;
export interface EmbeddingsOptions {
    /**
     * The text to generate the embeddings for. One of text or image is required.
     */
    text?: string;
    /**
     * The image to generate embeddings for
     */
    image?: string;
    /**
     * The model to use to generate the embeddings. Optional.
     */
    model?: string;
}
export interface EmbeddingsResult {
    /**
     * The embedding vectors corresponding to the words in the input text.
     */
    values: number[];
    /**
     * The model used to generate the embeddings.
     */
    model: string;
    /**
     * Number of tokens of the input text.
     */
    token_count?: number;
}
export interface ResultValidationError {
    code: 'validation_error' | 'json_error' | 'content_policy_violation';
    message: string;
    data?: CompletionResult[];
}
/**
 * Context information for LlumiverseError.
 * Provides details about where and how the error occurred.
 */
export interface LlumiverseErrorContext {
    /** The provider that generated the error (e.g., 'openai', 'bedrock', 'vertexai') */
    provider: string;
    /** The model that was being used when the error occurred */
    model: string;
    /** The operation that failed */
    operation: 'execute' | 'stream';
}
/**
 * Standardized error class for Llumiverse driver errors.
 *
 * Normalizes errors from different LLM providers (OpenAI, Anthropic, Bedrock, VertexAI, etc.)
 * into a consistent format. The primary value is the `retryable` flag, which enables upstream
 * consumers to implement smart retry logic.
 *
 * @example
 * ```typescript
 * try {
 *   const result = await driver.execute(segments, options);
 * } catch (error) {
 *   if (LlumiverseError.isLlumiverseError(error)) {
 *     console.log(`Provider: ${error.context.provider}`);
 *     console.log(`Model: ${error.context.model}`);
 *     console.log(`Retryable: ${error.retryable}`);
 *
 *     if (error.retryable) {
 *       // Implement retry logic with exponential backoff
 *       await retryWithBackoff(() => driver.execute(segments, options));
 *     } else {
 *       // Handle non-retryable error (e.g., invalid API key, malformed request)
 *       logError(error);
 *     }
 *   }
 *   throw error;
 * }
 * ```
 */
export declare class LlumiverseError extends Error {
    /**
     * HTTP status code (e.g., 429, 500) if available.
     * Undefined if the error doesn't have a numeric status code.
     */
    readonly code?: number;
    /**
     * Provider-specific error name/type (e.g., "ThrottlingException", "ValidationException").
     * Optional - used to preserve the semantic error type from the provider SDK.
     */
    readonly name: string;
    /**
     * Whether this error is retryable.
     * - True: Definitely retryable (rate limits, timeouts, server errors)
     * - False: Definitely not retryable (auth failures, invalid requests, malformed schemas)
     * - Undefined: Unknown retryability - allows consumers to decide default behavior
     *
     * When undefined, consumers can choose their retry strategy:
     * - Conservative: Don't retry unknown errors (avoid spam)
     * - Resilient: Retry unknown errors (prioritize success)
     */
    readonly retryable?: boolean;
    /**
     * Context about where and how the error occurred.
     * Includes provider, model, operation type.
     */
    readonly context: LlumiverseErrorContext;
    /**
     * The original error from the provider SDK.
     * Preserved for debugging and detailed error inspection.
     */
    readonly originalError: unknown;
    constructor(message: string, retryable: boolean | undefined, context: LlumiverseErrorContext, originalError: unknown, code?: number, name?: string);
    /**
     * Serialize the error to JSON for logging or transmission.
     * Includes all error properties except the original error object itself.
     */
    toJSON(): Record<string, unknown>;
    /**
     * Type guard to check if an error is a LlumiverseError.
     * Useful for conditional error handling.
     *
     * @param error - The error to check
     * @returns True if the error is a LlumiverseError
     */
    static isLlumiverseError(error: unknown): error is LlumiverseError;
}
export interface BaseResult {
    type: "text" | "json" | "image";
    value: any;
}
export interface TextResult extends BaseResult {
    type: "text";
    value: string;
}
export interface JsonResult extends BaseResult {
    type: "json";
}
export interface ImageResult extends BaseResult {
    type: "image";
    value: string;
}
/**
 * @discriminator type
 */
export type CompletionResult = TextResult | JsonResult | ImageResult;
export interface CompletionChunkObject {
    result: CompletionResult[];
    token_usage?: ExecutionTokenUsage;
    finish_reason?: "stop" | "length" | string;
    /**
     * Tool calls returned by the model during streaming.
     * Each chunk may contain partial tool call information that needs to be aggregated.
     */
    tool_use?: ToolUse[];
}
/**
 * Tool definition for LLM tool use.
 * The input_schema uses a permissive type to support both:
 * - AJV's JSONSchemaType<T> for type-safe schema generation
 * - Plain object schemas for simpler cases
 */
export interface ToolDefinition {
    name: string;
    description?: string;
    input_schema: {
        type?: unknown;
        properties?: Record<string, unknown> | null | undefined;
        required?: readonly string[] | string[];
        additionalProperties?: unknown;
        [k: string]: unknown;
    };
}
/**
 * A tool use instance represents a call to a tool.
 * The id property is used to identify the tool call.
 */
export interface ToolUse<ParamsT = JSONObject> {
    id: string;
    tool_name: string;
    tool_input: ParamsT | null;
    /**
     * Gemini thinking models require thought_signature to be passed back with tool results.
     * This preserves the model's reasoning state during multi-turn tool use.
     */
    thought_signature?: string;
}
export interface Completion {
    result: CompletionResult[];
    token_usage?: ExecutionTokenUsage;
    /**
     * Contains the tools from which the model awaits information.
     */
    tool_use?: ToolUse[];
    /**
     * The finish reason as reported by the model: stop | length or other model specific values
     */
    finish_reason?: "stop" | "length" | "tool_use" | string;
    /**
     * Set only if a result validation error occurred, otherwise if the result is valid the error field is undefined
     * This can only be set if the result_schema is set and the result could not be parsed as a json or if the result does not match the schema
     */
    error?: ResultValidationError;
    /**
     * The original response. Only included if the option include_original_response is set to true and the request is made using execute. Not supported when streaming.
     */
    original_response?: Record<string, any>;
    /**
     * The conversation context. This is an opaque structure that can be passed to the next request to restore the context.
     */
    conversation?: unknown;
}
export interface ExecutionResponse<PromptT = any> extends Completion {
    prompt: PromptT;
    /**
     * The time it took to execute the request in seconds
     */
    execution_time?: number;
    /**
     * The number of chunks for streamed executions
     */
    chunks?: number;
}
export interface CompletionStream<PromptT = any> extends AsyncIterable<string> {
    completion: ExecutionResponse<PromptT> | undefined;
}
/**
 * Minimal logger interface for LLM drivers.
 * Follows pino v10 signature: supports message-only or object-first (never message-first).
 * - Message-only: logger.info("message")
 * - Object-first: logger.info({ data }, "message")
 * - PREVENTS: logger.info("message", { data }) - compile error (objects not allowed in ...args)
 *
 * Additional args must be primitives (string | number | boolean) for string interpolation.
 */
export interface Logger {
    debug(msg: string, ...args: (string | number | boolean)[]): void;
    debug<T>(obj: T, msg?: T extends string ? never : string, ...args: (string | number | boolean)[]): void;
    info(msg: string, ...args: (string | number | boolean)[]): void;
    info<T>(obj: T, msg?: T extends string ? never : string, ...args: (string | number | boolean)[]): void;
    warn(msg: string, ...args: (string | number | boolean)[]): void;
    warn<T>(obj: T, msg?: T extends string ? never : string, ...args: (string | number | boolean)[]): void;
    error(msg: string, ...args: (string | number | boolean)[]): void;
    error<T>(obj: T, msg?: T extends string ? never : string, ...args: (string | number | boolean)[]): void;
}
export interface DriverOptions {
    logger?: Logger | "console";
}
export type JSONSchemaTypeName = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null" | "any";
export type JSONSchemaType = string | number | boolean | JSONSchemaObject | JSONSchemaArray | null;
export interface JSONSchemaObject {
    [key: string]: JSONSchemaType;
}
export interface JSONSchemaArray extends Array<JSONSchemaType> {
}
export interface JSONSchemaProperties {
    [key: string]: JSONSchema;
}
export interface JSONSchema {
    type?: JSONSchemaTypeName | JSONSchemaTypeName[];
    description?: string;
    properties?: JSONSchemaProperties;
    additionalProperties?: boolean | JSONSchema;
    required?: string[];
    [k: string]: any;
}
export type PromptFormatter<T = any> = (messages: PromptSegment[], schema?: JSONSchema) => T;
export interface PromptOptions {
    model: string;
    /**
     * A custom formatter to use for format the final model prompt from the input prompt segments.
     * If no one is specified the driver will choose a formatter compatible with the target model
     */
    format?: PromptFormatter;
    result_schema?: JSONSchema;
}
export interface StatelessExecutionOptions extends PromptOptions {
    /**
     * If set to true the original response from the target LLM will be included in the response under the original_response field.
     * This is useful for debugging and for some advanced use cases.
     * It is ignored on streaming requests
     */
    include_original_response?: boolean;
    model_options?: ModelOptions;
    /**
     * @deprecated This is deprecated. Use CompletionResult.type information instead.
     */
    output_modality?: Modalities;
}
export interface ExecutionOptions extends StatelessExecutionOptions {
    /**
     * Available tools for the request
     */
    tools?: ToolDefinition[];
    /**
     * This is an opaque structure that provides a conversation context
     * Each driver implementation will return a conversation property in the execution response
     * that can be passed here to restore the context when a new prompt is sent to the model.
     */
    conversation?: unknown | null;
    /**
     * Labels for billing attribution and cost tracking.
     * Passed through to provider APIs that support request-level labels (e.g. Vertex AI).
     * Keys and values must be lowercase, max 64 characters, containing only letters, numbers, underscores, and dashes.
     */
    labels?: Record<string, string>;
    /**
     * Number of turns to keep images in conversation history before stripping them.
     * - 0 (default): Strip images immediately after each turn
     * - 1: Keep images for current turn only, strip in next turn
     * - N: Keep images for N turns before stripping
     * - undefined: Same as 0, strip immediately
     *
     * Images are stripped to prevent JSON.stringify corruption (Uint8Array) and reduce storage bloat (base64).
     */
    stripImagesAfterTurns?: number;
    /**
     * Maximum tokens to keep for text content in tool results.
     * Text exceeding this limit will be truncated with a "[Content truncated...]" marker.
     * - undefined/0: No text truncation (default)
     * - N > 0: Truncate text to approximately N tokens (using ~4 chars/token estimate)
     */
    stripTextMaxTokens?: number;
    /**
     * Number of turns to keep heartbeat messages before stripping.
     * - 0: Strip immediately
     * - 1 (default): Keep for 1 turn then strip
     * - undefined: Same as 1, strip after 1 turn
     */
    stripHeartbeatsAfterTurns?: number;
}
export declare enum SharedOptions {
    max_tokens = "max_tokens",
    temperature = "temperature",
    top_p = "top_p",
    top_k = "top_k",
    presence_penalty = "presence_penalty",
    frequency_penalty = "frequency_penalty",
    stop_sequence = "stop_sequence",
    effort = "effort",
    seed = "seed",
    number_of_images = "number_of_images"
}
export declare enum OptionType {
    numeric = "numeric",
    enum = "enum",
    boolean = "boolean",
    string_list = "string_list"
}
export type ReasoningEffort = "low" | "medium" | "high";
/**
 * @discriminator _option_id
 */
export type ModelOptions = TextFallbackOptions | VertexAIOptions | BedrockOptions | OpenAiOptions | GroqOptions;
export interface ModelOptionsInfo {
    options: ModelOptionInfoItem[];
    _option_id: string;
}
export type ModelOptionInfoItem = NumericOptionInfo | EnumOptionInfo | BooleanOptionInfo | StringListOptionInfo;
interface OptionInfoPrototype {
    type: OptionType;
    name: string;
    description?: string;
    refresh?: boolean;
}
export interface NumericOptionInfo extends OptionInfoPrototype {
    type: OptionType.numeric;
    value?: number;
    min?: number;
    max?: number;
    step?: number;
    integer?: boolean;
    default?: number;
}
export interface EnumOptionInfo extends OptionInfoPrototype {
    type: OptionType.enum;
    value?: string;
    enum: Record<string, string>;
    default?: string;
}
export interface BooleanOptionInfo extends OptionInfoPrototype {
    type: OptionType.boolean;
    value?: boolean;
    default?: boolean;
}
export interface StringListOptionInfo extends OptionInfoPrototype {
    type: OptionType.string_list;
    value?: string[];
    default?: string[];
}
export declare enum PromptRole {
    safety = "safety",
    system = "system",
    user = "user",
    assistant = "assistant",
    negative = "negative",
    mask = "mask",
    /**
     * Used to send the response of a tool
     */
    tool = "tool"
}
export interface PromptSegment {
    role: PromptRole;
    content: string;
    /**
     * The tool use id if the segment is a tool response
     */
    tool_use_id?: string;
    /**
     * Gemini thinking models require thought_signature to be passed back with tool results.
     * This should be copied from the ToolUse.thought_signature when sending tool responses.
     */
    thought_signature?: string;
    files?: DataSource[];
}
export interface ExecutionTokenUsage {
    prompt?: number;
    result?: number;
    total?: number;
    /**
     * Number of input tokens read from prompt cache (discounted rate).
     */
    prompt_cached?: number;
    /**
     * Number of input tokens written to prompt cache.
     */
    prompt_cache_write?: number;
    prompt_new?: number;
}
/**
 * @deprecated This is deprecated. Use CompletionResult.type information instead.
 */
export declare enum Modalities {
    text = "text",
    image = "image"
}
/**
 * Represents the output and input modalities a model can support
 */
export interface ModelModalities {
    text?: boolean;
    image?: boolean;
    video?: boolean;
    audio?: boolean;
    embed?: boolean;
}
export interface ModelCapabilities {
    input: ModelModalities;
    output: ModelModalities;
    tool_support?: boolean;
    tool_support_streaming?: boolean;
}
export interface AIModel<ProviderKeys = string> {
    id: string;
    name: string;
    provider: ProviderKeys;
    description?: string;
    version?: string;
    type?: ModelType;
    tags?: string[];
    owner?: string;
    status?: AIModelStatus;
    can_stream?: boolean;
    is_custom?: boolean;
    is_multimodal?: boolean;
    input_modalities?: string[];
    output_modalities?: string[];
    tool_support?: boolean;
    environment?: string;
}
export declare enum AIModelStatus {
    Available = "available",
    Pending = "pending",
    Stopped = "stopped",
    Unavailable = "unavailable",
    Unknown = "unknown",
    Legacy = "legacy"
}
/**
 * payload to list available models for an environment
 * @param environmentId id of the environment
 * @param query text to search for in model name/description
 * @param type type of the model
 * @param tags tags for searching
 */
export interface ModelSearchPayload {
    text: string;
    type?: ModelType;
    tags?: string[];
    owner?: string;
}
export declare enum ModelType {
    Classifier = "classifier",
    Regressor = "regressor",
    Clustering = "clustering",
    AnomalyDetection = "anomaly-detection",
    TimeSeries = "time-series",
    Text = "text",
    Image = "image",
    Audio = "audio",
    Video = "video",
    Embedding = "embedding",
    Chat = "chat",
    Code = "code",
    NLP = "nlp",
    MultiModal = "multi-modal",
    Test = "test",
    Other = "other",
    Unknown = "unknown"
}
export interface DataSource {
    name: string;
    mime_type: string;
    getStream(): Promise<ReadableStream<Uint8Array | string>>;
    getURL(): Promise<string>;
}
export interface TrainingOptions {
    name: string;
    model: string;
    params?: JSONObject;
}
export interface TrainingPromptOptions {
    segments: PromptSegment[];
    completion: CompletionResult[];
    model: string;
    schema?: JSONSchema;
}
export declare enum TrainingJobStatus {
    running = "running",
    succeeded = "succeeded",
    failed = "failed",
    cancelled = "cancelled"
}
export interface TrainingJob {
    id: string;
    status: TrainingJobStatus;
    details?: string;
    model?: string;
}
export type JSONPrimitive = string | number | boolean | null;
export type JSONArray = JSONValue[];
export type JSONObject = {
    [key: string]: JSONValue;
};
export type JSONComposite = JSONArray | JSONObject;
export type JSONValue = JSONPrimitive | JSONComposite;
export {};
//# sourceMappingURL=types.d.ts.map