chore: v1.0.0 — intelligence: candle runtime, orchestrator, reranker, query expansion

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: devwhodevs

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "engraph"
-version = "0.7.0"
+version = "1.0.0"
 edition = "2024"
 description = "Local knowledge graph for AI agents. Hybrid search + MCP server for Obsidian vaults."
 license = "MIT"

Cargo.toml

@@ -1,9 +1,9 @@
 use anyhow::{Context, Result};
-use serde::Deserialize;
-use std::path::PathBuf;
+use serde::{Deserialize, Serialize};
+use std::path::{Path, PathBuf};
 
 /// Model override configuration.
-#[derive(Debug, Clone, Default, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 #[serde(default)]
 pub struct ModelConfig {
     /// Override embedding model URI (e.g., "hf:repo/file.gguf").
@@ -15,7 +15,7 @@ pub struct ModelConfig {
 }
 
 /// Application configuration, loaded from `~/.engraph/config.toml` with CLI overrides.
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(default)]
 pub struct Config {
     /// Path to the Obsidian vault to index.
@@ -91,6 +91,29 @@ impl Config {
     pub fn intelligence_enabled(&self) -> bool {
         self.intelligence.unwrap_or(false)
     }
+
+    /// Save config to a specific path.
+    pub fn save_to(&self, path: &Path) -> Result<()> {
+        let content = toml::to_string_pretty(self).context("serializing config")?;
+        std::fs::write(path, content).with_context(|| format!("writing {}", path.display()))?;
+        Ok(())
+    }
+
+    /// Load config from a specific path.
+    pub fn load_from(path: &Path) -> Result<Self> {
+        let contents =
+            std::fs::read_to_string(path).with_context(|| format!("reading {}", path.display()))?;
+        let config: Config =
+            toml::from_str(&contents).with_context(|| format!("parsing {}", path.display()))?;
+        Ok(config)
+    }
+
+    /// Save to the default config path (`~/.engraph/config.toml`).
+    pub fn save(&self) -> Result<()> {
+        let path = Self::data_dir()?.join("config.toml");
+        std::fs::create_dir_all(path.parent().unwrap())?;
+        self.save_to(&path)
+    }
 }
 
 #[cfg(test)]
@@ -192,4 +215,23 @@ rerank = "hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.ggu
         assert_eq!(cfg.intelligence, Some(false));
         assert!(!cfg.intelligence_enabled());
     }
+
+    #[test]
+    fn test_config_roundtrip_with_intelligence() {
+        let dir = tempfile::tempdir().unwrap();
+        let config_path = dir.path().join("config.toml");
+
+        let mut cfg = Config::default();
+        cfg.intelligence = Some(true);
+        cfg.models.embed = Some("hf:custom/model/embed.gguf".into());
+
+        cfg.save_to(&config_path).unwrap();
+
+        let loaded = Config::load_from(&config_path).unwrap();
+        assert_eq!(loaded.intelligence, Some(true));
+        assert_eq!(
+            loaded.models.embed,
+            Some("hf:custom/model/embed.gguf".into())
+        );
+    }
 }

src/config.rs

@@ -446,9 +446,7 @@ pub fn run_index(vault_path: &Path, config: &Config, rebuild: bool) -> Result<In
     let model_dim = embedder.dim();
     let mut rebuild = rebuild;
     if store.has_dimension_mismatch(model_dim)? {
-        eprintln!(
-            "Embedding model upgraded. Re-indexing vault (this may take a few minutes)..."
-        );
+        eprintln!("Embedding model upgraded. Re-indexing vault (this may take a few minutes)...");
         store.reset_for_reindex(model_dim)?;
         rebuild = true; // Force full rebuild
     }

src/indexer.rs

@@ -1023,8 +1023,8 @@ pub fn heuristic_orchestrate(query: &str) -> OrchestrationResult {
     let mut expansions = vec![trimmed.to_string()];
     if words.len() > 2 {
         let stopwords = [
-            "how", "does", "the", "a", "an", "is", "are", "was", "to", "in", "on", "for",
-            "with", "what", "when", "where",
+            "how", "does", "the", "a", "an", "is", "are", "was", "to", "in", "on", "for", "with",
+            "what", "when", "where",
         ];
         for word in &words {
             if word.len() > 2 && !stopwords.contains(&word.to_lowercase().as_str()) {
@@ -1150,9 +1150,10 @@ impl CandleOrchestrator {
             .map_err(|e| anyhow::anyhow!("opening GGUF {}: {e}", model_path.display()))?;
         let ct = candle_core::quantized::gguf_file::Content::read(&mut file)
             .map_err(|e| anyhow::anyhow!("reading GGUF {}: {e}", model_path.display()))?;
-        let model =
-            candle_transformers::models::quantized_qwen3::ModelWeights::from_gguf(ct, &mut file, &device)
-                .map_err(|e| anyhow::anyhow!("loading Qwen3 model weights: {e}"))?;
+        let model = candle_transformers::models::quantized_qwen3::ModelWeights::from_gguf(
+            ct, &mut file, &device,
+        )
+        .map_err(|e| anyhow::anyhow!("loading Qwen3 model weights: {e}"))?;
 
         tracing::info!(
             "loaded CandleOrchestrator from {}, device={:?}",
@@ -1314,9 +1315,7 @@ impl OrchestratorModel for CandleOrchestrator {
                 }
             },
             Err(e) => {
-                tracing::warn!(
-                    "orchestrator generation failed, falling back to heuristic: {e:#}"
-                );
+                tracing::warn!("orchestrator generation failed, falling back to heuristic: {e:#}");
                 Ok(heuristic_orchestrate(query))
             }
         }
@@ -1396,9 +1395,10 @@ impl CandleRerank {
             .map_err(|e| anyhow::anyhow!("opening GGUF {}: {e}", model_path.display()))?;
         let ct = candle_core::quantized::gguf_file::Content::read(&mut file)
             .map_err(|e| anyhow::anyhow!("reading GGUF {}: {e}", model_path.display()))?;
-        let model =
-            candle_transformers::models::quantized_qwen3::ModelWeights::from_gguf(ct, &mut file, &device)
-                .map_err(|e| anyhow::anyhow!("loading Qwen3 reranker model weights: {e}"))?;
+        let model = candle_transformers::models::quantized_qwen3::ModelWeights::from_gguf(
+            ct, &mut file, &device,
+        )
+        .map_err(|e| anyhow::anyhow!("loading Qwen3 reranker model weights: {e}"))?;
 
         tracing::info!(
             "loaded CandleRerank from {}, device={:?}, yes_id={}, no_id={}",
@@ -1712,7 +1712,11 @@ mod tests {
     fn test_heuristic_orchestrate_multi_word() {
         let result = heuristic_orchestrate("how does auth work");
         assert_eq!(result.intent, QueryIntent::Exploratory);
-        assert!(result.expansions.contains(&"how does auth work".to_string()));
+        assert!(
+            result
+                .expansions
+                .contains(&"how does auth work".to_string())
+        );
         assert!(result.expansions.len() > 1);
     }
 

src/llm.rs

@@ -72,8 +72,20 @@ enum Command {
         path: Option<PathBuf>,
     },
 
-    /// Interactively configure vault profile.
-    Configure,
+    /// Configure engraph settings.
+    Configure {
+        /// Enable intelligence features.
+        #[arg(long, conflicts_with = "disable_intelligence")]
+        enable_intelligence: bool,
+
+        /// Disable intelligence features.
+        #[arg(long, conflicts_with = "enable_intelligence")]
+        disable_intelligence: bool,
+
+        /// Override a model: --model embed|rerank|expand <uri>
+        #[arg(long, num_args = 2, value_names = &["TYPE", "URI"])]
+        model: Option<Vec<String>>,
+    },
 
     /// Manage embedding models.
     Models {
@@ -206,6 +218,38 @@ enum ModelsAction {
     Info { name: String },
 }
 
+/// Prompt user to enable intelligence, download models if yes.
+fn prompt_intelligence(data_dir: &std::path::Path) -> Result<bool> {
+    eprint!(
+        "\nEnable AI-powered search intelligence?\n\n\
+         This downloads ~1.3GB of additional models for:\n\
+         \x20 - Query expansion (rewrites your search into multiple variations)\n\
+         \x20 - Result reranking (LLM scores each result for relevance)\n\n\
+         Enable now? [y/N] "
+    );
+    io::stderr().flush()?;
+    let mut answer = String::new();
+    io::stdin().lock().read_line(&mut answer)?;
+    let enable = answer.trim().eq_ignore_ascii_case("y");
+
+    if enable {
+        let models_dir = data_dir.join("models");
+        let defaults = engraph::llm::ModelDefaults::default();
+        println!("Downloading intelligence models (~1.3GB)...");
+        let rerank_uri = engraph::llm::HfModelUri::parse(&defaults.rerank_uri)?;
+        engraph::llm::ensure_model(&rerank_uri, &models_dir)?;
+        let expand_uri = engraph::llm::HfModelUri::parse(&defaults.expand_uri)?;
+        engraph::llm::ensure_model(&expand_uri, &models_dir)?;
+        println!("Done.");
+    } else {
+        println!(
+            "Intelligence disabled. You can enable later with: engraph configure --enable-intelligence"
+        );
+    }
+
+    Ok(enable)
+}
+
 /// Check whether an index has been built by looking for engraph.db in data_dir.
 fn index_exists(data_dir: &std::path::Path) -> bool {
     data_dir.join("engraph.db").exists()
@@ -294,6 +338,13 @@ async fn main() -> Result<()> {
                 }
             }
 
+            // First-run intelligence prompt (only if not yet configured)
+            if cfg.intelligence.is_none() {
+                let enable = prompt_intelligence(&data_dir)?;
+                cfg.intelligence = Some(enable);
+                cfg.save()?;
+            }
+
             let result = indexer::run_index(&vault_path, &cfg, rebuild)?;
 
             println!(
@@ -413,11 +464,74 @@ async fn main() -> Result<()> {
 
             println!();
             println!("Wrote {}", data_dir.join("vault.toml").display());
+
+            // Intelligence onboarding (only if not yet configured)
+            if cfg.intelligence.is_none() {
+                let enable = prompt_intelligence(&data_dir)?;
+                cfg.intelligence = Some(enable);
+                cfg.save()?;
+            }
         }
 
-        Command::Configure => {
+        Command::Configure {
+            enable_intelligence,
+            disable_intelligence,
+            model,
+        } => {
+            let mut cfg = Config::load()?;
+
+            if enable_intelligence {
+                cfg.intelligence = Some(true);
+                println!("Intelligence enabled. Models will be downloaded on first search.");
+                let models_dir = data_dir.join("models");
+                let defaults = engraph::llm::ModelDefaults::default();
+                println!("Downloading intelligence models (~1.3GB)...");
+                let rerank_uri = engraph::llm::HfModelUri::parse(
+                    cfg.models.rerank.as_deref().unwrap_or(&defaults.rerank_uri),
+                )?;
+                engraph::llm::ensure_model(&rerank_uri, &models_dir)?;
+                let expand_uri = engraph::llm::HfModelUri::parse(
+                    cfg.models.expand.as_deref().unwrap_or(&defaults.expand_uri),
+                )?;
+                engraph::llm::ensure_model(&expand_uri, &models_dir)?;
+                println!("Done.");
+            } else if disable_intelligence {
+                cfg.intelligence = Some(false);
+                println!("Intelligence disabled. Models remain cached.");
+            }
+
+            if let Some(parts) = model
+                && parts.len() == 2
+            {
+                let model_type = &parts[0];
+                let uri = &parts[1];
+                engraph::llm::HfModelUri::parse(uri)?;
+                match model_type.as_str() {
+                    "embed" => {
+                        cfg.models.embed = Some(uri.clone());
+                        println!("Embedding model set to: {uri}");
+                        println!("Warning: Next 'engraph index' will re-embed your entire vault.");
+                    }
+                    "rerank" => {
+                        cfg.models.rerank = Some(uri.clone());
+                        println!("Reranker model set to: {uri}");
+                    }
+                    "expand" => {
+                        cfg.models.expand = Some(uri.clone());
+                        println!("Expansion model set to: {uri}");
+                    }
+                    other => {
+                        anyhow::bail!(
+                            "Unknown model type: {other}. Use: embed, rerank, or expand."
+                        );
+                    }
+                }
+            }
+
+            cfg.save()?;
             println!(
-                "Interactive configuration not yet implemented. Run 'engraph init' for auto-detection."
+                "Configuration saved to {}",
+                data_dir.join("config.toml").display()
             );
         }
 

src/main.rs

@@ -98,9 +98,13 @@ pub fn search_with_intelligence(
 
     for expanded_query in &orchestration.expansions {
         // Semantic lane
-        let query_vec = embedder.embed_one(expanded_query).context("embedding query")?;
+        let query_vec = embedder
+            .embed_one(expanded_query)
+            .context("embedding query")?;
         let tombstones = std::collections::HashSet::new();
-        let raw_results = config.store.search_vec(&query_vec, top_n * 3, &tombstones)?;
+        let raw_results = config
+            .store
+            .search_vec(&query_vec, top_n * 3, &tombstones)?;
 
         // Group semantic results by file_path, keeping best per file.
         let mut sem_by_file: HashMap<String, RankedResult> = HashMap::new();
@@ -196,8 +200,9 @@ pub fn search_with_intelligence(
     let final_fused = if let Some(reranker) = &mut config.reranker {
         let mut rerank_results: Vec<RankedResult> = Vec::new();
         for candidate in fused_pass1.iter().take(config.rerank_candidates) {
-            let score =
-                reranker.rerank_score(query, &candidate.snippet).unwrap_or(0.0) as f64;
+            let score = reranker
+                .rerank_score(query, &candidate.snippet)
+                .unwrap_or(0.0) as f64;
             rerank_results.push(RankedResult {
                 file_path: candidate.file_path.clone(),
                 file_id: candidate.file_id,
@@ -347,7 +352,11 @@ pub fn run_status(json: bool, data_dir: &Path) -> Result<()> {
     let model_name = "all-MiniLM-L6-v2";
 
     let config = crate::config::Config::load().unwrap_or_default();
-    let intelligence = if config.intelligence_enabled() { "enabled" } else { "disabled" };
+    let intelligence = if config.intelligence_enabled() {
+        "enabled"
+    } else {
+        "disabled"
+    };
 
     let output = format_status(&stats, index_size, model_name, intelligence, json);
     print!("{output}");