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

Client SDK for interacting with the Optimaiz logging & trace system.

export type Role = "system" | "user" | "assistant";
export interface StandardToolDefinition {
    name: string;
    description: string;
    parameters: {
        type: "object";
        properties: Record<string, {
            type: "string" | "number" | "boolean" | "object" | "array";
            description?: string;
            required?: boolean;
            enum?: string[];
        }>;
        required?: string[];
    };
    category?: string;
    tags?: string[];
    version?: string;
    deprecated?: boolean;
}
export interface OpenAIFormatTool {
    type: "function";
    function: {
        name: string;
        description: string;
        parameters: {
            type: "object";
            properties: Record<string, any>;
            required?: string[];
        };
    };
}
export interface AnthropicFormatTool {
    name: string;
    description: string;
    input_schema: {
        type: "object";
        properties: Record<string, any>;
        required?: string[];
    };
}
export interface MistralFormatTool {
    type: "function";
    function: {
        name: string;
        description: string;
        parameters: {
            type: "object";
            properties: Record<string, any>;
            required?: string[];
        };
    };
}
export interface IToolCall {
    id: string;
    name: string;
    arguments: Record<string, any>;
    type: "function";
}
export interface IToolResult {
    toolCallId: string;
    name: string;
    result: any;
    error?: string;
}
export interface IToolDefinition {
    name: string;
    description: string;
    parameters: {
        type: "object";
        properties: Record<string, any>;
        required?: string[];
    };
    category?: string;
    tags?: string[];
    version?: string;
    deprecated?: boolean;
}
export type MessageContent = {
    type: "text" | "image" | "audio" | "video";
    role: Role;
    value: string;
    mimeType?: string;
    extractedText?: string;
};
export type Feedback = {
    rating?: "up" | "down";
    comment?: string;
    submittedAt?: Date;
    labels?: string[];
};
export declare class OptimaizError extends Error {
    status?: number;
    details?: string;
    type?: string;
    constructor(message: string, status?: number, details?: string, type?: string);
}
export declare class OptimaizAuthenticationError extends OptimaizError {
    constructor(message: string, details?: string);
}
export declare class OptimaizValidationError extends OptimaizError {
    constructor(message: string, details?: string);
}
export declare class OptimaizServerError extends OptimaizError {
    constructor(message: string, details?: string);
}
export declare class OptimaizClient {
    private config;
    private baseUrl;
    constructor(config: {
        token: string;
        baseUrl?: string;
    });
    private post;
    startTrace(data: {
        traceId?: string;
        agentId?: string;
        flowId?: string;
        threadId?: string;
        sessionId?: string;
        userId?: string;
        promptTemplate?: MessageContent[];
        promptVariables?: Record<string, string>;
        tools?: StandardToolDefinition[];
        provider: string;
        model: string;
        modelParams?: Record<string, any>;
        metadata?: Record<string, any>;
        tags?: string[];
    }): Promise<any>;
    appendResponse(data: {
        traceId: string;
        rawResponse?: any;
        provider?: string;
        model?: string;
        threadId?: string;
        userId?: string;
        agentId?: string;
        flowId?: string;
        sessionId?: string;
    }): Promise<any>;
    finalizeTrace(traceId: string): Promise<any>;
    logError(traceId: string, error: {
        message: string;
        code?: string;
        details?: any;
    }): Promise<any>;
    sendFeedback(traceId: string, feedback: Feedback): Promise<any>;
    addToolExecution(data: {
        traceId: string;
        toolId: string;
        toolName: string;
        executionTime: Date;
        duration?: number;
        success: boolean;
        error?: string;
        result?: any;
    }): Promise<any>;
    addToolResults(data: {
        traceId: string;
        toolResults: IToolResult[];
    }): Promise<any>;
    composePrompts(templates: {
        role: Role;
        content: string;
        type?: MessageContent["type"];
    }[], variables: Record<string, string>): {
        prompts: MessageContent[];
        promptTemplate: MessageContent[];
        promptVariables: Record<string, string>;
    };
    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;
        userId?: string;
        sessionId?: string;
        promptTemplate?: MessageContent[];
        promptVariables?: Record<string, string>;
        tools?: StandardToolDefinition[];
        provider: string;
        model: string;
        modelParams?: Record<string, any>;
        metadata?: Record<string, any>;
        tags?: string[];
        call: () => Promise<T>;
    }): Promise<{
        response: T;
        traceId: string;
    }>;
    generatePromptFromTools({ toolInfo, toolInput, }: {
        toolInfo: StandardToolDefinition[];
        toolInput: {
            name: string;
            arguments: Record<string, any>;
        };
    }): {
        promptTemplate: MessageContent[];
        promptVariables: Record<string, string>;
    };
    call(data: {
        traceId?: string;
        promptTemplate?: MessageContent[];
        promptVariables: Record<string, string>;
        tools?: StandardToolDefinition[];
        modelParams?: Record<string, any>;
        threadId?: string;
        userId?: string;
        agentId?: string;
        flowId?: string;
        sessionId?: string;
        metadata?: Record<string, any>;
        tags?: string[];
    }): Promise<{
        data: any;
        error?: any;
    }>;
    convertToolsToProviderFormat(tools: StandardToolDefinition[], provider: string): any[];
    convertProviderToolsToStandard(tools: any[], provider: string): StandardToolDefinition[];
    validateTools(tools: StandardToolDefinition[]): {
        valid: boolean;
        errors: string[];
    };
    /**
     * Utility method to handle errors with proper error types
     */
    static handleError(error: any): never;
    /**
     * Check if an error is a specific type
     */
    static isAuthenticationError(error: any): error is OptimaizAuthenticationError;
    static isValidationError(error: any): error is OptimaizValidationError;
    static isServerError(error: any): error is OptimaizServerError;
}