@djangocfg/llm 2.1.164

package/src/providers/base.ts

@@ -0,0 +1,90 @@
+/**
+ * Base LLM provider
+ */
+
+import type {
+  LLMClient,
+  LLMConfig,
+  LLMMessage,
+  LLMProvider,
+  LLMRequestOptions,
+  LLMResponse,
+} from '../types';
+import { extractJson } from '../utils/json';
+
+export abstract class BaseLLMProvider implements LLMClient {
+  abstract provider: LLMProvider;
+
+  protected config: Required<
+    Pick<LLMConfig, 'model' | 'temperature' | 'maxTokens'>
+  > & LLMConfig;
+
+  constructor(config: LLMConfig) {
+    this.config = {
+      model: config.model ?? 'gpt-4o-mini',
+      temperature: config.temperature ?? 0.1,
+      maxTokens: config.maxTokens ?? 4096,
+      ...config,
+    };
+  }
+
+  /**
+   * Send chat messages (implemented by provider)
+   */
+  abstract chatMessages(
+    messages: LLMMessage[],
+    options?: LLMRequestOptions
+  ): Promise<LLMResponse>;
+
+  /**
+   * Send single chat message
+   */
+  async chat(prompt: string, options?: LLMRequestOptions): Promise<LLMResponse> {
+    const messages: LLMMessage[] = [];
+
+    if (options?.system) {
+      messages.push({ role: 'system', content: options.system });
+    }
+
+    messages.push({ role: 'user', content: prompt });
+
+    return this.chatMessages(messages, options);
+  }
+
+  /**
+   * Get JSON response
+   */
+  async json<T = unknown>(
+    prompt: string,
+    options?: LLMRequestOptions
+  ): Promise<T> {
+    const systemPrompt = `${options?.system ?? ''}\n\nRespond with valid JSON only. No markdown, no explanations.`.trim();
+
+    const response = await this.chat(prompt, {
+      ...options,
+      system: systemPrompt,
+      temperature: options?.temperature ?? 0,
+    });
+
+    return extractJson<T>(response.content);
+  }
+
+  /**
+   * Get JSON response with schema hint
+   */
+  async jsonSchema<T = unknown>(
+    prompt: string,
+    schema: string,
+    options?: LLMRequestOptions
+  ): Promise<T> {
+    const systemPrompt = `${options?.system ?? ''}\n\nRespond with valid JSON matching this schema:\n${schema}\n\nNo markdown, no explanations.`.trim();
+
+    const response = await this.chat(prompt, {
+      ...options,
+      system: systemPrompt,
+      temperature: options?.temperature ?? 0,
+    });
+
+    return extractJson<T>(response.content);
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,15 @@
+export { BaseLLMProvider } from './base';
+export { OpenAIProvider } from './openai';
+export { AnthropicProvider } from './anthropic';
+export {
+  SDKRouterProvider,
+  Model,
+  ModelPresets,
+  buildModelAlias,
+  SDKROUTER_BASE_URL,
+  type SDKRouterConfig,
+  type ModelTier,
+  type ModelCapability,
+  type ModelCategory,
+  type ModelOptions,
+} from './sdkrouter';

package/src/providers/openai.ts

@@ -0,0 +1,73 @@
+/**
+ * OpenAI provider
+ */
+
+import OpenAI from 'openai';
+import type {
+  LLMConfig,
+  LLMMessage,
+  LLMProvider,
+  LLMRequestOptions,
+  LLMResponse,
+} from '../types';
+import { BaseLLMProvider } from './base';
+
+export class OpenAIProvider extends BaseLLMProvider {
+  provider: LLMProvider = 'openai';
+  private client: OpenAI;
+
+  constructor(config: LLMConfig) {
+    super({
+      model: config.model ?? 'gpt-4o-mini',
+      ...config,
+    });
+
+    if (!config.apiKey) {
+      throw new Error('OpenAI API key is required');
+    }
+
+    this.client = new OpenAI({
+      apiKey: config.apiKey,
+      baseURL: config.baseUrl,
+    });
+  }
+
+  async chatMessages(
+    messages: LLMMessage[],
+    options?: LLMRequestOptions
+  ): Promise<LLMResponse> {
+    const model = options?.model ?? this.config.model;
+    const temperature = options?.temperature ?? this.config.temperature;
+    const maxTokens = options?.maxTokens ?? this.config.maxTokens;
+
+    // Add system message if provided
+    const allMessages = options?.system
+      ? [{ role: 'system' as const, content: options.system }, ...messages]
+      : messages;
+
+    const response = await this.client.chat.completions.create({
+      model,
+      messages: allMessages.map((m) => ({
+        role: m.role,
+        content: m.content,
+      })),
+      temperature,
+      max_tokens: maxTokens,
+    });
+
+    const choice = response.choices[0];
+
+    return {
+      content: choice.message.content ?? '',
+      model: response.model,
+      usage: response.usage
+        ? {
+            promptTokens: response.usage.prompt_tokens,
+            completionTokens: response.usage.completion_tokens,
+            totalTokens: response.usage.total_tokens,
+          }
+        : undefined,
+      finishReason: choice.finish_reason ?? undefined,
+    };
+  }
+}

package/src/providers/sdkrouter.ts

@@ -0,0 +1,279 @@
+/**
+ * SDKRouter provider
+ *
+ * Uses https://llm.sdkrouter.com - OpenAI-compatible LLM router
+ * with smart model aliases like @smart, @cheap, @balanced
+ */
+
+import OpenAI from 'openai';
+import type {
+  LLMConfig,
+  LLMMessage,
+  LLMProvider,
+  LLMRequestOptions,
+  LLMResponse,
+} from '../types';
+import { BaseLLMProvider } from './base';
+
+/** SDKRouter base URL */
+export const SDKROUTER_BASE_URL = 'https://llm.sdkrouter.com/v1';
+
+/**
+ * Model tier presets
+ *
+ * @example '@cheap', '@smart', '@balanced'
+ */
+export type ModelTier =
+  | 'cheap'     // Cheapest available
+  | 'budget'    // Budget-friendly
+  | 'standard'  // Standard tier
+  | 'balanced'  // Best quality/price ratio
+  | 'smart'     // Highest quality
+  | 'fast'      // Lowest latency
+  | 'premium';  // Top-tier
+
+/**
+ * Model capabilities (features)
+ *
+ * @example '@cheap+vision', '@smart+tools+json'
+ */
+export type ModelCapability =
+  | 'vision'     // Image understanding
+  | 'tools'      // Function/tool calling
+  | 'agents'     // Agent tool calling (verified)
+  | 'json'       // JSON mode
+  | 'streaming'  // Streaming support
+  | 'long'       // Long context (128k+)
+  | 'image';     // Image generation
+
+/**
+ * Model categories (use cases)
+ *
+ * @example '@balanced+code', '@smart+reasoning'
+ */
+export type ModelCategory =
+  | 'code'       // Code generation
+  | 'vision'     // Vision & images
+  | 'reasoning'  // Reasoning & math
+  | 'agents'     // Tool use & agents
+  | 'creative'   // Creative writing
+  | 'chat'       // Conversational
+  | 'analysis';  // Analysis & extraction
+
+/**
+ * Model alias builder options
+ */
+export interface ModelOptions {
+  // Capabilities
+  vision?: boolean;
+  tools?: boolean;
+  agents?: boolean;
+  json?: boolean;
+  streaming?: boolean;
+  long?: boolean;
+  image?: boolean;
+  // Categories
+  code?: boolean;
+  reasoning?: boolean;
+  creative?: boolean;
+  chat?: boolean;
+  analysis?: boolean;
+}
+
+/**
+ * Build model alias string
+ *
+ * @example
+ * ```ts
+ * buildModelAlias('smart')                    // '@smart'
+ * buildModelAlias('cheap', { vision: true })  // '@cheap+vision'
+ * buildModelAlias('balanced', { code: true, tools: true }) // '@balanced+code+tools'
+ * ```
+ */
+export function buildModelAlias(tier: ModelTier, options?: ModelOptions): string {
+  const parts: string[] = [tier];
+
+  if (options) {
+    // Capabilities (order matters for consistency)
+    if (options.vision) parts.push('vision');
+    if (options.tools) parts.push('tools');
+    if (options.agents) parts.push('agents');
+    if (options.json) parts.push('json');
+    if (options.streaming) parts.push('streaming');
+    if (options.long) parts.push('long');
+    if (options.image) parts.push('image');
+    // Categories
+    if (options.code) parts.push('code');
+    if (options.reasoning) parts.push('reasoning');
+    if (options.creative) parts.push('creative');
+    if (options.chat) parts.push('chat');
+    if (options.analysis) parts.push('analysis');
+  }
+
+  return '@' + parts.join('+');
+}
+
+/**
+ * Model alias builder with IDE autocomplete
+ *
+ * @example
+ * ```ts
+ * import { Model } from '@djangocfg/llm'
+ *
+ * Model.smart()                        // '@smart'
+ * Model.cheap({ vision: true })        // '@cheap+vision'
+ * Model.balanced({ code: true })       // '@balanced+code'
+ * Model.fast({ tools: true, json: true }) // '@fast+tools+json'
+ * ```
+ */
+export const Model = {
+  /** Cheapest available model */
+  cheap: (options?: ModelOptions): string => buildModelAlias('cheap', options),
+
+  /** Budget-friendly with decent quality */
+  budget: (options?: ModelOptions): string => buildModelAlias('budget', options),
+
+  /** Standard tier */
+  standard: (options?: ModelOptions): string => buildModelAlias('standard', options),
+
+  /** Best quality/price ratio (recommended) */
+  balanced: (options?: ModelOptions): string => buildModelAlias('balanced', options),
+
+  /** Highest quality model */
+  smart: (options?: ModelOptions): string => buildModelAlias('smart', options),
+
+  /** Lowest latency model */
+  fast: (options?: ModelOptions): string => buildModelAlias('fast', options),
+
+  /** Top-tier premium model */
+  premium: (options?: ModelOptions): string => buildModelAlias('premium', options),
+
+  /**
+   * Build alias from raw strings (escape hatch)
+   *
+   * @example Model.alias('cheap', 'vision', 'code') // '@cheap+vision+code'
+   */
+  alias: (tier: string, ...modifiers: string[]): string =>
+    '@' + [tier, ...modifiers].join('+'),
+} as const;
+
+/**
+ * Pre-built model aliases for common use cases
+ */
+export const ModelPresets = {
+  /** Translation: cheap + json mode */
+  translation: Model.cheap({ json: true }),
+
+  /** Code generation: balanced + code */
+  code: Model.balanced({ code: true }),
+
+  /** Code with tools: balanced + code + tools */
+  codeWithTools: Model.balanced({ code: true, tools: true }),
+
+  /** Vision: balanced + vision */
+  vision: Model.balanced({ vision: true }),
+
+  /** Reasoning: smart + reasoning */
+  reasoning: Model.smart({ reasoning: true }),
+
+  /** Creative writing: balanced + creative */
+  creative: Model.balanced({ creative: true }),
+
+  /** Fast chat: fast + chat */
+  fastChat: Model.fast({ chat: true }),
+
+  /** Analysis: balanced + analysis */
+  analysis: Model.balanced({ analysis: true }),
+
+  /** Agents: smart + agents + tools */
+  agents: Model.smart({ agents: true, tools: true }),
+} as const;
+
+/**
+ * SDKRouter provider config
+ */
+export interface SDKRouterConfig extends LLMConfig {
+  /** Model tier (shortcut for building alias) */
+  tier?: ModelTier;
+  /** Model options for alias building */
+  modelOptions?: ModelOptions;
+}
+
+/**
+ * SDKRouter LLM provider
+ *
+ * Uses OpenAI-compatible API at https://llm.sdkrouter.com
+ *
+ * @example
+ * ```ts
+ * const llm = new SDKRouterProvider({
+ *   apiKey: process.env.SDKROUTER_API_KEY,
+ *   model: Model.balanced({ code: true })
+ * })
+ * ```
+ */
+export class SDKRouterProvider extends BaseLLMProvider {
+  provider: LLMProvider = 'sdkrouter';
+  private client: OpenAI;
+
+  constructor(config: SDKRouterConfig) {
+    // Build model alias if tier provided
+    const model =
+      config.model ??
+      (config.tier
+        ? buildModelAlias(config.tier, config.modelOptions)
+        : '@balanced');
+
+    super({
+      model,
+      ...config,
+    });
+
+    if (!config.apiKey) {
+      throw new Error('SDKRouter API key is required (SDKROUTER_API_KEY)');
+    }
+
+    this.client = new OpenAI({
+      apiKey: config.apiKey,
+      baseURL: config.baseUrl ?? SDKROUTER_BASE_URL,
+    });
+  }
+
+  async chatMessages(
+    messages: LLMMessage[],
+    options?: LLMRequestOptions
+  ): Promise<LLMResponse> {
+    const model = options?.model ?? this.config.model;
+    const temperature = options?.temperature ?? this.config.temperature;
+    const maxTokens = options?.maxTokens ?? this.config.maxTokens;
+
+    const allMessages = options?.system
+      ? [{ role: 'system' as const, content: options.system }, ...messages]
+      : messages;
+
+    const response = await this.client.chat.completions.create({
+      model,
+      messages: allMessages.map((m) => ({
+        role: m.role,
+        content: m.content,
+      })),
+      temperature,
+      max_tokens: maxTokens,
+    });
+
+    const choice = response.choices[0];
+
+    return {
+      content: choice.message.content ?? '',
+      model: response.model,
+      usage: response.usage
+        ? {
+            promptTokens: response.usage.prompt_tokens,
+            completionTokens: response.usage.completion_tokens,
+            totalTokens: response.usage.total_tokens,
+          }
+        : undefined,
+      finishReason: choice.finish_reason ?? undefined,
+    };
+  }
+}

package/src/translator/cache.ts

@@ -0,0 +1,237 @@
+/**
+ * Translation Cache Manager
+ *
+ * Two-level caching: memory + localStorage/file
+ * Organized by language pairs for efficient lookup
+ */
+
+import crypto from 'crypto';
+
+export interface CacheStats {
+  memorySize: number;
+  hits: number;
+  misses: number;
+  languagePairs: Array<{
+    pair: string;
+    translations: number;
+  }>;
+}
+
+/**
+ * Translation cache with memory + persistent storage
+ */
+export class TranslationCache {
+  private memoryCache = new Map<string, string>();
+  private cacheOrder: string[] = [];
+  private hits = 0;
+  private misses = 0;
+
+  constructor(
+    private maxMemorySize: number = 1000,
+    private storage?: Storage // localStorage in browser, undefined in Node
+  ) {}
+
+  /**
+   * Generate hash for text
+   */
+  private getTextHash(text: string): string {
+    return crypto.createHash('md5').update(text).digest('hex');
+  }
+
+  /**
+   * Get storage key for language pair
+   */
+  private getStorageKey(sourceLang: string, targetLang: string): string {
+    return `translator:${sourceLang}-${targetLang}`;
+  }
+
+  /**
+   * Load from persistent storage
+   */
+  private loadFromStorage(sourceLang: string, targetLang: string): Record<string, string> {
+    if (!this.storage) return {};
+
+    try {
+      const key = this.getStorageKey(sourceLang, targetLang);
+      const data = this.storage.getItem(key);
+      return data ? JSON.parse(data) : {};
+    } catch {
+      return {};
+    }
+  }
+
+  /**
+   * Save to persistent storage
+   */
+  private saveToStorage(
+    sourceLang: string,
+    targetLang: string,
+    cache: Record<string, string>
+  ): void {
+    if (!this.storage) return;
+
+    try {
+      const key = this.getStorageKey(sourceLang, targetLang);
+      this.storage.setItem(key, JSON.stringify(cache));
+    } catch {
+      // Storage full or unavailable
+    }
+  }
+
+  /**
+   * Evict oldest entries if memory is full
+   */
+  private evictIfNeeded(): void {
+    while (this.memoryCache.size >= this.maxMemorySize && this.cacheOrder.length > 0) {
+      const oldestKey = this.cacheOrder.shift()!;
+      this.memoryCache.delete(oldestKey);
+    }
+  }
+
+  /**
+   * Get translation from cache
+   */
+  get(text: string, sourceLang: string, targetLang: string): string | undefined {
+    const textHash = this.getTextHash(text);
+    const cacheKey = `${sourceLang}-${targetLang}:${textHash}`;
+
+    // Check memory cache first
+    if (this.memoryCache.has(cacheKey)) {
+      this.hits++;
+      return this.memoryCache.get(cacheKey);
+    }
+
+    // Check persistent storage
+    const fileCache = this.loadFromStorage(sourceLang, targetLang);
+    if (textHash in fileCache) {
+      const translation = fileCache[textHash];
+      // Store in memory cache
+      this.evictIfNeeded();
+      this.memoryCache.set(cacheKey, translation);
+      this.cacheOrder.push(cacheKey);
+      this.hits++;
+      return translation;
+    }
+
+    this.misses++;
+    return undefined;
+  }
+
+  /**
+   * Store translation in cache
+   */
+  set(text: string, sourceLang: string, targetLang: string, translation: string): void {
+    const textHash = this.getTextHash(text);
+    const cacheKey = `${sourceLang}-${targetLang}:${textHash}`;
+
+    // Store in memory cache
+    this.evictIfNeeded();
+    this.memoryCache.set(cacheKey, translation);
+    if (!this.cacheOrder.includes(cacheKey)) {
+      this.cacheOrder.push(cacheKey);
+    }
+
+    // Store in persistent storage
+    const fileCache = this.loadFromStorage(sourceLang, targetLang);
+    fileCache[textHash] = translation;
+    this.saveToStorage(sourceLang, targetLang, fileCache);
+  }
+
+  /**
+   * Get multiple translations at once
+   */
+  getMany(
+    texts: string[],
+    sourceLang: string,
+    targetLang: string
+  ): { cached: Map<string, string>; uncached: string[] } {
+    const cached = new Map<string, string>();
+    const uncached: string[] = [];
+
+    for (const text of texts) {
+      const translation = this.get(text, sourceLang, targetLang);
+      if (translation !== undefined) {
+        cached.set(text, translation);
+      } else {
+        uncached.push(text);
+      }
+    }
+
+    return { cached, uncached };
+  }
+
+  /**
+   * Store multiple translations at once
+   */
+  setMany(
+    translations: Map<string, string>,
+    sourceLang: string,
+    targetLang: string
+  ): void {
+    for (const [text, translation] of translations) {
+      this.set(text, sourceLang, targetLang, translation);
+    }
+  }
+
+  /**
+   * Clear cache
+   */
+  clear(sourceLang?: string, targetLang?: string): void {
+    if (sourceLang && targetLang) {
+      // Clear specific language pair
+      const prefix = `${sourceLang}-${targetLang}:`;
+      for (const key of [...this.memoryCache.keys()]) {
+        if (key.startsWith(prefix)) {
+          this.memoryCache.delete(key);
+          const idx = this.cacheOrder.indexOf(key);
+          if (idx !== -1) this.cacheOrder.splice(idx, 1);
+        }
+      }
+
+      if (this.storage) {
+        this.storage.removeItem(this.getStorageKey(sourceLang, targetLang));
+      }
+    } else {
+      // Clear all
+      this.memoryCache.clear();
+      this.cacheOrder = [];
+      this.hits = 0;
+      this.misses = 0;
+    }
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): CacheStats {
+    const languagePairs: CacheStats['languagePairs'] = [];
+
+    // Count by language pair from memory
+    const pairCounts = new Map<string, number>();
+    for (const key of this.memoryCache.keys()) {
+      const pair = key.split(':')[0];
+      pairCounts.set(pair, (pairCounts.get(pair) || 0) + 1);
+    }
+
+    for (const [pair, count] of pairCounts) {
+      languagePairs.push({ pair, translations: count });
+    }
+
+    return {
+      memorySize: this.memoryCache.size,
+      hits: this.hits,
+      misses: this.misses,
+      languagePairs,
+    };
+  }
+}
+
+/**
+ * Create translation cache
+ */
+export function createCache(
+  maxMemorySize?: number,
+  storage?: Storage
+): TranslationCache {
+  return new TranslationCache(maxMemorySize, storage);
+}