claude-brain 0.15.2 → 0.16.0

package/src/retrieval/feedback/adaptive.ts

@@ -1,223 +1,223 @@
-/**
- * Adaptive Learning
- * Learns optimal retrieval thresholds from feedback
- */
-
-import type { Logger } from 'pino'
-import type { MemoryFeedback, AdaptiveThresholds, RetrievalMetrics } from '../types'
-import type { FeedbackStore } from './store'
-import { calculateAllMetrics, calculateAverageRating, calculatePositiveRate } from './metrics'
-
-/** Default thresholds before any learning */
-const DEFAULT_THRESHOLDS: AdaptiveThresholds = {
-  denseMinSimilarity: 0.3,
-  denseWeight: 0.7,
-  sparseWeight: 0.3,
-  rrfK: 60,
-  feedbackCount: 0,
-  lastUpdated: new Date().toISOString()
-}
-
-/** Thresholds bounds to prevent extreme values */
-const BOUNDS = {
-  denseMinSimilarity: { min: 0.1, max: 0.9 },
-  denseWeight: { min: 0.3, max: 0.9 },
-  sparseWeight: { min: 0.1, max: 0.7 },
-  rrfK: { min: 20, max: 100 }
-}
-
-export interface AdaptiveLearnerConfig {
-  /** Minimum feedback count before adaptation */
-  minFeedbackForAdaptation: number
-  /** Learning rate for threshold adjustments */
-  learningRate: number
-  /** Target positive feedback rate */
-  targetPositiveRate: number
-}
-
-const DEFAULT_CONFIG: AdaptiveLearnerConfig = {
-  minFeedbackForAdaptation: 10,
-  learningRate: 0.1,
-  targetPositiveRate: 0.7
-}
-
-export class AdaptiveLearner {
-  private logger: Logger
-  private feedbackStore: FeedbackStore
-  private config: AdaptiveLearnerConfig
-  private currentThresholds: AdaptiveThresholds
-
-  constructor(
-    logger: Logger,
-    feedbackStore: FeedbackStore,
-    config: Partial<AdaptiveLearnerConfig> = {}
-  ) {
-    this.logger = logger.child({ component: 'adaptive-learner' })
-    this.feedbackStore = feedbackStore
-    this.config = { ...DEFAULT_CONFIG, ...config }
-    this.currentThresholds = { ...DEFAULT_THRESHOLDS }
-  }
-
-  /**
-   * Get current adaptive thresholds
-   */
-  getThresholds(): AdaptiveThresholds {
-    return { ...this.currentThresholds }
-  }
-
-  /**
-   * Update thresholds based on feedback
-   */
-  async updateThresholds(): Promise<AdaptiveThresholds> {
-    const feedback = await this.feedbackStore.getRecentFeedback(1000)
-
-    if (feedback.length < this.config.minFeedbackForAdaptation) {
-      this.logger.debug({
-        feedbackCount: feedback.length,
-        required: this.config.minFeedbackForAdaptation
-      }, 'Not enough feedback for adaptation')
-      return this.currentThresholds
-    }
-
-    this.logger.info({ feedbackCount: feedback.length }, 'Adapting thresholds')
-
-    const metrics = calculateAllMetrics(feedback)
-    const positiveRate = calculatePositiveRate(feedback)
-    const avgRating = calculateAverageRating(feedback)
-
-    // Analyze feedback by provenance
-    const denseOnly = feedback.filter(f => this.inferProvenance(f) === 'dense')
-    const sparseOnly = feedback.filter(f => this.inferProvenance(f) === 'sparse')
-    const both = feedback.filter(f => this.inferProvenance(f) === 'both')
-
-    const densePositiveRate = denseOnly.length > 0 ? calculatePositiveRate(denseOnly) : 0.5
-    const sparsePositiveRate = sparseOnly.length > 0 ? calculatePositiveRate(sparseOnly) : 0.5
-    const bothPositiveRate = both.length > 0 ? calculatePositiveRate(both) : 0.5
-
-    // Adjust dense/sparse weights based on performance
-    if (denseOnly.length >= 5 && sparseOnly.length >= 5) {
-      // If dense performs better, increase its weight
-      if (densePositiveRate > sparsePositiveRate + 0.1) {
-        this.currentThresholds.denseWeight = this.adjustValue(
-          this.currentThresholds.denseWeight,
-          this.config.learningRate,
-          'increase',
-          BOUNDS.denseWeight
-        )
-        this.currentThresholds.sparseWeight = this.adjustValue(
-          this.currentThresholds.sparseWeight,
-          this.config.learningRate,
-          'decrease',
-          BOUNDS.sparseWeight
-        )
-      }
-      // If sparse performs better, increase its weight
-      else if (sparsePositiveRate > densePositiveRate + 0.1) {
-        this.currentThresholds.sparseWeight = this.adjustValue(
-          this.currentThresholds.sparseWeight,
-          this.config.learningRate,
-          'increase',
-          BOUNDS.sparseWeight
-        )
-        this.currentThresholds.denseWeight = this.adjustValue(
-          this.currentThresholds.denseWeight,
-          this.config.learningRate,
-          'decrease',
-          BOUNDS.denseWeight
-        )
-      }
-    }
-
-    // Adjust minimum similarity based on positive rate
-    if (positiveRate < this.config.targetPositiveRate - 0.1) {
-      // Too many negative results - lower threshold to get more results
-      this.currentThresholds.denseMinSimilarity = this.adjustValue(
-        this.currentThresholds.denseMinSimilarity,
-        this.config.learningRate,
-        'decrease',
-        BOUNDS.denseMinSimilarity
-      )
-    } else if (positiveRate > this.config.targetPositiveRate + 0.1) {
-      // Results are good - can raise threshold to be more selective
-      this.currentThresholds.denseMinSimilarity = this.adjustValue(
-        this.currentThresholds.denseMinSimilarity,
-        this.config.learningRate / 2, // More conservative increase
-        'increase',
-        BOUNDS.denseMinSimilarity
-      )
-    }
-
-    // Adjust RRF K based on metrics
-    // Higher K reduces effect of rank, lower K emphasizes top ranks
-    if (metrics.mrr < 0.5 && both.length > 0) {
-      // If MRR is low and we have combined results, try lower K
-      this.currentThresholds.rrfK = this.adjustValue(
-        this.currentThresholds.rrfK,
-        5, // Adjust by fixed amount
-        'decrease',
-        BOUNDS.rrfK
-      )
-    }
-
-    this.currentThresholds.feedbackCount = feedback.length
-    this.currentThresholds.lastUpdated = new Date().toISOString()
-
-    this.logger.info({
-      thresholds: this.currentThresholds,
-      metrics,
-      positiveRate,
-      avgRating
-    }, 'Thresholds adapted')
-
-    return this.currentThresholds
-  }
-
-  /**
-   * Adjust a value with bounds checking
-   */
-  private adjustValue(
-    current: number,
-    amount: number,
-    direction: 'increase' | 'decrease',
-    bounds: { min: number; max: number }
-  ): number {
-    const delta = direction === 'increase' ? amount : -amount
-    const newValue = current + delta
-    return Math.max(bounds.min, Math.min(bounds.max, newValue))
-  }
-
-  /**
-   * Infer provenance from feedback (heuristic)
-   * In a real implementation, this would be stored in feedback
-   */
-  private inferProvenance(feedback: MemoryFeedback): 'dense' | 'sparse' | 'both' {
-    // This is a heuristic - in production, provenance should be stored with feedback
-    // For now, assume most results are from combined search
-    return 'both'
-  }
-
-  /**
-   * Get adaptation status
-   */
-  getStatus(): {
-    feedbackCount: number
-    canAdapt: boolean
-    currentThresholds: AdaptiveThresholds
-    lastUpdated: string
-  } {
-    return {
-      feedbackCount: this.currentThresholds.feedbackCount,
-      canAdapt: this.currentThresholds.feedbackCount >= this.config.minFeedbackForAdaptation,
-      currentThresholds: this.currentThresholds,
-      lastUpdated: this.currentThresholds.lastUpdated
-    }
-  }
-
-  /**
-   * Reset thresholds to defaults
-   */
-  reset(): void {
-    this.currentThresholds = { ...DEFAULT_THRESHOLDS }
-    this.logger.info('Thresholds reset to defaults')
-  }
-}
+/**
+ * Adaptive Learning
+ * Learns optimal retrieval thresholds from feedback
+ */
+
+import type { Logger } from 'pino'
+import type { MemoryFeedback, AdaptiveThresholds, RetrievalMetrics } from '../types'
+import type { FeedbackStore } from './store'
+import { calculateAllMetrics, calculateAverageRating, calculatePositiveRate } from './metrics'
+
+/** Default thresholds before any learning */
+const DEFAULT_THRESHOLDS: AdaptiveThresholds = {
+  denseMinSimilarity: 0.3,
+  denseWeight: 0.7,
+  sparseWeight: 0.3,
+  rrfK: 60,
+  feedbackCount: 0,
+  lastUpdated: new Date().toISOString()
+}
+
+/** Thresholds bounds to prevent extreme values */
+const BOUNDS = {
+  denseMinSimilarity: { min: 0.1, max: 0.9 },
+  denseWeight: { min: 0.3, max: 0.9 },
+  sparseWeight: { min: 0.1, max: 0.7 },
+  rrfK: { min: 20, max: 100 }
+}
+
+export interface AdaptiveLearnerConfig {
+  /** Minimum feedback count before adaptation */
+  minFeedbackForAdaptation: number
+  /** Learning rate for threshold adjustments */
+  learningRate: number
+  /** Target positive feedback rate */
+  targetPositiveRate: number
+}
+
+const DEFAULT_CONFIG: AdaptiveLearnerConfig = {
+  minFeedbackForAdaptation: 10,
+  learningRate: 0.1,
+  targetPositiveRate: 0.7
+}
+
+export class AdaptiveLearner {
+  private logger: Logger
+  private feedbackStore: FeedbackStore
+  private config: AdaptiveLearnerConfig
+  private currentThresholds: AdaptiveThresholds
+
+  constructor(
+    logger: Logger,
+    feedbackStore: FeedbackStore,
+    config: Partial<AdaptiveLearnerConfig> = {}
+  ) {
+    this.logger = logger.child({ component: 'adaptive-learner' })
+    this.feedbackStore = feedbackStore
+    this.config = { ...DEFAULT_CONFIG, ...config }
+    this.currentThresholds = { ...DEFAULT_THRESHOLDS }
+  }
+
+  /**
+   * Get current adaptive thresholds
+   */
+  getThresholds(): AdaptiveThresholds {
+    return { ...this.currentThresholds }
+  }
+
+  /**
+   * Update thresholds based on feedback
+   */
+  async updateThresholds(): Promise<AdaptiveThresholds> {
+    const feedback = await this.feedbackStore.getRecentFeedback(1000)
+
+    if (feedback.length < this.config.minFeedbackForAdaptation) {
+      this.logger.debug({
+        feedbackCount: feedback.length,
+        required: this.config.minFeedbackForAdaptation
+      }, 'Not enough feedback for adaptation')
+      return this.currentThresholds
+    }
+
+    this.logger.info({ feedbackCount: feedback.length }, 'Adapting thresholds')
+
+    const metrics = calculateAllMetrics(feedback)
+    const positiveRate = calculatePositiveRate(feedback)
+    const avgRating = calculateAverageRating(feedback)
+
+    // Analyze feedback by provenance
+    const denseOnly = feedback.filter(f => this.inferProvenance(f) === 'dense')
+    const sparseOnly = feedback.filter(f => this.inferProvenance(f) === 'sparse')
+    const both = feedback.filter(f => this.inferProvenance(f) === 'both')
+
+    const densePositiveRate = denseOnly.length > 0 ? calculatePositiveRate(denseOnly) : 0.5
+    const sparsePositiveRate = sparseOnly.length > 0 ? calculatePositiveRate(sparseOnly) : 0.5
+    const bothPositiveRate = both.length > 0 ? calculatePositiveRate(both) : 0.5
+
+    // Adjust dense/sparse weights based on performance
+    if (denseOnly.length >= 5 && sparseOnly.length >= 5) {
+      // If dense performs better, increase its weight
+      if (densePositiveRate > sparsePositiveRate + 0.1) {
+        this.currentThresholds.denseWeight = this.adjustValue(
+          this.currentThresholds.denseWeight,
+          this.config.learningRate,
+          'increase',
+          BOUNDS.denseWeight
+        )
+        this.currentThresholds.sparseWeight = this.adjustValue(
+          this.currentThresholds.sparseWeight,
+          this.config.learningRate,
+          'decrease',
+          BOUNDS.sparseWeight
+        )
+      }
+      // If sparse performs better, increase its weight
+      else if (sparsePositiveRate > densePositiveRate + 0.1) {
+        this.currentThresholds.sparseWeight = this.adjustValue(
+          this.currentThresholds.sparseWeight,
+          this.config.learningRate,
+          'increase',
+          BOUNDS.sparseWeight
+        )
+        this.currentThresholds.denseWeight = this.adjustValue(
+          this.currentThresholds.denseWeight,
+          this.config.learningRate,
+          'decrease',
+          BOUNDS.denseWeight
+        )
+      }
+    }
+
+    // Adjust minimum similarity based on positive rate
+    if (positiveRate < this.config.targetPositiveRate - 0.1) {
+      // Too many negative results - lower threshold to get more results
+      this.currentThresholds.denseMinSimilarity = this.adjustValue(
+        this.currentThresholds.denseMinSimilarity,
+        this.config.learningRate,
+        'decrease',
+        BOUNDS.denseMinSimilarity
+      )
+    } else if (positiveRate > this.config.targetPositiveRate + 0.1) {
+      // Results are good - can raise threshold to be more selective
+      this.currentThresholds.denseMinSimilarity = this.adjustValue(
+        this.currentThresholds.denseMinSimilarity,
+        this.config.learningRate / 2, // More conservative increase
+        'increase',
+        BOUNDS.denseMinSimilarity
+      )
+    }
+
+    // Adjust RRF K based on metrics
+    // Higher K reduces effect of rank, lower K emphasizes top ranks
+    if (metrics.mrr < 0.5 && both.length > 0) {
+      // If MRR is low and we have combined results, try lower K
+      this.currentThresholds.rrfK = this.adjustValue(
+        this.currentThresholds.rrfK,
+        5, // Adjust by fixed amount
+        'decrease',
+        BOUNDS.rrfK
+      )
+    }
+
+    this.currentThresholds.feedbackCount = feedback.length
+    this.currentThresholds.lastUpdated = new Date().toISOString()
+
+    this.logger.info({
+      thresholds: this.currentThresholds,
+      metrics,
+      positiveRate,
+      avgRating
+    }, 'Thresholds adapted')
+
+    return this.currentThresholds
+  }
+
+  /**
+   * Adjust a value with bounds checking
+   */
+  private adjustValue(
+    current: number,
+    amount: number,
+    direction: 'increase' | 'decrease',
+    bounds: { min: number; max: number }
+  ): number {
+    const delta = direction === 'increase' ? amount : -amount
+    const newValue = current + delta
+    return Math.max(bounds.min, Math.min(bounds.max, newValue))
+  }
+
+  /**
+   * Infer provenance from feedback (heuristic)
+   * In a real implementation, this would be stored in feedback
+   */
+  private inferProvenance(feedback: MemoryFeedback): 'dense' | 'sparse' | 'both' {
+    // This is a heuristic - in production, provenance should be stored with feedback
+    // For now, assume most results are from combined search
+    return 'both'
+  }
+
+  /**
+   * Get adaptation status
+   */
+  getStatus(): {
+    feedbackCount: number
+    canAdapt: boolean
+    currentThresholds: AdaptiveThresholds
+    lastUpdated: string
+  } {
+    return {
+      feedbackCount: this.currentThresholds.feedbackCount,
+      canAdapt: this.currentThresholds.feedbackCount >= this.config.minFeedbackForAdaptation,
+      currentThresholds: this.currentThresholds,
+      lastUpdated: this.currentThresholds.lastUpdated
+    }
+  }
+
+  /**
+   * Reset thresholds to defaults
+   */
+  reset(): void {
+    this.currentThresholds = { ...DEFAULT_THRESHOLDS }
+    this.logger.info('Thresholds reset to defaults')
+  }
+}

package/src/retrieval/feedback/index.ts

@@ -1,16 +1,16 @@
-/**
- * Feedback Module Exports
- */
-
-export { FeedbackStore } from './store'
-export {
-  FeedbackMetrics,
-  calculateMRR,
-  calculatePrecisionAtK,
-  calculateNDCG,
-  calculateAllMetrics,
-  calculateAverageRating,
-  calculatePositiveRate,
-  calculateUsageRate
-} from './metrics'
-export { AdaptiveLearner, type AdaptiveLearnerConfig } from './adaptive'
+/**
+ * Feedback Module Exports
+ */
+
+export { FeedbackStore } from './store'
+export {
+  FeedbackMetrics,
+  calculateMRR,
+  calculatePrecisionAtK,
+  calculateNDCG,
+  calculateAllMetrics,
+  calculateAverageRating,
+  calculatePositiveRate,
+  calculateUsageRate
+} from './metrics'
+export { AdaptiveLearner, type AdaptiveLearnerConfig } from './adaptive'