Class: Kotoshu::Models::NearestNeighbor

Inherits:
Object
  • Object
show all
Defined in:
lib/kotoshu/models/nearest_neighbor.rb

Overview

Value object for embedding search results (nearest neighbors).

Represents a single suggestion from semantic similarity search, with similarity score and optional embedding reference.

Examples:

Creating a neighbor

neighbor = NearestNeighbor.new("hello", 0.85, embedding: emb)
neighbor.to_s  # => "hello [85%]"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(word, similarity, embedding: nil) ⇒ NearestNeighbor

Create a new nearest neighbor result.

Parameters:

  • word (String) —

    The suggested word

  • similarity (Float) —

    Cosine similarity (0.0 to 1.0)

  • embedding (WordEmbedding, nil) (defaults to: nil) —

    Optional embedding reference

Raises:

  • (ArgumentError) 


23
24
25
26
27
28
29
30
31
 
# File 'lib/kotoshu/models/nearest_neighbor.rb', line 23

def initialize(word, similarity, embedding: nil)
  raise ArgumentError, "Similarity must be 0-1" unless similarity.between?(0.0, 1.0)

  @word = word
  @similarity = similarity
  @distance = 1.0 - similarity
  @embedding = embedding
  freeze
end

Instance Attribute Details

#distance ⇒ Object (readonly)

Returns the value of attribute distance.



16
17
18
 
# File 'lib/kotoshu/models/nearest_neighbor.rb', line 16

def distance
  @distance
end

#embedding ⇒ Object (readonly)

Returns the value of attribute embedding.



16
17
18
 
# File 'lib/kotoshu/models/nearest_neighbor.rb', line 16

def embedding
  @embedding
end

#similarity ⇒ Object (readonly)

Returns the value of attribute similarity.



16
17
18
 
# File 'lib/kotoshu/models/nearest_neighbor.rb', line 16

def similarity
  @similarity
end

#word ⇒ Object (readonly)

Returns the value of attribute word.



16
17
18
 
# File 'lib/kotoshu/models/nearest_neighbor.rb', line 16

def word
  @word
end

Instance Method Details

#<=>(other) ⇒ Integer

Comparison for sorting (higher similarity = better).

Parameters:

Returns:

  • (Integer) —

    Comparison result (-1, 0, 1)



37
38
39
40
41
42
 
# File 'lib/kotoshu/models/nearest_neighbor.rb', line 37

def <=>(other)
  return 0 unless other.is_a?(NearestNeighbor)

  # Higher similarity = better rank (sort descending)
  other.similarity <=> @similarity
end

#==(other) ⇒ Boolean Also known as: eql?

Check if this equals another neighbor.

Parameters:

  • other (Object) —

    Another object

Returns:

  • (Boolean) —

    True if words match



48
49
50
51
52
 
# File 'lib/kotoshu/models/nearest_neighbor.rb', line 48

def ==(other)
  return false unless other.is_a?(NearestNeighbor)

  @word == other.word
end

#confidence_level ⇒ Symbol

Get confidence level category.

Returns:

  • (Symbol) —

    :high, :medium, or :low



80
81
82
83
84
 
# File 'lib/kotoshu/models/nearest_neighbor.rb', line 80

def confidence_level
  return :high if @similarity > 0.8
  return :medium if @similarity > 0.5
  :low
end

#hash ⇒ Integer

Hash code for hash table usage.

Returns:

  • (Integer) —

    Hash code



58
59
60
 
# File 'lib/kotoshu/models/nearest_neighbor.rb', line 58

def hash
  @word.hash
end

#high_confidence? ⇒ Boolean

Check if this is a high-confidence suggestion.

Returns:

  • (Boolean) —

    True if similarity > 0.8



73
74
75
 
# File 'lib/kotoshu/models/nearest_neighbor.rb', line 73

def high_confidence?
  @similarity > 0.8
end

#to_s ⇒ String Also known as: inspect

String representation with percentage.

Returns:

  • (String) —

    Human-readable representation



65
66
67
 
# File 'lib/kotoshu/models/nearest_neighbor.rb', line 65

def to_s
  "#{@word} [#{(@similarity * 100).to_i}%]"
end