@sprqvntrs/llm 3.13.0

package/src/helpers.ts

@@ -0,0 +1,185 @@
+import { z } from 'zod/v4';
+import type { LlmClientInterface } from './types/client-interface';
+
+/**
+ * Simple schema for language validation response
+ */
+const LanguageCheckSchema = z.object({
+  isCorrectLanguage: z.boolean(),
+});
+
+/**
+ * Checks if content is in the expected language using an LLM
+ *
+ * @param {Object} params - The parameters for checking language
+ * @param {LlmClientInterface} params.llm - The LLM client to use for language detection
+ * @param {string} params.content - The content to check
+ * @param {string} params.expectedLanguage - The expected language of the content
+ * @returns {Promise<boolean>} - Whether the content is in the expected language
+ */
+export async function isContentInLanguage({
+  llm,
+  content,
+  expectedLanguage,
+}: {
+  llm: LlmClientInterface;
+  content: string;
+  expectedLanguage: string;
+}): Promise<boolean> {
+  try {
+    const prompt = `
+      <task>
+        Determine if the following content is written in ${expectedLanguage} language.
+      </task>
+
+      <instructions>
+        - Analyze the text and determine if it's written in ${expectedLanguage}
+        - Return true if the content is in ${expectedLanguage}
+        - Return false if the content is in any other language
+        - Ignore small phrases or individual words that might be in other languages
+        - Focus on the primary language of the text
+      </instructions>
+
+      <content>
+        ${content}
+      </content>
+    `;
+
+    const response = await llm.createStructuredResponse({
+      prompt,
+      schema: LanguageCheckSchema,
+      reasoningEffort: 'low', // Language detection doesn't need high reasoning
+    });
+
+    return response.isCorrectLanguage;
+  } catch (error) {
+    console.error('Error checking language:', error);
+    // In case of error, assume the language is correct to avoid blocking the flow
+    return true;
+  }
+}
+
+/**
+ * Formats unstructured content into a structured format using an LLM
+ *
+ * This utility function takes unstructured content (typically from another LLM)
+ * and formats it according to a specified Zod schema. This is useful when working
+ * with LLMs that don't support structured outputs natively.
+ *
+ * @template T - The Zod schema type
+ * @param {Object} params - The parameters for formatting content
+ * @param {LlmClientInterface} params.llm - The LLM client to use for formatting
+ * @param {string} params.unstructuredContent - The unstructured content to format
+ * @param {T} params.schema - The Zod schema to validate against
+ * @param {string} [params.additionalInstructions] - Optional additional instructions for the formatting
+ * @returns {Promise<z.infer<T>>} - A promise that resolves to the structured content
+ */
+export async function formatContentToStructure<T extends z.ZodType>({
+  llm,
+  unstructuredContent,
+  schema,
+  additionalInstructions = '',
+}: {
+  llm: LlmClientInterface;
+  unstructuredContent: string;
+  schema: T;
+  additionalInstructions?: string;
+}): Promise<z.infer<T>> {
+  const conversionPrompt = `
+    This is the output of an AI model that is not able to respond in the format we need.
+    Please convert the output to the format we need. If you encounter any errors, return false on the success property (if applicable).
+    ${additionalInstructions ? `\n${additionalInstructions}` : ''}
+    <output>
+      ${JSON.stringify(unstructuredContent, null, 2)}
+    </output>
+  `;
+
+  const completion = await llm.createStructuredResponse({
+    prompt: conversionPrompt,
+    schema: schema,
+    reasoningEffort: 'low', // Formatting typically doesn't need high reasoning
+  });
+
+  return completion as z.infer<T>;
+}
+
+/**
+ * Attempts to generate and format content with language validation
+ *
+ * This function orchestrates the process of generating content with one LLM,
+ * checking if it's in the correct language, and formatting it with another LLM.
+ *
+ * @template T - The Zod schema type
+ * @param {Object} params - The parameters for generating and formatting
+ * @param {Function} params.generateContent - Function that generates the unstructured content
+ * @param {LlmClientInterface} params.languageCheckLlm - The LLM client to use for language validation
+ * @param {LlmClientInterface} params.formatterLlm - The LLM client to use for formatting
+ * @param {string} params.expectedLanguage - The expected language of the output
+ * @param {T} params.schema - The Zod schema to validate against
+ * @param {number} [params.maxAttempts=3] - Maximum number of attempts to get correct language
+ * @param {string} [params.additionalInstructions] - Optional additional instructions for formatting
+ * @returns {Promise<z.infer<T>>} - A promise that resolves to the structured content
+ */
+export async function generateAndFormatWithLanguageCheck<T extends z.ZodType>({
+  generateContent,
+  languageCheckLlm,
+  formatterLlm,
+  expectedLanguage,
+  schema,
+  maxAttempts = 3,
+  additionalInstructions,
+}: {
+  generateContent: () => Promise<string>;
+  languageCheckLlm: LlmClientInterface;
+  formatterLlm: LlmClientInterface;
+  expectedLanguage: string;
+  schema: T;
+  maxAttempts?: number;
+  additionalInstructions?: string;
+}): Promise<z.infer<T> & { languageCorrect: boolean }> {
+  let attempts = 0;
+
+  while (attempts < maxAttempts) {
+    attempts++;
+
+    // Step 1: Generate content
+    const unstructuredContent = await generateContent();
+
+    // Step 2: Check if content is in the expected language
+    const isLanguageCorrect = await isContentInLanguage({
+      llm: languageCheckLlm,
+      content: unstructuredContent,
+      expectedLanguage,
+    });
+
+    // Step 3: Format the content regardless of language correctness
+    const formattedContent = await formatContentToStructure({
+      llm: formatterLlm,
+      unstructuredContent,
+      schema,
+      additionalInstructions,
+    });
+
+    // Add language check result to the response
+    const result = {
+      ...(formattedContent as object),
+      languageCorrect: isLanguageCorrect,
+    } as z.infer<T> & { languageCorrect: boolean };
+
+    // If language is correct, return immediately
+    if (isLanguageCorrect) {
+      return result;
+    }
+
+    // If we've reached max attempts, return the last result anyway
+    if (attempts === maxAttempts) {
+      console.warn(`Max attempts reached. Language still incorrect after ${maxAttempts} tries.`);
+      return result;
+    }
+
+    console.info(`Incorrect language detected, retrying...`);
+  }
+
+  // This should never be reached due to the while loop conditions
+  throw new Error('Unexpected end of content generation process');
+}

package/src/llm.ts

@@ -0,0 +1,107 @@
+import { OpenAIClient } from './clients/openai-client';
+import { AnthropicClient } from './clients/anthropic-client';
+import { OpenRouterClient } from './clients/openrouter-client';
+import type { LlmClientInterface } from './types/client-interface';
+import type { AnthropicModel } from './model-types';
+
+export type LlmProvider = 'openai' | 'anthropic' | 'openrouter';
+
+export type LlmClientOptions = {
+  apiKey?: string;
+  /**
+   * Enable debug mode for development.
+   * - If true: always log debug messages
+   * - If false: never log debug messages
+   * - If undefined: auto-detect based on NODE_ENV (enabled in development)
+   */
+  debug?: boolean;
+  /**
+   * Some debug/testing contexts need to opt into reasoning endpoints explicitly (OpenAI only).
+   */
+  useReasoningMode?: boolean;
+  /**
+   * OpenAI API key for structured formatting (used by Anthropic and OpenRouter clients).
+   * If provided, these clients will use OpenAI for reliable structured output formatting.
+   */
+  openaiApiKey?: string;
+};
+
+/**
+ * Unified LLM client factory for all AI model interactions.
+ * Returns a client that implements the unified LlmClientInterface,
+ * providing consistent API across different providers.
+ */
+export class LLM {
+  /**
+   * Get an LLM client that implements the unified interface.
+   * Works with OpenAI, Anthropic, and OpenRouter providers transparently.
+   *
+   * @param provider - The LLM provider ('openai', 'anthropic', or 'openrouter')
+   * @param model - The model identifier (e.g., 'gpt-4o', 'claude-sonnet-4-20250514', 'openai/gpt-4o-mini')
+   * @param options - Optional configuration overrides
+   * @returns Client implementing LlmClientInterface
+   * @example
+   * const llm = LLM.getClient('openai', 'gpt-4o');
+   * const llm2 = LLM.getClient('openrouter', 'openai/gpt-4o-mini');
+   * const result = await llm.createStructuredResponse({ prompt, schema });
+   */
+  static getClient(provider: LlmProvider, model: string, options?: LlmClientOptions): LlmClientInterface {
+    switch (provider) {
+      case 'openai':
+        return this._createOpenAIClient(model, options);
+      case 'anthropic':
+        return this._createAnthropicClient(model, options);
+      case 'openrouter':
+        return this._createOpenRouterClient(model, options);
+    }
+  }
+
+  /**
+   * Create an OpenAI client instance
+   */
+  private static _createOpenAIClient(model: string, options?: LlmClientOptions): OpenAIClient {
+    const apiKey = options?.apiKey ?? process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      throw new Error('OPENAI_API_KEY is not set');
+    }
+    return new OpenAIClient({
+      apiKey,
+      model,
+      debug: options?.debug,
+    });
+  }
+
+  /**
+   * Create an Anthropic client instance
+   */
+  private static _createAnthropicClient(model: string, options?: LlmClientOptions): AnthropicClient {
+    const apiKey = options?.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+      throw new Error('ANTHROPIC_API_KEY is not set');
+    }
+
+    return new AnthropicClient({
+      apiKey,
+      model: model as AnthropicModel,
+      openaiApiKey: options?.openaiApiKey,
+      debug: options?.debug,
+    });
+  }
+
+  /**
+   * Create an OpenRouter client instance
+   */
+  private static _createOpenRouterClient(model: string, options?: LlmClientOptions): OpenRouterClient {
+    const apiKey = options?.apiKey ?? process.env.OPENROUTER_API_KEY;
+    if (!apiKey) {
+      throw new Error('OPENROUTER_API_KEY is not set');
+    }
+
+    return new OpenRouterClient({
+      apiKey,
+      model,
+      openaiApiKey: options?.openaiApiKey,
+      debug: options?.debug,
+    });
+  }
+}

package/src/model-types.ts

@@ -0,0 +1,61 @@
+import type { ChatModel as OpenAIChatModel } from 'openai/resources/shared';
+import type { Model as AnthropicModelType } from '@anthropic-ai/sdk/resources/messages/messages';
+
+/**
+ * OpenAI models released after the SDK's ChatModel union was last cut.
+ * Keep here until `openai` ships an SDK that includes them in `ChatModel`,
+ * then drop these literals.
+ */
+type OpenAINewerModel =
+  | 'gpt-5.5'
+  | 'gpt-5.5-pro'
+  | 'gpt-5.6-terra'
+  | 'gpt-5.6-terra-pro'
+  | 'gpt-5.6-luna'
+  | 'gpt-5.6-luna-pro'
+  | 'gpt-5.6-sol'
+  | 'gpt-5.6-sol-pro';
+
+/**
+ * OpenAI model types from the official SDK, plus newer models not yet in the
+ * SDK's `ChatModel` union and the embedding models we use directly.
+ */
+export type OpenAIModel =
+  | OpenAIChatModel
+  | OpenAINewerModel
+  | 'text-embedding-3-large'
+  | 'text-embedding-ada-002';
+
+/**
+ * Anthropic model types from the official SDK
+ */
+export type AnthropicModel = AnthropicModelType;
+
+/**
+ * OpenRouter model types
+ * OpenRouter provides access to 300+ models across multiple providers
+ * Models are specified in the format 'provider/model-name'
+ * Examples: 'openai/gpt-4', 'anthropic/claude-3-opus', 'google/gemini-2.5-flash-lite-preview-09-2025'
+ */
+export type OpenRouterModel = string;
+
+/**
+ * Map of provider to their available models
+ */
+export type ProviderModelMap = {
+  openai: OpenAIModel;
+  anthropic: AnthropicModel;
+  openrouter: OpenRouterModel;
+};
+
+/**
+ * Provider-specific model configuration with automatic model type inference
+ * When you set provider: 'openai', the model field will autocomplete with OpenAI models
+ * When you set provider: 'anthropic', the model field will autocomplete with Anthropic models
+ */
+export type ModelConfig<P extends keyof ProviderModelMap = keyof ProviderModelMap> = {
+  [K in P]: {
+    provider: K;
+    model: ProviderModelMap[K];
+  };
+}[P];

package/src/models.ts

@@ -0,0 +1,98 @@
+import type { ModelConfig } from './model-types';
+
+/**
+ * Default model configurations for LLM operations
+ * These are used internally by the LLM package for formatting and structure operations
+ */
+export const DEFAULT_MODELS = {
+  /**
+   * Model used for converting unstructured content into structured format
+   * This is typically used when an Anthropic response needs to be formatted
+   */
+  STRUCTURED_FORMATTER: {
+    provider: 'openai',
+    model: 'gpt-5-mini-2025-08-07',
+  } as ModelConfig<'openai'>,
+
+  /**
+   * Model used for language detection and validation
+   */
+  LANGUAGE_DETECTOR: {
+    provider: 'openai',
+    model: 'gpt-5-nano-2025-08-07',
+  } as ModelConfig<'openai'>,
+
+  /**
+   * Default Anthropic model for generation tasks
+   */
+  ANTHROPIC_DEFAULT: {
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-6',
+  } as ModelConfig<'anthropic'>,
+
+  /**
+   * Default OpenAI model for generation tasks
+   */
+  OPENAI_DEFAULT: {
+    provider: 'openai',
+    model: 'gpt-5.4',
+  } as ModelConfig<'openai'>,
+} as const;
+
+/**
+ * Maps reasoning effort levels to provider-specific parameters
+ *
+ * Note: this map is legacy — it is exported for backwards compatibility but is not
+ * consumed by any client. Clients pass the normalized `ReasoningEffortLevel` straight
+ * through to the provider (OpenAI and OpenRouter both accept `reasoning.effort`,
+ * including 'none'; Anthropic translates it into an extended-thinking budget).
+ */
+export const REASONING_EFFORT_MAP = {
+  openai: {
+    none: 'none' as const,
+    low: undefined, // OpenAI doesn't use reasoning_effort for low
+    medium: 'medium' as const,
+    high: 'high' as const,
+  },
+} as const;
+
+/**
+ * Base max tokens for Anthropic responses
+ * When using thinking mode, actual max_tokens will be: max(ANTHROPIC_MAX_TOKENS, budget_tokens + 4096)
+ * to ensure max_tokens > thinking.budget_tokens as required by the API
+ */
+export const ANTHROPIC_MAX_TOKENS = 4096;
+
+/**
+ * Default system prompt used across all LLM clients
+ * Instructs the model to generate content directly without asking clarifying questions
+ */
+export const DEFAULT_SYSTEM_PROMPT = `You are an expert assistant.
+
+When given a task, produce the requested output directly:
+- Do NOT ask clarifying questions
+- Do NOT present multiple options or menus for the user to choose from
+- Do NOT include meta-commentary about the task
+- Make reasonable assumptions when details are unspecified`;
+
+/**
+ * Web search tool configurations for different providers
+ */
+export const WEB_SEARCH_TOOLS = {
+  /**
+   * Anthropic web search tool configuration
+   * See: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/web-search-tool
+   */
+  ANTHROPIC: {
+    type: 'web_search_20250305',
+    name: 'web_search',
+  },
+
+  /**
+   * OpenAI web search tool configuration for Responses API
+   * See: https://cookbook.openai.com/examples/responses_api/responses_example
+   */
+  OPENAI: {
+    type: 'web_search',
+  },
+} as const;