@twelvehart/supermemory-runtime 1.0.0-next.0

package/src/services/llm/index.ts

@@ -0,0 +1,309 @@
+/**
+ * LLM Provider Module
+ *
+ * Factory functions and exports for LLM-based memory extraction.
+ * Provides a unified interface for multiple LLM providers.
+ */
+
+import { getLogger } from '../../utils/logger.js'
+import { config as appConfig } from '../../config/index.js'
+import { isLLMFeatureEnabled } from '../../config/feature-flags.js'
+import type {
+  LLMProvider,
+  LLMProviderType,
+  OpenAILLMConfig,
+  AnthropicLLMConfig,
+  MockLLMConfig,
+  CacheConfig,
+} from './types.js'
+import { createOpenAIProvider } from './openai.js'
+import { createAnthropicProvider } from './anthropic.js'
+import { createMockProvider } from './mock.js'
+
+const logger = getLogger('LLMFactory')
+
+// ============================================================================
+// Re-exports
+// ============================================================================
+
+// Types
+export * from './types.js'
+
+// Base
+export { BaseLLMProvider, LLMError, DEFAULT_LLM_CONFIG, DEFAULT_CACHE_CONFIG } from './base.js'
+
+// Providers
+export { OpenAILLMProvider, createOpenAIProvider } from './openai.js'
+export { AnthropicLLMProvider, createAnthropicProvider } from './anthropic.js'
+export { MockLLMProvider, createMockProvider } from './mock.js'
+
+// Prompts (for testing/customization)
+export {
+  MEMORY_EXTRACTION_SYSTEM_PROMPT,
+  MEMORY_EXTRACTION_EXAMPLES,
+  RELATIONSHIP_DETECTION_SYSTEM_PROMPT,
+  RELATIONSHIP_DETECTION_EXAMPLES,
+  generateExtractionPrompt,
+  generateRelationshipPrompt,
+  parseExtractionResponse,
+  parseRelationshipResponse,
+} from './prompts.js'
+
+// Specialized Services (for memory service TODOs)
+export { MemoryClassifierService, getMemoryClassifier, resetMemoryClassifier } from './memory-classifier.service.js'
+export type { ClassificationResult, ClassifierConfig } from './memory-classifier.service.js'
+
+export {
+  ContradictionDetectorService,
+  getContradictionDetector,
+  resetContradictionDetector,
+} from './contradiction-detector.service.js'
+export type { ContradictionResult, DetectorConfig } from './contradiction-detector.service.js'
+
+export {
+  MemoryExtensionDetectorService,
+  getMemoryExtensionDetector,
+  resetMemoryExtensionDetector,
+} from './memory-extension-detector.service.js'
+export type { ExtensionResult, ExtensionDetectorConfig } from './memory-extension-detector.service.js'
+
+// ============================================================================
+// Environment Variable Names
+// ============================================================================
+
+const ENV_VARS = {
+  LLM_PROVIDER: 'LLM_PROVIDER',
+  OPENAI_API_KEY: 'OPENAI_API_KEY',
+  OPENAI_MODEL: 'OPENAI_MODEL',
+  OPENAI_BASE_URL: 'OPENAI_BASE_URL',
+  ANTHROPIC_API_KEY: 'ANTHROPIC_API_KEY',
+  ANTHROPIC_MODEL: 'ANTHROPIC_MODEL',
+  LLM_CACHE_ENABLED: 'LLM_CACHE_ENABLED',
+  LLM_CACHE_TTL_MS: 'LLM_CACHE_TTL_MS',
+} as const
+
+const PLACEHOLDER_API_KEYS = new Set(['sk-your-openai-api-key-here', 'anthropic-your-api-key-here'])
+
+function getConfiguredEnvValue(name: string): string | undefined {
+  const value = process.env[name]?.trim()
+  if (!value || PLACEHOLDER_API_KEYS.has(value)) {
+    return undefined
+  }
+  return value
+}
+
+function getConfiguredApiKey(...values: Array<string | undefined>): string {
+  for (const value of values) {
+    const trimmed = value?.trim()
+    if (trimmed && !PLACEHOLDER_API_KEYS.has(trimmed)) {
+      return trimmed
+    }
+  }
+  return ''
+}
+
+// ============================================================================
+// Factory Configuration
+// ============================================================================
+
+export interface LLMFactoryConfig {
+  /** Preferred provider type */
+  provider?: LLMProviderType
+
+  /** OpenAI-specific config */
+  openai?: Partial<OpenAILLMConfig>
+
+  /** Anthropic-specific config */
+  anthropic?: Partial<AnthropicLLMConfig>
+
+  /** Mock provider config */
+  mock?: MockLLMConfig
+
+  /** Cache configuration */
+  cache?: Partial<CacheConfig>
+
+  /** Whether to fallback to regex if no LLM available */
+  fallbackToRegex?: boolean
+}
+
+// ============================================================================
+// Factory Functions
+// ============================================================================
+
+/**
+ * Create an LLM provider based on configuration
+ */
+export function createLLMProvider(config: LLMFactoryConfig = {}): LLMProvider {
+  const providerType = config.provider ?? getDefaultProviderType()
+
+  logger.debug('Creating LLM provider', { type: providerType })
+
+  switch (providerType) {
+    case 'openai': {
+      const openaiConfig = getOpenAIConfig(config)
+      return createOpenAIProvider(openaiConfig)
+    }
+
+    case 'anthropic': {
+      const anthropicConfig = getAnthropicConfig(config)
+      return createAnthropicProvider(anthropicConfig)
+    }
+
+    case 'mock': {
+      return createMockProvider(config.mock ?? {})
+    }
+
+    default: {
+      logger.warn(`Unknown provider type: ${providerType}, falling back to mock`)
+      return createMockProvider({})
+    }
+  }
+}
+
+/**
+ * Get the default provider type based on available API keys
+ *
+ * NOTE: Only checks process.env for runtime detection.
+ */
+export function getDefaultProviderType(): LLMProviderType {
+  // Check environment variable first
+  const envProvider = process.env[ENV_VARS.LLM_PROVIDER]?.toLowerCase()
+  if (envProvider === 'mock') {
+    return envProvider
+  }
+
+  if (envProvider === 'openai' && getConfiguredEnvValue(ENV_VARS.OPENAI_API_KEY)) {
+    return envProvider
+  }
+
+  if (envProvider === 'anthropic' && getConfiguredEnvValue(ENV_VARS.ANTHROPIC_API_KEY)) {
+    return envProvider
+  }
+
+  // Check for API keys in process.env only
+  const hasOpenAI = !!getConfiguredEnvValue(ENV_VARS.OPENAI_API_KEY)
+  const hasAnthropic = !!getConfiguredEnvValue(ENV_VARS.ANTHROPIC_API_KEY)
+
+  if (hasOpenAI) {
+    return 'openai'
+  }
+
+  if (hasAnthropic) {
+    return 'anthropic'
+  }
+
+  // No API keys - return mock for graceful degradation
+  logger.info('No LLM API keys found, using mock provider')
+  return 'mock'
+}
+
+/**
+ * Get OpenAI configuration from environment and provided config
+ */
+function getOpenAIConfig(factoryConfig: LLMFactoryConfig): OpenAILLMConfig {
+  const apiKey = getConfiguredApiKey(factoryConfig.openai?.apiKey, process.env[ENV_VARS.OPENAI_API_KEY], appConfig.openaiApiKey)
+
+  return {
+    apiKey,
+    model: factoryConfig.openai?.model ?? process.env[ENV_VARS.OPENAI_MODEL] ?? 'gpt-4o-mini',
+    baseUrl: factoryConfig.openai?.baseUrl ?? process.env[ENV_VARS.OPENAI_BASE_URL],
+    maxTokens: factoryConfig.openai?.maxTokens ?? 2000,
+    temperature: factoryConfig.openai?.temperature ?? 0.1,
+    timeoutMs: factoryConfig.openai?.timeoutMs ?? 30000,
+    maxRetries: factoryConfig.openai?.maxRetries ?? 3,
+    retryDelayMs: factoryConfig.openai?.retryDelayMs ?? 1000,
+  }
+}
+
+/**
+ * Get Anthropic configuration from environment and provided config
+ */
+function getAnthropicConfig(factoryConfig: LLMFactoryConfig): AnthropicLLMConfig {
+  const apiKey = getConfiguredApiKey(factoryConfig.anthropic?.apiKey, process.env[ENV_VARS.ANTHROPIC_API_KEY])
+
+  return {
+    apiKey,
+    model: factoryConfig.anthropic?.model ?? process.env[ENV_VARS.ANTHROPIC_MODEL] ?? 'claude-3-haiku-20240307',
+    maxTokens: factoryConfig.anthropic?.maxTokens ?? 2000,
+    temperature: factoryConfig.anthropic?.temperature ?? 0.1,
+    timeoutMs: factoryConfig.anthropic?.timeoutMs ?? 30000,
+    maxRetries: factoryConfig.anthropic?.maxRetries ?? 3,
+    retryDelayMs: factoryConfig.anthropic?.retryDelayMs ?? 1000,
+  }
+}
+
+/**
+ * Check if any LLM provider is available
+ *
+ * NOTE: Only checks process.env for runtime availability detection.
+ * This allows tests to dynamically disable LLM by clearing env vars.
+ */
+export function isLLMAvailable(): boolean {
+  if (!isLLMFeatureEnabled()) {
+    return false
+  }
+  const hasOpenAI = !!getConfiguredEnvValue(ENV_VARS.OPENAI_API_KEY)
+  const hasAnthropic = !!getConfiguredEnvValue(ENV_VARS.ANTHROPIC_API_KEY)
+  return hasOpenAI || hasAnthropic
+}
+
+/**
+ * Get list of available provider types
+ *
+ * NOTE: Only checks process.env for runtime availability detection.
+ */
+export function getAvailableProviders(): LLMProviderType[] {
+  if (!isLLMFeatureEnabled()) {
+    return ['mock']
+  }
+  const providers: LLMProviderType[] = ['mock']
+
+  if (getConfiguredEnvValue(ENV_VARS.OPENAI_API_KEY)) {
+    providers.push('openai')
+  }
+
+  if (getConfiguredEnvValue(ENV_VARS.ANTHROPIC_API_KEY)) {
+    providers.push('anthropic')
+  }
+
+  return providers
+}
+
+// ============================================================================
+// Singleton Instance
+// ============================================================================
+
+let _llmProviderInstance: LLMProvider | null = null
+
+/**
+ * Get the singleton LLM provider instance
+ */
+export function getLLMProvider(config?: LLMFactoryConfig): LLMProvider {
+  if (!_llmProviderInstance) {
+    _llmProviderInstance = createLLMProvider(config)
+  }
+  return _llmProviderInstance
+}
+
+/**
+ * Reset the singleton instance (useful for testing)
+ */
+export function resetLLMProvider(): void {
+  _llmProviderInstance = null
+}
+
+/**
+ * Set a custom LLM provider instance (useful for testing)
+ */
+export function setLLMProvider(provider: LLMProvider): void {
+  _llmProviderInstance = provider
+}
+
+/**
+ * Proxy-based lazy singleton for backwards compatibility
+ */
+export const llmProvider = new Proxy({} as LLMProvider, {
+  get(_, prop) {
+    return getLLMProvider()[prop as keyof LLMProvider]
+  },
+})

package/src/services/llm/memory-classifier.service.ts

@@ -0,0 +1,383 @@
+/**
+ * Memory Type Classifier Service
+ *
+ * LLM-based semantic memory type classification with caching and fallback.
+ * Replaces pattern matching for TODO-001 in memory.service.ts
+ *
+ * Cost optimization:
+ * - Prompt caching to reduce API calls
+ * - In-memory cache with TTL
+ * - Batch classification when possible
+ * - Fallback to pattern matching on API errors
+ *
+ * Target: <$0.60/month with typical usage
+ */
+
+import { getLogger } from '../../utils/logger.js'
+import { createHash } from 'crypto'
+import type { MemoryType } from '../../types/index.js'
+import { getLLMProvider, isLLMAvailable } from './index.js'
+import { LLMError } from './base.js'
+import { classifyMemoryTypeHeuristically, calculateHeuristicConfidence } from './heuristics.js'
+
+const logger = getLogger('MemoryClassifier')
+
+// ============================================================================
+// Prompt Templates
+// ============================================================================
+
+export const MEMORY_CLASSIFIER_SYSTEM_PROMPT = `You are a memory classification expert. Classify the given content into ONE of these types:
+
+- fact: Objective information, statements of truth, definitions
+- event: Time-bound occurrences, meetings, experiences
+- preference: Personal likes, dislikes, preferences, opinions
+- skill: Abilities, capabilities, expertise, knowledge areas
+- relationship: Interpersonal connections, social bonds
+- context: Current situations, states, or ongoing activities
+- note: General notes, reminders, todos
+
+Respond with ONLY a JSON object:
+{
+  "type": "one of the types above",
+  "confidence": 0.0-1.0,
+  "reasoning": "brief explanation"
+}`
+
+export function buildMemoryClassifierUserPrompt(content: string): string {
+  return `Classify this content:\n\n"${content}"\n\nRespond with JSON only.`
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ClassificationResult {
+  type: MemoryType
+  confidence: number
+  reasoning?: string
+  cached: boolean
+  usedLLM: boolean
+}
+
+export interface ClassifierConfig {
+  /** Minimum confidence for LLM classification (0-1) */
+  minConfidence?: number
+  /** Whether to enable caching */
+  enableCache?: boolean
+  /** Cache TTL in milliseconds */
+  cacheTTLMs?: number
+  /** Maximum cache size */
+  maxCacheSize?: number
+  /** Whether to fallback to pattern matching on errors */
+  fallbackToPatterns?: boolean
+}
+
+interface CacheEntry {
+  type: MemoryType
+  confidence: number
+  reasoning?: string
+  timestamp: number
+}
+
+// ============================================================================
+// Memory Type Classifier
+// ============================================================================
+
+export class MemoryClassifierService {
+  private config: Required<ClassifierConfig>
+  private cache: Map<string, CacheEntry> = new Map()
+  private stats = {
+    totalClassifications: 0,
+    llmClassifications: 0,
+    patternClassifications: 0,
+    cacheHits: 0,
+    errors: 0,
+    totalCost: 0,
+  }
+
+  constructor(config: ClassifierConfig = {}) {
+    this.config = {
+      minConfidence: config.minConfidence ?? 0.6,
+      enableCache: config.enableCache ?? true,
+      cacheTTLMs: config.cacheTTLMs ?? 15 * 60 * 1000, // 15 minutes
+      maxCacheSize: config.maxCacheSize ?? 1000,
+      fallbackToPatterns: config.fallbackToPatterns ?? true,
+    }
+
+    logger.info('Memory classifier initialized', {
+      cacheEnabled: this.config.enableCache,
+      fallbackEnabled: this.config.fallbackToPatterns,
+    })
+  }
+
+  // ============================================================================
+  // Public API
+  // ============================================================================
+
+  /**
+   * Classify memory content into a type using LLM or pattern matching
+   *
+   * @param content - The content to classify
+   * @returns Classification result with type, confidence, and metadata
+   */
+  async classify(content: string): Promise<ClassificationResult> {
+    this.stats.totalClassifications++
+
+    // Check cache first
+    if (this.config.enableCache) {
+      const cached = this.getCached(content)
+      if (cached) {
+        this.stats.cacheHits++
+        logger.debug('Cache hit for classification', { contentPreview: content.substring(0, 50) })
+        return {
+          type: cached.type,
+          confidence: cached.confidence,
+          reasoning: cached.reasoning,
+          cached: true,
+          usedLLM: false,
+        }
+      }
+    }
+
+    // Try LLM classification if available
+    if (isLLMAvailable()) {
+      try {
+        const result = await this.classifyWithLLM(content)
+        this.stats.llmClassifications++
+
+        // Cache the result
+        if (this.config.enableCache && result.confidence >= this.config.minConfidence) {
+          this.setCached(content, {
+            type: result.type,
+            confidence: result.confidence,
+            reasoning: result.reasoning,
+            timestamp: Date.now(),
+          })
+        }
+
+        return {
+          ...result,
+          cached: false,
+          usedLLM: true,
+        }
+      } catch (error) {
+        this.stats.errors++
+        logger.warn('LLM classification failed, falling back to patterns', {
+          error: error instanceof Error ? error.message : String(error),
+        })
+
+        if (!this.config.fallbackToPatterns) {
+          throw error
+        }
+      }
+    }
+
+    // Fallback to pattern matching
+    const patternResult = this.classifyWithPatterns(content)
+    this.stats.patternClassifications++
+
+    return {
+      type: patternResult.type,
+      confidence: patternResult.confidence,
+      cached: false,
+      usedLLM: false,
+    }
+  }
+
+  /**
+   * Get classification statistics
+   */
+  getStats() {
+    const cacheHitRate =
+      this.stats.totalClassifications > 0 ? (this.stats.cacheHits / this.stats.totalClassifications) * 100 : 0
+
+    return {
+      ...this.stats,
+      cacheHitRate: parseFloat(cacheHitRate.toFixed(2)),
+      cacheSize: this.cache.size,
+    }
+  }
+
+  /**
+   * Clear the cache
+   */
+  clearCache(): void {
+    this.cache.clear()
+    logger.info('Classification cache cleared')
+  }
+
+  // ============================================================================
+  // LLM Classification
+  // ============================================================================
+
+  private async classifyWithLLM(content: string): Promise<{
+    type: MemoryType
+    confidence: number
+    reasoning?: string
+  }> {
+    const provider = getLLMProvider()
+
+    try {
+      const response = await provider.generateJson(
+        MEMORY_CLASSIFIER_SYSTEM_PROMPT,
+        buildMemoryClassifierUserPrompt(content)
+      )
+
+      const parsed = this.parseJsonResponse(response.rawResponse, response.provider)
+
+      // Estimate cost (Haiku: ~$0.25 per million input tokens, ~$1.25 per million output)
+      const inputCost = ((response.tokensUsed?.prompt ?? 0) / 1000000) * 0.25
+      const outputCost = ((response.tokensUsed?.completion ?? 0) / 1000000) * 1.25
+      this.stats.totalCost += inputCost + outputCost
+
+      logger.debug('LLM classification successful', {
+        type: parsed.type,
+        confidence: parsed.confidence,
+        tokensUsed: response.tokensUsed?.total ?? 0,
+        cost: inputCost + outputCost,
+      })
+
+      return parsed
+    } catch (error) {
+      if (error instanceof LLMError) {
+        throw error
+      }
+      throw new Error(`LLM classification failed: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+
+  // ============================================================================
+  // Pattern Matching Fallback
+  // ============================================================================
+
+  private classifyWithPatterns(content: string): {
+    type: MemoryType
+    confidence: number
+  } {
+    const heuristic = classifyMemoryTypeHeuristically(content)
+    const type = heuristic.type
+    const confidence = calculateHeuristicConfidence(heuristic.matchCount, {
+      base: 0.5,
+      perMatch: 0.1,
+      max: 0.9,
+      defaultConfidence: 0.3,
+    })
+
+    logger.debug('Pattern classification', {
+      type,
+      confidence,
+      matchCount: heuristic.matchCount,
+    })
+
+    return { type, confidence }
+  }
+
+  private parseJsonResponse(
+    rawResponse: string,
+    provider: 'openai' | 'anthropic' | 'mock'
+  ): {
+    type: MemoryType
+    confidence: number
+    reasoning?: string
+  } {
+    const trimmed = rawResponse.trim()
+    const jsonMatch = trimmed.startsWith('{') ? trimmed : trimmed.match(/\{[\s\S]*\}/)?.[0]
+    if (!jsonMatch) {
+      throw LLMError.invalidResponse(provider, 'No JSON object found in response')
+    }
+
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(jsonMatch)
+    } catch {
+      throw LLMError.invalidResponse(provider, 'Invalid JSON response')
+    }
+
+    if (!parsed || typeof parsed !== 'object' || !('type' in parsed) || !('confidence' in parsed)) {
+      throw LLMError.invalidResponse(provider, 'Missing required fields in JSON response')
+    }
+
+    const type = (parsed as { type: MemoryType }).type
+    const confidence = (parsed as { confidence: number }).confidence
+    const reasoning = (parsed as { reasoning?: string }).reasoning
+
+    const validTypes: MemoryType[] = ['fact', 'event', 'preference', 'skill', 'relationship', 'context', 'note']
+    if (!validTypes.includes(type)) {
+      throw LLMError.invalidResponse(provider, 'Invalid memory type in response')
+    }
+    if (typeof confidence !== 'number' || Number.isNaN(confidence)) {
+      throw LLMError.invalidResponse(provider, 'Invalid confidence in response')
+    }
+
+    return { type, confidence, reasoning }
+  }
+
+  // ============================================================================
+  // Caching
+  // ============================================================================
+
+  private getCacheKey(content: string): string {
+    // Use first 500 chars for cache key to avoid huge keys
+    const normalized = content.substring(0, 500).trim().toLowerCase()
+    return createHash('sha256').update(normalized).digest('hex')
+  }
+
+  private getCached(content: string): CacheEntry | null {
+    const key = this.getCacheKey(content)
+    const entry = this.cache.get(key)
+
+    if (!entry) {
+      return null
+    }
+
+    // Check if expired
+    const age = Date.now() - entry.timestamp
+    if (age > this.config.cacheTTLMs) {
+      this.cache.delete(key)
+      return null
+    }
+
+    return entry
+  }
+
+  private setCached(content: string, entry: CacheEntry): void {
+    // Enforce cache size limit
+    if (this.cache.size >= this.config.maxCacheSize) {
+      // Remove oldest 10% of entries
+      const entries = Array.from(this.cache.entries())
+      entries.sort((a, b) => a[1].timestamp - b[1].timestamp)
+      const excess = this.cache.size - this.config.maxCacheSize + 1
+      const minimumToRemove = Math.max(1, Math.ceil(this.config.maxCacheSize * 0.1))
+      const toRemove = entries.slice(0, Math.max(excess, minimumToRemove))
+      for (const [key] of toRemove) {
+        this.cache.delete(key)
+      }
+    }
+
+    const key = this.getCacheKey(content)
+    this.cache.set(key, entry)
+  }
+}
+
+// ============================================================================
+// Singleton Instance
+// ============================================================================
+
+let _instance: MemoryClassifierService | null = null
+
+/**
+ * Get the singleton instance
+ */
+export function getMemoryClassifier(config?: ClassifierConfig): MemoryClassifierService {
+  if (!_instance) {
+    _instance = new MemoryClassifierService(config)
+  }
+  return _instance
+}
+
+/**
+ * Reset the singleton (for testing)
+ */
+export function resetMemoryClassifier(): void {
+  _instance = null
+}