Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/docs/guides/AGENTICDB_QUICKSTART.md

@@ -0,0 +1,143 @@
+# AgenticDB Quick Start Guide
+
+Get started with Ruvector's AgenticDB API in 5 minutes.
+
+## Installation
+
+```bash
+# Add to Cargo.toml
+[dependencies]
+ruvector-core = "0.1"
+```
+
+## Basic Usage
+
+```rust
+use ruvector_core::{AgenticDB, DbOptions, Result};
+use std::collections::HashMap;
+
+fn main() -> Result<()> {
+    // 1. Initialize database
+    let db = AgenticDB::with_dimensions(128)?;
+
+    // 2. Store a learning episode
+    let episode_id = db.store_episode(
+        "Learn to optimize code".to_string(),
+        vec!["analyzed bottleneck".to_string(), "applied optimization".to_string()],
+        vec!["code 2x faster".to_string()],
+        "Profiling first helps identify real bottlenecks".to_string(),
+    )?;
+    println!("Stored episode: {}", episode_id);
+
+    // 3. Retrieve similar past experiences
+    let similar = db.retrieve_similar_episodes("code optimization", 5)?;
+    println!("Found {} similar experiences", similar.len());
+
+    // 4. Create a reusable skill
+    let skill_id = db.create_skill(
+        "Code Profiler".to_string(),
+        "Profile code to find performance bottlenecks".to_string(),
+        HashMap::new(),
+        vec!["run profiler".to_string(), "analyze hotspots".to_string()],
+    )?;
+    println!("Created skill: {}", skill_id);
+
+    // 5. Add causal knowledge
+    db.add_causal_edge(
+        vec!["inefficient loop".to_string()],
+        vec!["slow performance".to_string()],
+        0.9,
+        "Performance analysis".to_string(),
+    )?;
+
+    // 6. Start RL training
+    let session = db.start_session("Q-Learning".to_string(), 4, 2)?;
+    db.add_experience(&session, vec![1.0; 4], vec![1.0; 2], 1.0, vec![0.0; 4], false)?;
+    
+    // 7. Get predictions
+    let prediction = db.predict_with_confidence(&session, vec![1.0; 4])?;
+    println!("Predicted action: {:?}", prediction.action);
+
+    Ok(())
+}
+```
+
+## Five Core APIs
+
+### 1. Reflexion Memory
+Learn from past mistakes:
+```rust
+// Store mistake
+db.store_episode(task, actions, observations, critique)?;
+
+// Learn from history
+let similar = db.retrieve_similar_episodes("similar situation", 5)?;
+```
+
+### 2. Skill Library
+Build reusable patterns:
+```rust
+// Create skill
+db.create_skill(name, description, params, examples)?;
+
+// Find relevant skills
+let skills = db.search_skills("what I need to do", 5)?;
+```
+
+### 3. Causal Memory
+Understand cause and effect:
+```rust
+// Add relationship (supports multiple causes → multiple effects)
+db.add_causal_edge(
+    vec!["cause1", "cause2"],
+    vec!["effect1", "effect2"],
+    confidence,
+    context,
+)?;
+
+// Query with utility function
+let results = db.query_with_utility(query, k, 0.7, 0.2, 0.1)?;
+```
+
+### 4. Learning Sessions
+Train RL models:
+```rust
+// Start training
+let session = db.start_session("DQN", state_dim, action_dim)?;
+
+// Add experience
+db.add_experience(&session, state, action, reward, next_state, done)?;
+
+// Make predictions
+let pred = db.predict_with_confidence(&session, current_state)?;
+```
+
+### 5. Vector Search
+Fast similarity search:
+```rust
+// All text is automatically embedded and indexed
+// Just use the high-level APIs above!
+```
+
+## Complete Example
+
+See `examples/agenticdb_demo.rs` for a full demonstration.
+
+## Documentation
+
+- Full API reference: `docs/AGENTICDB_API.md`
+- Implementation details: `docs/PHASE3_SUMMARY.md`
+
+## Performance
+
+- 10-100x faster than original agenticDB
+- O(log n) search with HNSW index
+- SIMD-optimized distance calculations
+- Concurrent access with lock-free reads
+
+## Next Steps
+
+1. Try the example: `cargo run --example agenticdb_demo`
+2. Read the API docs: `docs/AGENTICDB_API.md`
+3. Run tests: `cargo test -p ruvector-core agenticdb`
+4. Build your agentic AI system!