ruby_llm_mesh 0.1.0

data/lib/ruby_llm_mesh/providers/base.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module RubyLlmMesh
+  module Providers
+    class Base
+      attr_reader :config
+
+      def initialize(config = RubyLlmMesh.configuration)
+        @config = config
+      end
+
+      def name
+        raise NotImplementedError
+      end
+
+      def complete(prompt:, system: nil, model: nil, **options)
+        raise NotImplementedError
+      end
+
+      protected
+
+      def http_post(url, headers:, body:, timeout: nil)
+        uri = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = timeout || config.timeout
+        http.read_timeout = timeout || config.timeout
+
+        request = Net::HTTP::Post.new(uri)
+        headers.each { |k, v| request[k] = v }
+        request.body = JSON.generate(body)
+
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        response = http.request(request)
+        latency_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+
+        [response, latency_ms]
+      rescue Net::OpenTimeout, Net::ReadTimeout, Timeout::Error => e
+        raise TimeoutError.new(e.message, provider: name)
+      rescue SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ETIMEDOUT => e
+        raise ProviderError.new(e.message, provider: name)
+      end
+
+      def parse_json(response)
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        { "raw" => response.body }
+      end
+
+      def raise_for_status!(response)
+        code = response.code.to_i
+        return if code.between?(200, 299)
+
+        body = response.body
+        message = "#{name} HTTP #{code}: #{body.to_s[0, 300]}"
+
+        case code
+        when 401, 403
+          raise AuthenticationError.new(message, provider: name, status: code, body: body)
+        when 429
+          raise RateLimitError.new(message, provider: name, status: code, body: body)
+        else
+          raise ProviderError.new(message, provider: name, status: code, body: body)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm_mesh/providers/local_node.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module RubyLlmMesh
+  module Providers
+    # OpenAI-compatible local runtime (Ollama, LM Studio, vLLM, llama.cpp server, etc.)
+    class LocalNode < Base
+      def name
+        :local_node
+      end
+
+      def complete(prompt:, system: nil, model: nil, **options)
+        model ||= config.local_node_model
+        messages = []
+        messages << { role: "system", content: system } if system
+        messages << { role: "user", content: prompt }
+
+        body = {
+          model: model,
+          messages: messages,
+          stream: false,
+          temperature: options.fetch(:temperature, 0.7)
+        }
+        body[:options] = { num_predict: options[:max_tokens] } if options[:max_tokens]
+
+        response, latency_ms = http_post(
+          "#{config.local_node_base_url.chomp('/')}/v1/chat/completions",
+          headers: { "Content-Type" => "application/json" },
+          body: body
+        )
+
+        # Fallback to Ollama native chat API if OpenAI-compat endpoint is missing
+        if response.code.to_i == 404
+          response, latency_ms = http_post(
+            "#{config.local_node_base_url.chomp('/')}/api/chat",
+            headers: { "Content-Type" => "application/json" },
+            body: { model: model, messages: messages, stream: false }
+          )
+          raise_for_status!(response)
+          data = parse_json(response)
+          content = data.dig("message", "content").to_s
+          return Response.new(
+            content: content,
+            provider: name,
+            model: model,
+            usage: {},
+            raw: data,
+            latency_ms: latency_ms
+          )
+        end
+
+        raise_for_status!(response)
+        data = parse_json(response)
+        content = data.dig("choices", 0, "message", "content").to_s
+
+        Response.new(
+          content: content,
+          provider: name,
+          model: data["model"] || model,
+          usage: data["usage"] || {},
+          raw: data,
+          latency_ms: latency_ms
+        )
+      end
+    end
+  end
+end

data/lib/ruby_llm_mesh/providers/openai.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RubyLlmMesh
+  module Providers
+    class Openai < Base
+      def name
+        :openai
+      end
+
+      def complete(prompt:, system: nil, model: nil, **options)
+        api_key = config.openai_api_key
+        raise AuthenticationError.new("OPENAI_API_KEY is not configured", provider: name) if api_key.to_s.empty?
+
+        model ||= config.openai_model
+        messages = []
+        messages << { role: "system", content: system } if system
+        messages << { role: "user", content: prompt }
+
+        body = {
+          model: model,
+          messages: messages,
+          temperature: options.fetch(:temperature, 0.7)
+        }
+        body[:max_tokens] = options[:max_tokens] if options[:max_tokens]
+        body[:tools] = options[:tools] if options[:tools]
+
+        response, latency_ms = http_post(
+          "#{config.openai_base_url.chomp('/')}/chat/completions",
+          headers: {
+            "Authorization" => "Bearer #{api_key}",
+            "Content-Type" => "application/json"
+          },
+          body: body
+        )
+
+        raise_for_status!(response)
+        data = parse_json(response)
+        choice = data.dig("choices", 0, "message", "content").to_s
+
+        Response.new(
+          content: choice,
+          provider: name,
+          model: data["model"] || model,
+          usage: data["usage"] || {},
+          raw: data,
+          latency_ms: latency_ms
+        )
+      end
+    end
+  end
+end

data/lib/ruby_llm_mesh/rag/chunker.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RubyLlmMesh
+  module Rag
+    # Lightweight text chunker with optional overlap for RAG pipelines.
+    class Chunker
+      DEFAULT_SIZE = 800
+      DEFAULT_OVERLAP = 100
+
+      def initialize(size: DEFAULT_SIZE, overlap: DEFAULT_OVERLAP, separator: /\n{2,}|\n|\s+/)
+        raise ArgumentError, "overlap must be less than size" if overlap >= size
+
+        @size = size
+        @overlap = overlap
+        @separator = separator
+      end
+
+      def chunk(text)
+        return [] if text.nil? || text.strip.empty?
+
+        paragraphs = text.to_s.split(@separator).map(&:strip).reject(&:empty?)
+        chunks = []
+        buffer = +""
+
+        paragraphs.each do |piece|
+          candidate = buffer.empty? ? piece : "#{buffer} #{piece}"
+          if candidate.length <= @size
+            buffer = candidate
+          else
+            chunks << buffer unless buffer.empty?
+            buffer = overlap_tail(buffer)
+            buffer = buffer.empty? ? piece : "#{buffer} #{piece}"
+            while buffer.length > @size
+              chunks << buffer[0, @size]
+              buffer = overlap_tail(buffer[0, @size]) + buffer[@size..]
+            end
+          end
+        end
+
+        chunks << buffer unless buffer.empty?
+        chunks
+      end
+
+      private
+
+      def overlap_tail(text)
+        return "" if @overlap.zero? || text.nil? || text.empty?
+
+        text[[text.length - @overlap, 0].max..]
+      end
+    end
+  end
+end

data/lib/ruby_llm_mesh/rag/embeddings.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RubyLlmMesh
+  module Rag
+    # Zero-dependency bag-of-words style embeddings for local prototyping.
+    # Swap for a real embedding provider in production.
+    class Embeddings
+      def initialize(dimensions: 256)
+        @dimensions = dimensions
+      end
+
+      def embed(text)
+        vector = Array.new(@dimensions, 0.0)
+        tokenize(text).each do |token|
+          index = stable_hash(token) % @dimensions
+          vector[index] += 1.0
+        end
+        normalize!(vector)
+        vector
+      end
+
+      def embed_many(texts)
+        Array(texts).map { |t| embed(t) }
+      end
+
+      def cosine_similarity(a, b)
+        raise ArgumentError, "vectors must match length" unless a.length == b.length
+
+        dot = 0.0
+        a.each_index { |i| dot += a[i] * b[i] }
+        dot
+      end
+
+      def top_k(query, documents, k: 3)
+        query_vec = embed(query)
+        scored = documents.map do |doc|
+          text = doc.is_a?(Hash) ? doc[:text] || doc["text"] : doc.to_s
+          score = cosine_similarity(query_vec, embed(text))
+          { document: doc, score: score }
+        end
+        scored.sort_by { |row| -row[:score] }.first(k)
+      end
+
+      private
+
+      def tokenize(text)
+        text.to_s.downcase.scan(/[a-z0-9_]+/)
+      end
+
+      def stable_hash(token)
+        # FNV-1a 32-bit
+        hash = 2166136261
+        token.each_byte do |byte|
+          hash ^= byte
+          hash = (hash * 16777619) & 0xffffffff
+        end
+        hash
+      end
+
+      def normalize!(vector)
+        norm = Math.sqrt(vector.sum { |v| v * v })
+        return vector if norm.zero?
+
+        vector.map! { |v| v / norm }
+      end
+    end
+  end
+end

data/lib/ruby_llm_mesh/rag/tools.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RubyLlmMesh
+  module Rag
+    # Helpers for structuring tool / function-calling schemas across providers.
+    module Tools
+      module_function
+
+      def define(name:, description:, parameters: {}, required: [])
+        {
+          name: name.to_s,
+          description: description.to_s,
+          parameters: {
+            type: "object",
+            properties: parameters,
+            required: Array(required).map(&:to_s)
+          }
+        }
+      end
+
+      def for_openai(tools)
+        Array(tools).map do |tool|
+          {
+            type: "function",
+            function: {
+              name: tool[:name] || tool["name"],
+              description: tool[:description] || tool["description"],
+              parameters: tool[:parameters] || tool["parameters"]
+            }
+          }
+        end
+      end
+
+      def for_anthropic(tools)
+        Array(tools).map do |tool|
+          {
+            name: tool[:name] || tool["name"],
+            description: tool[:description] || tool["description"],
+            input_schema: tool[:parameters] || tool["parameters"]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm_mesh/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RubyLlmMesh
+  class Railtie < ::Rails::Railtie
+    initializer "ruby_llm_mesh.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        require_relative "active_record/acts_as_ai_agent"
+        extend RubyLlmMesh::ActiveRecord::ActsAsAiAgent
+      end
+    end
+  end
+end

data/lib/ruby_llm_mesh/response.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RubyLlmMesh
+  class Response
+    attr_reader :content, :provider, :model, :usage, :raw, :latency_ms, :fallback_used
+
+    def initialize(content:, provider:, model: nil, usage: {}, raw: nil, latency_ms: nil, fallback_used: false)
+      @content = content
+      @provider = provider
+      @model = model
+      @usage = usage || {}
+      @raw = raw
+      @latency_ms = latency_ms
+      @fallback_used = fallback_used
+    end
+
+    def text
+      content
+    end
+
+    def to_s
+      content.to_s
+    end
+
+    def to_h
+      {
+        content: content,
+        provider: provider,
+        model: model,
+        usage: usage,
+        latency_ms: latency_ms,
+        fallback_used: fallback_used
+      }
+    end
+  end
+end

data/lib/ruby_llm_mesh/router.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RubyLlmMesh
+  class Router
+    PROVIDER_MAP = {
+      openai: Providers::Openai,
+      anthropic: Providers::Anthropic,
+      local_node: Providers::LocalNode
+    }.freeze
+
+    class << self
+      def circuit_breaker
+        @circuit_breaker ||= CircuitBreaker.new(
+          failure_threshold: RubyLlmMesh.configuration.circuit_failure_threshold,
+          reset_timeout: RubyLlmMesh.configuration.circuit_reset_timeout
+        )
+      end
+
+      def reset_circuit_breaker!
+        @circuit_breaker = nil
+      end
+    end
+
+    def initialize(config: RubyLlmMesh.configuration, circuit_breaker: self.class.circuit_breaker)
+      @config = config
+      @circuit_breaker = circuit_breaker
+    end
+
+    def complete(prompt:, providers: nil, fallback: nil, system: nil, model: nil, **options)
+      raise ArgumentError, "prompt is required" if prompt.nil? || prompt.to_s.strip.empty?
+
+      provider_list = Array(providers || @config.default_providers).map(&:to_sym)
+      raise ArgumentError, "providers list cannot be empty" if provider_list.empty?
+
+      use_fallback = fallback.nil? ? @config.fallback : fallback
+      errors = {}
+      attempted = 0
+
+      provider_list.each_with_index do |provider_name, index|
+        unless PROVIDER_MAP.key?(provider_name)
+          errors[provider_name] = ProviderError.new("Unknown provider: #{provider_name}", provider: provider_name)
+          next
+        end
+
+        unless @circuit_breaker.allow?(provider_name)
+          errors[provider_name] = CircuitOpenError.new(
+            "Circuit open for #{provider_name}",
+            provider: provider_name
+          )
+          log(:warn, "Skipping #{provider_name} — circuit open")
+          next
+        end
+
+        begin
+          attempted += 1
+          log(:info, "Routing to #{provider_name}")
+          provider = PROVIDER_MAP[provider_name].new(@config)
+          response = provider.complete(prompt: prompt, system: system, model: model, **options)
+          @circuit_breaker.record_success(provider_name)
+          return Response.new(
+            content: response.content,
+            provider: response.provider,
+            model: response.model,
+            usage: response.usage,
+            raw: response.raw,
+            latency_ms: response.latency_ms,
+            fallback_used: index.positive?
+          )
+        rescue ProviderError => e
+          @circuit_breaker.record_failure(provider_name)
+          errors[provider_name] = e
+          log(:error, "#{provider_name} failed: #{e.message}")
+          break unless use_fallback
+        end
+      end
+
+      raise AllProvidersFailedError, errors
+    end
+
+    private
+
+    def log(level, message)
+      logger = @config.logger
+      return unless logger
+
+      if logger.respond_to?(level)
+        logger.public_send(level, "[RubyLlmMesh] #{message}")
+      elsif logger.respond_to?(:call)
+        logger.call(level, message)
+      end
+    end
+  end
+end

data/lib/ruby_llm_mesh/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RubyLlmMesh
+  VERSION = "0.1.0"
+end

data/lib/ruby_llm_mesh.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "ruby_llm_mesh/version"
+require_relative "ruby_llm_mesh/errors"
+require_relative "ruby_llm_mesh/configuration"
+require_relative "ruby_llm_mesh/response"
+require_relative "ruby_llm_mesh/circuit_breaker"
+require_relative "ruby_llm_mesh/providers/base"
+require_relative "ruby_llm_mesh/providers/openai"
+require_relative "ruby_llm_mesh/providers/anthropic"
+require_relative "ruby_llm_mesh/providers/local_node"
+require_relative "ruby_llm_mesh/router"
+require_relative "ruby_llm_mesh/rag/chunker"
+require_relative "ruby_llm_mesh/rag/embeddings"
+require_relative "ruby_llm_mesh/rag/tools"
+
+# Optional Rails integration — only load railtie when Rails is already present
+if defined?(Rails::Railtie)
+  require_relative "ruby_llm_mesh/railtie"
+end
+
+module RubyLlmMesh
+  class << self
+    def complete(prompt:, providers: nil, fallback: nil, **options)
+      Router.new.complete(prompt: prompt, providers: providers, fallback: fallback, **options)
+    end
+
+    def chat(**)
+      complete(**)
+    end
+  end
+end
+
+# Friendly alias matching the public DSL from the project overview
+module AiAgentRouter
+  def self.complete(...)
+    RubyLlmMesh.complete(...)
+  end
+
+  def self.configure(&)
+    RubyLlmMesh.configure(&)
+  end
+
+  def self.configuration
+    RubyLlmMesh.configuration
+  end
+end

data/ruby_llm_mesh.gemspec

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "lib/ruby_llm_mesh/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "ruby_llm_mesh"
+  spec.version = RubyLlmMesh::VERSION
+  spec.authors = ["theworker02"]
+  spec.email = ["theworker02@users.noreply.github.com"]
+
+  spec.summary = "Unified multi-provider AI routing with circuit-breaking and local fallback for Ruby & Rails"
+  spec.description = <<~DESC
+    ruby_llm_mesh (AiAgentRouter) is a drop-in Ruby gem that routes AI prompts across
+    OpenAI, Anthropic, and local node runtimes with automatic circuit-breaking,
+    fallback ladders, lightweight RAG helpers, and optional ActiveRecord hooks.
+  DESC
+  spec.homepage = "https://github.com/theworker02/ruby_llm_mesh"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/theworker02/ruby_llm_mesh"
+  spec.metadata["changelog_uri"] = "https://github.com/theworker02/ruby_llm_mesh/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://theworker02.github.io/ruby_llm_mesh/"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/theworker02/ruby_llm_mesh/issues"
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.start_with?(*%w[test/ spec/ features/ .git .github docs/]) ||
+        f.end_with?(".gem")
+    end
+  end
+  # Ensure packaging works before the first commit
+  if spec.files.empty?
+    spec.files = Dir[
+      "lib/**/*",
+      "sig/**/*",
+      "exe/**/*",
+      "assets/**/*",
+      "LICENSE*",
+      "README*",
+      "CHANGELOG*",
+      "CODE_OF_CONDUCT*",
+      "*.gemspec"
+    ]
+  end
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "minitest", "~> 5.25"
+  spec.add_development_dependency "rake", "~> 13.2"
+  spec.add_development_dependency "webmock", "~> 3.24"
+end

data/sig/ruby_llm_mesh.rbs

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RubyLlmMesh
+  VERSION: String
+
+  class Configuration
+    attr_accessor default_providers: Array[Symbol]
+    attr_accessor fallback: bool
+    attr_accessor timeout: Integer
+    attr_accessor max_retries: Integer
+    attr_accessor openai_api_key: String?
+    attr_accessor openai_base_url: String
+    attr_accessor openai_model: String
+    attr_accessor anthropic_api_key: String?
+    attr_accessor anthropic_base_url: String
+    attr_accessor anthropic_model: String
+    attr_accessor local_node_base_url: String
+    attr_accessor local_node_model: String
+    attr_accessor circuit_failure_threshold: Integer
+    attr_accessor circuit_reset_timeout: Integer
+    attr_accessor logger: untyped
+  end
+
+  def self.configuration: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.reset_configuration!: () -> void
+  def self.complete: (
+    prompt: String,
+    ?providers: Array[Symbol]?,
+    ?fallback: bool?,
+    **untyped
+  ) -> Response
+  def self.chat: (**untyped) -> Response
+
+  class Response
+    attr_reader content: String
+    attr_reader provider: Symbol
+    attr_reader model: String?
+    attr_reader usage: Hash[untyped, untyped]
+    attr_reader raw: untyped
+    attr_reader latency_ms: Integer?
+    attr_reader fallback_used: bool
+
+    def initialize: (
+      content: String,
+      provider: Symbol,
+      ?model: String?,
+      ?usage: Hash[untyped, untyped],
+      ?raw: untyped,
+      ?latency_ms: Integer?,
+      ?fallback_used: bool
+    ) -> void
+    def text: () -> String
+    def to_s: () -> String
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class Router
+    def complete: (
+      prompt: String,
+      ?providers: Array[Symbol]?,
+      ?fallback: bool?,
+      ?system: String?,
+      ?model: String?,
+      **untyped
+    ) -> Response
+  end
+
+  class CircuitBreaker
+    def allow?: (Symbol) -> bool
+    def record_success: (Symbol) -> void
+    def record_failure: (Symbol) -> void
+    def state_for: (Symbol) -> Symbol
+    def reset!: (?Symbol?) -> void
+  end
+end
+
+module AiAgentRouter
+  def self.complete: (**untyped) -> RubyLlmMesh::Response
+  def self.configure: () { (RubyLlmMesh::Configuration) -> void } -> void
+  def self.configuration: () -> RubyLlmMesh::Configuration
+end