refactor!: remove MockEmbedder from public API

MockEmbedder was a 64-dim keyword-bag helper exposed in the public
API since the prototype era. It was never a real embedder — its
presence muddled the public surface (consumers could accidentally
pick it as a CLI default, fixture configs could opaquely use it
for production), and the 'no mocks unless absolutely necessary'
rule never applied to it cleanly because it lived in src/.

Lifted to tests/common/test_embedder.rs as BagOfWordsEmbedder.
Visible only to integration tests; never to consumers, never to
the CLI, never to the published crate.

BREAKING CHANGES (pre-publication cleanup):
- pub MockEmbedder removed from src/embedding.rs
- CLI --embedder mock flag removed; default is now --embedder fastembed
- EvalSuite no longer accepts embedding_model = "mock" in router.toml
- RouterConfig::default_config now uses "fastembed/AllMiniLML6V2"

Added: EvalSuite::from_dir_with_embedder(path, embedder) for tests
that want to inject a fast deterministic embedder explicitly.

scoring.rs unit test uses a local InlineKwEmbed (not reachable from
tests/common/ in src unit tests) with identical routing semantics.

Author: NeuralEmpowerment

CHANGELOG.md

@@ -8,6 +8,20 @@ with a 0.x convention: breaking changes can land on minor bumps until 1.0.0.
 
 ## [Unreleased]
 
+### Removed (BREAKING: pre-publication cleanup)
+- `MockEmbedder` removed from public API entirely. It was a 64-dim keyword-bag
+  helper for testing routing math, not a real embedder, and its presence in the
+  public surface invited misuse (e.g. accidental CLI default, misleading first
+  impressions). Lifted to `tests/common/test_embedder.rs` as `BagOfWordsEmbedder`,
+  visible only to integration tests.
+- CLI `--embedder mock` flag removed; default is now `--embedder fastembed`.
+- `EvalSuite`'s `embedding_model = "mock"` config string no longer accepted.
+
+### Added
+- `EvalSuite::from_dir_with_embedder(path, Box<dyn EmbeddingProvider>)` for
+  tests that need to inject a fast deterministic embedder without the fastembed
+  model download.
+
 ## [0.1.1] - 2026-05-07
 
 First public release on crates.io. Slimmed dep graph (254 → ~21 lean / ~210 default), polished public API.
@@ -44,7 +58,7 @@ First public release on crates.io. Slimmed dep graph (254 → ~21 lean / ~210 de
   30-second example, BYO-embedder example, decision JSON, contract testing,
   CLI, real performance numbers, status, roadmap.
 - `CONTRIBUTING.md` and issue/PR templates.
-- `src/time_util.rs` — std-only ISO-8601 + compact timestamp formatters,
+- `src/time_util.rs`: std-only ISO-8601 + compact timestamp formatters,
   replacing chrono. Hinnant's `civil_from_days` algorithm.
 
 ### Migration from 0.1.0 (internal preview)

src/config.rs

@@ -111,13 +111,15 @@ impl RouterConfig {
         Ok(config)
     }
 
-    /// Return a sensible default config suitable for testing with `MockEmbedder`.
+    /// Return a sensible default config. Useful in tests where the caller
+    /// supplies a custom [`EmbeddingProvider`](crate::embedding::EmbeddingProvider)
+    /// directly rather than relying on auto-construction from `embedding_model`.
     pub fn default_config() -> Self {
         RouterConfig {
             router: RouterSection {
                 name: "semrouter".to_string(),
                 version: "0.1.0".to_string(),
-                embedding_model: "mock".to_string(),
+                embedding_model: "fastembed/AllMiniLML6V2".to_string(),
                 vector_dimension: 384,
                 similarity: "cosine".to_string(),
                 top_k: 3,

src/embedding.rs

@@ -51,144 +51,6 @@ pub trait EmbeddingProvider {
     fn dimension(&self) -> usize;
 }
 
-// ── MockEmbedder ──────────────────────────────────────────────────────────────
-
-/// Maps keywords to fixed embedding dimensions so different semantic domains
-/// occupy non-overlapping dimension ranges, enabling reliable cosine similarity.
-const VOCAB: &[(&str, usize)] = &[
-    // coding (dims 0-15)
-    ("debug", 0),
-    ("code", 1),
-    ("error", 2),
-    ("function", 3),
-    ("test", 4),
-    ("implement", 5),
-    ("fix", 6),
-    ("rust", 7),
-    ("python", 8),
-    ("javascript", 9),
-    ("refactor", 10),
-    ("compile", 11),
-    ("variable", 12),
-    ("class", 13),
-    ("syntax", 14),
-    ("module", 15),
-    // second brain (dims 16-31)
-    ("save", 16),
-    ("brain", 17),
-    ("note", 18),
-    ("knowledge", 19),
-    ("capture", 20),
-    ("store", 21),
-    ("idea", 22),
-    ("memory", 23),
-    ("archive", 24),
-    ("organize", 25),
-    ("file", 26),
-    ("link", 27),
-    ("thought", 28),
-    ("insight", 29),
-    ("category", 30),
-    ("tag", 31),
-    // research (dims 32-47)
-    ("research", 32),
-    ("find", 33),
-    ("look", 34),
-    ("search", 35),
-    ("information", 36),
-    ("learn", 37),
-    ("understand", 38),
-    ("explain", 39),
-    ("study", 40),
-    ("read", 41),
-    ("paper", 42),
-    ("article", 43),
-    ("data", 44),
-    ("source", 45),
-    ("evidence", 46),
-    ("review", 47),
-    // model/task routing (dims 48-63)
-    ("complex", 48),
-    ("simple", 49),
-    ("reasoning", 50),
-    ("quick", 51),
-    ("expensive", 52),
-    ("cheap", 53),
-    ("fast", 54),
-    ("slow", 55),
-    ("creative", 56),
-    ("analytical", 57),
-    ("generate", 58),
-    ("summarize", 59),
-    ("analyze", 60),
-    ("strategy", 61),
-    ("plan", 62),
-    ("decide", 63),
-];
-
-const DIM: usize = 64;
-
-/// Deterministic keyword-bag embedder for tests; not suitable for production use.
-pub struct MockEmbedder;
-
-impl Default for MockEmbedder {
-    fn default() -> Self {
-        MockEmbedder
-    }
-}
-
-impl MockEmbedder {
-    /// Create a new `MockEmbedder`.
-    pub fn new() -> Self {
-        MockEmbedder
-    }
-}
-
-impl EmbeddingProvider for MockEmbedder {
-    fn embed(&self, text: &str) -> Result<Vec<f32>, RouterError> {
-        let lower = text.to_lowercase();
-        let words: Vec<&str> = lower.split_whitespace().collect();
-        let mut vec = vec![0.0f32; DIM];
-
-        for word in &words {
-            let word = word.trim_matches(|c: char| !c.is_alphanumeric());
-            for &(keyword, dim) in VOCAB {
-                if word == keyword || word.starts_with(keyword) {
-                    vec[dim] += 1.0;
-                }
-            }
-        }
-
-        // Small per-text noise so identical-keyword texts can still be distinguished
-        let hash = fnv_hash(text);
-        for (i, slot) in vec.iter_mut().enumerate() {
-            let noise = ((hash
-                .wrapping_add(i as u64)
-                .wrapping_mul(6364136223846793005))
-                >> 33) as f32
-                / (u32::MAX as f32)
-                * 0.05;
-            *slot += noise;
-        }
-
-        normalize(&mut vec);
-        Ok(vec)
-    }
-
-    fn dimension(&self) -> usize {
-        DIM
-    }
-}
-
-fn fnv_hash(s: &str) -> u64 {
-    let mut hash: u64 = 14695981039346656037;
-    for byte in s.bytes() {
-        hash = hash.wrapping_mul(1099511628211);
-        hash ^= byte as u64;
-    }
-    hash
-}
-
 // ── Math helpers ──────────────────────────────────────────────────────────────
 
 /// Normalize a vector in-place to unit length; no-op if the norm is near zero.
@@ -207,41 +69,3 @@ pub fn cosine_similarity(a: &[f32], b: &[f32]) -> f32 {
     a.iter().zip(b.iter()).map(|(x, y)| x * y).sum()
 }
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn mock_embedder_is_deterministic() {
-        let e = MockEmbedder::new();
-        let v1 = e.embed("Help me debug this Python error").unwrap();
-        let v2 = e.embed("Help me debug this Python error").unwrap();
-        assert_eq!(v1, v2);
-    }
-
-    #[test]
-    fn mock_embedder_produces_normalized_vector() {
-        let e = MockEmbedder::new();
-        let v = e.embed("Save this idea to my second brain").unwrap();
-        let norm: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();
-        assert!(
-            (norm - 1.0).abs() < 1e-5,
-            "Expected unit vector, got norm={norm}"
-        );
-    }
-
-    #[test]
-    fn coding_texts_are_more_similar_to_each_other() {
-        let e = MockEmbedder::new();
-        let coding1 = e.embed("Help me debug this Python error").unwrap();
-        let coding2 = e.embed("Fix this Rust compile error in my code").unwrap();
-        let brain = e.embed("Save this idea to my second brain").unwrap();
-
-        let sim_same = cosine_similarity(&coding1, &coding2);
-        let sim_diff = cosine_similarity(&coding1, &brain);
-        assert!(
-            sim_same > sim_diff,
-            "same-domain sim={sim_same} should > cross-domain sim={sim_diff}"
-        );
-    }
-}

src/main.rs

@@ -5,15 +5,14 @@ use std::path::{Path, PathBuf};
 use clap::{Parser, Subcommand, ValueEnum};
 use semrouter::{
     config::RouterConfig,
-    embedding::{EmbeddingProvider, FastEmbedEmbedder, MockEmbedder},
+    embedding::{EmbeddingProvider, FastEmbedEmbedder},
     eval::{load_eval_cases, run_eval, EvalMetrics},
     experiment::ExperimentResult,
     SemanticRouter,
 };
 
 #[derive(Debug, Clone, ValueEnum)]
 enum EmbedderType {
-    Mock,
     Fastembed,
 }
 
@@ -38,8 +37,8 @@ struct Cli {
     #[arg(long, default_value = "routes.jsonl")]
     routes: PathBuf,
 
-    /// Embedder backend: mock (keyword-based, no network) or fastembed (local ONNX)
-    #[arg(long, default_value = "mock", value_enum)]
+    /// Embedder backend: fastembed (local ONNX, default)
+    #[arg(long, default_value = "fastembed", value_enum)]
     embedder: EmbedderType,
 
     #[command(subcommand)]
@@ -83,7 +82,6 @@ enum Commands {
 
 fn build_embedder(embedder_type: &EmbedderType) -> Result<Box<dyn EmbeddingProvider>, String> {
     match embedder_type {
-        EmbedderType::Mock => Ok(Box::new(MockEmbedder::new())),
         EmbedderType::Fastembed => FastEmbedEmbedder::new()
             .map(|e| Box::new(e) as Box<dyn EmbeddingProvider>)
             .map_err(|e| format!("Failed to create fastembed embedder: {e}")),
@@ -92,7 +90,6 @@ fn build_embedder(embedder_type: &EmbedderType) -> Result<Box<dyn EmbeddingProvi
 
 fn embedder_label(t: &EmbedderType) -> &'static str {
     match t {
-        EmbedderType::Mock => "mock",
         EmbedderType::Fastembed => "fastembed",
     }
 }

src/scoring.rs

@@ -81,12 +81,40 @@ pub fn score_routes(
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::embedding::{EmbeddingProvider, MockEmbedder};
+    use crate::embedding::{normalize, EmbeddingProvider};
+    use crate::error::RouterError;
     use crate::route::{EmbeddedExample, RiskLevel, RouteExample};
 
+    // Minimal inline keyword-bag embedder for this unit test only.
+    // Keeps scoring.rs free of a dependency on the test-only BagOfWordsEmbedder
+    // in tests/common/ (which is not reachable from src/ unit tests).
+    struct InlineKwEmbed;
+    impl EmbeddingProvider for InlineKwEmbed {
+        fn embed(&self, text: &str) -> Result<Vec<f32>, RouterError> {
+            const KW: &[(&str, usize)] = &[
+                ("debug", 0), ("code", 1), ("error", 2), ("fix", 6), ("rust", 7),
+                ("python", 8), ("compile", 11), ("test", 4),
+                ("save", 16), ("brain", 17), ("note", 18), ("knowledge", 19),
+                ("capture", 20), ("store", 21), ("idea", 22), ("insight", 29),
+            ];
+            let lower = text.to_lowercase();
+            let mut v = vec![0.0f32; 64];
+            for word in lower.split_whitespace() {
+                let word = word.trim_matches(|c: char| !c.is_alphanumeric());
+                for &(kw, dim) in KW {
+                    if word == kw || word.starts_with(kw) {
+                        v[dim] += 1.0;
+                    }
+                }
+            }
+            normalize(&mut v);
+            Ok(v)
+        }
+        fn dimension(&self) -> usize { 64 }
+    }
+
     fn make_example(id: &str, route: &str, text: &str) -> EmbeddedExample {
-        let e = MockEmbedder::new();
-        let embedding = e.embed(text).unwrap();
+        let embedding = InlineKwEmbed.embed(text).unwrap();
         EmbeddedExample {
             example: RouteExample {
                 id: id.to_string(),
@@ -122,8 +150,7 @@ mod tests {
             ),
         ];
 
-        let embedder = MockEmbedder::new();
-        let input = embedder.embed("debug this code error in python").unwrap();
+        let input = InlineKwEmbed.embed("debug this code error in python").unwrap();
         let candidates = score_routes(&input, &examples, 3, &[], 0.0);
 
         assert!(!candidates.is_empty());