rubyllm-semantic_router 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5b01b92cdb4fa6f65278ec83440543f95642cf85026ea142cb2564c326c0512c
+  data.tar.gz: c1670b2f6379c451e711950f8d50982ec01671a1070ade3805f4fab5b557108a
+SHA512:
+  metadata.gz: f06a9a3b105253c45af254f3fdb98346ed28af13a73c36abd0f6eb57709de9b47cdec4a8dd24d214abac004da547124b4468e98b8e6b9d574c0e81583b978489
+  data.tar.gz: 9e092a880b2c627850e50ce2f376fba33bd88ae7de824ab1bf50e32d88f416f74128bd9920a456bbbf394f26f6eba0ac74d2bdd8a43019d7bdd7060e41ad43a4

data/.gitignore

@@ -0,0 +1,21 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+# Bundle vendor
+vendor/
+
+# IDE
+.idea/
+*.swp
+
+# RSpec
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,68 @@
+PATH
+  remote: .
+  specs:
+    rubyllm-semantic_router (0.1.0)
+      ruby_llm (~> 1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    base64 (0.3.0)
+    diff-lcs (1.6.2)
+    event_stream_parser (1.0.0)
+    faraday (2.14.0)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-multipart (1.2.0)
+      multipart-post (~> 2.0)
+    faraday-net_http (3.4.2)
+      net-http (~> 0.5)
+    faraday-retry (2.4.0)
+      faraday (~> 2.0)
+    json (2.18.0)
+    logger (1.7.0)
+    marcel (1.1.0)
+    multipart-post (2.4.1)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
+    rake (13.3.1)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    ruby_llm (1.9.1)
+      base64
+      event_stream_parser (~> 1)
+      faraday (>= 1.10.0)
+      faraday-multipart (>= 1)
+      faraday-net_http (>= 1)
+      faraday-retry (>= 1)
+      marcel (~> 1.0)
+      ruby_llm-schema (~> 0.2.1)
+      zeitwerk (~> 2)
+    ruby_llm-schema (0.2.5)
+    uri (1.1.1)
+    zeitwerk (2.7.4)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubyllm-semantic_router!
+
+BUNDLED WITH
+   2.5.22

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Chris Hasiński
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,262 @@
+# RubyLLM Semantic Router
+
+Route user messages to specialized LLM agents based on semantic similarity. Think of it as a fast, embedding-based classifier that decides which expert should handle each message.
+
+## The Problem
+
+You have multiple specialized chat agents:
+- A **product expert** that knows your catalog
+- An **account manager** that handles billing and settings
+- A **support agent** that troubleshoots issues
+
+How do you decide which one handles "I can't log in" vs "What's your return policy" vs "Show me laptops under $1000"?
+
+This gem provides fast, embedding-based routing - no LLM call needed for the routing decision itself.
+
+## How It Works
+
+```
+User: "What's your cheapest laptop?"
+            │
+            ▼
+   ┌─────────────────┐
+   │  Embed message  │  ← ~2ms, $0.00001
+   └────────┬────────┘
+            │
+            ▼
+   ┌─────────────────┐
+   │  Find similar   │  ← Compare to your examples
+   │  examples (kNN) │     "Show me computers" → product
+   └────────┬────────┘     "Reset password" → account
+            │
+            ▼
+   ┌─────────────────┐
+   │  Route to       │  ← Product agent handles it
+   │  Product Agent  │
+   └─────────────────┘
+```
+
+**Key insight**: The routing decision is just an embedding + kNN lookup. No LLM call needed. Fast and cheap.
+
+## Quick Start
+
+```ruby
+require 'rubyllm/semantic_router'
+
+# 1. Define your agents as regular RubyLLM chat objects
+product_chat = RubyLLM.chat(model: "gpt-4o-mini")
+                      .with_instructions("You're a product expert. Help users find products.")
+
+support_chat = RubyLLM.chat(model: "gpt-4o")
+                      .with_instructions("You're technical support. Troubleshoot issues.")
+                      .with_tools(DiagnosticTool, TicketCreator)
+
+# 2. Create router with your agents
+router = RubyLLM::SemanticRouter.new(
+  agents: {
+    product: product_chat,
+    support: support_chat
+  },
+  default_agent: :product  # Fallback when uncertain
+)
+
+# 3. Train with examples (the more, the better)
+router.import_examples([
+  { text: "Show me laptops", agent: :product },
+  { text: "Compare these two phones", agent: :product },
+  { text: "What's on sale?", agent: :product },
+  { text: "I can't log in", agent: :support },
+  { text: "App keeps crashing", agent: :support },
+  { text: "Error message when I checkout", agent: :support },
+])
+
+# 4. Chat! Routing happens automatically.
+router.ask("What gaming laptops do you have?")  # → product agent
+router.ask("My order is stuck")                  # → support agent
+```
+
+## When To Use This
+
+**Good fit:**
+- High-volume customer service with 3+ clearly separated domains
+- Different models per task (cheap for FAQ, expensive for reasoning)
+- Compliance requirements that need audit trails per agent
+- Tool sets that would confuse a single LLM if combined
+
+**Probably overkill:**
+- Small apps with <1000 daily users
+- Overlapping domains where context matters more than classification
+- No training examples available
+
+## API
+
+### Defining Agents
+
+Agents are just RubyLLM chat objects - use the same API you already know:
+
+```ruby
+my_agent = RubyLLM.chat(model: "claude-sonnet-4")
+                  .with_instructions("You're a specialist...")
+                  .with_tools(Tool1, Tool2)
+                  .with_temperature(0.7)
+```
+
+### Router Options
+
+```ruby
+router = RubyLLM::SemanticRouter.new(
+  agents: {
+    product: product_chat,
+    support: support_chat
+  },
+  default_agent: :product,
+
+  # When confidence is below threshold, what to do?
+  fallback: :default_agent,      # Use default (default)
+  # fallback: :keep_current,     # Stay with current agent
+  # fallback: :ask_clarification # Ask user to rephrase
+
+  similarity_threshold: 0.7,     # 0.0-1.0, higher = stricter
+  embedding_model: "text-embedding-3-small"
+)
+```
+
+### Training
+
+```ruby
+# One at a time
+router.add_example("Cancel my subscription", agent: :billing)
+
+# Batch import (faster - single embedding API call)
+router.import_examples([
+  { text: "...", agent: :billing },
+  { text: "...", agent: :support },
+])
+```
+
+### Debugging
+
+```ruby
+# Preview routing without sending message
+decision = router.match("test message")
+decision.agent       # => :product
+decision.confidence  # => 0.85
+
+# See all matches and scores
+router.debug_routing("test message")
+# => {
+#   message: "test message",
+#   threshold: 0.7,
+#   would_route_to: :product,
+#   top_matches: [
+#     { agent: :product, example: "show products", confidence: 0.85 },
+#     { agent: :support, example: "help me", confidence: 0.42 }
+#   ]
+# }
+```
+
+### Conversation Flow
+
+```ruby
+router.ask("Show me phones")        # Routes to :product
+router.current_agent                 # => :product
+
+router.ask("Actually, I need help") # Routes to :support
+router.current_agent                 # => :support
+
+# Full history is preserved across agent switches
+router.messages.size                 # => 4 (2 exchanges)
+```
+
+### ActiveRecord + pgvector
+
+Use the [neighbor](https://github.com/ankane/neighbor) gem for PostgreSQL:
+
+```ruby
+# Migration
+create_table :routing_examples do |t|
+  t.string :agent_name, null: false
+  t.text :example_text, null: false
+  t.vector :embedding, limit: 1536  # text-embedding-3-small dimensions
+end
+
+# Model
+class RoutingExample < ApplicationRecord
+  has_neighbors :embedding
+end
+
+# Usage
+router = RubyLLM::SemanticRouter.new(
+  agents: { product: product_chat, support: support_chat },
+  default_agent: :product
+)
+router.with_examples(RoutingExample.all)
+
+# Scoped for multi-tenant
+router.with_examples(RoutingExample.where(tenant_id: current_tenant.id))
+```
+
+### Custom Vector Search
+
+Bring your own vector database (Pinecone, Qdrant, OpenSearch, etc.):
+
+```ruby
+router = RubyLLM::SemanticRouter.new(
+  agents: { product: product_chat, support: support_chat },
+  default_agent: :product,
+  find_examples: ->(embedding, limit:) {
+    # Pinecone
+    Pinecone.index("examples").query(vector: embedding, top_k: limit).matches.map do |m|
+      { agent_name: m.metadata[:agent], text: m.metadata[:text], score: m.score }
+    end
+  }
+)
+
+# Or with OpenSearch/Searchkick
+router = RubyLLM::SemanticRouter.new(
+  agents: { ... },
+  default_agent: :product,
+  find_examples: ->(embedding, limit:) {
+    RoutingExample.search("*",
+      knn: { field: :embedding, vector: embedding, k: limit }
+    ).map { |r| { agent_name: r.agent_name, text: r.text, distance: r.distance } }
+  }
+)
+```
+
+Return an array of hashes/objects with:
+- `agent_name` (or `agent`) - which agent this example routes to
+- `text` or `example_text` - the example text (optional, for debugging)
+- `distance` (lower is better) or `score` (higher is better)
+
+## How Agents Share Context
+
+When the router switches agents, the new agent sees the **full conversation history** but with its own system prompt. This means:
+
+1. Agent A responds with context
+2. User asks something in Agent B's domain
+3. Router switches to Agent B
+4. Agent B sees the full chat, responds with its own expertise
+
+The conversation flows naturally. Users don't notice the switch.
+
+## Caveats
+
+1. **You need training examples.** At least 5-10 per agent, more is better.
+
+2. **Embeddings aren't magic.** "I want to return this" and "What's your return policy" are different intents. Train for both.
+
+3. **Threshold tuning matters.** Start with 0.7, use `debug_routing` to see scores, adjust.
+
+4. **Tool cycles are atomic.** If Agent A calls a tool, it keeps control until done. No mid-tool handoffs.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rubyllm/semantic_router"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/rubyllm/semantic_router/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module SemanticRouter
+    # Global configuration for the semantic router
+    class Configuration
+      # Default embedding model to use when not specified per-router
+      attr_accessor :default_embedding_model
+
+      # Default similarity threshold (0.0 - 1.0)
+      attr_accessor :default_similarity_threshold
+
+      # Default number of neighbors to consider for routing
+      attr_accessor :default_k_neighbors
+
+      # Default fallback behavior (:default_agent, :keep_current, :ask_clarification)
+      attr_accessor :default_fallback
+
+      def initialize
+        @default_embedding_model = "text-embedding-3-small"
+        @default_similarity_threshold = 0.7
+        @default_k_neighbors = 3
+        @default_fallback = :default_agent
+      end
+    end
+  end
+end

data/lib/rubyllm/semantic_router/errors.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module SemanticRouter
+    # Base error class for all semantic router errors
+    class Error < StandardError; end
+
+    # Raised when an agent name is not found in the router
+    class AgentNotFoundError < Error
+      def initialize(agent_name, available_agents)
+        super("Agent '#{agent_name}' not found. Available agents: #{available_agents.join(', ')}")
+      end
+    end
+
+    # Raised when no default agent is configured
+    class NoDefaultAgentError < Error
+      def initialize
+        super("No default agent configured. Set default_agent when creating the router.")
+      end
+    end
+
+    # Raised when no agents are configured
+    class NoAgentsError < Error
+      def initialize
+        super("No agents configured. Add at least one agent to the router.")
+      end
+    end
+
+    # Raised when routing examples are required but none exist
+    class NoRoutingExamplesError < Error
+      def initialize
+        super("No routing examples found. Add examples using router.add_example or configure a fallback.")
+      end
+    end
+
+    # Raised when embedding generation fails
+    class EmbeddingError < Error
+      def initialize(original_error)
+        super("Failed to generate embedding: #{original_error.message}")
+      end
+    end
+
+    # Raised when an invalid fallback behavior is specified
+    class InvalidFallbackError < Error
+      VALID_BEHAVIORS = %i[default_agent keep_current ask_clarification].freeze
+
+      def initialize(behavior)
+        super("Invalid fallback behavior '#{behavior}'. Valid options: #{VALID_BEHAVIORS.join(', ')}")
+      end
+    end
+
+    # Raised when agent definition is incomplete
+    class InvalidAgentError < Error
+      def initialize(message)
+        super("Invalid agent definition: #{message}")
+      end
+    end
+  end
+end