Class: SwarmSDK::V3::Memory::Embedder

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/v3/memory/embedder.rb

Overview

ONNX-based text embedder using Informers gem

Uses the ‘Informers.pipeline(“embedding”, …)` API to generate sentence embeddings via ONNX inference. Lazy-loads the model on first use to avoid startup cost.

Model name and cache directory are read from Configuration, with environment variable overrides.

The model is automatically downloaded on first use if not cached. Use #preload! to trigger an eager download before first embedding.

Examples:

Basic usage

embedder = Embedder.new
vector = embedder.embed("The API uses JWT tokens")
vector.length  #=> 384

Eager download

embedder = Embedder.new
embedder.preload!  # Downloads model if not cached

Custom model via environment variable

ENV["SWARM_EMBEDDING_MODEL"] = "sentence-transformers/all-MiniLM-L6-v2"
embedder = Embedder.new

Constant Summary collapse

DIMENSIONS = 
384
DEFAULT_MODEL =

Default embedding model (QA-optimized, 384 dimensions)

"sentence-transformers/multi-qa-MiniLM-L6-cos-v1"
MODEL_ENV_VAR =

Environment variable for model override

"SWARM_EMBEDDING_MODEL"

Instance Method Summary collapse

Instance Method Details

#cached? ⇒ Boolean

Check if the embedding model is cached locally

Verifies that the model directory exists and contains the required tokenizer and ONNX model files.

Examples:

embedder = Embedder.new
embedder.cached?  #=> true (if already downloaded)

Returns:

  • (Boolean) —

    true if model files exist on disk



121
122
123
124
125
126
127
128
129
130
 
# File 'lib/swarm_sdk/v3/memory/embedder.rb', line 121

def cached?
  cache_dir = resolve_cache_dir
  model_dir = File.join(cache_dir, model_name)
  return false unless File.directory?(model_dir)

  # Check for required model files
  tokenizer = File.join(model_dir, "tokenizer.json")
  onnx_model = File.join(model_dir, "onnx", "model.onnx")
  File.exist?(tokenizer) && File.exist?(onnx_model)
end

#dimensions ⇒ Integer

Number of dimensions in the embedding vector

Returns:

  • (Integer) 


42
43
44
 
# File 'lib/swarm_sdk/v3/memory/embedder.rb', line 42

def dimensions
  DIMENSIONS
end

#embed(text) ⇒ Array<Float>

Generate an embedding vector for text

Lazy-loads the model on first call. The model will be downloaded automatically if not cached locally.

Examples:

vector = embedder.embed("Hello world")
vector.length  #=> 384

Parameters:

  • text (String) —

    Text to embed

Returns:

  • (Array<Float>) —

    Embedding vector (384 dimensions)

Raises:

  • (MemoryError) —

    If model loading or embedding fails



70
71
72
73
74
 
# File 'lib/swarm_sdk/v3/memory/embedder.rb', line 70

def embed(text)
  pipeline.call(text)
rescue StandardError => e
  raise MemoryError, "Embedding failed for text (#{text.length} chars): #{e.message}"
end

#embed_batch(texts) ⇒ Array<Array<Float>>

Generate embeddings for multiple texts

More efficient than calling embed() in a loop because the pipeline can batch internally.

Parameters:

  • texts (Array<String>) —

    Texts to embed

Returns:

  • (Array<Array<Float>>) —

    Embedding vectors

Raises:



84
85
86
87
88
89
90
 
# File 'lib/swarm_sdk/v3/memory/embedder.rb', line 84

def embed_batch(texts)
  return [] if texts.empty?

  pipeline.call(texts)
rescue StandardError => e
  raise MemoryError, "Batch embedding failed (#{texts.size} texts): #{e.message}"
end

#model_name ⇒ String

The model name used for embeddings

Resolution order:

  1. SWARM_EMBEDDING_MODEL environment variable

  2. Configuration.instance.embedding_model

  3. DEFAULT_MODEL constant

Returns:

  • (String) —

    Sentence-transformer model identifier



54
55
56
 
# File 'lib/swarm_sdk/v3/memory/embedder.rb', line 54

def model_name
  ENV[MODEL_ENV_VAR] || Configuration.instance.embedding_model || DEFAULT_MODEL
end

#preload! ⇒ void

This method returns an undefined value.

Eagerly download and load the embedding model

Triggers model download if not already cached. Useful for ensuring the model is available before first use. This is a one-time download of ~90MB.

Examples:

embedder = Embedder.new
embedder.preload!  # Downloads model files (~90MB)

Raises:



104
105
106
107
108
109
 
# File 'lib/swarm_sdk/v3/memory/embedder.rb', line 104

def preload!
  pipeline
  nil
rescue StandardError => e
  raise MemoryError, "Failed to preload embedding model '#{model_name}': #{e.message}"
end