@endlessriver/optimaiz/dist/index.d.mts

SDK for LLM observability - track costs, latency, and usage across OpenAI, Anthropic, Gemini, and more

/**
 * Core types for Optimaiz SDK
 */
type Role = 'system' | 'user' | 'assistant' | 'tool';
interface MessageContent {
    type: 'text' | 'image' | 'audio' | 'video';
    role: Role;
    value: string;
    mimeType?: string;
    extractedText?: string;
}
interface Feedback {
    rating?: 'up' | 'down';
    comment?: string;
    labels?: string[];
    submittedAt?: Date;
}
interface ToolParameter {
    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
    description?: string;
    required?: boolean;
    enum?: string[];
    items?: ToolParameter;
    properties?: Record<string, ToolParameter>;
}
interface ToolDefinition {
    name: string;
    description: string;
    parameters: {
        type: 'object';
        properties: Record<string, ToolParameter>;
        required?: string[];
    };
    category?: string;
    tags?: string[];
    version?: string;
    deprecated?: boolean;
}
interface OpenAITool {
    type: 'function';
    function: {
        name: string;
        description: string;
        parameters: {
            type: 'object';
            properties: Record<string, any>;
            required?: string[];
        };
    };
}
interface AnthropicTool {
    name: string;
    description: string;
    input_schema: {
        type: 'object';
        properties: Record<string, any>;
        required?: string[];
    };
}
interface MistralTool {
    type: 'function';
    function: {
        name: string;
        description: string;
        parameters: {
            type: 'object';
            properties: Record<string, any>;
            required?: string[];
        };
    };
}
interface ToolCall {
    id: string;
    type: 'function';
    function: {
        name: string;
        arguments: Record<string, any>;
    };
}
interface ToolResult {
    toolCallId: string;
    name: string;
    result: any;
    error?: string;
}
interface ToolExecution {
    toolId: string;
    toolName: string;
    executionTime: Date;
    duration?: number;
    success: boolean;
    error?: string;
    result?: any;
}
interface TokenUsage {
    promptTokens: number;
    completionTokens: number;
    totalTokens: number;
    cost?: number;
}
interface Interaction {
    traceId: string;
    agentId?: string;
    flowId?: string;
    threadId?: string;
    sessionId?: string;
    userId?: string;
    provider: string;
    model: string;
    prompts: MessageContent[];
    promptTemplate?: MessageContent[];
    promptVariables?: Record<string, string>;
    tools?: ToolDefinition[];
    responses?: MessageContent[];
    modelParams?: Record<string, any>;
    usage?: TokenUsage;
    toolCalls?: ToolCall[];
    toolResults?: ToolResult[];
    toolsExecuted?: ToolExecution[];
    error?: {
        message: string;
        code?: string;
        details?: any;
    };
    feedback?: Feedback;
    metadata?: Record<string, any>;
    tags?: string[];
    startTime?: Date;
    endTime?: Date;
    latencyMs?: number;
    createdAt?: Date;
    updatedAt?: Date;
}
interface OptimaixConfig {
    token: string;
    baseUrl?: string;
    timeout?: number;
    retries?: number;
    debug?: boolean;
}
interface StartTraceRequest {
    traceId?: string;
    agentId?: string;
    flowId?: string;
    threadId?: string;
    sessionId?: string;
    userId?: string;
    promptTemplate?: MessageContent[];
    promptVariables?: Record<string, string>;
    tools?: ToolDefinition[];
    provider: string;
    model: string;
    modelParams?: Record<string, any>;
    metadata?: Record<string, any>;
    tags?: string[];
}
interface AppendResponseRequest {
    traceId: string;
    rawResponse?: any;
    provider?: string;
    model?: string;
    threadId?: string;
    userId?: string;
    agentId?: string;
    flowId?: string;
    sessionId?: string;
}
interface TraceResponse {
    success: boolean;
    traceId: string;
    interaction?: Interaction;
    error?: string;
}

/**
 * Optimaiz SDK Client
 *
 * Main client for interacting with Optimaiz server (OSS or Cloud)
 */

declare class OptimaizClient {
    private baseUrl;
    private token;
    private timeout;
    private retries;
    private debug;
    constructor(config: OptimaixConfig);
    private log;
    private request;
    /**
     * Start a new trace
     */
    startTrace(data: StartTraceRequest): Promise<TraceResponse>;
    /**
     * Append LLM response to a trace
     */
    appendResponse(data: AppendResponseRequest): Promise<TraceResponse>;
    /**
     * Finalize a trace (calculate latency, etc.)
     */
    finalizeTrace(traceId: string): Promise<TraceResponse>;
    /**
     * Log an error to a trace
     */
    logError(traceId: string, error: {
        message: string;
        code?: string;
        details?: any;
    }): Promise<TraceResponse>;
    /**
     * Send feedback for a trace
     */
    sendFeedback(traceId: string, feedback: Feedback): Promise<TraceResponse>;
    /**
     * Add tool execution record
     */
    addToolExecution(data: {
        traceId: string;
        toolId: string;
        toolName: string;
        executionTime?: Date;
        duration?: number;
        success: boolean;
        error?: string;
        result?: any;
    }): Promise<TraceResponse>;
    /**
     * Add tool results to a trace
     */
    addToolResults(data: {
        traceId: string;
        toolResults: ToolResult[];
    }): Promise<TraceResponse>;
    /**
     * Compose prompts from templates and variables
     */
    composePrompts(templates: Array<{
        role: Role;
        content: string;
        type?: MessageContent['type'];
    }>, variables: Record<string, string>): {
        prompts: MessageContent[];
        promptTemplate: MessageContent[];
        promptVariables: Record<string, string>;
    };
    /**
     * High-level wrapper for LLM calls with automatic tracing
     */
    wrapLLMCall<T>({ traceId, agentId, flowId, threadId, sessionId, userId, promptTemplate, promptVariables, tools, provider, model, modelParams, metadata, tags, call, }: {
        traceId?: string;
        agentId?: string;
        flowId?: string;
        threadId?: string;
        sessionId?: string;
        userId?: string;
        promptTemplate?: MessageContent[];
        promptVariables?: Record<string, string>;
        tools?: ToolDefinition[];
        provider: string;
        model: string;
        modelParams?: Record<string, any>;
        metadata?: Record<string, any>;
        tags?: string[];
        call: () => Promise<T>;
    }): Promise<{
        response: T;
        traceId: string;
    }>;
    /**
     * Convert tools to provider-specific format
     */
    convertToolsToProvider(tools: ToolDefinition[], provider: string): any[];
    /**
     * Convert provider-specific tools to unified format
     */
    convertToolsFromProvider(tools: any[], provider: string): ToolDefinition[];
    /**
     * Validate tool definitions
     */
    validateTools(tools: ToolDefinition[]): {
        valid: boolean;
        errors: string[];
    };
}

/**
 * Custom error classes for Optimaiz SDK
 */
declare class OptimaizError extends Error {
    status?: number;
    details?: string;
    type?: string;
    constructor(message: string, status?: number, details?: string, type?: string);
}
declare class OptimaizAuthenticationError extends OptimaizError {
    constructor(message: string, details?: string);
}
declare class OptimaizValidationError extends OptimaizError {
    constructor(message: string, details?: string);
}
declare class OptimaizServerError extends OptimaizError {
    constructor(message: string, details?: string);
}
declare class OptimaizNetworkError extends OptimaizError {
    constructor(message: string, details?: string);
}
/**
 * Error type guards
 */
declare function isOptimaizError(error: any): error is OptimaizError;
declare function isAuthenticationError(error: any): error is OptimaizAuthenticationError;
declare function isValidationError(error: any): error is OptimaizValidationError;
declare function isServerError(error: any): error is OptimaizServerError;
declare function isNetworkError(error: any): error is OptimaizNetworkError;

/**
 * Tool conversion utilities for multi-provider support
 */

/**
 * Validate tool definitions
 */
declare function validateTools(tools: ToolDefinition[]): {
    valid: boolean;
    errors: string[];
};
/**
 * Convert unified tool definitions to OpenAI format
 */
declare function toOpenAIFormat(tools: ToolDefinition[]): OpenAITool[];
/**
 * Convert unified tool definitions to Anthropic format
 */
declare function toAnthropicFormat(tools: ToolDefinition[]): AnthropicTool[];
/**
 * Convert unified tool definitions to Mistral format
 */
declare function toMistralFormat(tools: ToolDefinition[]): MistralTool[];
/**
 * Convert tools to provider-specific format
 */
declare function toProviderFormat(tools: ToolDefinition[], provider: string): any[];
/**
 * Convert OpenAI format tools to unified format
 */
declare function fromOpenAIFormat(tools: OpenAITool[]): ToolDefinition[];
/**
 * Convert Anthropic format tools to unified format
 */
declare function fromAnthropicFormat(tools: AnthropicTool[]): ToolDefinition[];
/**
 * Convert Mistral format tools to unified format
 */
declare function fromMistralFormat(tools: MistralTool[]): ToolDefinition[];
/**
 * Convert provider-specific tools to unified format
 */
declare function fromProviderFormat(tools: any[], provider: string): ToolDefinition[];

export { type AnthropicTool, type AppendResponseRequest, type Feedback, type Interaction, type MessageContent, type MistralTool, type OpenAITool, type OptimaixConfig, OptimaizAuthenticationError, OptimaizClient, OptimaizError, OptimaizNetworkError, OptimaizServerError, OptimaizValidationError, type Role, type StartTraceRequest, type TokenUsage, type ToolCall, type ToolDefinition, type ToolExecution, type ToolParameter, type ToolResult, type TraceResponse, OptimaizClient as default, fromAnthropicFormat, fromMistralFormat, fromOpenAIFormat, fromProviderFormat, isAuthenticationError, isNetworkError, isOptimaizError, isServerError, isValidationError, toAnthropicFormat, toMistralFormat, toOpenAIFormat, toProviderFormat, validateTools };