Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

feat(core): gate ONNX transforms behind a default-on `ml` feature (static/lexical builds) (#2165)

Matthew Jacksoncdba2eccddaa
diff --git a/crates/headroom-core/Cargo.toml b/crates/headroom-core/Cargo.toml
index 80076965e..198ace6f0 100644
--- a/crates/headroom-core/Cargo.toml
+++ b/crates/headroom-core/Cargo.toml
@@ -67,7 +67,7 @@ flate2 = "1"
# crate depends on `ort`, which is already in our dep tree via
# `fastembed`, so adding it doesn't pull a new ML runtime — both
# crates share the ONNX Runtime singleton.
-magika = "1"
+magika = { version = "1", optional = true }
# `unidiff` is the Stage-3d Tier-2 diff detector. We use the parser
# itself as the "is this a diff?" oracle — anything that successfully
# parses to ≥1 PatchedFile is a diff. The deterministic parser
@@ -132,15 +132,25 @@ http = "1"
# runtime AVX2 guard could run (#1278). With `ort-load-dynamic` the
# library is only dlopen'd at first use, where the AVX2 guard falls
# back to the non-ONNX detection tiers.
-fastembed = { version = "5", default-features = false, features = [
+fastembed = { version = "5", default-features = false, optional = true, features = [
"hf-hub-rustls-tls",
"ort-load-dynamic",
"image-models",
] }
-ort = { version = "2.0.0-rc.12", default-features = false, features = ["load-dynamic"] }
+ort = { version = "2.0.0-rc.12", default-features = false, optional = true, features = ["load-dynamic"] }
[features]
-default = []
+# `ml` is ON by default, so a stock build is byte-for-byte what it was before:
+# the ONNX-backed transforms (fastembed embeddings, magika detection, the
+# smart-crusher ML path) are all compiled in. Turning it OFF
+# (`default-features = false`) drops `ort`/`fastembed`/`magika` from the tree
+# entirely, so a consumer that only uses the lexical path (`TextCrusher` /
+# BM25 relevance) builds with no ONNX Runtime at all — which is what lets that
+# consumer ship a fully-static musl binary. See the source `#[cfg(feature =
+# "ml")]` gates (TODO: the module + dispatch gating is the collaborative half
+# of this change — flagged in the PR).
+default = ["ml"]
+ml = ["dep:ort", "dep:fastembed", "dep:magika"]
# Compile in the Redis CCR backend. Enable for multi-worker deployments
# that want a shared CCR store with no sticky-session at the LB. The
# SQLite backend (always compiled) is the production default for
diff --git a/crates/headroom-core/src/lib.rs b/crates/headroom-core/src/lib.rs
index 753fcdc76..8a907045a 100644
--- a/crates/headroom-core/src/lib.rs
+++ b/crates/headroom-core/src/lib.rs
@@ -4,6 +4,7 @@ pub mod auth_mode;
pub mod cache_control;
pub mod ccr;
pub mod compression_policy;
+#[cfg(feature = "ml")]
mod onnx_cpu;
pub mod relevance;
pub mod signals;
diff --git a/crates/headroom-core/src/relevance/embedding.rs b/crates/headroom-core/src/relevance/embedding.rs
index 32c658d29..02facf02b 100644
--- a/crates/headroom-core/src/relevance/embedding.rs
+++ b/crates/headroom-core/src/relevance/embedding.rs
@@ -26,8 +26,10 @@
//! kernels, same weights — embeddings agree to floating-point
//! representation. Cosine similarity agrees to ~1e-6.
+#[cfg(feature = "ml")]
use std::sync::Mutex;
+#[cfg(feature = "ml")]
use fastembed::{EmbeddingModel, InitOptions, TextEmbedding};
use super::base::{RelevanceScore, RelevanceScorer};
@@ -39,6 +41,7 @@ use super::base::{RelevanceScore, RelevanceScorer};
/// for backwards compatibility but `is_available()` returns `false`
/// when the inner model failed to load (mimicking Python's
/// "sentence-transformers not installed" branch).
+#[cfg(feature = "ml")]
pub struct EmbeddingScorer {
pub model_name: String,
/// `None` when model load failed — `is_available()` returns false
@@ -55,6 +58,7 @@ pub struct EmbeddingScorer {
model: Option<Mutex<TextEmbedding>>,
}
+#[cfg(feature = "ml")]
impl Default for EmbeddingScorer {
/// Returns an unloaded scorer (model = None, is_available = false).
///
@@ -75,6 +79,7 @@ impl Default for EmbeddingScorer {
}
}
+#[cfg(feature = "ml")]
impl EmbeddingScorer {
/// Construct the scorer with the default model
/// (BAAI/bge-small-en-v1.5). May trigger a one-time HF Hub
@@ -118,6 +123,7 @@ impl EmbeddingScorer {
}
}
+#[cfg(feature = "ml")]
impl RelevanceScorer for EmbeddingScorer {
fn score(&self, item: &str, context: &str) -> RelevanceScore {
if item.is_empty() || context.is_empty() {
@@ -207,8 +213,66 @@ impl RelevanceScorer for EmbeddingScorer {
}
}
+/// Lexical-only build stub.
+///
+/// Without the `ml` feature the fastembed/ONNX backend is compiled out
+/// entirely. `EmbeddingScorer` still exists so `HybridScorer` and
+/// `create_scorer` compile unchanged, but it carries no model and is
+/// permanently unavailable: `is_available()` is always `false` and the
+/// scoring methods return the same empty scores the ml build produces
+/// when its model failed to load. `HybridScorer` therefore takes its
+/// BM25 fallback path exactly as it does when embeddings are stubbed.
+#[cfg(not(feature = "ml"))]
+pub struct EmbeddingScorer {
+ pub model_name: String,
+}
+
+#[cfg(not(feature = "ml"))]
+impl Default for EmbeddingScorer {
+ fn default() -> Self {
+ EmbeddingScorer {
+ model_name: "BAAI/bge-small-en-v1.5".to_string(),
+ }
+ }
+}
+
+#[cfg(not(feature = "ml"))]
+impl RelevanceScorer for EmbeddingScorer {
+ fn score(&self, item: &str, context: &str) -> RelevanceScore {
+ if item.is_empty() || context.is_empty() {
+ return RelevanceScore::empty("Embedding: empty input");
+ }
+ RelevanceScore::empty("Embedding: model not available")
+ }
+
+ fn score_batch(&self, items: &[&str], context: &str) -> Vec<RelevanceScore> {
+ if items.is_empty() {
+ return Vec::new();
+ }
+ if context.is_empty() {
+ return items
+ .iter()
+ .map(|_| RelevanceScore::empty("Embedding: empty context"))
+ .collect();
+ }
+ items
+ .iter()
+ .map(|_| RelevanceScore::empty("Embedding: model not available"))
+ .collect()
+ }
+
+ fn is_available(&self) -> bool {
+ false
+ }
+}
+
/// Cosine similarity for two vectors. Clamped to `[0, 1]` since we
/// only care about positive similarity (mirrors Python `_cosine_similarity`).
+///
+/// Only the `ml` build calls this at runtime (from the fastembed-backed
+/// scorer); the lexical-only build keeps it solely for the unit tests
+/// that pin its numeric behavior.
+#[cfg(any(feature = "ml", test))]
fn cosine_similarity(a: &[f32], b: &[f32]) -> f64 {
if a.is_empty() || b.is_empty() || a.len() != b.len() {
return 0.0;
@@ -239,12 +303,14 @@ mod tests {
// download). Without the env var, only the offline-safe stub
// path is exercised.
+ #[cfg(feature = "ml")]
fn fastembed_enabled() -> bool {
std::env::var("RUN_FASTEMBED_TESTS").is_ok()
}
/// Construct a stub scorer with `model = None` for offline-safe
/// tests of the unavailable-path behavior.
+ #[cfg(feature = "ml")]
fn unavailable_scorer() -> EmbeddingScorer {
EmbeddingScorer {
model_name: "test".to_string(),
@@ -252,6 +318,13 @@ mod tests {
}
}
+ /// In the lexical-only build the scorer is always unavailable, so
+ /// `default()` already gives the stub we want to exercise.
+ #[cfg(not(feature = "ml"))]
+ fn unavailable_scorer() -> EmbeddingScorer {
+ EmbeddingScorer::default()
+ }
+
#[test]
fn cosine_similarity_orthogonal_vectors() {
let a = vec![1.0_f32, 0.0, 0.0, 0.0];
@@ -327,6 +400,7 @@ mod tests {
// ---------- AVX2 CPU guard (issue #1723) ----------
+ #[cfg(feature = "ml")]
#[test]
fn onnx_guard_matches_cpu_features() {
let supported = crate::onnx_cpu::onnx_runtime_supported_by_cpu();
@@ -336,6 +410,7 @@ mod tests {
assert!(supported);
}
+ #[cfg(feature = "ml")]
#[test]
fn try_new_errors_on_unsupported_cpu_instead_of_sigill() {
// On a no-AVX2 host the guard must turn the SIGILL into a plain Err
@@ -352,6 +427,7 @@ mod tests {
// ---------- model-backed tests (gated on RUN_FASTEMBED_TESTS) ----------
+ #[cfg(feature = "ml")]
#[test]
fn fastembed_loads_default_model() {
if !fastembed_enabled() {
@@ -362,6 +438,7 @@ mod tests {
assert_eq!(s.model_name, "BGESmallENV15");
}
+ #[cfg(feature = "ml")]
#[test]
fn fastembed_semantic_match_outranks_unrelated() {
if !fastembed_enabled() {
@@ -378,6 +455,7 @@ mod tests {
);
}
+ #[cfg(feature = "ml")]
#[test]
fn fastembed_batch_returns_one_score_per_item() {
if !fastembed_enabled() {
diff --git a/crates/headroom-core/src/transforms/detection.rs b/crates/headroom-core/src/transforms/detection.rs
index 43b8d2f75..55a81c471 100644
--- a/crates/headroom-core/src/transforms/detection.rs
+++ b/crates/headroom-core/src/transforms/detection.rs
@@ -47,6 +47,7 @@
//! for those specifically; not preemptively.
use crate::transforms::content_detector::ContentType;
+#[cfg(feature = "ml")]
use crate::transforms::magika_detector::magika_detect;
use crate::transforms::unidiff_detector::is_diff;
@@ -61,6 +62,10 @@ pub fn detect(content: &str) -> ContentType {
}
// ── Tier 1: Magika ──────────────────────────────────────────
+ // Only present in the `ml` build. Without the ML crates the magika
+ // detector is compiled out; the chain skips Tier 1 and begins at
+ // Tier 2, exactly as it would when magika returns PlainText.
+ #[cfg(feature = "ml")]
match magika_detect(content) {
Ok(ContentType::PlainText) => {
// Magika says "I don't know" or "plain text". Continue
@@ -92,12 +97,23 @@ pub fn detect(content: &str) -> ContentType {
#[cfg(test)]
mod tests {
use super::*;
+ #[cfg(feature = "ml")]
use crate::transforms::magika_detector::magika_runtime_available_for_session_init;
+ #[cfg(feature = "ml")]
fn magika_available() -> bool {
magika_runtime_available_for_session_init().is_ok()
}
+ // Without the ML crates there is no magika session at all, so the
+ // detection chain always starts at Tier 2. Report "unavailable" so
+ // the shared assertions below exercise the same fallthrough path
+ // they use on a host where magika can't initialize.
+ #[cfg(not(feature = "ml"))]
+ fn magika_available() -> bool {
+ false
+ }
+
#[test]
fn empty_input_short_circuits_to_plain_text() {
assert_eq!(detect(""), ContentType::PlainText);
diff --git a/crates/headroom-core/src/transforms/mod.rs b/crates/headroom-core/src/transforms/mod.rs
index b4b8ba65f..d65c1deca 100644
--- a/crates/headroom-core/src/transforms/mod.rs
+++ b/crates/headroom-core/src/transforms/mod.rs
@@ -22,6 +22,7 @@ pub mod detection;
pub mod diff_compressor;
pub mod live_zone;
pub mod log_compressor;
+#[cfg(feature = "ml")]
pub mod magika_detector;
pub mod pipeline;
pub mod recommendations;
@@ -49,6 +50,7 @@ pub use log_compressor::{
LogCompressionResult, LogCompressor, LogCompressorConfig, LogCompressorStats, LogFormat,
LogLevel, LogLine,
};
+#[cfg(feature = "ml")]
pub use magika_detector::{magika_detect, map_magika_label, MagikaDetectorError};
pub use pipeline::{
CompressionContext, CompressionPipeline, CompressionPipelineBuilder, DiffNoise, DiffOffload,