Class: RubyLLM::Agents::EmbeddingResult

Inherits:
Object
  • Object
show all
Includes:
Trackable
Defined in:
lib/ruby_llm/agents/results/embedding_result.rb

Overview

Result object for embedding operations

Wraps embedding vectors with metadata about the operation including token usage, cost, timing, and utility methods for similarity calculations.

Examples:

Single text embedding

result = MyEmbedder.call(text: "Hello world")
result.vector        # => [0.123, -0.456, ...]
result.dimensions    # => 1536
result.input_tokens  # => 2

Batch embedding

result = MyEmbedder.call(texts: ["Hello", "World"])
result.vectors       # => [[...], [...]]
result.count         # => 2

Similarity comparison

result1 = MyEmbedder.call(text: "Ruby programming")
result2 = MyEmbedder.call(text: "Python programming")
result1.similarity(result2)  # => 0.85

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Trackable

included

Constructor Details

#initialize(attributes = {}) ⇒ EmbeddingResult

Creates a new EmbeddingResult instance

Parameters:

  • attributes (Hash) (defaults to: {}) —

    Result attributes

Options Hash (attributes):

  • :vectors (Array<Array<Float>>) —

    The embedding vectors

  • :model_id (String) —

    The model used

  • :dimensions (Integer) —

    Vector dimensionality

  • :input_tokens (Integer) —

    Tokens consumed

  • :total_cost (Float) —

    Cost in USD

  • :duration_ms (Integer) —

    Duration in milliseconds

  • :count (Integer) —

    Number of texts

  • :started_at (Time) —

    Start time

  • :completed_at (Time) —

    Completion time

  • :tenant_id (String) —

    Tenant identifier

  • :error_class (String) —

    Error class name

  • :error_message (String) —

    Error message



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 97

def initialize(attributes = {})
  @vectors = attributes[:vectors] || []
  @model_id = attributes[:model_id]
  @dimensions = attributes[:dimensions]
  @input_tokens = attributes[:input_tokens]
  @total_cost = attributes[:total_cost]
  @duration_ms = attributes[:duration_ms]
  @count = attributes[:count] || @vectors.size
  @started_at = attributes[:started_at]
  @completed_at = attributes[:completed_at]
  @tenant_id = attributes[:tenant_id]
  @error_class = attributes[:error_class]
  @error_message = attributes[:error_message]
  @execution_id = attributes[:execution_id]
  @agent_class_name = attributes[:agent_class_name]
  register_with_tracker
end

Instance Attribute Details

#completed_at ⇒ Object (readonly) 



64
65
66
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 64

def completed_at
  @completed_at
end

#count ⇒ Object (readonly) 



56
57
58
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 56

def count
  @count
end

#dimensions ⇒ Object (readonly) 



40
41
42
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 40

def dimensions
  @dimensions
end

#duration_ms ⇒ Object (readonly) 



52
53
54
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 52

def duration_ms
  @duration_ms
end

#error_class ⇒ Object (readonly) 



72
73
74
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 72

def error_class
  @error_class
end

#error_message ⇒ Object (readonly) 



76
77
78
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 76

def error_message
  @error_message
end

#execution_id ⇒ Object (readonly) 



80
81
82
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 80

def execution_id
  @execution_id
end

#input_tokens ⇒ Object (readonly) 



44
45
46
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 44

def input_tokens
  @input_tokens
end

#model_id ⇒ Object (readonly) 



36
37
38
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 36

def model_id
  @model_id
end

#started_at ⇒ Object (readonly) 



60
61
62
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 60

def started_at
  @started_at
end

#tenant_id ⇒ Object (readonly) 



68
69
70
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 68

def tenant_id
  @tenant_id
end

#total_cost ⇒ Object (readonly) 



48
49
50
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 48

def total_cost
  @total_cost
end

#vectors ⇒ Object (readonly) 



32
33
34
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 32

def vectors
  @vectors
end

Instance Method Details

#batch? ⇒ Boolean

Returns whether this result contains multiple embeddings

Returns:

  • (Boolean) —

    true if count > 1



132
133
134
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 132

def batch?
  count > 1
end

#error? ⇒ Boolean

Returns whether the execution failed

Returns:

  • (Boolean) —

    true if an error occurred



155
156
157
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 155

def error?
  !success?
end

#execution ⇒ RubyLLM::Agents::Execution?

Loads the associated Execution record from the database

Returns:



118
119
120
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 118

def execution
  @execution ||= RubyLLM::Agents::Execution.find_by(id: execution_id) if execution_id
end

#most_similar(others, limit: 10, index: 0) ⇒ Array<Hash>

Finds the most similar vectors from a collection

Examples:

Find top 5 similar

result.most_similar(document_embeddings, limit: 5)

Parameters:

  • others (Array<EmbeddingResult, Array<Float>>) —

    Collection to search

  • limit (Integer) (defaults to: 10) —

    Maximum results to return

  • index (Integer) (defaults to: 0) —

    Index of the source vector (for batch results)

Returns:

  • (Array<Hash>) —

    Sorted results with :index and :similarity keys



196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 196

def most_similar(others, limit: 10, index: 0)
  v1 = vectors[index]
  return [] if v1.nil?

  similarities = others.each_with_index.map do |other, idx|
    v2 = case other
    when EmbeddingResult
      other.vector
    when Array
      other
    else
      next nil
    end

    next nil if v2.nil?

    {index: idx, similarity: cosine_similarity(v1, v2)}
  end.compact

  similarities.sort_by { |s| -s[:similarity] }.first(limit)
end

#similarity(other, index: 0) ⇒ Float

Calculates cosine similarity between this embedding and another

Examples:

Compare two results

result1.similarity(result2)  # => 0.85

Compare with raw vector

result.similarity([0.1, 0.2, 0.3])

Compare specific vector from batch

batch_result.similarity(other, index: 2)

Parameters:

  • other (EmbeddingResult, Array<Float>) —

    Another embedding or vector

  • index (Integer) (defaults to: 0) —

    Index of the vector to compare (for batch results)

Returns:

  • (Float) —

    Cosine similarity score (-1.0 to 1.0)



170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 170

def similarity(other, index: 0)
  v1 = vectors[index]
  return nil if v1.nil?

  v2 = case other
  when EmbeddingResult
    other.vector
  when Array
    other
  else
    raise ArgumentError, "other must be EmbeddingResult or Array, got #{other.class}"
  end

  return nil if v2.nil?

  cosine_similarity(v1, v2)
end

#single? ⇒ Boolean

Returns whether this result contains a single embedding

Returns:

  • (Boolean) —

    true if count is 1



125
126
127
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 125

def single?
  count == 1
end

#success? ⇒ Boolean

Returns whether the execution succeeded

Returns:

  • (Boolean) —

    true if no error occurred



148
149
150
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 148

def success?
  error_class.nil?
end

#to_h ⇒ Hash

Converts the result to a hash

Returns:

  • (Hash) —

    All result data as a hash



221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 221

def to_h
  {
    vectors: vectors,
    model_id: model_id,
    dimensions: dimensions,
    input_tokens: input_tokens,
    total_cost: total_cost,
    duration_ms: duration_ms,
    count: count,
    started_at: started_at,
    completed_at: completed_at,
    tenant_id: tenant_id,
    error_class: error_class,
    error_message: error_message,
    execution_id: execution_id
  }
end

#vector ⇒ Array<Float>?

Returns the first (or only) embedding vector

Convenience method for single-text embeddings.

Returns:

  • (Array<Float>, nil) —

    The embedding vector or nil if batch



141
142
143
 
# File 'lib/ruby_llm/agents/results/embedding_result.rb', line 141

def vector
  vectors.first
end