ruvllm 2.2.0

//! ReasoningBank - Production-grade learning from Claude trajectories
//!
//! This module implements a complete system for learning from Claude (and other LLM)
//! trajectories, enabling continuous improvement through:
//!
//! - **Trajectory Recording**: Real-time capture of execution paths with quality metrics
//! - **Pattern Storage**: HNSW-indexed pattern storage for fast similarity search (150x faster)
//! - **Verdict Analysis**: Enhanced verdict system for failure analysis and root cause detection
//! - **Memory Consolidation**: EWC++ style consolidation to prevent catastrophic forgetting
//! - **Memory Distillation**: Compress old trajectories while preserving key lessons
//!
//! ## Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────────────┐
//! │                         ReasoningBank                               │
//! ├─────────────────────────────────────────────────────────────────────┤
//! │  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐              │
//! │  │ Trajectory  │──>│   Pattern   │──>│  Verdict    │              │
//! │  │  Recorder   │   │   Store     │   │  Analyzer   │              │
//! │  └─────────────┘   └─────────────┘   └─────────────┘              │
//! │        │                  │                  │                     │
//! │        v                  v                  v                     │
//! │  ┌─────────────────────────────────────────────────────┐         │
//! │  │              HNSW Index (ruvector-core)             │         │
//! │  │            ef_construction=200, M=32                │         │
//! │  └─────────────────────────────────────────────────────┘         │
//! │        │                  │                  │                     │
//! │        v                  v                  v                     │
//! │  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐              │
//! │  │ Consolidator│   │ Distiller   │   │   Export    │              │
//! │  │   (EWC++)   │   │             │   │             │              │
//! │  └─────────────┘   └─────────────┘   └─────────────┘              │
//! └─────────────────────────────────────────────────────────────────────┘
//! ```
//!
//! ## Example Usage
//!
//! ```rust,ignore
//! use ruvllm::reasoning_bank::{
//!     ReasoningBank, ReasoningBankConfig,
//!     TrajectoryRecorder, Verdict,
//! };
//!
//! // Create the reasoning bank
//! let config = ReasoningBankConfig::default();
//! let bank = ReasoningBank::new(config)?;
//!
//! // Start recording a trajectory
//! let mut recorder = bank.start_trajectory("user-query-embedding");
//! recorder.add_step(action, rationale, outcome, confidence);
//! recorder.add_step(action2, rationale2, outcome2, confidence2);
//!
//! // Complete with a verdict
//! let trajectory = recorder.complete(Verdict::Success);
//!
//! // Store for learning
//! bank.store_trajectory(trajectory)?;
//!
//! // Search for similar patterns
//! let similar = bank.search_similar(&query_embedding, 10)?;
//!
//! // Periodic consolidation
//! bank.consolidate()?;
//! ```

pub mod consolidation;
pub mod distillation;
pub mod pattern_store;
pub mod trajectory;
pub mod verdicts;

// Re-exports for convenience
pub use consolidation::{
    ConsolidationConfig, ConsolidationResult, FisherInformation, ImportanceScore,
    PatternConsolidator,
};
pub use distillation::{
    CompressedTrajectory, DistillationConfig, DistillationResult, KeyLesson, MemoryDistiller,
};
pub use pattern_store::{
    Pattern, PatternCategory, PatternSearchResult, PatternStats, PatternStore, PatternStoreConfig,
};
pub use trajectory::{
    StepOutcome, Trajectory, TrajectoryId, TrajectoryMetadata, TrajectoryRecorder, TrajectoryStep,
};
pub use verdicts::{
    FailurePattern, RecoveryStrategy, RootCause, Verdict, VerdictAnalysis, VerdictAnalyzer,
};

use crate::error::Result;
use parking_lot::RwLock;
use serde::{Deserialize, Serialize};
use std::sync::Arc;

/// Configuration for the ReasoningBank
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ReasoningBankConfig {
    /// Storage path for persistent data
    pub storage_path: String,
    /// Embedding dimension for vectors
    pub embedding_dim: usize,
    /// HNSW ef_construction parameter (default: 200)
    pub ef_construction: usize,
    /// HNSW ef_search parameter (default: 100)
    pub ef_search: usize,
    /// HNSW M parameter (default: 32)
    pub m: usize,
    /// Maximum trajectories to store before compression
    pub max_trajectories: usize,
    /// Minimum quality threshold for pattern extraction
    pub min_quality_threshold: f32,
    /// Consolidation interval in seconds
    pub consolidation_interval_secs: u64,
    /// Enable automatic consolidation
    pub auto_consolidate: bool,
    /// Pattern store configuration
    pub pattern_config: PatternStoreConfig,
    /// Consolidation configuration
    pub consolidation_config: ConsolidationConfig,
    /// Distillation configuration
    pub distillation_config: DistillationConfig,
}

impl Default for ReasoningBankConfig {
    fn default() -> Self {
        Self {
            storage_path: ".ruvllm/reasoning_bank".to_string(),
            embedding_dim: 768,
            ef_construction: 200,
            ef_search: 100,
            m: 32,
            max_trajectories: 100_000,
            min_quality_threshold: 0.3,
            consolidation_interval_secs: 3600, // 1 hour
            auto_consolidate: true,
            pattern_config: PatternStoreConfig::default(),
            consolidation_config: ConsolidationConfig::default(),
            distillation_config: DistillationConfig::default(),
        }
    }
}

/// Main ReasoningBank for learning from Claude trajectories
///
/// The ReasoningBank provides a unified interface for:
/// - Recording trajectories during Claude interactions
/// - Storing and indexing patterns with HNSW
/// - Analyzing verdicts and extracting lessons
/// - Consolidating patterns to prevent forgetting
/// - Distilling old trajectories to preserve key insights
pub struct ReasoningBank {
    /// Configuration
    config: ReasoningBankConfig,
    /// Pattern store with HNSW index
    pattern_store: Arc<RwLock<PatternStore>>,
    /// Verdict analyzer
    verdict_analyzer: VerdictAnalyzer,
    /// Pattern consolidator
    consolidator: PatternConsolidator,
    /// Memory distiller
    distiller: MemoryDistiller,
    /// Trajectory storage (in-memory buffer)
    trajectories: Arc<RwLock<Vec<Trajectory>>>,
    /// Statistics
    stats: Arc<RwLock<ReasoningBankStats>>,
}

/// Statistics for the ReasoningBank
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ReasoningBankStats {
    /// Total trajectories recorded
    pub total_trajectories: u64,
    /// Total patterns stored
    pub total_patterns: u64,
    /// Successful trajectories
    pub success_count: u64,
    /// Failed trajectories
    pub failure_count: u64,
    /// Recovered via reflection
    pub recovered_count: u64,
    /// Consolidations performed
    pub consolidation_count: u64,
    /// Distillations performed
    pub distillation_count: u64,
    /// Average quality score
    pub avg_quality: f32,
    /// Last consolidation timestamp (Unix seconds)
    pub last_consolidation: u64,
    /// Last distillation timestamp (Unix seconds)
    pub last_distillation: u64,
}

impl ReasoningBank {
    /// Create a new ReasoningBank with the given configuration
    pub fn new(config: ReasoningBankConfig) -> Result<Self> {
        let pattern_store = PatternStore::new(config.pattern_config.clone())?;
        let verdict_analyzer = VerdictAnalyzer::new();
        let consolidator = PatternConsolidator::new(config.consolidation_config.clone());
        let distiller = MemoryDistiller::new(config.distillation_config.clone());

        Ok(Self {
            config,
            pattern_store: Arc::new(RwLock::new(pattern_store)),
            verdict_analyzer,
            consolidator,
            distiller,
            trajectories: Arc::new(RwLock::new(Vec::new())),
            stats: Arc::new(RwLock::new(ReasoningBankStats::default())),
        })
    }

    /// Start recording a new trajectory
    pub fn start_trajectory(&self, query_embedding: Vec<f32>) -> TrajectoryRecorder {
        TrajectoryRecorder::new(query_embedding)
    }

    /// Store a completed trajectory
    pub fn store_trajectory(&self, trajectory: Trajectory) -> Result<()> {
        // Update statistics
        {
            let mut stats = self.stats.write();
            stats.total_trajectories += 1;

            match &trajectory.verdict {
                Verdict::Success => stats.success_count += 1,
                Verdict::Failure(_) => stats.failure_count += 1,
                Verdict::RecoveredViaReflection { .. } => stats.recovered_count += 1,
                _ => {}
            }

            // Update rolling average quality
            let n = stats.total_trajectories as f32;
            stats.avg_quality = stats.avg_quality * ((n - 1.0) / n) + trajectory.quality / n;
        }

        // Store trajectory
        {
            let mut trajectories = self.trajectories.write();
            trajectories.push(trajectory.clone());

            // Check if we need to trigger distillation
            if trajectories.len() > self.config.max_trajectories {
                drop(trajectories);
                self.distill()?;
            }
        }

        // Extract pattern if quality is above threshold
        if trajectory.quality >= self.config.min_quality_threshold {
            let pattern = Pattern::from_trajectory(&trajectory);
            let mut store = self.pattern_store.write();
            store.store_pattern(pattern)?;

            let mut stats = self.stats.write();
            stats.total_patterns += 1;
        }

        Ok(())
    }

    /// Analyze a trajectory verdict and extract lessons
    pub fn analyze_verdict(&self, trajectory: &Trajectory) -> VerdictAnalysis {
        self.verdict_analyzer.analyze(trajectory)
    }

    /// Search for similar patterns by embedding
    pub fn search_similar(
        &self,
        query_embedding: &[f32],
        limit: usize,
    ) -> Result<Vec<PatternSearchResult>> {
        let store = self.pattern_store.read();
        store.search_similar(query_embedding, limit)
    }

    /// Search patterns by category
    pub fn search_by_category(
        &self,
        category: PatternCategory,
        limit: usize,
    ) -> Result<Vec<Pattern>> {
        let store = self.pattern_store.read();
        store.get_by_category(category, limit)
    }

    /// Consolidate patterns to prevent forgetting
    pub fn consolidate(&self) -> Result<ConsolidationResult> {
        let mut store = self.pattern_store.write();
        let patterns = store.get_all_patterns()?;

        let result = self.consolidator.consolidate_patterns(&patterns)?;

        // Apply consolidation results
        for pattern_id in &result.merged_pattern_ids {
            store.remove_pattern(*pattern_id)?;
        }

        for pattern_id in &result.pruned_pattern_ids {
            store.remove_pattern(*pattern_id)?;
        }

        // Update stats
        {
            let mut stats = self.stats.write();
            stats.consolidation_count += 1;
            stats.last_consolidation = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap_or_default()
                .as_secs();
        }

        Ok(result)
    }

    /// Distill old trajectories to preserve key lessons
    pub fn distill(&self) -> Result<DistillationResult> {
        let trajectories = {
            let mut traj = self.trajectories.write();
            std::mem::take(&mut *traj)
        };

        let result = self.distiller.extract_key_lessons(&trajectories)?;

        // Store compressed trajectories back
        {
            let mut traj = self.trajectories.write();
            for compressed in &result.compressed_trajectories {
                // Reconstruct minimal trajectory from compressed form
                let minimal = Trajectory::from_compressed(compressed);
                traj.push(minimal);
            }
        }

        // Store extracted lessons as patterns
        {
            let mut store = self.pattern_store.write();
            for lesson in &result.key_lessons {
                let pattern = Pattern::from_lesson(lesson);
                store.store_pattern(pattern)?;
            }
        }

        // Update stats
        {
            let mut stats = self.stats.write();
            stats.distillation_count += 1;
            stats.last_distillation = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap_or_default()
                .as_secs();
        }

        Ok(result)
    }

    /// Prune low-quality patterns
    pub fn prune_low_quality(&self, min_quality: f32) -> Result<usize> {
        let mut store = self.pattern_store.write();
        store.prune_low_quality(min_quality)
    }

    /// Merge similar patterns
    pub fn merge_similar_patterns(&self, similarity_threshold: f32) -> Result<usize> {
        let mut store = self.pattern_store.write();
        store.merge_similar(similarity_threshold)
    }

    /// Get statistics
    pub fn stats(&self) -> ReasoningBankStats {
        self.stats.read().clone()
    }

    /// Get pattern store statistics
    pub fn pattern_stats(&self) -> PatternStats {
        self.pattern_store.read().stats()
    }

    /// Get configuration
    pub fn config(&self) -> &ReasoningBankConfig {
        &self.config
    }

    /// Export all patterns for transfer learning
    pub fn export_patterns(&self) -> Result<Vec<Pattern>> {
        let store = self.pattern_store.read();
        store.get_all_patterns()
    }

    /// Import patterns from another ReasoningBank
    pub fn import_patterns(&self, patterns: Vec<Pattern>) -> Result<usize> {
        let mut store = self.pattern_store.write();
        let mut imported = 0;

        for pattern in patterns {
            if store.store_pattern(pattern).is_ok() {
                imported += 1;
            }
        }

        let mut stats = self.stats.write();
        stats.total_patterns += imported as u64;

        Ok(imported)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_reasoning_bank_config_default() {
        let config = ReasoningBankConfig::default();
        assert_eq!(config.embedding_dim, 768);
        assert_eq!(config.ef_construction, 200);
        assert_eq!(config.ef_search, 100);
        assert_eq!(config.m, 32);
    }

    #[test]
    fn test_reasoning_bank_creation() {
        let config = ReasoningBankConfig {
            storage_path: "/tmp/test_reasoning_bank".to_string(),
            ..Default::default()
        };
        let bank = ReasoningBank::new(config);
        assert!(bank.is_ok());
    }

    #[test]
    fn test_trajectory_recording() {
        let config = ReasoningBankConfig::default();
        let bank = ReasoningBank::new(config).unwrap();

        let mut recorder = bank.start_trajectory(vec![0.1; 768]);
        recorder.add_step(
            "analyze".to_string(),
            "Need to understand the problem".to_string(),
            StepOutcome::Success,
            0.9,
        );

        let trajectory = recorder.complete(Verdict::Success);
        assert!(!trajectory.steps.is_empty());
    }

    #[test]
    fn test_stats_tracking() {
        // Use a unique temp dir for the underlying VectorDB; the default
        // `.reasoning_bank_patterns` path is shared and triggers
        // "Database already open. Cannot acquire lock." when nextest runs
        // tests concurrently.
        let tmp = tempfile::tempdir().unwrap();
        let mut config = ReasoningBankConfig::default();
        config.pattern_config.storage_path =
            Some(tmp.path().join("pat").to_string_lossy().into_owned());
        let bank = ReasoningBank::new(config).unwrap();

        let stats = bank.stats();
        assert_eq!(stats.total_trajectories, 0);
    }
}