gte 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae83f737b57f798d39cf1fdc895d67948de27d36b46ea02c211a440d3acaa8c9
-  data.tar.gz: 9eaf9651b2ccf1fdb93efe4666ed70537628453a8cf92e234b454560560a83e8
+  metadata.gz: fc149108c647dc5b14154bfbdc4975b53670b9ed3cf7d80760cc2b415c935a48
+  data.tar.gz: 32a682a95d56c8fab8d0d64a7ada0c0347ae796b6aefe6191f9aca8fc96426c2
 SHA512:
-  metadata.gz: a262194a53bf804e47b0ef9c5910c1e2b814a9824823a92a73867a631c7b26310b3163e61997d9c163dab402a40d49946b76a64cc0421741ae235f623180cb95
-  data.tar.gz: 6acf5b58140012df9fa25971ed0f1fdfa707cc3efbe5f7f22104e35ad57877778a08cf9f8b311017be8f40e255289e3249e35c1e3780ae231f9f66e08cbb6ac3
+  metadata.gz: f5c69d954f51a51521b143b576942a9c0505ad60574c1727f963dd79e0b6c22cacc4e6d9af75394ae06f451521dbc788af51f1e79397a5cc66a41b4ce1b31933
+  data.tar.gz: 9e75fdbc9b5c8cfdd9d0e377a7e4a944057ec604e38ab23d960c4ed75ec6a72ce1dd27c2dd1bb2802721387babdabe0996e0c42be34d17d98253e0582b375de1

data/README.md

@@ -55,12 +55,21 @@ Config fields and defaults:
 - `normalize`: `true` (L2 normalization at Ruby-facing API)
 - `output_tensor`: `nil` (auto-select output tensor)
 - `max_length`: `nil` (uses tokenizer/model defaults)
+- `execution_providers`: `nil` (falls back to `GTE_EXECUTION_PROVIDERS` / CPU default)
 
 Notes:
 
 - Return a `Config::Text` from the block (for example, `config.with(...)`).
 - Model instances are cached by full config key; different config values create different cached instances.
 
+Low-level embedder setup (without model cache):
+
+```ruby
+embedder = GTE::Embedder.config(ENV.fetch("GTE_MODEL_DIR")) do |config|
+  config.with(threads: 0, execution_providers: "cpu")
+end
+```
+
 ## Reranker
 
 Use `GTE::Reranker.config(model_dir)` for cross-encoder reranking.
@@ -97,6 +106,7 @@ Reranker config fields and defaults:
 - `sigmoid`: `false` (set `true` if you want bounded [0,1] style scores)
 - `output_tensor`: `nil`
 - `max_length`: `nil`
+- `execution_providers`: `nil`
 
 ## Runtime + Result Examples
 
@@ -123,14 +133,30 @@ Input policy is text-only. Graphs requiring unsupported multimodal inputs (such
 
 ## Execution Providers
 
-Default execution provider is `xnnpack` on all platforms (including macOS arm64).
+Default behavior is CPU fallback via ONNX Runtime's default provider (no explicit provider registration).
+
+Configure providers with `GTE_EXECUTION_PROVIDERS` (comma-separated, case-insensitive).
+Supported values:
+
+- `cpu` or `none`: CPU fallback (skip explicit provider registration)
+- `xnnpack`
+- `coreml`
 
-To opt in to CoreML explicitly:
+Examples:
 
 ```bash
+export GTE_EXECUTION_PROVIDERS=cpu
 export GTE_EXECUTION_PROVIDERS=xnnpack,coreml
 ```
 
+Ruby per-instance override (takes precedence over `GTE_EXECUTION_PROVIDERS`):
+
+```ruby
+model = GTE.config(ENV.fetch("GTE_MODEL_DIR")) do |config|
+  config.with(execution_providers: "cpu")
+end
+```
+
 ## Development
 
 Run commands inside `nix develop` via Make targets:
@@ -154,8 +180,13 @@ nix develop -c bundle exec rake bench:matrix_sweep
 nix develop -c bundle exec ruby bench/memory_probe.rb --compare-pure
 ```
 
-For release tracking and regression detection, record a run entry in `RUNS.md`:
+To run benchmark + append a `RUNS.md` entry + enforce goal checks:
 
 ```bash
 make bench-record
 ```
+
+`bench/runs_ledger.rb check` is goal-focused by default:
+
+- Enforces goal metric (`response_time_p95` ratio threshold).
+- Does not require current-version coverage in `RUNS.md` unless explicitly enabled.

data/Rakefile

@@ -56,7 +56,7 @@ namespace :bench do
     )
   end
 
-  desc 'Run Puma benchmark, append RUNS.md entry, and enforce goal/regression checks'
+  desc 'Run Puma benchmark, append RUNS.md entry, and enforce goal checks'
   task :record_run do
     run_in_nix(
       'bundle', 'exec', 'ruby', 'bench/puma_compare.rb',
@@ -74,7 +74,7 @@ namespace :bench do
     )
   end
 
-  desc 'Validate current Puma benchmark output against 2x goal and regression policy'
+  desc 'Validate current Puma benchmark output against 2x goal only'
   task :check_goal do
     run_in_nix(
       'bundle', 'exec', 'ruby', 'bench/runs_ledger.rb', 'check',

data/VERSION

@@ -1 +1 @@
-0.0.5
+0.0.6

data/ext/gte/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "gte"
-version = "0.0.5"
+version = "0.0.6"
 edition = "2021"
 authors = ["elcuervo <elcuervo@elcuervo.net>"]
 license = "MIT"

data/ext/gte/src/embedder.rs

@@ -39,6 +39,7 @@ impl Embedder {
         model_name: Option<&str>,
         output_tensor_override: Option<&str>,
         max_length_override: Option<usize>,
+        execution_providers_override: Option<&str>,
     ) -> Result<Self> {
         const PREFERRED_EMBEDDING_OUTPUTS: [&str; 4] = [
             "pooler_output",
@@ -73,6 +74,7 @@ impl Embedder {
             with_attention_mask: true,
             num_threads,
             optimization_level,
+            execution_providers: execution_providers_override.map(str::to_string),
         };
         let session = build_session(&model_path, &session_config)?;
 
@@ -96,6 +98,7 @@ impl Embedder {
             with_attention_mask,
             num_threads,
             optimization_level,
+            execution_providers: execution_providers_override.map(str::to_string),
         };
 
         let tokenizer = Tokenizer::new(&tokenizer_path, config.max_length, config.with_type_ids)?;

data/ext/gte/src/model_config.rs

@@ -14,4 +14,5 @@ pub struct ModelConfig {
     pub with_attention_mask: bool,
     pub num_threads: usize,
     pub optimization_level: u8,
+    pub execution_providers: Option<String>,
 }

data/ext/gte/src/reranker.rs

@@ -33,6 +33,7 @@ impl Reranker {
         model_name: Option<&str>,
         output_tensor_override: Option<&str>,
         max_length_override: Option<usize>,
+        execution_providers_override: Option<&str>,
     ) -> Result<Self> {
         let dir = dir.as_ref();
         let tokenizer_path = resolve_tokenizer_path(dir)?;
@@ -60,6 +61,7 @@ impl Reranker {
             with_attention_mask: true,
             num_threads,
             optimization_level,
+            execution_providers: execution_providers_override.map(str::to_string),
         };
         let session = build_session(&model_path, &probe_config)?;
 

data/ext/gte/src/ruby_embedder.rs

@@ -171,6 +171,7 @@ impl RbEmbedder {
         normalize: bool,
         output_tensor: String,
         max_length: usize,
+        execution_providers: String,
     ) -> Result<Self, Error> {
         let name = if model_name.is_empty() {
             None
@@ -187,6 +188,11 @@ impl RbEmbedder {
         } else {
             Some(max_length)
         };
+        let execution_providers_override = if execution_providers.is_empty() {
+            None
+        } else {
+            Some(execution_providers.as_str())
+        };
         let embedder = Embedder::from_dir(
             &dir_path,
             num_threads,
@@ -194,6 +200,7 @@ impl RbEmbedder {
             name,
             output_override,
             max_length_override,
+            execution_providers_override,
         )
         .map_err(magnus::Error::from)?;
         Ok(RbEmbedder {
@@ -224,6 +231,7 @@ impl RbReranker {
         sigmoid: bool,
         output_tensor: String,
         max_length: usize,
+        execution_providers: String,
     ) -> Result<Self, Error> {
         let name = if model_name.is_empty() {
             None
@@ -240,6 +248,11 @@ impl RbReranker {
         } else {
             Some(max_length)
         };
+        let execution_providers_override = if execution_providers.is_empty() {
+            None
+        } else {
+            Some(execution_providers.as_str())
+        };
         let reranker = Reranker::from_dir(
             &dir_path,
             num_threads,
@@ -247,6 +260,7 @@ impl RbReranker {
             name,
             output_override,
             max_length_override,
+            execution_providers_override,
         )
         .map_err(magnus::Error::from)?;
         Ok(RbReranker {
@@ -362,12 +376,12 @@ impl RbTensor {
 pub fn register(ruby: &Ruby) -> Result<(), Error> {
     let module = ruby.define_module("GTE")?;
     let embedder_class = module.define_class("Embedder", ruby.class_object())?;
-    embedder_class.define_singleton_method("new", function!(RbEmbedder::rb_new, 7))?;
+    embedder_class.define_singleton_method("new", function!(RbEmbedder::rb_new, 8))?;
     embedder_class.define_method("embed", method!(RbEmbedder::rb_embed, 1))?;
     embedder_class.define_method("embed_one", method!(RbEmbedder::rb_embed_one, 1))?;
 
     let reranker_class = module.define_class("Reranker", ruby.class_object())?;
-    reranker_class.define_singleton_method("new", function!(RbReranker::rb_new, 7))?;
+    reranker_class.define_singleton_method("new", function!(RbReranker::rb_new, 8))?;
     reranker_class.define_method("score", method!(RbReranker::rb_score, 2))?;
 
     let tensor_class = module.define_class("Tensor", ruby.class_object())?;

data/ext/gte/src/session.rs

@@ -22,7 +22,7 @@ pub fn build_session<P: AsRef<Path>>(model_path: P, config: &ModelConfig) -> Res
         .with_optimization_level(opt_level)?
         .with_memory_pattern(true)?;
 
-    let providers = preferred_execution_providers();
+    let providers = preferred_execution_providers(config.execution_providers.as_deref());
     if !providers.is_empty() {
         builder = builder.with_execution_providers(providers)?;
     }
@@ -34,19 +34,40 @@ pub fn build_session<P: AsRef<Path>>(model_path: P, config: &ModelConfig) -> Res
     Ok(builder.commit_from_file(model_path)?)
 }
 
-fn preferred_execution_providers() -> Vec<ExecutionProviderDispatch> {
-    let order = std::env::var("GTE_EXECUTION_PROVIDERS")
-        .unwrap_or_else(|_| "xnnpack".to_string())
-        .to_ascii_lowercase();
+fn preferred_execution_providers(order_override: Option<&str>) -> Vec<ExecutionProviderDispatch> {
+    let order = resolve_provider_order(order_override);
 
     let mut providers = Vec::new();
-    for provider in order.split(',').map(str::trim).filter(|p| !p.is_empty()) {
+    for provider in parse_provider_registrations(order.as_str()) {
         match provider {
             "xnnpack" => {
                 providers.push(XNNPACKExecutionProvider::default().build().fail_silently())
             }
             "coreml" => providers.push(CoreMLExecutionProvider::default().build().fail_silently()),
-            "none" => {}
+            _ => {}
+        }
+    }
+    providers
+}
+
+fn resolve_provider_order(order_override: Option<&str>) -> String {
+    let env_order = std::env::var("GTE_EXECUTION_PROVIDERS").ok();
+    resolve_provider_order_with_env(order_override, env_order.as_deref())
+}
+
+fn resolve_provider_order_with_env(order_override: Option<&str>, env_order: Option<&str>) -> String {
+    order_override
+        .or(env_order)
+        .unwrap_or("cpu")
+        .to_ascii_lowercase()
+}
+
+fn parse_provider_registrations(order: &str) -> Vec<&str> {
+    let mut providers = Vec::new();
+    for provider in order.split(',').map(str::trim).filter(|p| !p.is_empty()) {
+        match provider {
+            "xnnpack" | "coreml" => providers.push(provider),
+            "none" | "cpu" => {}
             _ => {}
         }
     }
@@ -86,3 +107,42 @@ pub fn run_session(
         ExtractorMode::Raw => Ok(array.into_dimensionality::<Ix2>()?.into_owned()),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{parse_provider_registrations, resolve_provider_order_with_env};
+
+    #[test]
+    fn parse_provider_registrations_keeps_supported_order() {
+        let parsed = parse_provider_registrations("xnnpack,coreml");
+        assert_eq!(parsed, vec!["xnnpack", "coreml"]);
+    }
+
+    #[test]
+    fn parse_provider_registrations_treats_cpu_and_none_as_fallback() {
+        assert!(parse_provider_registrations("cpu").is_empty());
+        assert!(parse_provider_registrations("none").is_empty());
+        assert!(parse_provider_registrations("none,cpu").is_empty());
+    }
+
+    #[test]
+    fn parse_provider_registrations_ignores_unknowns_and_empties() {
+        let parsed = parse_provider_registrations(" ,xnnpak,,xnnpack,unknown,coreml,");
+        assert_eq!(parsed, vec!["xnnpack", "coreml"]);
+    }
+
+    #[test]
+    fn resolve_provider_order_prefers_override() {
+        assert_eq!(
+            resolve_provider_order_with_env(Some("xnnpack"), Some("coreml")),
+            "xnnpack"
+        );
+        assert_eq!(resolve_provider_order_with_env(Some("CPU"), None), "cpu");
+    }
+
+    #[test]
+    fn resolve_provider_order_falls_back_to_env_then_cpu_default() {
+        assert_eq!(resolve_provider_order_with_env(None, Some("coreml")), "coreml");
+        assert_eq!(resolve_provider_order_with_env(None, None), "cpu");
+    }
+}

data/ext/gte/tests/inference_integration_test.rs

@@ -5,8 +5,8 @@ use gte::embedder::Embedder;
 fn test_e5_single_embedding_shape() {
     const DIR: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/fixtures/e5");
 
-    let embedder =
-        Embedder::from_dir(DIR, 0, 3, None, None, None).expect("embedder should initialize");
+    let embedder = Embedder::from_dir(DIR, 0, 3, None, None, None, None)
+        .expect("embedder should initialize");
     let result = embedder
         .embed(vec!["query: Hello world".to_string()])
         .expect("embed should succeed");
@@ -20,8 +20,8 @@ fn test_e5_single_embedding_shape() {
 fn test_clip_single_embedding_shape() {
     const DIR: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/fixtures/clip");
 
-    let embedder =
-        Embedder::from_dir(DIR, 0, 3, None, None, None).expect("embedder should initialize");
+    let embedder = Embedder::from_dir(DIR, 0, 3, None, None, None, None)
+        .expect("embedder should initialize");
     let result = embedder
         .embed(vec!["a photo of a cat".to_string()])
         .expect("embed should succeed");
@@ -35,8 +35,8 @@ fn test_clip_single_embedding_shape() {
 fn test_e5_batch_embedding_shape() {
     const DIR: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/fixtures/e5");
 
-    let embedder =
-        Embedder::from_dir(DIR, 0, 3, None, None, None).expect("embedder should initialize");
+    let embedder = Embedder::from_dir(DIR, 0, 3, None, None, None, None)
+        .expect("embedder should initialize");
     let texts = vec![
         "query: first sentence".to_string(),
         "query: second sentence".to_string(),
@@ -54,8 +54,8 @@ fn test_e5_batch_embedding_shape() {
 fn test_e5_long_input_truncation_no_error() {
     const DIR: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/fixtures/e5");
 
-    let embedder =
-        Embedder::from_dir(DIR, 0, 3, None, None, None).expect("embedder should initialize");
+    let embedder = Embedder::from_dir(DIR, 0, 3, None, None, None, None)
+        .expect("embedder should initialize");
     let very_long_text = "word ".repeat(1000);
     let result = embedder
         .embed(vec![very_long_text])

data/lib/gte/config.rb

@@ -4,12 +4,12 @@ module GTE
   module Config
     Text = Data.define(
       :model_dir, :threads, :optimization_level,
-      :model_name, :normalize, :output_tensor, :max_length
+      :model_name, :normalize, :output_tensor, :max_length, :execution_providers
     )
 
     Reranker = Data.define(
       :model_dir, :threads, :optimization_level,
-      :model_name, :sigmoid, :output_tensor, :max_length
+      :model_name, :sigmoid, :output_tensor, :max_length, :execution_providers
     )
   end
 end

data/lib/gte/embedder.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module GTE
+  class Embedder
+    class << self
+      def config(model_dir)
+        cfg = default_config(model_dir)
+        cfg = yield(cfg) if block_given?
+        from_config(cfg)
+      end
+
+      def from_config(config)
+        new(
+          config.model_dir,
+          config.threads,
+          config.optimization_level,
+          config.model_name.to_s,
+          config.normalize,
+          config.output_tensor.to_s,
+          config.max_length || 0,
+          config.execution_providers.to_s
+        )
+      end
+
+      private
+
+      def default_config(model_dir)
+        Config::Text.new(
+          model_dir: File.expand_path(model_dir),
+          threads: 3,
+          optimization_level: 3,
+          model_name: nil,
+          normalize: true,
+          output_tensor: nil,
+          max_length: nil,
+          execution_providers: nil
+        )
+      end
+    end
+  end
+end

data/lib/gte/model.rb

@@ -8,15 +8,7 @@ module GTE
       raise ArgumentError, 'config must be a GTE::Config::Text' unless config.is_a?(Config::Text)
 
       @config = config
-      @embedder = GTE::Embedder.new(
-        config.model_dir,
-        config.threads,
-        config.optimization_level,
-        config.model_name.to_s,
-        config.normalize,
-        config.output_tensor.to_s,
-        config.max_length || 0
-      )
+      @embedder = GTE::Embedder.from_config(config)
     end
 
     def embed(texts)

data/lib/gte/reranker.rb

@@ -24,7 +24,8 @@ module GTE
           model_name: nil,
           sigmoid: false,
           output_tensor: nil,
-          max_length: nil
+          max_length: nil,
+          execution_providers: nil
         )
       end
 
@@ -36,7 +37,8 @@ module GTE
           cfg.model_name.to_s,
           cfg.sigmoid,
           cfg.output_tensor.to_s,
-          cfg.max_length || 0
+          cfg.max_length || 0,
+          cfg.execution_providers.to_s
         )
       end
     end

data/lib/gte.rb

@@ -9,6 +9,7 @@ rescue LoadError
 end
 
 require 'gte/config'
+require 'gte/embedder'
 require 'gte/model'
 require 'gte/reranker'
 
@@ -25,7 +26,8 @@ module GTE
         model_name: nil,
         normalize: true,
         output_tensor: nil,
-        max_length: nil
+        max_length: nil,
+        execution_providers: nil
       )
 
       cfg = yield(cfg) if block_given?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gte
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - elcuervo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-15 00:00:00.000000000 Z
+date: 2026-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -114,6 +114,7 @@ files:
 - ext/gte/tests/tokenizer_unit_test.rs
 - lib/gte.rb
 - lib/gte/config.rb
+- lib/gte/embedder.rb
 - lib/gte/model.rb
 - lib/gte/reranker.rb
 - lib/gte/version.rb