feat: pluggable model layer with ModelBackend trait

Extract embedding into a ModelBackend trait. Existing ONNX embedder
implements the trait. Users can configure models in vault.toml and
manage them via 'engraph models list/info'. Registry ships with
known-good models. Prepare for future GGUF adapter.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: devwhodevs

src/embedder.rs

@@ -157,6 +157,28 @@ impl Embedder {
     }
 }
 
+impl crate::model::ModelBackend for Embedder {
+    fn embed_batch(&mut self, texts: &[&str]) -> Result<Vec<Vec<f32>>> {
+        self.embed_batch(texts)
+    }
+
+    fn embed_one(&mut self, text: &str) -> Result<Vec<f32>> {
+        self.embed_one(text)
+    }
+
+    fn token_count(&self, text: &str) -> usize {
+        self.token_count(text)
+    }
+
+    fn dim(&self) -> usize {
+        EMBEDDING_DIM
+    }
+
+    fn name(&self) -> &str {
+        "onnx:all-MiniLM-L6-v2"
+    }
+}
+
 /// L2-normalize a vector. Returns a zero vector if input norm is zero.
 fn normalize_vector(v: &[f32]) -> Vec<f32> {
     let norm: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();

src/lib.rs

@@ -6,6 +6,7 @@ pub mod fts;
 pub mod fusion;
 pub mod hnsw;
 pub mod indexer;
+pub mod model;
 pub mod profile;
 pub mod search;
 pub mod store;

src/main.rs

@@ -1,5 +1,6 @@
 use engraph::config;
 use engraph::indexer;
+use engraph::model;
 use engraph::profile;
 use engraph::search;
 use engraph::store;
@@ -74,6 +75,20 @@ enum Command {
 
     /// Interactively configure vault profile.
     Configure,
+
+    /// Manage embedding models.
+    Models {
+        #[command(subcommand)]
+        action: ModelsAction,
+    },
+}
+
+#[derive(Subcommand, Debug)]
+enum ModelsAction {
+    /// List available models.
+    List,
+    /// Show info about a model.
+    Info { name: String },
 }
 
 /// Check whether an index has been built by looking for engraph.db in data_dir.
@@ -296,6 +311,38 @@ fn main() -> Result<()> {
                 "Interactive configuration not yet implemented. Run 'engraph init' for auto-detection."
             );
         }
+
+        Command::Models { action } => {
+            let registry = model::ModelRegistry::default();
+            match action {
+                ModelsAction::List => {
+                    println!("{:<30} {:>5}  {}", "NAME", "DIM", "DESCRIPTION");
+                    println!("{}", "-".repeat(70));
+                    for entry in &registry.entries {
+                        println!(
+                            "{:<30} {:>5}  {}",
+                            entry.name, entry.dim, entry.description
+                        );
+                    }
+                }
+                ModelsAction::Info { name } => {
+                    if let Some(entry) = registry.get(&name) {
+                        println!("Name:        {}", entry.name);
+                        println!("Format:      {:?}", entry.format);
+                        println!("Dimensions:  {}", entry.dim);
+                        println!("SHA-256:     {}", entry.sha256);
+                        println!("URL:         {}", entry.url);
+                        println!("Description: {}", entry.description);
+                    } else {
+                        eprintln!("Unknown model: {name}");
+                        eprintln!(
+                            "Run 'engraph models list' to see available models."
+                        );
+                        std::process::exit(1);
+                    }
+                }
+            }
+        }
     }
 
     Ok(())

src/model.rs

@@ -0,0 +1,141 @@
+use anyhow::Result;
+use serde::{Deserialize, Serialize};
+
+/// Trait for embedding backends. Any model that can embed text implements this.
+pub trait ModelBackend {
+    fn embed_batch(&mut self, texts: &[&str]) -> Result<Vec<Vec<f32>>>;
+    fn embed_one(&mut self, text: &str) -> Result<Vec<f32>>;
+    fn token_count(&self, text: &str) -> usize;
+    fn dim(&self) -> usize;
+    fn name(&self) -> &str;
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum ModelFormat {
+    Onnx,
+    Gguf,
+    File,
+}
+
+#[derive(Debug, Clone)]
+pub struct ModelSpec {
+    pub format: ModelFormat,
+    pub name: String,
+    pub path: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ModelRegistryEntry {
+    pub name: String,
+    pub format: ModelFormat,
+    pub url: String,
+    pub sha256: String,
+    pub dim: usize,
+    pub description: String,
+}
+
+pub struct ModelRegistry {
+    pub entries: Vec<ModelRegistryEntry>,
+}
+
+impl Default for ModelRegistry {
+    fn default() -> Self {
+        Self {
+            entries: vec![ModelRegistryEntry {
+                name: "onnx:all-MiniLM-L6-v2".to_string(),
+                format: ModelFormat::Onnx,
+                url: "https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx".to_string(),
+                sha256: "6fd5d72fe4589f189f8ebc006442dbb529bb7ce38f8082112682524616046452".to_string(),
+                dim: 384,
+                description: "Lightweight general-purpose sentence embeddings".to_string(),
+            }],
+        }
+    }
+}
+
+impl ModelRegistry {
+    pub fn get(&self, name: &str) -> Option<&ModelRegistryEntry> {
+        self.entries.iter().find(|e| e.name == name)
+    }
+}
+
+pub fn parse_model_spec(spec: &str) -> ModelSpec {
+    if let Some(path) = spec.strip_prefix("file:") {
+        return ModelSpec {
+            format: ModelFormat::File,
+            name: spec.to_string(),
+            path: path.to_string(),
+        };
+    }
+    if let Some((format_str, name)) = spec.split_once(':') {
+        let format = match format_str {
+            "onnx" => ModelFormat::Onnx,
+            "gguf" => ModelFormat::Gguf,
+            _ => ModelFormat::Onnx,
+        };
+        ModelSpec {
+            format,
+            name: name.to_string(),
+            path: String::new(),
+        }
+    } else {
+        ModelSpec {
+            format: ModelFormat::Onnx,
+            name: spec.to_string(),
+            path: String::new(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_model_registry_default() {
+        let registry = ModelRegistry::default();
+        assert_eq!(registry.entries.len(), 1);
+        let entry = &registry.entries[0];
+        assert_eq!(entry.name, "onnx:all-MiniLM-L6-v2");
+        assert_eq!(entry.dim, 384);
+        assert_eq!(entry.format, ModelFormat::Onnx);
+    }
+
+    #[test]
+    fn test_parse_model_spec_onnx() {
+        let spec = parse_model_spec("onnx:all-MiniLM-L6-v2");
+        assert_eq!(spec.format, ModelFormat::Onnx);
+        assert_eq!(spec.name, "all-MiniLM-L6-v2");
+        assert!(spec.path.is_empty());
+    }
+
+    #[test]
+    fn test_parse_model_spec_file() {
+        let spec = parse_model_spec("file:/path/to/model.onnx");
+        assert_eq!(spec.format, ModelFormat::File);
+        assert_eq!(spec.name, "file:/path/to/model.onnx");
+        assert_eq!(spec.path, "/path/to/model.onnx");
+    }
+
+    #[test]
+    fn test_parse_model_spec_bare() {
+        let spec = parse_model_spec("my-custom-model");
+        assert_eq!(spec.format, ModelFormat::Onnx);
+        assert_eq!(spec.name, "my-custom-model");
+        assert!(spec.path.is_empty());
+    }
+
+    #[test]
+    fn test_registry_get_existing() {
+        let registry = ModelRegistry::default();
+        let entry = registry.get("onnx:all-MiniLM-L6-v2");
+        assert!(entry.is_some());
+        assert_eq!(entry.unwrap().dim, 384);
+    }
+
+    #[test]
+    fn test_registry_get_missing() {
+        let registry = ModelRegistry::default();
+        assert!(registry.get("nonexistent-model").is_none());
+    }
+}