rubyllm-semantic_router 0.1.0

data/lib/rubyllm/semantic_router/strategies/semantic.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module SemanticRouter
+    module Strategies
+      # Semantic routing strategy using embeddings and kNN search
+      #
+      # This strategy:
+      # 1. Generates an embedding for the user's message
+      # 2. Finds the nearest routing examples using cosine similarity
+      # 3. Routes to the agent associated with the best match
+      # 4. Falls back if confidence is below threshold
+      class Semantic < Base
+        def route(message, agents:, examples:, current_agent:, config:, find_examples: nil)
+          # If custom find_examples provided, use it
+          # Otherwise, check if we have examples to search
+          has_search = find_examples.respond_to?(:call) ||
+                       (examples && !examples_empty?(examples))
+
+          unless has_search
+            return apply_fallback(
+              config: config,
+              current_agent: current_agent,
+              default_agent: config.default_agent
+            )
+          end
+
+          # Generate embedding for the message
+          embedding = generate_embedding(message, config.embedding_model)
+
+          # Find nearest neighbors using custom search or built-in
+          matches = if find_examples.respond_to?(:call)
+            find_with_custom_search(find_examples, embedding, config.k_neighbors)
+          else
+            find_nearest_neighbors(examples, embedding, config)
+          end
+
+          # No matches found
+          if matches.empty?
+            return apply_fallback(
+              config: config,
+              current_agent: current_agent,
+              default_agent: config.default_agent
+            )
+          end
+
+          # Get best match and calculate confidence
+          best_match = matches.first
+          confidence = calculate_confidence(best_match)
+
+          # Check threshold
+          if confidence < config.similarity_threshold
+            return apply_fallback(
+              config: config,
+              current_agent: current_agent,
+              default_agent: config.default_agent
+            )
+          end
+
+          # Return semantic match decision
+          RoutingDecision.new(
+            agent: extract_agent_name(best_match),
+            confidence: confidence,
+            matched_example: extract_example_text(best_match),
+            reason: :semantic_match
+          )
+        end
+
+        private
+
+        def examples_empty?(examples)
+          if examples.respond_to?(:empty?)
+            examples.empty?
+          elsif examples.respond_to?(:count)
+            examples.count.zero?
+          else
+            !examples || examples.to_a.empty?
+          end
+        end
+
+        def generate_embedding(message, model)
+          response = RubyLLM.embed(message, model: model)
+          vectors = response.vectors
+          # RubyLLM returns vector directly for single input, array of vectors for batch
+          vectors.first.is_a?(Array) ? vectors.first : vectors
+        rescue StandardError => e
+          raise EmbeddingError, e
+        end
+
+        def find_nearest_neighbors(examples, embedding, config)
+          # Support both ActiveRecord (with neighbor gem) and in-memory arrays
+          if examples.respond_to?(:nearest_neighbors)
+            # ActiveRecord with neighbor gem
+            examples.nearest_neighbors(:embedding, embedding, distance: :cosine)
+                    .limit(config.k_neighbors)
+                    .to_a
+          else
+            # In-memory array - calculate distances manually
+            find_nearest_in_memory(examples.to_a, embedding, config.k_neighbors)
+          end
+        end
+
+        def find_with_custom_search(find_examples, embedding, limit)
+          # Call the custom search function
+          results = find_examples.call(embedding, limit: limit)
+          return [] if results.nil? || results.empty?
+
+          # Normalize results to have a consistent interface
+          results.map do |result|
+            CustomSearchMatch.new(result)
+          end
+        end
+
+        def find_nearest_in_memory(examples, query_embedding, k)
+          # Calculate cosine distance for each example
+          scored = examples.map do |example|
+            distance = cosine_distance(query_embedding, example.embedding)
+            [example, distance]
+          end
+
+          # Sort by distance (ascending) and take top k
+          scored.sort_by { |_, distance| distance }
+                .first(k)
+                .map { |example, distance| InMemoryMatch.new(example, distance) }
+        end
+
+        def cosine_distance(a, b)
+          # Cosine distance = 1 - cosine similarity
+          dot_product = a.zip(b).sum { |x, y| x * y }
+          magnitude_a = Math.sqrt(a.sum { |x| x**2 })
+          magnitude_b = Math.sqrt(b.sum { |x| x**2 })
+
+          return 1.0 if magnitude_a.zero? || magnitude_b.zero?
+
+          1.0 - (dot_product / (magnitude_a * magnitude_b))
+        end
+
+        def calculate_confidence(match)
+          # Convert cosine distance to similarity (confidence)
+          # Distance is 0-2 for cosine, similarity is 0-1
+          distance = extract_distance(match)
+          [1.0 - distance, 0.0].max
+        end
+
+        def extract_distance(match)
+          if match.respond_to?(:neighbor_distance)
+            match.neighbor_distance
+          elsif match.respond_to?(:distance)
+            match.distance
+          else
+            1.0 # Maximum distance if we can't determine
+          end
+        end
+
+        def extract_agent_name(match)
+          if match.respond_to?(:agent_name)
+            match.agent_name
+          elsif match.respond_to?(:example) && match.example.respond_to?(:agent_name)
+            match.example.agent_name
+          else
+            raise Error, "Cannot extract agent_name from match: #{match.inspect}"
+          end
+        end
+
+        def extract_example_text(match)
+          if match.respond_to?(:example_text)
+            match.example_text
+          elsif match.respond_to?(:example) && match.example.respond_to?(:example_text)
+            match.example.example_text
+          elsif match.respond_to?(:text)
+            match.text
+          else
+            nil
+          end
+        end
+
+        # Wrapper for in-memory matches to provide a consistent interface
+        class InMemoryMatch
+          attr_reader :example, :distance
+
+          def initialize(example, distance)
+            @example = example
+            @distance = distance
+          end
+
+          def agent_name
+            example.agent_name
+          end
+
+          def example_text
+            example.example_text
+          end
+
+          def neighbor_distance
+            distance
+          end
+        end
+
+        # Wrapper for custom search results (from find_examples callable)
+        # Accepts hashes or objects with agent_name, example_text, distance/score
+        class CustomSearchMatch
+          attr_reader :result
+
+          def initialize(result)
+            @result = result
+          end
+
+          def agent_name
+            fetch(:agent_name) || fetch(:agent)
+          end
+
+          def example_text
+            fetch(:example_text) || fetch(:text)
+          end
+
+          def distance
+            # Support both distance (lower is better) and score (higher is better)
+            if (d = fetch(:distance))
+              d
+            elsif (s = fetch(:score))
+              1.0 - s  # Convert score to distance
+            else
+              0.0
+            end
+          end
+
+          def neighbor_distance
+            distance
+          end
+
+          private
+
+          def fetch(key)
+            if result.is_a?(Hash)
+              result[key] || result[key.to_s]
+            elsif result.respond_to?(key)
+              result.send(key)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubyllm/semantic_router/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module SemanticRouter
+    VERSION = "0.1.0"
+  end
+end

data/lib/rubyllm/semantic_router.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+begin
+  require "ruby_llm"
+rescue LoadError
+  # ruby_llm not available, will need to be provided externally
+end
+
+begin
+  require "neighbor"
+rescue LoadError
+  # neighbor not available, in-memory mode only
+end
+
+require_relative "semantic_router/version"
+require_relative "semantic_router/errors"
+require_relative "semantic_router/configuration"
+require_relative "semantic_router/routing_decision"
+require_relative "semantic_router/strategies/base"
+require_relative "semantic_router/strategies/semantic"
+require_relative "semantic_router/router"
+
+module RubyLLM
+  module SemanticRouter
+    class << self
+      attr_accessor :configuration
+
+      def new(**options)
+        Router.new(**options)
+      end
+
+      def configure
+        self.configuration ||= Configuration.new
+        yield(configuration) if block_given?
+        configuration
+      end
+
+      def reset_configuration!
+        self.configuration = Configuration.new
+      end
+    end
+  end
+end

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "3.3.10"

data/rubyllm-semantic_router.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "rubyllm/semantic_router/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "rubyllm-semantic_router"
+  spec.version       = RubyLLM::SemanticRouter::VERSION
+  spec.authors       = ["Chris Hasiński"]
+  spec.email         = ["krzysztof.hasinski@gmail.com"]
+
+  spec.summary       = "Semantic routing for RubyLLM multi-agent systems"
+  spec.description   = "Route messages to specialized RubyLLM chat agents based on semantic similarity using embeddings and kNN lookup"
+  spec.homepage      = "https://github.com/khasinski/ruby_llm-semantic_router"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "ruby_llm", "~> 1.0"
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  # spec.add_development_dependency "neighbor", ">= 0.3"  # Optional: for ActiveRecord tests
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: rubyllm-semantic_router
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Hasiński
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Route messages to specialized RubyLLM chat agents based on semantic similarity
+  using embeddings and kNN lookup
+email:
+- krzysztof.hasinski@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/rubyllm/semantic_router.rb
+- lib/rubyllm/semantic_router/configuration.rb
+- lib/rubyllm/semantic_router/errors.rb
+- lib/rubyllm/semantic_router/router.rb
+- lib/rubyllm/semantic_router/routing_decision.rb
+- lib/rubyllm/semantic_router/strategies/base.rb
+- lib/rubyllm/semantic_router/strategies/semantic.rb
+- lib/rubyllm/semantic_router/version.rb
+- mise.toml
+- rubyllm-semantic_router.gemspec
+homepage: https://github.com/khasinski/ruby_llm-semantic_router
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/khasinski/ruby_llm-semantic_router
+  source_code_uri: https://github.com/khasinski/ruby_llm-semantic_router
+  changelog_uri: https://github.com/khasinski/ruby_llm-semantic_router/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Semantic routing for RubyLLM multi-agent systems
+test_files: []