@elevasis/core 0.7.1 → 0.8.0

package/src/execution/engine/llm/adapters/server/adapter-factory.ts

@@ -1,130 +1,130 @@
-/**
- * LLM Adapter Factory
- * Creates LLM adapter instances based on model configuration
- */
-
-import type { LLMAdapter } from '../../types'
-import type { ModelConfig, OpenRouterOptions, GoogleOptions, AnthropicOptions } from '../../model-info'
-import { OpenAIAdapter, isOpenAIModel } from './openai'
-import { OpenRouterAdapter, isOpenRouterModel } from './openrouter'
-import { GoogleAdapter, isGoogleModel } from './google'
-import { AnthropicAdapter, isAnthropicModel } from './anthropic'
-import { MockAdapter, isMockModel } from '../mock-adapter'
-import { UniversalLLMAdapter } from '../universal-adapter'
-import type { AIUsageCollector } from '../../../../../operations/observability/ai-usage-collector'
-import type { AICallContext, BaseAICall } from '../../../../../operations/observability/types'
-
-/**
- * Resolve API key at runtime
- * Handles the case where env vars weren't loaded at module import time
- * (e.g., in Docker when dotenv runs after module imports)
- *
- * @param configApiKey - API key from config (may be placeholder)
- * @param provider - Provider name to determine which env var to check
- * @returns Resolved API key
- */
-function resolveApiKey(configApiKey: string, provider: string): string {
-  // If the config has a real API key (not a placeholder), use it
-  const isPlaceholder =
-    !configApiKey ||
-    configApiKey.startsWith('placeholder-') ||
-    configApiKey.includes('placeholder') ||
-    configApiKey.includes('test-api-key')
-  if (!isPlaceholder) {
-    return configApiKey
-  }
-
-  // Resolve from environment at runtime based on provider
-  const envVarMap: Record<string, string | undefined> = {
-    anthropic: process.env.ANTHROPIC_API_KEY,
-    openai: process.env.OPENAI_API_KEY,
-    openrouter: process.env.OPENROUTER_API_KEY,
-    google: process.env.GOOGLE_AI_STUDIO_KEY
-  }
-
-  const envKey = envVarMap[provider]
-  if (envKey) {
-    return envKey
-  }
-
-  // Fallback to config value (will fail at API call time with auth error)
-  return configApiKey
-}
-
-/**
- * Create base adapter based on model configuration
- * Routes to the appropriate provider-specific adapter
- *
- * @param config - Model configuration from resource definition
- * @returns Base LLM adapter instance (without observability wrapper)
- */
-function createBaseAdapter(config: ModelConfig): LLMAdapter {
-  const { model, provider, modelOptions } = config
-  const apiKey = resolveApiKey(config.apiKey, provider)
-
-  // OpenAI models
-  if (isOpenAIModel(model, provider)) {
-    return new OpenAIAdapter({
-      apiKey,
-      model,
-      modelOptions // Flat structure - no vendor namespace needed
-    })
-  }
-
-  // OpenRouter models (access to 400+ models via single API)
-  if (isOpenRouterModel(model)) {
-    return new OpenRouterAdapter({
-      apiKey,
-      model,
-      modelOptions: modelOptions as OpenRouterOptions
-    })
-  }
-
-  // Google models (direct SDK access via @google/genai)
-  if (isGoogleModel(model, provider)) {
-    return new GoogleAdapter({
-      apiKey,
-      model,
-      modelOptions: modelOptions as GoogleOptions
-    })
-  }
-
-  // Anthropic models (direct SDK access via @anthropic-ai/sdk)
-  if (isAnthropicModel(model, provider)) {
-    return new AnthropicAdapter({
-      apiKey,
-      model,
-      modelOptions: modelOptions as AnthropicOptions
-    })
-  }
-
-  // Mock provider (for testing)
-  if (isMockModel(model, provider)) {
-    return new MockAdapter()
-  }
-
-  throw new Error(`Unsupported model: ${model} with provider: ${provider}`)
-}
-
-/**
- * Create LLM adapter based on model configuration
- * Creates a stateless adapter instance for the execution
- * Automatically wraps with UniversalLLMAdapter for reliability and observability
- *
- * @param config - Model configuration from resource definition (includes model identifier)
- * @param aiUsageCollector - Optional collector for tracking AI usage
- * @param callType - Optional call type discriminator for observability
- * @param context - Optional typed context for observability
- * @returns Stateless LLM adapter instance (wrapped with UniversalLLMAdapter)
- */
-export function createLLMAdapter(
-  config: ModelConfig,
-  aiUsageCollector?: AIUsageCollector,
-  callType?: BaseAICall['callType'],
-  context?: AICallContext
-): LLMAdapter {
-  const baseAdapter = createBaseAdapter(config)
-
-  // Wrap with UniversalLLMAdapter for automatic retry, circuit breaker, and observability
-  return new UniversalLLMAdapter(baseAdapter, config.model, aiUsageCollector, callType, context)
-}
+/**
+ * LLM Adapter Factory
+ * Creates LLM adapter instances based on model configuration
+ */
+
+import type { LLMAdapter } from '../../types'
+import type { ModelConfig, OpenRouterOptions, GoogleOptions, AnthropicOptions } from '../../model-info'
+import { OpenAIAdapter, isOpenAIModel } from './openai'
+import { OpenRouterAdapter, isOpenRouterModel } from './openrouter'
+import { GoogleAdapter, isGoogleModel } from './google'
+import { AnthropicAdapter, isAnthropicModel } from './anthropic'
+import { MockAdapter, isMockModel } from '../mock-adapter'
+import { UniversalLLMAdapter } from '../universal-adapter'
+import type { AIUsageCollector } from '../../../../../operations/observability/ai-usage-collector'
+import type { AICallContext, BaseAICall } from '../../../../../operations/observability/types'
+
+/**
+ * Resolve API key at runtime
+ * Handles the case where env vars weren't loaded at module import time
+ * (e.g., in Docker when dotenv runs after module imports)
+ *
+ * @param configApiKey - API key from config (may be placeholder)
+ * @param provider - Provider name to determine which env var to check
+ * @returns Resolved API key
+ */
+function resolveApiKey(configApiKey: string, provider: string): string {
+  // If the config has a real API key (not a placeholder), use it
+  const isPlaceholder =
+    !configApiKey ||
+    configApiKey.startsWith('placeholder-') ||
+    configApiKey.includes('placeholder') ||
+    configApiKey.includes('test-api-key')
+  if (!isPlaceholder) {
+    return configApiKey
+  }
+
+  // Resolve from environment at runtime based on provider
+  const envVarMap: Record<string, string | undefined> = {
+    anthropic: process.env.ANTHROPIC_API_KEY,
+    openai: process.env.OPENAI_API_KEY,
+    openrouter: process.env.OPENROUTER_API_KEY,
+    google: process.env.GOOGLE_AI_STUDIO_KEY
+  }
+
+  const envKey = envVarMap[provider]
+  if (envKey) {
+    return envKey
+  }
+
+  // Fallback to config value (will fail at API call time with auth error)
+  return configApiKey
+}
+
+/**
+ * Create base adapter based on model configuration
+ * Routes to the appropriate provider-specific adapter
+ *
+ * @param config - Model configuration from resource definition
+ * @returns Base LLM adapter instance (without observability wrapper)
+ */
+function createBaseAdapter(config: ModelConfig): LLMAdapter {
+  const { model, provider, modelOptions } = config
+  const apiKey = resolveApiKey(config.apiKey, provider)
+
+  // OpenAI models
+  if (isOpenAIModel(model, provider)) {
+    return new OpenAIAdapter({
+      apiKey,
+      model,
+      modelOptions // Flat structure - no vendor namespace needed
+    })
+  }
+
+  // OpenRouter models (access to 400+ models via single API)
+  if (isOpenRouterModel(model)) {
+    return new OpenRouterAdapter({
+      apiKey,
+      model,
+      modelOptions: modelOptions as OpenRouterOptions
+    })
+  }
+
+  // Google models (direct SDK access via @google/genai)
+  if (isGoogleModel(model, provider)) {
+    return new GoogleAdapter({
+      apiKey,
+      model,
+      modelOptions: modelOptions as GoogleOptions
+    })
+  }
+
+  // Anthropic models (direct SDK access via @anthropic-ai/sdk)
+  if (isAnthropicModel(model, provider)) {
+    return new AnthropicAdapter({
+      apiKey,
+      model,
+      modelOptions: modelOptions as AnthropicOptions
+    })
+  }
+
+  // Mock provider (for testing)
+  if (isMockModel(model, provider)) {
+    return new MockAdapter()
+  }
+
+  throw new Error(`Unsupported model: ${model} with provider: ${provider}`)
+}
+
+/**
+ * Create LLM adapter based on model configuration
+ * Creates a stateless adapter instance for the execution
+ * Automatically wraps with UniversalLLMAdapter for reliability and observability
+ *
+ * @param config - Model configuration from resource definition (includes model identifier)
+ * @param aiUsageCollector - Optional collector for tracking AI usage
+ * @param callType - Optional call type discriminator for observability
+ * @param context - Optional typed context for observability
+ * @returns Stateless LLM adapter instance (wrapped with UniversalLLMAdapter)
+ */
+export function createLLMAdapter(
+  config: ModelConfig,
+  aiUsageCollector?: AIUsageCollector,
+  callType?: BaseAICall['callType'],
+  context?: AICallContext
+): LLMAdapter {
+  const baseAdapter = createBaseAdapter(config)
+
+  // Wrap with UniversalLLMAdapter for automatic retry, circuit breaker, and observability
+  return new UniversalLLMAdapter(baseAdapter, config.model, aiUsageCollector, callType, context)
+}

package/src/execution/engine/llm/adapters/server/anthropic.ts

@@ -1,137 +1,137 @@
-/**
- * Anthropic Adapter
- * Stateless translation layer between Universal Protocol and Anthropic API
- *
- * Responsibilities:
- * 1. Translate LLMGenerateRequest to Anthropic message format
- * 2. Call Anthropic SDK with tool_use for structured output
- * 3. Parse Anthropic response (extract from tool_use block)
- * 4. Translate back to LLMGenerateResponse
- */
-
-import type { LLMAdapter, LLMGenerateRequest, LLMGenerateResponse } from '../../types'
-import type { LLMModel, ModelSpecificOptions } from '../../model-info'
-import { bslogExternalServiceError, isSystemError } from '../../../../../platform/utils/server/betterstack-logger'
-import { composeSignal } from './compose-signal'
-import { DEFAULT_LLM_TIMEOUT } from '../../../../../platform/constants/timeouts'
-
-/**
- * Anthropic adapter configuration
- */
-export interface AnthropicAdapterConfig {
-  apiKey: string
-  model: LLMModel
-  modelOptions?: ModelSpecificOptions
-}
-
-/**
- * Check if the model and provider combination is for Anthropic
- *
- * @param model - Model identifier (e.g., 'claude-opus-4-5-20251101')
- * @param provider - Provider name
- * @returns True if this is an Anthropic model configuration
- */
-export function isAnthropicModel(model: LLMModel, provider: string): boolean {
-  return model.startsWith('claude-') && provider === 'anthropic'
-}
-
-/**
- * Anthropic Claude Adapter - Implements universal protocol
- * Uses tool_use for structured output (Anthropic's recommended approach)
- *
- * Key differences from other adapters:
- * - System messages go in separate `system` field (not in messages array)
- * - Structured output via tool_use (not native JSON mode)
- * - Response content is array of blocks (not string)
- * - max_tokens is required (not optional)
- * - Total tokens must be calculated (not provided)
- */
-export class AnthropicAdapter implements LLMAdapter {
-  private clientPromise: Promise<import('@anthropic-ai/sdk').default>
-  private model: LLMModel
-
-  constructor(config: AnthropicAdapterConfig) {
-    // Lazy load Anthropic SDK
-    this.clientPromise = import('@anthropic-ai/sdk').then(
-      ({ default: AnthropicClass }) => new AnthropicClass({ apiKey: config.apiKey })
-    )
-    this.model = config.model
-    // modelOptions reserved for future use (e.g., extended thinking)
-  }
-
-  /**
-   * Generate structured output from messages using Anthropic Claude
-   *
-   * @param request - Generic generation request
-   * @returns Structured output with usage metadata
-   */
-  async generate<T>(request: LLMGenerateRequest): Promise<LLMGenerateResponse<T>> {
-    const client = await this.clientPromise
-
-    try {
-      // Extract system messages (Anthropic uses separate system field)
-      const systemMessages = request.messages.filter((msg) => msg.role === 'system')
-      const nonSystemMessages = request.messages.filter((msg) => msg.role !== 'system')
-
-      // Build system content (combine multiple system messages)
-      const systemContent =
-        systemMessages.length > 0 ? systemMessages.map((msg) => msg.content).join('\n\n') : undefined
-
-      // Convert messages to Anthropic format
-      const anthropicMessages = nonSystemMessages.map((msg) => ({
-        role: msg.role as 'user' | 'assistant',
-        content: msg.content
-      }))
-
-      // Use tool_use for structured output (Anthropic's recommended approach)
-      // This guarantees schema compliance without requiring JSON mode
-      // Stream + finalMessage() to avoid SDK non-streaming timeout rejection
-      // at high max_tokens values (SDK calculates estimated time > 10 min → error)
-      const stream = client.messages.stream(
-        {
-          model: this.model,
-          max_tokens: request.maxOutputTokens || 4000, // Required for Anthropic
-          system: systemContent,
-          messages: anthropicMessages,
-          tools: [
-            {
-              name: 'structured_output',
-              description: 'Return structured output matching the required schema',
-              input_schema: request.responseSchema as import('@anthropic-ai/sdk').Anthropic.Tool['input_schema']
-            }
-          ],
-          tool_choice: { type: 'tool', name: 'structured_output' },
-          temperature: request.temperature,
-          top_p: request.topP
-        },
-        { signal: composeSignal(DEFAULT_LLM_TIMEOUT, request.signal) }
-      )
-      const response = await stream.finalMessage()
-
-      // Extract structured output from tool_use block
-      const toolUseBlock = response.content.find((block) => block.type === 'tool_use')
-      if (!toolUseBlock || toolUseBlock.type !== 'tool_use') {
-        throw new Error('Anthropic response missing tool_use block for structured output')
-      }
-      const output = toolUseBlock.input as T
-
-      // Calculate total tokens (Anthropic doesn't provide total_tokens)
-      const usage = {
-        inputTokens: response.usage.input_tokens,
-        outputTokens: response.usage.output_tokens,
-        totalTokens: response.usage.input_tokens + response.usage.output_tokens
-      }
-
-      return { output, usage }
-    } catch (error) {
-      // Add Better Stack logging for system errors (5xx only)
-      if (isSystemError(error)) {
-        bslogExternalServiceError('anthropic', 'messages.create', error as Error, {
-          model: this.model
-        })
-      }
-
-      throw error
-    }
-  }
-}
+/**
+ * Anthropic Adapter
+ * Stateless translation layer between Universal Protocol and Anthropic API
+ *
+ * Responsibilities:
+ * 1. Translate LLMGenerateRequest to Anthropic message format
+ * 2. Call Anthropic SDK with tool_use for structured output
+ * 3. Parse Anthropic response (extract from tool_use block)
+ * 4. Translate back to LLMGenerateResponse
+ */
+
+import type { LLMAdapter, LLMGenerateRequest, LLMGenerateResponse } from '../../types'
+import type { LLMModel, ModelSpecificOptions } from '../../model-info'
+import { bslogExternalServiceError, isSystemError } from '../../../../../platform/utils/server/betterstack-logger'
+import { composeSignal } from './compose-signal'
+import { DEFAULT_LLM_TIMEOUT } from '../../../../../platform/constants/timeouts'
+
+/**
+ * Anthropic adapter configuration
+ */
+export interface AnthropicAdapterConfig {
+  apiKey: string
+  model: LLMModel
+  modelOptions?: ModelSpecificOptions
+}
+
+/**
+ * Check if the model and provider combination is for Anthropic
+ *
+ * @param model - Model identifier (e.g., 'claude-opus-4-5-20251101')
+ * @param provider - Provider name
+ * @returns True if this is an Anthropic model configuration
+ */
+export function isAnthropicModel(model: LLMModel, provider: string): boolean {
+  return model.startsWith('claude-') && provider === 'anthropic'
+}
+
+/**
+ * Anthropic Claude Adapter - Implements universal protocol
+ * Uses tool_use for structured output (Anthropic's recommended approach)
+ *
+ * Key differences from other adapters:
+ * - System messages go in separate `system` field (not in messages array)
+ * - Structured output via tool_use (not native JSON mode)
+ * - Response content is array of blocks (not string)
+ * - max_tokens is required (not optional)
+ * - Total tokens must be calculated (not provided)
+ */
+export class AnthropicAdapter implements LLMAdapter {
+  private clientPromise: Promise<import('@anthropic-ai/sdk').default>
+  private model: LLMModel
+
+  constructor(config: AnthropicAdapterConfig) {
+    // Lazy load Anthropic SDK
+    this.clientPromise = import('@anthropic-ai/sdk').then(
+      ({ default: AnthropicClass }) => new AnthropicClass({ apiKey: config.apiKey })
+    )
+    this.model = config.model
+    // modelOptions reserved for future use (e.g., extended thinking)
+  }
+
+  /**
+   * Generate structured output from messages using Anthropic Claude
+   *
+   * @param request - Generic generation request
+   * @returns Structured output with usage metadata
+   */
+  async generate<T>(request: LLMGenerateRequest): Promise<LLMGenerateResponse<T>> {
+    const client = await this.clientPromise
+
+    try {
+      // Extract system messages (Anthropic uses separate system field)
+      const systemMessages = request.messages.filter((msg) => msg.role === 'system')
+      const nonSystemMessages = request.messages.filter((msg) => msg.role !== 'system')
+
+      // Build system content (combine multiple system messages)
+      const systemContent =
+        systemMessages.length > 0 ? systemMessages.map((msg) => msg.content).join('\n\n') : undefined
+
+      // Convert messages to Anthropic format
+      const anthropicMessages = nonSystemMessages.map((msg) => ({
+        role: msg.role as 'user' | 'assistant',
+        content: msg.content
+      }))
+
+      // Use tool_use for structured output (Anthropic's recommended approach)
+      // This guarantees schema compliance without requiring JSON mode
+      // Stream + finalMessage() to avoid SDK non-streaming timeout rejection
+      // at high max_tokens values (SDK calculates estimated time > 10 min → error)
+      const stream = client.messages.stream(
+        {
+          model: this.model,
+          max_tokens: request.maxOutputTokens || 4000, // Required for Anthropic
+          system: systemContent,
+          messages: anthropicMessages,
+          tools: [
+            {
+              name: 'structured_output',
+              description: 'Return structured output matching the required schema',
+              input_schema: request.responseSchema as import('@anthropic-ai/sdk').Anthropic.Tool['input_schema']
+            }
+          ],
+          tool_choice: { type: 'tool', name: 'structured_output' },
+          temperature: request.temperature,
+          top_p: request.topP
+        },
+        { signal: composeSignal(DEFAULT_LLM_TIMEOUT, request.signal) }
+      )
+      const response = await stream.finalMessage()
+
+      // Extract structured output from tool_use block
+      const toolUseBlock = response.content.find((block) => block.type === 'tool_use')
+      if (!toolUseBlock || toolUseBlock.type !== 'tool_use') {
+        throw new Error('Anthropic response missing tool_use block for structured output')
+      }
+      const output = toolUseBlock.input as T
+
+      // Calculate total tokens (Anthropic doesn't provide total_tokens)
+      const usage = {
+        inputTokens: response.usage.input_tokens,
+        outputTokens: response.usage.output_tokens,
+        totalTokens: response.usage.input_tokens + response.usage.output_tokens
+      }
+
+      return { output, usage }
+    } catch (error) {
+      // Add Better Stack logging for system errors (5xx only)
+      if (isSystemError(error)) {
+        bslogExternalServiceError('anthropic', 'messages.create', error as Error, {
+          model: this.model
+        })
+      }
+
+      throw error
+    }
+  }
+}