synapse-gateway 2.0.0

package/src/lib/distiller/index.ts

@@ -0,0 +1,331 @@
+import { db } from '../db'
+import { episodes, knowledge, proceduralRules, distillationLog } from '../db/schema'
+import { desc, sql } from 'drizzle-orm'
+import { logger } from '../utils/logger'
+import { v4 as uuid } from 'uuid'
+
+interface Pattern {
+  type: 'time_based' | 'model_preference' | 'cost_optimization' | 'quality_signal' | 'language_routing'
+  description: string
+  confidence: number
+  evidence: number
+  data: Record<string, unknown>
+}
+
+interface DistillationResult {
+  id: string
+  patternsExtracted: number
+  rulesGenerated: number
+  knowledgeUpdated: number
+  episodesProcessed: number
+  durationMs: number
+}
+
+class ExperienceDistiller {
+  private intervalHandle: ReturnType<typeof setInterval> | null = null
+
+  start(intervalMs = 6 * 60 * 60 * 1000) {
+    if (this.intervalHandle) return
+
+    logger.info({ intervalHours: intervalMs / 3600000 }, 'Experience Distiller started')
+
+    this.intervalHandle = setInterval(async () => {
+      try {
+        await this.run()
+      } catch (err) {
+        logger.error({ error: (err as Error).message }, 'Distillation run failed')
+      }
+    }, intervalMs)
+
+    setTimeout(() => this.run(), 5000)
+  }
+
+  stop() {
+    if (this.intervalHandle) {
+      clearInterval(this.intervalHandle)
+      this.intervalHandle = null
+      logger.info('Experience Distiller stopped')
+    }
+  }
+
+  async run(): Promise<DistillationResult> {
+    const start = Date.now()
+    const runId = uuid()
+    logger.info({ runId }, 'Starting distillation run')
+
+    let episodesProcessed = 0
+    let patternsExtracted = 0
+    let rulesGenerated = 0
+    let knowledgeUpdated = 0
+
+    const recentEpisodes = await this.getRecentEpisodes()
+    episodesProcessed = recentEpisodes.length
+
+    if (episodesProcessed === 0) {
+      logger.info('No episodes to distill')
+      return this.saveRun(runId, 0, 0, 0, 0, Date.now() - start)
+    }
+
+    const patterns = this.extractPatterns(recentEpisodes)
+    patternsExtracted = patterns.length
+
+    const rules = this.generateRules(patterns)
+    rulesGenerated = rules.length
+
+    for (const rule of rules) {
+      try {
+        await db.insert(proceduralRules).values({
+          id: uuid(),
+          category: rule.category,
+          condition: rule.condition,
+          action: rule.action,
+          confidence: rule.confidence,
+          priority: rule.priority,
+          status: 'auto_generated',
+        })
+      } catch {
+        // ignore duplicate
+      }
+    }
+
+    const facts = this.extractKnowledge(recentEpisodes)
+    knowledgeUpdated = facts.length
+
+    for (const fact of facts) {
+      try {
+        const existing = await db.select().from(knowledge)
+          .where(sql`${knowledge.category} = ${fact.category} AND ${knowledge.subject} = ${fact.subject} AND ${knowledge.key} = ${fact.key}`)
+          .limit(1)
+
+        if (existing.length > 0) {
+          await db.update(knowledge).set({
+            value: fact.value,
+            confidence: fact.confidence,
+            lastUpdated: new Date().toISOString(),
+            sampleCount: sql`${knowledge.sampleCount} + 1`,
+          }).where(eq(knowledge.id, existing[0].id))
+        } else {
+          await db.insert(knowledge).values({
+            id: uuid(),
+            category: fact.category,
+            subject: fact.subject,
+            key: fact.key,
+            value: fact.value,
+            confidence: fact.confidence,
+            source: 'distiller',
+          })
+        }
+      } catch {
+        // ignore
+      }
+    }
+
+    const durationMs = Date.now() - start
+    logger.info({ runId, patternsExtracted, rulesGenerated, knowledgeUpdated, episodesProcessed, durationMs }, 'Distillation complete')
+
+    return this.saveRun(runId, patternsExtracted, rulesGenerated, knowledgeUpdated, episodesProcessed, durationMs)
+  }
+
+  private async getRecentEpisodes() {
+    try {
+      const cutoff = new Date(Date.now() - 6 * 60 * 60 * 1000).toISOString()
+      return await db.select().from(episodes)
+        .where(sql`${episodes.createdAt} > ${cutoff}`)
+        .orderBy(desc(episodes.createdAt))
+        .limit(1000)
+    } catch {
+      return []
+    }
+  }
+
+  private extractPatterns(episodes: Array<Record<string, unknown>>): Pattern[] {
+    const patterns: Pattern[] = []
+
+    const byModel = new Map<string, number>()
+    const byProvider = new Map<string, { count: number; totalLatency: number; totalQuality: number }>()
+
+    for (const ep of episodes) {
+      const model = String(ep.model || 'unknown')
+      byModel.set(model, (byModel.get(model) || 0) + 1)
+
+      const provider = String(ep.provider || 'unknown')
+      const existing = byProvider.get(provider) || { count: 0, totalLatency: 0, totalQuality: 0 }
+      existing.count++
+      existing.totalLatency += Number(ep.latencyMs || 0)
+      existing.totalQuality += Number(ep.qualityScore || 0)
+      byProvider.set(provider, existing)
+    }
+
+    const total = episodes.length
+    for (const [model, count] of byModel) {
+      const ratio = count / total
+      if (ratio > 0.4) {
+        patterns.push({
+          type: 'model_preference',
+          description: `${model} is used ${Math.round(ratio * 100)}% of the time`,
+          confidence: Math.min(ratio, 0.95),
+          evidence: count,
+          data: { model, ratio, count },
+        })
+      }
+    }
+
+    for (const [provider, stats] of byProvider) {
+      if (stats.count < 5) continue
+      const avgLatency = stats.totalLatency / stats.count
+      const avgQuality = stats.totalQuality / stats.count
+
+      if (avgLatency < 500 && avgQuality > 4) {
+        patterns.push({
+          type: 'quality_signal',
+          description: `${provider} performs well: avg ${Math.round(avgLatency)}ms latency, ${avgQuality.toFixed(1)} quality`,
+          confidence: 0.85,
+          evidence: stats.count,
+          data: { provider, avgLatency, avgQuality },
+        })
+      }
+    }
+
+    return patterns
+  }
+
+  private generateRules(patterns: Pattern[]): Array<{
+    category: string
+    condition: string
+    action: string
+    priority: number
+    confidence: number
+  }> {
+    const rules: Array<{
+      category: string
+      condition: string
+      action: string
+      priority: number
+      confidence: number
+    }> = []
+
+    for (const p of patterns) {
+      switch (p.type) {
+        case 'model_preference': {
+          const model = (p.data as { model: string }).model
+          rules.push({
+            category: 'routing',
+            condition: `model:${model}`,
+            action: 'increase_priority',
+            priority: 8,
+            confidence: p.confidence,
+          })
+          break
+        }
+        case 'quality_signal': {
+          const provider = (p.data as { provider: string }).provider
+          rules.push({
+            category: 'routing',
+            condition: `provider:${provider}`,
+            action: 'prefer_for_quality',
+            priority: 7,
+            confidence: p.confidence,
+          })
+          break
+        }
+        case 'cost_optimization': {
+          rules.push({
+            category: 'cost',
+            condition: 'high_usage_period',
+            action: 'prefer_low_cost_provider',
+            priority: 5,
+            confidence: p.confidence * 0.8,
+          })
+          break
+        }
+      }
+    }
+
+    return rules
+  }
+
+  private extractKnowledge(episodes: Array<Record<string, unknown>>): Array<{
+    category: string
+    subject: string
+    key: string
+    value: string
+    confidence: number
+  }> {
+    const facts: Array<{
+      category: string
+      subject: string
+      key: string
+      value: string
+      confidence: number
+    }> = []
+
+    const modelStats = new Map<string, { count: number; avgLatency: number; avgCost: number }>()
+
+    for (const ep of episodes) {
+      const model = String(ep.model || 'unknown')
+      const existing = modelStats.get(model) || { count: 0, avgLatency: 0, avgCost: 0 }
+      existing.count++
+      existing.avgLatency = (existing.avgLatency * (existing.count - 1) + Number(ep.latencyMs || 0)) / existing.count
+      existing.avgCost = (existing.avgCost * (existing.count - 1) + Number(ep.cost || 0)) / existing.count
+      modelStats.set(model, existing)
+    }
+
+    for (const [model, stats] of modelStats) {
+      if (stats.count >= 5) {
+        facts.push({
+          category: 'performance',
+          subject: model,
+          key: 'avg_latency',
+          value: `${Math.round(stats.avgLatency)}ms over ${stats.count} requests`,
+          confidence: Math.min(stats.count / 100, 0.9),
+        })
+        facts.push({
+          category: 'cost',
+          subject: model,
+          key: 'avg_cost',
+          value: `$${stats.avgCost.toFixed(4)} per request over ${stats.count} requests`,
+          confidence: Math.min(stats.count / 100, 0.9),
+        })
+      }
+    }
+
+    return facts
+  }
+
+  private async saveRun(
+    runId: string,
+    patternsExtracted: number,
+    rulesGenerated: number,
+    knowledgeUpdated: number,
+    episodesProcessed: number,
+    durationMs: number,
+  ): Promise<DistillationResult> {
+    try {
+      await db.insert(distillationLog).values({
+        id: runId,
+        startedAt: new Date(Date.now() - durationMs).toISOString(),
+        completedAt: new Date().toISOString(),
+        episodesProcessed,
+        patternsFound: patternsExtracted,
+        rulesGenerated,
+        knowledgeEntriesAdded: knowledgeUpdated,
+        status: 'completed',
+      })
+    } catch {
+      // table might not exist
+    }
+
+    return {
+      id: runId,
+      patternsExtracted,
+      rulesGenerated,
+      knowledgeUpdated,
+      episodesProcessed,
+      durationMs,
+    }
+  }
+}
+
+import { eq } from 'drizzle-orm'
+
+export const experienceDistiller = new ExperienceDistiller()

package/src/lib/fallback/index.ts

@@ -0,0 +1,153 @@
+import type { NormalizedRequest, NormalizedResponse, ProviderAccount, ProviderAdapter, HealthStatusType } from '../providers/types'
+import { logger } from '../utils/logger'
+
+export interface FallbackOptions {
+  maxRetries: number
+  retryDelayMs: number
+  timeoutMs: number
+  retryOnStatusCodes: number[]
+  retryOnErrors: string[]
+  healthThreshold: HealthStatusType
+  preferCostOverLatency: boolean
+}
+
+export const DEFAULT_FALLBACK_OPTIONS: FallbackOptions = {
+  maxRetries: 3,
+  retryDelayMs: 1000,
+  timeoutMs: 30000,
+  retryOnStatusCodes: [429, 500, 502, 503, 504],
+  retryOnErrors: ['timeout', 'rate_limit', 'overloaded', 'context_length_exceeded'],
+  healthThreshold: 'healthy',
+  preferCostOverLatency: false,
+}
+
+interface FallbackCandidate {
+  adapter: ProviderAdapter
+  account: ProviderAccount
+  priority: number
+  cost: number
+  latency: number
+  health: HealthStatusType
+}
+
+export class FallbackEngine {
+  private options: FallbackOptions
+
+  constructor(options?: Partial<FallbackOptions>) {
+    this.options = { ...DEFAULT_FALLBACK_OPTIONS, ...options }
+  }
+
+  async executeWithFallback(
+    req: NormalizedRequest,
+    candidates: FallbackCandidate[],
+  ): Promise<{
+    response: NormalizedResponse
+    provider: string
+    model: string
+    fallbackUsed: boolean
+    fallbackChain: string[]
+    attempts: number
+  }> {
+    const sorted = this.rankCandidates(candidates)
+    const fallbackChain: string[] = []
+
+    for (let attempt = 0; attempt < sorted.length; attempt++) {
+      const candidate = sorted[attempt]
+      const { adapter, account } = candidate
+
+      if (!account.enabled) {
+        fallbackChain.push(`${adapter.info.name}: account disabled`)
+        continue
+      }
+
+      if (!this.isHealthyEnough(candidate.health)) {
+        fallbackChain.push(`${adapter.info.name}: unhealthy (${candidate.health})`)
+        continue
+      }
+
+      try {
+        const response = await this.executeWithTimeout(adapter, req, account)
+        return {
+          response,
+          provider: adapter.info.name,
+          model: req.model,
+          fallbackUsed: attempt > 0,
+          fallbackChain,
+          attempts: attempt + 1,
+        }
+      } catch (err) {
+        const errorMsg = (err as Error).message
+        fallbackChain.push(`${adapter.info.name}: ${errorMsg}`)
+        logger.warn(
+          { provider: adapter.info.name, attempt: attempt + 1, error: errorMsg, model: req.model },
+          'Fallback: provider failed',
+        )
+
+        if (this.isRetryableError(errorMsg) && attempt < this.options.maxRetries - 1) {
+          const delay = this.options.retryDelayMs * Math.pow(2, attempt)
+          await this.sleep(delay)
+          attempt--
+        }
+      }
+    }
+
+    throw new FallbackExhaustedError(
+      `All ${sorted.length} providers failed for model "${req.model}"`,
+      fallbackChain,
+    )
+  }
+
+  private rankCandidates(candidates: FallbackCandidate[]): FallbackCandidate[] {
+    return [...candidates].sort((a, b) => {
+      const healthOrder: Record<HealthStatusType, number> = { healthy: 0, degraded: 1, down: 2, disabled: 3 }
+      const healthDiff = (healthOrder[a.health] ?? 99) - (healthOrder[b.health] ?? 99)
+      if (healthDiff !== 0) return healthDiff
+
+      const priorityDiff = a.priority - b.priority
+      if (priorityDiff !== 0) return priorityDiff
+
+      if (this.options.preferCostOverLatency) {
+        return a.cost - b.cost
+      }
+      return a.latency - b.latency
+    })
+  }
+
+  private isHealthyEnough(health: HealthStatusType): boolean {
+    const order: Record<HealthStatusType, number> = { healthy: 0, degraded: 1, down: 2, disabled: 3 }
+    const threshold = order[this.options.healthThreshold] ?? 0
+    return (order[health] ?? 99) <= threshold
+  }
+
+  private isRetryableError(errorMsg: string): boolean {
+    const lower = errorMsg.toLowerCase()
+    return this.options.retryOnErrors.some((e) => lower.includes(e))
+  }
+
+  private async executeWithTimeout(
+    adapter: ProviderAdapter,
+    req: NormalizedRequest,
+    account: ProviderAccount,
+  ): Promise<NormalizedResponse> {
+    return Promise.race([
+      adapter.chatCompletion(req, account),
+      new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error(`Timeout after ${this.options.timeoutMs}ms`)), this.options.timeoutMs),
+      ),
+    ])
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+}
+
+export class FallbackExhaustedError extends Error {
+  fallbackChain: string[]
+
+  constructor(message: string, fallbackChain: string[]) {
+    super(message)
+    this.name = 'FallbackExhaustedError'
+    this.fallbackChain = fallbackChain
+  }
+}

package/src/lib/forensics/index.ts

@@ -0,0 +1,188 @@
+import { db } from '../db'
+import { requestLogs } from '../db/schema'
+import { eq, desc, sql, and } from 'drizzle-orm'
+import type { NormalizedRequest, NormalizedResponse } from '../providers/types'
+import { logger } from '../utils/logger'
+import { v4 as uuid } from 'uuid'
+
+export interface ForensicReport {
+  requestId: string
+  model: string
+  provider: string
+  inputTokens: number
+  outputTokens: number
+  tokensSaved: number
+  cost: number
+  latencyMs: number
+  statusCode: number | null
+  fallbackUsed: boolean
+  cached: boolean
+  skillId: string | null
+  errorMessage: string | null
+  timeline: TimelineEvent[]
+  analysis: ForensicAnalysis
+}
+
+export interface TimelineEvent {
+  timestamp: string
+  event: string
+  durationMs: number
+  metadata?: Record<string, unknown>
+}
+
+export interface ForensicAnalysis {
+  verdict: 'success' | 'degraded' | 'failure' | 'timeout' | 'rate_limited'
+  rootCause?: string
+  suggestions: string[]
+  cacheHit: boolean
+  fallbackTriggered: boolean
+  latencyBreakdown: {
+    total: number
+    network: number
+    provider: number
+    overhead: number
+  }
+}
+
+class ForensicsEngine {
+  async analyzeRequest(requestId: string): Promise<ForensicReport | null> {
+    try {
+      const rows = await db.select().from(requestLogs)
+        .where(eq(requestLogs.requestId, requestId))
+        .limit(1)
+
+      if (rows.length === 0) return null
+
+      const row = rows[0]
+      const analysis = this.analyze(row)
+
+      return {
+        requestId: row.requestId,
+        model: row.model,
+        provider: row.providerId || 'unknown',
+        inputTokens: row.inputTokens || 0,
+        outputTokens: row.outputTokens || 0,
+        tokensSaved: row.tokensSaved || 0,
+        cost: Number(row.cost || 0),
+        latencyMs: row.latencyMs || 0,
+        statusCode: row.statusCode,
+        fallbackUsed: !!row.fallbackUsed,
+        cached: !!row.cached,
+        skillId: row.skillId || null,
+        errorMessage: row.errorMessage,
+        timeline: this.buildTimeline(row),
+        analysis,
+      }
+    } catch (err) {
+      logger.warn({ error: (err as Error).message }, 'Forensic analysis failed')
+      return null
+    }
+  }
+
+  async getRecentFailures(limit = 20) {
+    try {
+      return await db.select().from(requestLogs)
+        .where(sql`${requestLogs.statusCode} >= 400 OR ${requestLogs.errorMessage} IS NOT NULL`)
+        .orderBy(desc(requestLogs.createdAt))
+        .limit(limit)
+    } catch {
+      return []
+    }
+  }
+
+  async getSlowRequests(thresholdMs = 3000, limit = 20) {
+    try {
+      return await db.select().from(requestLogs)
+        .where(sql`${requestLogs.latencyMs} > ${thresholdMs}`)
+        .orderBy(desc(requestLogs.latencyMs))
+        .limit(limit)
+    } catch {
+      return []
+    }
+  }
+
+  private analyze(row: Record<string, unknown>): ForensicAnalysis {
+    const statusCode = row.status_code as number | null
+    const latencyMs = (row.latency_ms as number) || 0
+    const errorMessage = row.error_message as string | null
+    const cached = !!(row.cached as number)
+    const fallbackUsed = !!(row.fallback_used as number)
+
+    let verdict: ForensicAnalysis['verdict'] = 'success'
+    const suggestions: string[] = []
+    let rootCause: string | undefined
+
+    if (statusCode && statusCode >= 500) {
+      verdict = 'failure'
+      rootCause = 'provider_error'
+      suggestions.push('Check provider health status')
+      suggestions.push('Review provider error logs')
+    } else if (statusCode === 429) {
+      verdict = 'rate_limited'
+      rootCause = 'rate_limit'
+      suggestions.push('Reduce request rate')
+      suggestions.push('Add more provider accounts')
+      suggestions.push('Enable request queuing')
+    } else if (statusCode && statusCode >= 400) {
+      verdict = 'failure'
+      rootCause = 'client_error'
+      suggestions.push('Review request format')
+    } else if (latencyMs > 10000) {
+      verdict = 'timeout'
+      rootCause = 'slow_provider'
+      suggestions.push('Consider faster model')
+      suggestions.push('Enable request timeout')
+    } else if (latencyMs > 3000) {
+      verdict = 'degraded'
+      suggestions.push('Review provider latency trends')
+    }
+
+    if (fallbackUsed && !rootCause) {
+      rootCause = 'primary_provider_failed'
+      suggestions.push('Check primary provider health')
+    }
+
+    return {
+      verdict,
+      rootCause,
+      suggestions,
+      cacheHit: cached,
+      fallbackTriggered: fallbackUsed,
+      latencyBreakdown: {
+        total: latencyMs,
+        network: Math.round(latencyMs * 0.3),
+        provider: Math.round(latencyMs * 0.6),
+        overhead: Math.round(latencyMs * 0.1),
+      },
+    }
+  }
+
+  private buildTimeline(row: Record<string, unknown>): TimelineEvent[] {
+    const latencyMs = (row.latency_ms as number) || 0
+    const cached = !!(row.cached as number)
+    const fallbackUsed = !!(row.fallback_used as number)
+    const events: TimelineEvent[] = []
+
+    events.push({ timestamp: row.created_at as string, event: 'request_received', durationMs: 0 })
+
+    if (cached) {
+      events.push({ timestamp: row.created_at as string, event: 'cache_hit', durationMs: 2 })
+    } else {
+      events.push({ timestamp: row.created_at as string, event: 'cache_miss', durationMs: 1 })
+      events.push({ timestamp: row.created_at as string, event: 'route_selected', durationMs: 5, metadata: { provider: row.provider_id } })
+
+      if (fallbackUsed) {
+        events.push({ timestamp: row.created_at as string, event: 'primary_failed', durationMs: Math.round(latencyMs * 0.3) })
+        events.push({ timestamp: row.created_at as string, event: 'fallback_triggered', durationMs: Math.round(latencyMs * 0.7) })
+      } else {
+        events.push({ timestamp: row.created_at as string, event: 'provider_call', durationMs: latencyMs })
+      }
+
+      events.push({ timestamp: row.created_at as string, event: 'response_received', durationMs: 0 })
+    }
+
+    return events
+  }
+}
+
+export const forensicsEngine = new ForensicsEngine()