@djangocfg/llm 2.1.164

package/src/translator/types.ts

@@ -0,0 +1,112 @@
+/**
+ * Translator types
+ */
+
+import type { LLMRequestOptions } from '../types';
+
+/**
+ * Language code
+ */
+export type LanguageCode =
+  | 'en'
+  | 'ru'
+  | 'ko'
+  | 'ja'
+  | 'zh'
+  | 'de'
+  | 'fr'
+  | 'es'
+  | 'it'
+  | 'pt'
+  | 'pt-BR'
+  | 'ar'
+  | 'nl'
+  | 'tr'
+  | 'pl'
+  | 'sv'
+  | 'no'
+  | 'da'
+  | 'uk'
+  | 'hi'
+  | string;
+
+/**
+ * Language names map
+ */
+export const LANGUAGE_NAMES: Record<string, string> = {
+  en: 'English',
+  ru: 'Russian',
+  ko: 'Korean',
+  ja: 'Japanese',
+  zh: 'Chinese',
+  de: 'German',
+  fr: 'French',
+  es: 'Spanish',
+  it: 'Italian',
+  pt: 'Portuguese',
+  'pt-BR': 'Brazilian Portuguese',
+  ar: 'Arabic',
+  nl: 'Dutch',
+  tr: 'Turkish',
+  pl: 'Polish',
+  sv: 'Swedish',
+  no: 'Norwegian',
+  da: 'Danish',
+  uk: 'Ukrainian',
+  hi: 'Hindi',
+};
+
+/**
+ * Translation options
+ */
+export interface TranslateOptions extends LLMRequestOptions {
+  /** Source language (default: 'en') */
+  sourceLanguage?: LanguageCode;
+  /** Max retries on validation failure */
+  maxRetries?: number;
+  /** Preserve placeholders like {name}, {{var}} */
+  preservePlaceholders?: boolean;
+}
+
+/**
+ * Translation result
+ */
+export interface TranslateResult<T> {
+  /** Translated data */
+  data: T;
+  /** Whether translation is valid (keys preserved) */
+  valid: boolean;
+  /** Validation errors if any */
+  errors: string[];
+  /** Number of retries used */
+  retries: number;
+  /** Source language */
+  sourceLanguage: string;
+  /** Target language */
+  targetLanguage: string;
+}
+
+/**
+ * Batch translation item
+ */
+export interface BatchTranslateItem<T> {
+  /** Data to translate */
+  data: T;
+  /** Target language */
+  targetLanguage: LanguageCode;
+  /** Options override */
+  options?: TranslateOptions;
+}
+
+/**
+ * Cache stats
+ */
+export interface CacheStats {
+  memorySize: number;
+  hits: number;
+  misses: number;
+  languagePairs: Array<{
+    pair: string;
+    translations: number;
+  }>;
+}

package/src/translator/validator.ts

@@ -0,0 +1,181 @@
+/**
+ * Translation validation
+ */
+
+import { extractPlaceholders } from './text-utils';
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/**
+ * Validate that JSON keys are not translated
+ */
+export function validateJsonKeys(
+  original: unknown,
+  translated: unknown,
+  path: string = ''
+): ValidationResult {
+  const errors: string[] = [];
+
+  // Type check
+  if (typeof original !== typeof translated) {
+    errors.push(`Type mismatch at ${path || 'root'}: expected ${typeof original}, got ${typeof translated}`);
+    return { valid: false, errors };
+  }
+
+  // Null check
+  if (original === null || translated === null) {
+    if (original !== translated) {
+      errors.push(`Null mismatch at ${path || 'root'}`);
+    }
+    return { valid: errors.length === 0, errors };
+  }
+
+  // Array
+  if (Array.isArray(original)) {
+    if (!Array.isArray(translated)) {
+      errors.push(`Expected array at ${path || 'root'}`);
+      return { valid: false, errors };
+    }
+
+    if (original.length !== translated.length) {
+      errors.push(
+        `Array length mismatch at ${path || 'root'}: expected ${original.length}, got ${translated.length}`
+      );
+    }
+
+    const minLen = Math.min(original.length, translated.length);
+    for (let i = 0; i < minLen; i++) {
+      const result = validateJsonKeys(
+        original[i],
+        translated[i],
+        `${path}[${i}]`
+      );
+      errors.push(...result.errors);
+    }
+
+    return { valid: errors.length === 0, errors };
+  }
+
+  // Object
+  if (typeof original === 'object') {
+    if (typeof translated !== 'object' || Array.isArray(translated)) {
+      errors.push(`Expected object at ${path || 'root'}`);
+      return { valid: false, errors };
+    }
+
+    const origKeys = Object.keys(original as Record<string, unknown>);
+    const transKeys = Object.keys(translated as Record<string, unknown>);
+
+    // Check for missing keys
+    for (const key of origKeys) {
+      if (!transKeys.includes(key)) {
+        errors.push(`Missing key: ${path ? `${path}.${key}` : key}`);
+      }
+    }
+
+    // Check for extra keys (keys that were translated!)
+    for (const key of transKeys) {
+      if (!origKeys.includes(key)) {
+        errors.push(
+          `Unexpected key: ${path ? `${path}.${key}` : key} (key was translated?)`
+        );
+      }
+    }
+
+    // Recurse into matching keys
+    for (const key of origKeys) {
+      if (transKeys.includes(key)) {
+        const result = validateJsonKeys(
+          (original as Record<string, unknown>)[key],
+          (translated as Record<string, unknown>)[key],
+          path ? `${path}.${key}` : key
+        );
+        errors.push(...result.errors);
+      }
+    }
+
+    return { valid: errors.length === 0, errors };
+  }
+
+  // Primitives (string, number, boolean) - no validation needed for structure
+  return { valid: true, errors: [] };
+}
+
+/**
+ * Validate that placeholders are preserved
+ */
+export function validatePlaceholders(
+  original: unknown,
+  translated: unknown,
+  path: string = ''
+): ValidationResult {
+  const errors: string[] = [];
+
+  if (typeof original === 'string' && typeof translated === 'string') {
+    const origPlaceholders = extractPlaceholders(original);
+    const transPlaceholders = extractPlaceholders(translated);
+
+    for (const placeholder of origPlaceholders) {
+      if (!transPlaceholders.includes(placeholder)) {
+        errors.push(
+          `Missing placeholder "${placeholder}" at ${path || 'root'}`
+        );
+      }
+    }
+
+    for (const placeholder of transPlaceholders) {
+      if (!origPlaceholders.includes(placeholder)) {
+        errors.push(
+          `Extra placeholder "${placeholder}" at ${path || 'root'}`
+        );
+      }
+    }
+  } else if (Array.isArray(original) && Array.isArray(translated)) {
+    const minLen = Math.min(original.length, translated.length);
+    for (let i = 0; i < minLen; i++) {
+      const result = validatePlaceholders(
+        original[i],
+        translated[i],
+        `${path}[${i}]`
+      );
+      errors.push(...result.errors);
+    }
+  } else if (
+    typeof original === 'object' &&
+    original !== null &&
+    typeof translated === 'object' &&
+    translated !== null
+  ) {
+    for (const key of Object.keys(original as Record<string, unknown>)) {
+      if (key in (translated as Record<string, unknown>)) {
+        const result = validatePlaceholders(
+          (original as Record<string, unknown>)[key],
+          (translated as Record<string, unknown>)[key],
+          path ? `${path}.${key}` : key
+        );
+        errors.push(...result.errors);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Full validation of translation
+ */
+export function validateTranslation(
+  original: unknown,
+  translated: unknown
+): ValidationResult {
+  const keyResult = validateJsonKeys(original, translated);
+  const placeholderResult = validatePlaceholders(original, translated);
+
+  return {
+    valid: keyResult.valid && placeholderResult.valid,
+    errors: [...keyResult.errors, ...placeholderResult.errors],
+  };
+}

package/src/types.ts

@@ -0,0 +1,85 @@
+/**
+ * LLM types
+ */
+
+export type LLMProvider = 'openai' | 'anthropic' | 'sdkrouter';
+
+export type OpenAIModel =
+  | 'gpt-4o'
+  | 'gpt-4o-mini'
+  | 'gpt-4-turbo'
+  | 'gpt-4'
+  | 'gpt-3.5-turbo';
+
+export type AnthropicModel =
+  | 'claude-3-5-sonnet-latest'
+  | 'claude-3-5-haiku-latest'
+  | 'claude-3-opus-latest';
+
+export type LLMModel = OpenAIModel | AnthropicModel | string;
+
+export interface LLMMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface LLMConfig {
+  /** Provider (auto-detected from env if not specified) */
+  provider?: LLMProvider;
+  /** API key (from env if not specified) */
+  apiKey?: string;
+  /** Default model */
+  model?: LLMModel;
+  /** Default temperature (0-1) */
+  temperature?: number;
+  /** Default max tokens */
+  maxTokens?: number;
+  /** Base URL override */
+  baseUrl?: string;
+}
+
+export interface LLMRequestOptions {
+  /** Model override */
+  model?: LLMModel;
+  /** Temperature override (0-1) */
+  temperature?: number;
+  /** Max tokens override */
+  maxTokens?: number;
+  /** System prompt */
+  system?: string;
+}
+
+export interface LLMResponse {
+  content: string;
+  model: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  finishReason?: string;
+}
+
+export interface LLMClient {
+  /** Provider name */
+  provider: LLMProvider;
+
+  /** Send chat message */
+  chat(prompt: string, options?: LLMRequestOptions): Promise<LLMResponse>;
+
+  /** Send chat messages */
+  chatMessages(
+    messages: LLMMessage[],
+    options?: LLMRequestOptions
+  ): Promise<LLMResponse>;
+
+  /** Get JSON response */
+  json<T = unknown>(prompt: string, options?: LLMRequestOptions): Promise<T>;
+
+  /** Get JSON response with schema hint */
+  jsonSchema<T = unknown>(
+    prompt: string,
+    schema: string,
+    options?: LLMRequestOptions
+  ): Promise<T>;
+}

package/src/utils/env.ts

@@ -0,0 +1,67 @@
+/**
+ * Environment utilities
+ */
+
+import type { LLMProvider } from '../types';
+
+/**
+ * Get API key from environment
+ */
+export function getApiKey(provider?: LLMProvider): string | undefined {
+  if (provider === 'sdkrouter') {
+    return process.env.SDKROUTER_API_KEY;
+  }
+  if (provider === 'openai') {
+    return process.env.OPENAI_API_KEY;
+  }
+  if (provider === 'anthropic') {
+    return process.env.ANTHROPIC_API_KEY;
+  }
+
+  // Auto-detect (sdkrouter first as preferred)
+  return (
+    process.env.SDKROUTER_API_KEY ||
+    process.env.OPENAI_API_KEY ||
+    process.env.ANTHROPIC_API_KEY
+  );
+}
+
+/**
+ * Detect provider from environment
+ */
+export function detectProvider(): LLMProvider | undefined {
+  // Explicit provider
+  const explicit = process.env.LLM_PROVIDER?.toLowerCase();
+  if (explicit === 'sdkrouter' || explicit === 'openai' || explicit === 'anthropic') {
+    return explicit;
+  }
+
+  // Auto-detect from API keys (sdkrouter preferred)
+  if (process.env.SDKROUTER_API_KEY) {
+    return 'sdkrouter';
+  }
+  if (process.env.OPENAI_API_KEY) {
+    return 'openai';
+  }
+  if (process.env.ANTHROPIC_API_KEY) {
+    return 'anthropic';
+  }
+
+  return undefined;
+}
+
+/**
+ * Get default model for provider
+ */
+export function getDefaultModel(provider: LLMProvider): string {
+  if (provider === 'sdkrouter') {
+    return process.env.SDKROUTER_MODEL || '@balanced';
+  }
+  if (provider === 'openai') {
+    return process.env.OPENAI_MODEL || 'gpt-4o-mini';
+  }
+  if (provider === 'anthropic') {
+    return process.env.ANTHROPIC_MODEL || 'claude-3-5-haiku-latest';
+  }
+  return '@balanced';
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './env';
+export * from './json';

package/src/utils/json.ts

@@ -0,0 +1,44 @@
+/**
+ * JSON parsing utilities
+ */
+
+/**
+ * Extract JSON from LLM response (handles markdown code blocks)
+ */
+export function extractJson<T = unknown>(text: string): T {
+  let jsonStr = text.trim();
+
+  // Remove markdown code blocks
+  if (jsonStr.startsWith('```json')) {
+    jsonStr = jsonStr.slice(7);
+  } else if (jsonStr.startsWith('```')) {
+    jsonStr = jsonStr.slice(3);
+  }
+
+  if (jsonStr.endsWith('```')) {
+    jsonStr = jsonStr.slice(0, -3);
+  }
+
+  jsonStr = jsonStr.trim();
+
+  // Try to find JSON object or array
+  const jsonStart = jsonStr.search(/[\[{]/);
+  const jsonEndBracket = jsonStr.lastIndexOf(']');
+  const jsonEndBrace = jsonStr.lastIndexOf('}');
+  const jsonEnd = Math.max(jsonEndBracket, jsonEndBrace);
+
+  if (jsonStart !== -1 && jsonEnd !== -1) {
+    jsonStr = jsonStr.slice(jsonStart, jsonEnd + 1);
+  }
+
+  try {
+    return JSON.parse(jsonStr) as T;
+  } catch (error) {
+    throw new Error(
+      `Failed to parse JSON from LLM response: ${error instanceof Error ? error.message : 'Unknown error'}\n\nResponse:\n${text}`
+    );
+  }
+}
+
+// Re-export from translator validator for backwards compatibility
+export { validateJsonKeys } from '../translator/validator';

package/src/utils/schema.ts

@@ -0,0 +1,153 @@
+/**
+ * Schema utilities for structured LLM outputs
+ *
+ * Provides helpers for working with Zod schemas and LLM structured outputs.
+ * Zod is optional - only used if installed.
+ */
+
+import type { LLMClient, LLMRequestOptions, LLMResponse } from '../types';
+import { extractJson } from './json';
+
+/**
+ * Minimal Zod-like schema interface
+ * Compatible with Zod but doesn't require it
+ */
+export interface ZodLikeSchema<T = unknown> {
+  parse(data: unknown): T;
+  safeParse(data: unknown): { success: true; data: T } | { success: false; error: unknown };
+}
+
+/**
+ * JSON Schema representation for LLM prompts
+ */
+export interface JsonSchemaDefinition {
+  type: string;
+  properties?: Record<string, JsonSchemaDefinition>;
+  items?: JsonSchemaDefinition;
+  required?: string[];
+  description?: string;
+  enum?: unknown[];
+}
+
+/**
+ * Generate a simple JSON schema string from a TypeScript type example
+ *
+ * @example
+ * ```ts
+ * const schema = generateSchemaFromExample({ name: '', age: 0, active: true })
+ * // { type: "object", properties: { name: { type: "string" }, ... } }
+ * ```
+ */
+export function generateSchemaFromExample(example: unknown): JsonSchemaDefinition {
+  if (example === null) {
+    return { type: 'null' };
+  }
+
+  if (Array.isArray(example)) {
+    const itemSchema =
+      example.length > 0 ? generateSchemaFromExample(example[0]) : { type: 'string' };
+    return { type: 'array', items: itemSchema };
+  }
+
+  if (typeof example === 'object') {
+    const properties: Record<string, JsonSchemaDefinition> = {};
+    const required: string[] = [];
+
+    for (const [key, value] of Object.entries(example)) {
+      properties[key] = generateSchemaFromExample(value);
+      required.push(key);
+    }
+
+    return { type: 'object', properties, required };
+  }
+
+  return { type: typeof example };
+}
+
+/**
+ * Convert JSON schema to a prompt-friendly string
+ */
+export function schemaToPromptString(schema: JsonSchemaDefinition): string {
+  return JSON.stringify(schema, null, 2);
+}
+
+/**
+ * Get structured output from LLM with validation
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const UserSchema = z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ * })
+ *
+ * const user = await getStructuredOutput(llm, 'Extract user info from: John is 25', UserSchema)
+ * // { name: 'John', age: 25 }
+ * ```
+ */
+export async function getStructuredOutput<T>(
+  client: LLMClient,
+  prompt: string,
+  schema: ZodLikeSchema<T>,
+  options?: LLMRequestOptions
+): Promise<{ data: T; response: LLMResponse } | { error: string; raw: unknown }> {
+  const response = await client.chat(prompt, {
+    ...options,
+    temperature: 0,
+    system: options?.system ?? 'Return ONLY valid JSON matching the requested structure.',
+  });
+
+  try {
+    const parsed = extractJson(response.content);
+    const result = schema.safeParse(parsed);
+
+    if (result.success) {
+      return { data: result.data, response };
+    }
+
+    return {
+      error: 'Schema validation failed',
+      raw: parsed,
+    };
+  } catch (error) {
+    return {
+      error: error instanceof Error ? error.message : 'Failed to parse JSON',
+      raw: response.content,
+    };
+  }
+}
+
+/**
+ * Get structured output with retry on validation failure
+ */
+export async function getStructuredOutputWithRetry<T>(
+  client: LLMClient,
+  prompt: string,
+  schema: ZodLikeSchema<T>,
+  options?: LLMRequestOptions & { maxRetries?: number }
+): Promise<{ data: T; retries: number } | { error: string; raw: unknown; retries: number }> {
+  const maxRetries = options?.maxRetries ?? 2;
+  let retries = 0;
+  let lastError = '';
+  let lastRaw: unknown;
+
+  while (retries <= maxRetries) {
+    const result = await getStructuredOutput(client, prompt, schema, options);
+
+    if ('data' in result) {
+      return { data: result.data, retries };
+    }
+
+    lastError = result.error;
+    lastRaw = result.raw;
+    retries++;
+
+    if (retries <= maxRetries) {
+      console.warn(`Structured output validation failed (attempt ${retries}/${maxRetries + 1})`);
+    }
+  }
+
+  return { error: lastError, raw: lastRaw, retries };
+}