memvid--memvid/examples/basic_usage.rs

//! Basic usage example demonstrating create, put, find, and timeline operations.
//!
//! Run with: cargo run --example basic_usage

use std::path::PathBuf;
use tempfile::tempdir;

use memvid_core::{Memvid, PutOptions, Result, SearchRequest, TimelineQuery};

fn main() -> Result<()> {
    // Create a temporary directory for our example
    let dir = tempdir().expect("failed to create temp dir");
    let path: PathBuf = dir.path().join("example.mv2");

    println!("=== Memvid Core Basic Usage Example ===\n");

    // ========================================
    // 1. CREATE a new memory file
    // ========================================
    println!("1. Creating memory file at {:?}", path);
    let mut mem = Memvid::create(&path)?;
    println!("   Memory created successfully!\n");

    // ========================================
    // 2. PUT documents into the memory
    // ========================================
    println!("2. Adding documents to memory...");

    // Simple put with just bytes
    let seq1 = mem.put_bytes(b"Hello, Memvid! This is a simple text document.")?;
    println!("   Added document 1, sequence: {}", seq1);

    // Put with options (title, URI, tags)
    let options = PutOptions::builder()
        .title("Getting Started Guide")
        .uri("mv2://docs/getting-started.md")
        .tag("category", "documentation")
        .tag("version", "2.0")
        .build();
    let seq2 = mem.put_bytes_with_options(
        b"This guide covers the basics of using Memvid for AI memory storage.",
        options,
    )?;
    println!("   Added document 2 (with metadata), sequence: {}", seq2);

    // Add more documents
    let options = PutOptions::builder()
        .title("API Reference")
        .uri("mv2://docs/api-reference.md")
        .tag("category", "documentation")
        .build();
    mem.put_bytes_with_options(
        b"The Memvid API provides methods for create, put, find, and timeline operations.",
        options,
    )?;

    let options = PutOptions::builder()
        .title("FAQ")
        .uri("mv2://docs/faq.md")
        .tag("category", "support")
        .build();
    mem.put_bytes_with_options(
        b"Frequently asked questions about Memvid memory files and search.",
        options,
    )?;

    // Commit changes to persist them
    mem.commit()?;
    println!("   Committed all changes\n");

    // ========================================
    // 3. STATS - Check memory statistics
    // ========================================
    println!("3. Memory statistics:");
    let stats = mem.stats()?;
    println!("   Frame count: {}", stats.frame_count);
    println!("   Has lexical index: {}", stats.has_lex_index);
    println!("   Has vector index: {}", stats.has_vec_index);
    println!("   Has time index: {}", stats.has_time_index);
    println!();

    // ========================================
    // 4. FIND - Search for documents
    // ========================================
    println!("4. Searching for documents...");

    // Search for "memvid"
    let request = SearchRequest {
        query: "memvid".to_string(),
        top_k: 10,
        snippet_chars: 200,
        uri: None,
        scope: None,
        cursor: None,
        #[cfg(feature = "temporal_track")]
        temporal: None,
        as_of_frame: None,
        as_of_ts: None,
        no_sketch: false,
        acl_context: None,
        acl_enforcement_mode: memvid_core::types::AclEnforcementMode::Audit,
    };
    let response = mem.search(request)?;
    println!("   Query: 'memvid'");
    println!("   Total hits: {}", response.total_hits);
    println!("   Elapsed: {}ms", response.elapsed_ms);
    for hit in &response.hits {
        let title = hit.title.as_deref().unwrap_or("Untitled");
        let score = hit.score.unwrap_or(0.0);
        println!("   - [{}] {} (score: {:.3})", hit.frame_id, title, score);
        println!(
            "     Snippet: {}...",
            &hit.text.chars().take(60).collect::<String>()
        );
    }
    println!();

    // Search within a scope
    let request = SearchRequest {
        query: "documentation".to_string(),
        top_k: 10,
        snippet_chars: 100,
        uri: None,
        scope: Some("mv2://docs/".to_string()),
        cursor: None,
        #[cfg(feature = "temporal_track")]
        temporal: None,
        as_of_frame: None,
        as_of_ts: None,
        no_sketch: false,
        acl_context: None,
        acl_enforcement_mode: memvid_core::types::AclEnforcementMode::Audit,
    };
    let response = mem.search(request)?;
    println!("   Query: 'documentation' (scope: mv2://docs/)");
    println!("   Total hits: {}", response.total_hits);
    println!();

    // ========================================
    // 5. TIMELINE - Browse documents chronologically
    // ========================================
    println!("5. Timeline (chronological view):");
    let timeline = mem.timeline(TimelineQuery::default())?;
    for entry in &timeline {
        let uri = entry.uri.as_deref().unwrap_or("(no uri)");
        println!(
            "   [{}] {} - {}",
            entry.frame_id,
            uri,
            entry.preview.chars().take(40).collect::<String>()
        );
    }
    println!();

    // ========================================
    // 6. REOPEN - Close and reopen the memory
    // ========================================
    println!("6. Closing and reopening memory...");
    drop(mem);

    let reopened = Memvid::open(&path)?;
    let stats = reopened.stats()?;
    println!("   Reopened successfully!");
    println!("   Frame count after reopen: {}", stats.frame_count);
    println!();

    // ========================================
    // 7. VERIFY - Check file integrity
    // ========================================
    println!("7. Verifying file integrity...");
    drop(reopened); // Close the memory before verifying
    let report = Memvid::verify(&path, false)?;
    println!("   Verification status: {:?}", report.overall_status);
    println!();

    println!("=== Example completed successfully! ===");

    Ok(())
}