simple-ai-provider
Version:
A simple and extensible AI provider package for easy integration of multiple AI services
278 lines (277 loc) • 9.2 kB
TypeScript
/**
* OpenWebUI Provider Implementation
*
* This module provides integration with OpenWebUI instances, supporting both the native
* chat completions API and Ollama proxy endpoints. OpenWebUI is a self-hosted interface
* for large language models that provides a unified API for various model backends.
*
* Key Features:
* - Dual API support: Chat completions (OpenAI-compatible) and Ollama proxy
* - Local model support through Ollama integration
* - Self-hosted deployment flexibility with custom base URLs
* - Streaming support for real-time response delivery
* - Comprehensive model management and discovery
*
* OpenWebUI-Specific Considerations:
* - Typically runs on localhost with custom ports (default: 3000)
* - May use self-signed certificates requiring insecure connections
* - Supports both conversation and single-prompt formats
* - Model availability depends on configured backends (Ollama, etc.)
* - Rate limiting and authentication vary by deployment configuration
*
* @author Jan-Marlon Leibl
* @version 1.0.0
* @see https://docs.openwebui.com/
*/
import type { AIProviderConfig, CompletionParams, CompletionResponse, CompletionChunk, ProviderInfo } from '../types/index.js';
import { BaseAIProvider } from './base.js';
/**
* Configuration interface for OpenWebUI provider with OpenWebUI-specific options.
*
* @example
* ```typescript
* const config: OpenWebUIConfig = {
* apiKey: 'your-openwebui-api-key', // Optional for local instances
* baseUrl: 'http://localhost:3000',
* defaultModel: 'llama3.1:latest',
* useOllamaProxy: false,
* dangerouslyAllowInsecureConnections: true
* };
* ```
*/
export interface OpenWebUIConfig extends AIProviderConfig {
/**
* Default model to use for requests.
*
* Common OpenWebUI models:
* - 'llama3.1:latest': Latest Llama 3.1 model
* - 'mistral:latest': Mistral model variant
* - 'codellama:latest': Code-specialized Llama
* - 'phi3:latest': Microsoft Phi-3 model
*
* @default 'llama3.1:latest'
*/
defaultModel?: string;
/**
* Base URL for the OpenWebUI instance.
*
* This should point to your OpenWebUI deployment. For local development,
* this is typically localhost with the configured port.
*
* @default 'http://localhost:3000'
*/
baseUrl?: string;
/**
* Whether to use Ollama API proxy endpoints instead of chat completions.
*
* - `false`: Use OpenAI-compatible chat completions API (recommended)
* - `true`: Use direct Ollama generate API (for legacy compatibility)
*
* @default false
*/
useOllamaProxy?: boolean;
/**
* Whether to allow insecure SSL connections.
*
* This is often needed for local OpenWebUI instances that use
* self-signed certificates or HTTP instead of HTTPS.
*
* @default true
*/
dangerouslyAllowInsecureConnections?: boolean;
}
/**
* OpenWebUI provider implementation.
*
* This class handles interactions with OpenWebUI instances, providing support
* for both the native chat completions API and direct Ollama proxy access.
* It's designed to work with self-hosted OpenWebUI deployments.
*
* Usage Pattern:
* 1. Deploy OpenWebUI instance (local or remote)
* 2. Create provider with instance URL and configuration
* 3. Call initialize() to test connection and discover models
* 4. Use complete() or stream() for text generation
* 5. Handle AIProviderError exceptions for deployment-specific issues
*
* @example
* ```typescript
* const openwebui = new OpenWebUIProvider({
* apiKey: 'optional-api-key',
* baseUrl: 'http://localhost:3000',
* defaultModel: 'llama3.1:latest',
* useOllamaProxy: false
* });
*
* await openwebui.initialize();
*
* const response = await openwebui.complete({
* messages: [
* { role: 'user', content: 'Explain container orchestration.' }
* ],
* maxTokens: 500,
* temperature: 0.7
* });
* ```
*/
export declare class OpenWebUIProvider extends BaseAIProvider {
/** Default model identifier for requests */
private readonly defaultModel;
/** Base URL for the OpenWebUI instance */
private readonly baseUrl;
/** Whether to use Ollama proxy API instead of chat completions */
private readonly useOllamaProxy;
/** Whether to allow insecure SSL connections */
private readonly dangerouslyAllowInsecureConnections;
/**
* Creates a new OpenWebUI provider instance.
*
* @param config - OpenWebUI-specific configuration options
* @throws {AIProviderError} If configuration validation fails
*/
constructor(config: OpenWebUIConfig);
/**
* Returns comprehensive information about the OpenWebUI provider.
*
* @returns Provider information including capabilities and supported models
*/
getInfo(): ProviderInfo;
/**
* Normalizes the base URL by removing trailing slashes and validating format.
*
* @private
* @param baseUrl - Raw base URL
* @returns Normalized base URL
*/
private normalizeBaseUrl;
/**
* Validates the provider configuration for common issues.
*
* @private
* @throws {AIProviderError} If configuration is invalid
*/
private validateConfiguration;
/**
* Validates the connection to the OpenWebUI instance.
*
* @private
* @throws {AIProviderError} If connection validation fails
*/
private validateConnection;
/**
* Makes an HTTP request with proper error handling and configuration.
*
* @private
* @param url - Request URL
* @param method - HTTP method
* @param body - Request body (optional)
* @returns Promise resolving to Response object
*/
private makeRequest;
/**
* Converts generic messages to OpenWebUI chat format.
*
* @private
* @param messages - Input messages
* @returns OpenWebUI-formatted messages
*/
private convertMessages;
/**
* Converts messages to a single prompt string for Ollama API.
*
* @private
* @param messages - Input messages
* @returns Formatted prompt string
*/
private convertMessagesToPrompt;
/**
* Formats OpenWebUI chat completion response to standard interface.
*
* @private
* @param response - Raw OpenWebUI response
* @returns Formatted completion response
*/
private formatChatResponse;
/**
* Formats Ollama generate response to standard interface.
*
* @private
* @param response - Raw Ollama response
* @returns Formatted completion response
*/
private formatOllamaResponse;
/**
* Handles and transforms OpenWebUI-specific errors.
*
* @private
* @param error - Original error
* @returns Normalized AIProviderError
*/
private handleOpenWebUIError;
/**
* Completes using OpenWebUI's chat completions API (OpenAI-compatible).
*
* @private
* @param params - Completion parameters
* @returns Promise resolving to formatted completion response
*/
private completeWithChat;
/**
* Completes using Ollama proxy API (direct Ollama format).
*
* @private
* @param params - Completion parameters
* @returns Promise resolving to formatted completion response
*/
private completeWithOllama;
/**
* Streams using OpenWebUI's chat completions API with enhanced chunk processing.
*
* @private
* @param params - Completion parameters
* @returns AsyncIterable of completion chunks
*/
private streamWithChat;
/**
* Streams using Ollama proxy API with enhanced error handling.
*
* @private
* @param params - Completion parameters
* @returns AsyncIterable of completion chunks
*/
private streamWithOllama;
/**
* Initializes the OpenWebUI provider by testing the connection.
*
* This method:
* 1. Tests connectivity to the OpenWebUI instance
* 2. Validates API access and permissions
* 3. Optionally discovers available models
* 4. Verifies the default model is accessible
*
* @protected
* @throws {Error} If connection validation fails
*/
protected doInitialize(): Promise<void>;
/**
* Generates a text completion using the configured API method.
*
* This method automatically chooses between chat completions API
* and Ollama proxy based on the useOllamaProxy configuration.
*
* @protected
* @param params - Validated completion parameters
* @returns Promise resolving to formatted completion response
* @throws {Error} If API request fails
*/
protected doComplete(params: CompletionParams): Promise<CompletionResponse>;
/**
* Generates a streaming text completion using the configured API method.
*
* @protected
* @param params - Validated completion parameters
* @returns AsyncIterable yielding completion chunks
* @throws {Error} If streaming request fails
*/
protected doStream(params: CompletionParams): AsyncIterable<CompletionChunk>;
}