openmemory 0.1.1

//! # OpenMemory - Cognitive Memory System for AI Applications
//!
//! OpenMemory is a sophisticated memory system that provides:
//! - **Cognitive Sectors**: Automatic classification into episodic, semantic, procedural, emotional, and reflective memory
//! - **Hybrid Similarity Graph (HSG)**: Advanced retrieval combining vector similarity, token overlap, graph relationships, and recency
//! - **Memory Decay**: Time-based salience decay with reinforcement on access
//! - **Multiple Embedding Providers**: Synthetic (local), OpenAI, Ollama, Gemini, AWS Bedrock
//!
//! ## Quick Start
//!
//! ```rust,no_run
//! use openmemory::{OpenMemory, OpenMemoryOptions, AddOptions, QueryOptions};
//!
//! #[tokio::main]
//! async fn main() -> openmemory::Result<()> {
//!     // Create an OpenMemory instance
//!     let om = OpenMemory::new(OpenMemoryOptions {
//!         db_path: "./data/memory.db".into(),
//!         ..Default::default()
//!     }).await?;
//!
//!     // Add a memory
//!     let result = om.add("I learned Rust today!", AddOptions::default()).await?;
//!     println!("Added memory: {} (sector: {:?})", result.id, result.primary_sector);
//!
//!     // Query memories
//!     let results = om.query("What did I learn?", QueryOptions::default()).await?;
//!     for mem in results {
//!         println!("[{:.2}] {}", mem.score, mem.content);
//!     }
//!
//!     Ok(())
//! }
//! ```

pub mod core;
pub mod memory;
pub mod utils;

// Re-exports for convenience
pub use crate::core::config::{Config, ConfigBuilder};
pub use crate::core::db::Database;
pub use crate::core::error::{Error, Result};
pub use crate::core::types::*;
pub use crate::memory::embed::{create_provider, EmbeddingProvider};
pub use crate::memory::hsg::{classify_content, HsgEngine};
pub use crate::memory::decay::{DecayConfig, DecayEngine};

use std::path::PathBuf;
use std::sync::Arc;

/// Options for creating an OpenMemory instance
#[derive(Clone)]
pub struct OpenMemoryOptions {
    /// Path to the SQLite database file
    pub db_path: PathBuf,
    /// Performance tier
    pub tier: Tier,
    /// Embedding provider
    pub embedding_kind: EmbeddingKind,
    /// Vector dimensions
    pub vec_dim: Option<usize>,
    /// Default user ID
    pub user_id: Option<String>,
    /// OpenAI API key (for OpenAI embeddings)
    pub openai_key: Option<String>,
    /// Gemini API key (for Gemini embeddings)
    pub gemini_key: Option<String>,
    /// Ollama server URL
    pub ollama_url: Option<String>,
}

impl Default for OpenMemoryOptions {
    fn default() -> Self {
        Self {
            db_path: PathBuf::from("./data/openmemory.sqlite"),
            tier: Tier::Smart,
            embedding_kind: EmbeddingKind::Synthetic,
            vec_dim: None,
            user_id: None,
            openai_key: None,
            gemini_key: None,
            ollama_url: None,
        }
    }
}

/// Options for adding a memory
#[derive(Default, Clone)]
pub struct AddOptions {
    /// Tags for the memory
    pub tags: Option<Vec<String>>,
    /// Additional metadata
    pub metadata: Option<serde_json::Value>,
    /// User identifier
    pub user_id: Option<String>,
    /// Initial salience [0, 1]
    pub salience: Option<f64>,
    /// Custom decay lambda
    pub decay_lambda: Option<f64>,
}

/// Options for querying memories
#[derive(Clone)]
pub struct QueryOptions {
    /// Number of results to return
    pub k: usize,
    /// Filter by sectors
    pub sectors: Option<Vec<Sector>>,
    /// Minimum salience threshold
    pub min_salience: Option<f64>,
    /// Filter by user
    pub user_id: Option<String>,
}

impl Default for QueryOptions {
    fn default() -> Self {
        Self {
            k: 10,
            sectors: None,
            min_salience: None,
            user_id: None,
        }
    }
}

/// OpenMemory - Main API
///
/// The primary interface for interacting with the memory system.
pub struct OpenMemory {
    config: Config,
    db: Arc<Database>,
    embedder: Arc<dyn EmbeddingProvider>,
    hsg: HsgEngine,
    decay: DecayEngine,
}

impl OpenMemory {
    /// Create a new OpenMemory instance
    ///
    /// # Arguments
    /// * `options` - Configuration options
    ///
    /// # Example
    /// ```rust,no_run
    /// use openmemory::{OpenMemory, OpenMemoryOptions};
    ///
    /// #[tokio::main]
    /// async fn main() {
    ///     let om = OpenMemory::new(OpenMemoryOptions::default()).await.unwrap();
    /// }
    /// ```
    pub async fn new(options: OpenMemoryOptions) -> Result<Self> {
        // Build config from options
        let mut config = Config::default();
        config.db_path = options.db_path;
        config.tier = options.tier;
        config.embedding_kind = options.embedding_kind;
        config.vec_dim = options.vec_dim.unwrap_or_else(|| options.tier.default_dimension());
        config.openai_key = options.openai_key;
        config.gemini_key = options.gemini_key;

        if let Some(url) = options.ollama_url {
            config.ollama_url = url;
        }

        // Create database
        let db = Arc::new(Database::new(&config)?);

        // Create embedding provider
        let embedder: Arc<dyn EmbeddingProvider> = Arc::from(create_provider(&config));

        // Create HSG engine
        let hsg = HsgEngine::new(db.clone(), embedder.clone());

        // Create decay engine
        let decay = DecayEngine::with_defaults(db.clone());

        Ok(Self {
            config,
            db,
            embedder,
            hsg,
            decay,
        })
    }

    /// Create an in-memory instance (useful for testing)
    pub async fn in_memory() -> Result<Self> {
        let options = OpenMemoryOptions {
            db_path: PathBuf::from(":memory:"),
            ..Default::default()
        };
        Self::new(options).await
    }

    /// Add a memory
    ///
    /// # Arguments
    /// * `content` - The text content to store
    /// * `options` - Additional options (tags, metadata, etc.)
    ///
    /// # Returns
    /// The result containing the generated ID and classified sectors
    pub async fn add(&self, content: &str, options: AddOptions) -> Result<AddResult> {
        // Classify content
        let classification = classify_content(content, options.metadata.as_ref());

        // Generate ID
        let id = utils::generate_id();

        // Get decay lambda from options, sector default, or config
        let decay_lambda = options
            .decay_lambda
            .unwrap_or_else(|| classification.primary.default_decay_lambda());

        // Get initial salience
        let salience = options.salience.unwrap_or(0.5);

        // Create memory row
        let now = utils::now_ms();
        let mem = MemRow {
            id: id.clone(),
            content: content.to_string(),
            primary_sector: classification.primary,
            tags: options.tags.clone(),
            meta: options.metadata.clone(),
            user_id: options.user_id.clone(),
            created_at: now,
            updated_at: now,
            last_seen_at: now,
            salience,
            decay_lambda,
            version: 1,
        };

        // Insert into database
        self.db.insert_memory(&mem, 0, None)?;

        // Generate and store embeddings
        let all_sectors = {
            let mut sectors = vec![classification.primary];
            sectors.extend(classification.additional.clone());
            sectors
        };

        for sector in &all_sectors {
            let embedding = self.embedder.embed(content, sector).await?;
            let entry = VectorEntry {
                id: id.clone(),
                sector: *sector,
                user_id: options.user_id.clone(),
                vector: embedding.vector,
                dim: embedding.dim,
            };
            self.db.insert_vector(&entry)?;
        }

        Ok(AddResult {
            id,
            primary_sector: classification.primary,
            sectors: all_sectors,
        })
    }

    /// Query memories
    ///
    /// Uses the HSG algorithm to find relevant memories.
    ///
    /// # Arguments
    /// * `query` - Search query
    /// * `options` - Query options (k, filters, etc.)
    pub async fn query(&self, query: &str, options: QueryOptions) -> Result<Vec<HsgQueryResult>> {
        self.hsg.query(
            query,
            options.k,
            options.sectors.as_deref(),
            options.min_salience,
            options.user_id.as_deref(),
        ).await
    }

    /// Delete a memory by ID
    pub async fn delete(&self, id: &str) -> Result<()> {
        // Delete vectors
        self.db.delete_vectors(id)?;

        // Delete waypoints
        self.db.delete_waypoints(id)?;

        // Delete memory
        self.db.delete_memory(id)?;

        Ok(())
    }

    /// Get a memory by ID
    pub async fn get(&self, id: &str) -> Result<Option<MemRow>> {
        self.db.get_memory(id)
    }

    /// Get all memories with pagination
    pub async fn get_all(&self, limit: usize, offset: usize) -> Result<Vec<MemRow>> {
        self.db.get_all_memories(limit, offset)
    }

    /// Get memories by sector
    pub async fn get_by_sector(
        &self,
        sector: &Sector,
        limit: usize,
        offset: usize,
    ) -> Result<Vec<MemRow>> {
        self.db.get_memories_by_sector(sector, limit, offset)
    }

    /// Run decay on all memories
    pub async fn run_decay(&self) -> Result<DecayStats> {
        self.decay.run_decay()
    }

    /// Reinforce a memory (increase salience)
    pub async fn reinforce(&self, id: &str, boost: Option<f64>) -> Result<()> {
        self.decay.reinforce(id, boost)
    }

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

    /// Get embedding provider info
    pub fn embedding_info(&self) -> EmbeddingInfo {
        EmbeddingInfo {
            provider: self.config.embedding_kind,
            dimensions: self.embedder.dimensions(),
            name: self.embedder.name().to_string(),
        }
    }
}

/// Information about the embedding provider
#[derive(Debug, Clone)]
pub struct EmbeddingInfo {
    /// Provider type
    pub provider: EmbeddingKind,
    /// Vector dimensions
    pub dimensions: usize,
    /// Provider name
    pub name: String,
}

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

    #[tokio::test]
    async fn test_in_memory_instance() {
        let om = OpenMemory::in_memory().await.unwrap();
        assert_eq!(om.embedding_info().provider, EmbeddingKind::Synthetic);
    }

    #[tokio::test]
    async fn test_add_and_get() {
        let om = OpenMemory::in_memory().await.unwrap();

        let result = om.add("Test memory content", AddOptions::default()).await.unwrap();
        assert!(!result.id.is_empty());

        let mem = om.get(&result.id).await.unwrap();
        assert!(mem.is_some());
        assert_eq!(mem.unwrap().content, "Test memory content");
    }

    #[tokio::test]
    async fn test_add_with_tags() {
        let om = OpenMemory::in_memory().await.unwrap();

        let options = AddOptions {
            tags: Some(vec!["test".to_string(), "rust".to_string()]),
            ..Default::default()
        };

        let result = om.add("Learning Rust programming", options).await.unwrap();

        let mem = om.get(&result.id).await.unwrap().unwrap();
        assert_eq!(mem.tags.unwrap().len(), 2);
    }

    #[tokio::test]
    async fn test_delete() {
        let om = OpenMemory::in_memory().await.unwrap();

        let result = om.add("To be deleted", AddOptions::default()).await.unwrap();
        assert!(om.get(&result.id).await.unwrap().is_some());

        om.delete(&result.id).await.unwrap();
        assert!(om.get(&result.id).await.unwrap().is_none());
    }

    #[tokio::test]
    async fn test_sector_classification() {
        let om = OpenMemory::in_memory().await.unwrap();

        // Episodic content
        let result = om.add("Yesterday I went to the park", AddOptions::default()).await.unwrap();
        assert_eq!(result.primary_sector, Sector::Episodic);

        // Procedural content
        let result = om.add("How to install: first download, then run", AddOptions::default()).await.unwrap();
        assert_eq!(result.primary_sector, Sector::Procedural);
    }

    #[tokio::test]
    async fn test_query() {
        let om = OpenMemory::in_memory().await.unwrap();

        om.add("Rust is a systems programming language", AddOptions::default()).await.unwrap();
        om.add("Python is great for data science", AddOptions::default()).await.unwrap();
        om.add("I love programming in Rust", AddOptions::default()).await.unwrap();

        let results = om.query("Rust programming", QueryOptions { k: 10, ..Default::default() }).await.unwrap();

        // Should find relevant results
        assert!(!results.is_empty());
    }
}