ai.libx.js 0.1.1

package/src/utils/errors.ts

@@ -0,0 +1,76 @@
+export class AILibError extends Error {
+	constructor(message: string, public code?: string, public statusCode?: number) {
+		super(message);
+		this.name = 'AILibError';
+	}
+}
+
+export class AuthenticationError extends AILibError {
+	constructor(message: string, provider?: string) {
+		super(
+			provider ? `${provider}: ${message}` : message,
+			'AUTHENTICATION_ERROR',
+			401
+		);
+		this.name = 'AuthenticationError';
+	}
+}
+
+export class InvalidRequestError extends AILibError {
+	constructor(message: string) {
+		super(message, 'INVALID_REQUEST', 400);
+		this.name = 'InvalidRequestError';
+	}
+}
+
+export class RateLimitError extends AILibError {
+	constructor(message: string, provider?: string) {
+		super(
+			provider ? `${provider}: ${message}` : message,
+			'RATE_LIMIT_ERROR',
+			429
+		);
+		this.name = 'RateLimitError';
+	}
+}
+
+export class ModelNotFoundError extends AILibError {
+	constructor(model: string) {
+		super(`Model not found: ${model}`, 'MODEL_NOT_FOUND', 404);
+		this.name = 'ModelNotFoundError';
+	}
+}
+
+export class ProviderError extends AILibError {
+	constructor(message: string, provider: string, originalError?: any) {
+		super(`${provider}: ${message}`, 'PROVIDER_ERROR');
+		this.name = 'ProviderError';
+		if (originalError) {
+			this.stack = originalError.stack;
+		}
+	}
+}
+
+export function handleProviderError(error: any, provider: string): never {
+	if (error instanceof AILibError) {
+		throw error;
+	}
+
+	const status = error.status || error.statusCode;
+	const message = error.message || error.error?.message || 'Unknown error';
+
+	if (status === 401 || status === 403) {
+		throw new AuthenticationError(message, provider);
+	}
+
+	if (status === 429) {
+		throw new RateLimitError(message, provider);
+	}
+
+	if (status === 400) {
+		throw new InvalidRequestError(message);
+	}
+
+	throw new ProviderError(message, provider, error);
+}
+

package/src/utils/model-normalization.ts

@@ -0,0 +1,100 @@
+/**
+ * Model alias resolution and normalization
+ * Handles common aliases and provides forward compatibility
+ */
+
+const MODEL_ALIASES: Record<string, string> = {
+	// OpenAI aliases
+	'gpt-5': 'chatgpt-4o-latest',
+	'gpt-4.5-preview': 'gpt-4o',
+	'gpt-4.5': 'gpt-4o',
+	'gpt-4-latest': 'gpt-4o',
+
+	// Anthropic aliases
+	'claude-4': 'claude-sonnet-4-0',
+	'claude-3.5': 'claude-3-5-sonnet-latest',
+	'claude-3': 'claude-3-opus-20240229',
+
+	// Google aliases
+	'gemini': 'models/gemini-2.0-flash',
+	'gemini-2': 'models/gemini-2.0-flash',
+	'gemini-pro': 'models/gemini-2.5-pro',
+
+	// DeepSeek aliases
+	'deepseek': 'deepseek-chat',
+	'deepseek-r1': 'deepseek-reasoner',
+};
+
+/**
+ * Normalize model name by resolving aliases
+ */
+export function normalizeModelName(model: string): string {
+	// Extract provider and model parts
+	const parts = model.split('/');
+
+	if (parts.length === 1) {
+		// No provider prefix, just model name
+		return MODEL_ALIASES[model] || model;
+	}
+
+	const [provider, modelName] = parts;
+	const normalizedModel = MODEL_ALIASES[modelName] || modelName;
+
+	return `${provider}/${normalizedModel}`;
+}
+
+/**
+ * Check if a model is a reasoning model (requires special handling)
+ */
+export function isReasoningModel(model: string): boolean {
+	const modelLower = model.toLowerCase();
+
+	return (
+		modelLower.includes('/o1') ||
+		modelLower.includes('/o3') ||
+		modelLower.includes('reasoning') ||
+		modelLower.includes('reasoner') ||
+		modelLower.includes('-r1') ||
+		modelLower.includes('qwq')
+	);
+}
+
+/**
+ * Check if model doesn't support system messages
+ */
+export function supportsSystemMessages(model: string): boolean {
+	const modelLower = model.toLowerCase();
+
+	// o1, o3 models don't support system messages
+	if (modelLower.includes('/o1') || modelLower.includes('/o3')) {
+		return false;
+	}
+
+	return true;
+}
+
+/**
+ * Get adjusted parameters for reasoning models
+ */
+export function getReasoningModelAdjustments(model: string): {
+	temperature?: number;
+	topP?: number;
+	maxTokens?: number;
+	useMaxCompletionTokens?: boolean;
+} {
+	if (!isReasoningModel(model)) {
+		return {};
+	}
+
+	// o1/o3 models require specific parameter handling
+	if (model.toLowerCase().includes('/o1') || model.toLowerCase().includes('/o3')) {
+		return {
+			temperature: 1, // Fixed for o1/o3
+			topP: 1, // Fixed for o1/o3
+			useMaxCompletionTokens: true, // Use max_completion_tokens instead of max_tokens
+		};
+	}
+
+	return {};
+}
+

package/src/utils/request-logger.ts

@@ -0,0 +1,179 @@
+/**
+ * Request logging and metrics tracking
+ */
+
+export interface RequestMetadata {
+	requestId: string;
+	provider: string;
+	model: string;
+	timestamp: number;
+	metadata?: Record<string, any>;
+}
+
+export interface RequestTracker extends RequestMetadata {
+	startTime: number;
+}
+
+export interface CompletedRequest extends RequestMetadata {
+	latency: number;
+	success: boolean;
+	tokens?: number;
+	error?: string;
+}
+
+export interface ProviderStats {
+	requests: number;
+	avgLatency: number;
+	tokens: number;
+	errors: number;
+}
+
+export interface LoggerStats {
+	totalRequests: number;
+	successfulRequests: number;
+	failedRequests: number;
+	averageLatency: number;
+	totalTokensUsed: number;
+	providerBreakdown: Record<string, ProviderStats>;
+}
+
+/**
+ * Simple request logger for tracking metrics
+ */
+export class RequestLogger {
+	private requests: CompletedRequest[] = [];
+	private enabled: boolean;
+
+	constructor(enabled: boolean = false) {
+		this.enabled = enabled;
+	}
+
+	/**
+	 * Start tracking a request
+	 */
+	startRequest(
+		provider: string,
+		model: string,
+		metadata?: Record<string, any>
+	): RequestTracker {
+		return {
+			requestId: this.generateId(),
+			provider,
+			model,
+			timestamp: Date.now(),
+			startTime: Date.now(),
+			metadata,
+		};
+	}
+
+	/**
+	 * Complete and log a request
+	 */
+	logRequest(tracker: RequestTracker, success: boolean, tokens?: number, error?: string): void {
+		if (!this.enabled) return;
+
+		const latency = Date.now() - tracker.startTime;
+
+		this.requests.push({
+			requestId: tracker.requestId,
+			provider: tracker.provider,
+			model: tracker.model,
+			timestamp: tracker.timestamp,
+			metadata: tracker.metadata,
+			latency,
+			success,
+			tokens,
+			error,
+		});
+	}
+
+	/**
+	 * Get aggregated statistics
+	 */
+	getStats(): LoggerStats {
+		const successful = this.requests.filter((r) => r.success);
+		const failed = this.requests.filter((r) => !r.success);
+
+		const totalLatency = this.requests.reduce((sum, r) => sum + r.latency, 0);
+		const totalTokens = this.requests.reduce((sum, r) => sum + (r.tokens || 0), 0);
+
+		// Provider breakdown
+		const providerBreakdown: Record<string, ProviderStats> = {};
+
+		for (const request of this.requests) {
+			if (!providerBreakdown[request.provider]) {
+				providerBreakdown[request.provider] = {
+					requests: 0,
+					avgLatency: 0,
+					tokens: 0,
+					errors: 0,
+				};
+			}
+
+			const stats = providerBreakdown[request.provider];
+			stats.requests++;
+			stats.tokens += request.tokens || 0;
+			if (!request.success) stats.errors++;
+		}
+
+		// Calculate average latencies per provider
+		for (const provider in providerBreakdown) {
+			const providerRequests = this.requests.filter((r) => r.provider === provider);
+			const providerLatency = providerRequests.reduce((sum, r) => sum + r.latency, 0);
+			providerBreakdown[provider].avgLatency =
+				providerRequests.length > 0 ? providerLatency / providerRequests.length : 0;
+		}
+
+		return {
+			totalRequests: this.requests.length,
+			successfulRequests: successful.length,
+			failedRequests: failed.length,
+			averageLatency: this.requests.length > 0 ? totalLatency / this.requests.length : 0,
+			totalTokensUsed: totalTokens,
+			providerBreakdown,
+		};
+	}
+
+	/**
+	 * Get all requests (for detailed analysis)
+	 */
+	getRequests(): CompletedRequest[] {
+		return [...this.requests];
+	}
+
+	/**
+	 * Clear all logged requests
+	 */
+	clear(): void {
+		this.requests = [];
+	}
+
+	/**
+	 * Enable or disable logging
+	 */
+	setEnabled(enabled: boolean): void {
+		this.enabled = enabled;
+	}
+
+	private generateId(): string {
+		return `req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+	}
+}
+
+/**
+ * Global logger instance
+ */
+let globalLogger: RequestLogger | null = null;
+
+/**
+ * Get or create global logger
+ */
+export function getRequestLogger(enabled: boolean = false): RequestLogger {
+	if (!globalLogger) {
+		globalLogger = new RequestLogger(enabled);
+	} else {
+		globalLogger.setEnabled(enabled);
+	}
+	return globalLogger;
+}
+

package/src/utils/stream.ts

@@ -0,0 +1,93 @@
+import { StreamChunk } from '../types';
+
+/**
+ * Parse SSE (Server-Sent Events) data line
+ */
+export function parseSSELine(line: string): { event?: string; data?: string; } | null {
+	if (!line.trim() || line.startsWith(':')) {
+		return null;
+	}
+
+	if (line.startsWith('event:')) {
+		return { event: line.slice(6).trim() };
+	}
+
+	if (line.startsWith('data:')) {
+		return { data: line.slice(5).trim() };
+	}
+
+	return null;
+}
+
+/**
+ * Transform a ReadableStream of Uint8Array to lines
+ */
+export async function* streamLines(stream: ReadableStream<Uint8Array>): AsyncIterable<string> {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	let buffer = '';
+
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+
+			if (done) {
+				if (buffer.trim()) {
+					yield buffer;
+				}
+				break;
+			}
+
+			buffer += decoder.decode(value, { stream: true });
+			const lines = buffer.split('\n');
+			buffer = lines.pop() || '';
+
+			for (const line of lines) {
+				if (line.trim()) {
+					yield line;
+				}
+			}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+
+/**
+ * Generic SSE parser for streaming responses
+ */
+export async function* parseSSEStream(
+	stream: ReadableStream<Uint8Array>
+): AsyncIterable<any> {
+	let currentData = '';
+
+	for await (const line of streamLines(stream)) {
+		const parsed = parseSSELine(line);
+
+		if (parsed?.data) {
+			currentData = parsed.data;
+
+			if (currentData === '[DONE]') {
+				break;
+			}
+
+			try {
+				const json = JSON.parse(currentData);
+				yield json;
+			} catch (e) {
+				// Skip invalid JSON
+				continue;
+			}
+		}
+	}
+}
+
+/**
+ * Helper to create an async iterable from chunks
+ */
+export async function* createChunkStream(chunks: StreamChunk[]): AsyncIterable<StreamChunk> {
+	for (const chunk of chunks) {
+		yield chunk;
+	}
+}
+

package/src/utils/validation.ts

@@ -0,0 +1,69 @@
+import { ChatOptions, Message } from '../types';
+import { InvalidRequestError } from './errors';
+
+export function validateChatOptions(options: ChatOptions): void {
+	if (!options.model) {
+		throw new InvalidRequestError('Model is required');
+	}
+
+	if (!options.messages || !Array.isArray(options.messages)) {
+		throw new InvalidRequestError('Messages must be an array');
+	}
+
+	if (options.messages.length === 0) {
+		throw new InvalidRequestError('At least one message is required');
+	}
+
+	options.messages.forEach((msg, idx) => {
+		validateMessage(msg, idx);
+	});
+
+	if (options.temperature !== undefined) {
+		if (typeof options.temperature !== 'number' || options.temperature < 0 || options.temperature > 2) {
+			throw new InvalidRequestError('Temperature must be between 0 and 2');
+		}
+	}
+
+	if (options.maxTokens !== undefined) {
+		if (typeof options.maxTokens !== 'number' || options.maxTokens < 1) {
+			throw new InvalidRequestError('maxTokens must be a positive number');
+		}
+	}
+
+	if (options.topP !== undefined) {
+		if (typeof options.topP !== 'number' || options.topP < 0 || options.topP > 1) {
+			throw new InvalidRequestError('topP must be between 0 and 1');
+		}
+	}
+}
+
+export function validateMessage(message: Message, index: number): void {
+	if (!message.role) {
+		throw new InvalidRequestError(`Message at index ${index} is missing role`);
+	}
+
+	if (!['system', 'user', 'assistant', 'tool'].includes(message.role)) {
+		throw new InvalidRequestError(
+			`Invalid role "${message.role}" at index ${index}. Must be: system, user, assistant, or tool`
+		);
+	}
+
+	if (message.content === undefined || message.content === null) {
+		throw new InvalidRequestError(`Message at index ${index} is missing content`);
+	}
+
+	if (typeof message.content !== 'string') {
+		throw new InvalidRequestError(`Message content at index ${index} must be a string`);
+	}
+}
+
+export function validateApiKey(apiKey: string | undefined, provider: string): string {
+	if (!apiKey) {
+		throw new InvalidRequestError(
+			`API key is required for ${provider}. ` +
+			`Pass it in the constructor or per-request options.`
+		);
+	}
+	return apiKey;
+}
+