ruby_llm_mesh 0.1.0 → 2.2.0

data/lib/ruby_llm_mesh/configuration.rb

@@ -7,13 +7,23 @@ module RubyLlmMesh
                   :anthropic_api_key, :anthropic_base_url, :anthropic_model,
                   :local_node_base_url, :local_node_model,
                   :circuit_failure_threshold, :circuit_reset_timeout,
-                  :logger
+                  :logger,
+                  :mesh_port, :fallback_providers, :auto_boot_mesh,
+                  :semantic_cache_enabled, :semantic_cache_threshold,
+                  :semantic_cache_ttl, :semantic_cache_dimensions,
+                  :redis_url, :semantic_cache_backend,
+                  :peer_discovery_enabled, :peer_urls,
+                  :peer_health_interval, :peer_health_timeout,
+                  :peer_health_path,
+                  :budget_enabled, :budget_max_tokens, :budget_max_usd, :budget_prices,
+                  :retry_backoff
 
     def initialize
       @default_providers = %i[openai anthropic local_node]
       @fallback = true
       @timeout = 30
       @max_retries = 1
+      @retry_backoff = Float(ENV.fetch("RUBY_LLM_MESH_RETRY_BACKOFF", "0.1"))
 
       @openai_api_key = ENV.fetch("OPENAI_API_KEY", nil)
       @openai_base_url = ENV.fetch("OPENAI_BASE_URL", "https://api.openai.com/v1")
@@ -29,7 +39,48 @@ module RubyLlmMesh
       @circuit_failure_threshold = 3
       @circuit_reset_timeout = 60
       @logger = nil
+
+      # Sovereign mesh / native core
+      @mesh_port = Integer(ENV.fetch("RUBY_LLM_MESH_PORT", "4233"))
+      @auto_boot_mesh = ENV.fetch("RUBY_LLM_MESH_AUTO_BOOT", "true") == "true"
+      @fallback_providers = %i[openai anthropic local_node]
+
+      # Semantic cache — opt-in
+      @semantic_cache_enabled = ENV.fetch("RUBY_LLM_MESH_SEMANTIC_CACHE", "false") == "true"
+      @semantic_cache_threshold = Float(ENV.fetch("RUBY_LLM_MESH_CACHE_THRESHOLD", "0.92"))
+      @semantic_cache_ttl = Integer(ENV.fetch("RUBY_LLM_MESH_CACHE_TTL", "3600"))
+      @semantic_cache_dimensions = 256
+      @redis_url = ENV.fetch("REDIS_URL", nil)
+      @semantic_cache_backend = nil
+
+      # Local peer mesh discovery / health
+      @peer_discovery_enabled = ENV.fetch("RUBY_LLM_MESH_PEER_DISCOVERY", "false") == "true"
+      peer_urls_env = ENV.fetch("RUBY_LLM_MESH_PEER_URLS", "")
+      @peer_urls = peer_urls_env.empty? ? [] : peer_urls_env.split(",").map(&:strip).reject(&:empty?)
+      @peer_health_interval = Integer(ENV.fetch("RUBY_LLM_MESH_PEER_HEALTH_INTERVAL", "30"))
+      @peer_health_timeout = Integer(ENV.fetch("RUBY_LLM_MESH_PEER_HEALTH_TIMEOUT", "2"))
+      @peer_health_path = ENV.fetch("RUBY_LLM_MESH_PEER_HEALTH_PATH", "/api/tags")
+
+      # Token/cost budget guard — opt-in
+      @budget_enabled = ENV.fetch("RUBY_LLM_MESH_BUDGET_ENABLED", "false") == "true"
+      @budget_max_tokens = integer_env("RUBY_LLM_MESH_BUDGET_MAX_TOKENS")
+      @budget_max_usd = float_env("RUBY_LLM_MESH_BUDGET_MAX_USD")
+      @budget_prices = {}
+    end
+
+    private
+
+    def integer_env(key)
+      value = ENV.fetch(key, nil)
+      value.nil? || value.empty? ? nil : Integer(value)
     end
+
+    def float_env(key)
+      value = ENV.fetch(key, nil)
+      value.nil? || value.empty? ? nil : Float(value)
+    end
+
+    public
   end
 
   class << self
@@ -42,7 +93,12 @@ module RubyLlmMesh
     end
 
     def reset_configuration!
+      NativeCore.reset! if defined?(NativeCore)
       @configuration = Configuration.new
+      Cache::SemanticCache.reset! if defined?(Cache::SemanticCache)
+      Mesh::PeerRegistry.reset! if defined?(Mesh::PeerRegistry)
+      Mesh::HealthMonitor.reset! if defined?(Mesh::HealthMonitor)
+      Budget.reset! if defined?(Budget)
     end
   end
 end

data/lib/ruby_llm_mesh/errors.rb

@@ -21,6 +21,17 @@ module RubyLlmMesh
   class AuthenticationError < ProviderError; end
   class CircuitOpenError < ProviderError; end
 
+  class BudgetExceededError < Error
+    attr_reader :dimension, :consumed, :limit
+
+    def initialize(message, dimension: nil, consumed: nil, limit: nil)
+      @dimension = dimension
+      @consumed = consumed
+      @limit = limit
+      super(message)
+    end
+  end
+
   class AllProvidersFailedError < Error
     attr_reader :errors
 

data/lib/ruby_llm_mesh/mesh/health_monitor.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module RubyLlmMesh
+  module Mesh
+    # Pings local LLM peers and marks them healthy/unhealthy for routing.
+    class HealthMonitor
+      class << self
+        def instance(config: RubyLlmMesh.configuration, registry: nil)
+          @instance ||= new(config: config, registry: registry)
+        end
+
+        def reset!
+          @instance&.stop!
+          @instance = nil
+        end
+      end
+
+      def initialize(config: RubyLlmMesh.configuration, registry: nil)
+        @config = config
+        @registry = registry || PeerRegistry.instance(config: config)
+        @mutex = Mutex.new
+        @thread = nil
+        @stopped = true
+      end
+
+      def check_all!
+        @registry.all_urls.each { |url| check!(url) }
+      end
+
+      def check!(url)
+        healthy = healthy?(url)
+        if healthy
+          @registry.mark_healthy(url)
+        else
+          @registry.mark_unhealthy(url, error: "health check failed")
+        end
+        healthy
+      rescue StandardError => e
+        @registry.mark_unhealthy(url, error: e.message)
+        false
+      end
+
+      def healthy?(url)
+        base = url.to_s.chomp("/")
+        paths = [
+          @config.peer_health_path,
+          "/v1/models",
+          "/api/tags"
+        ].uniq
+
+        paths.any? { |path| ping("#{base}#{path}") }
+      end
+
+      def start!
+        return unless @config.peer_discovery_enabled
+        return if @thread&.alive?
+
+        @stopped = false
+        interval = [@config.peer_health_interval, 1].max
+        @thread = Thread.new do
+          until @stopped
+            begin
+              check_all!
+            rescue StandardError
+              # keep looping
+            end
+            sleep interval
+          end
+        end
+        @thread.abort_on_exception = false
+        @thread
+      end
+
+      def stop!
+        @stopped = true
+        @thread&.kill
+        @thread = nil
+      end
+
+      def running?
+        !@stopped && @thread&.alive?
+      end
+
+      private
+
+      def ping(url)
+        uri = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @config.peer_health_timeout
+        http.read_timeout = @config.peer_health_timeout
+        request = Net::HTTP::Get.new(uri)
+        response = http.request(request)
+        response.code.to_i.between?(200, 299)
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/ruby_llm_mesh/mesh/peer_registry.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module RubyLlmMesh
+  module Mesh
+    # Registry of local LLM peer base URLs (Ollama, LM Studio, etc.).
+    class PeerRegistry
+      Peer = Struct.new(:url, :healthy, :last_checked_at, :last_error, keyword_init: true)
+
+      class << self
+        def instance(config: RubyLlmMesh.configuration)
+          @instance ||= new(config: config)
+        end
+
+        def reset!
+          @instance = nil
+        end
+      end
+
+      def initialize(config: RubyLlmMesh.configuration)
+        @config = config
+        @mutex = Mutex.new
+        @peers = {}
+        seed_from_config!
+      end
+
+      def enabled?
+        !!@config.peer_discovery_enabled || !peer_urls.empty?
+      end
+
+      def register(url)
+        normalized = normalize_url(url)
+        return if normalized.empty?
+
+        @mutex.synchronize do
+          @peers[normalized] ||= Peer.new(url: normalized, healthy: true, last_checked_at: nil, last_error: nil)
+        end
+      end
+
+      def unregister(url)
+        @mutex.synchronize { @peers.delete(normalize_url(url)) }
+      end
+
+      def mark_healthy(url)
+        update_peer(url) do |peer|
+          peer.healthy = true
+          peer.last_error = nil
+          peer.last_checked_at = Time.now
+        end
+      end
+
+      def mark_unhealthy(url, error: nil)
+        update_peer(url) do |peer|
+          peer.healthy = false
+          peer.last_error = error&.to_s
+          peer.last_checked_at = Time.now
+        end
+      end
+
+      def healthy_urls
+        seed_from_config!
+        @mutex.synchronize do
+          # Only return peers currently marked healthy. When every peer is
+          # unhealthy, return [] so callers (e.g. LocalNode) can apply their
+          # own last-resort fallback — never reintroduce unhealthy URLs.
+          @peers.values.select(&:healthy).map(&:url)
+        end
+      end
+
+      def all_urls
+        seed_from_config!
+        @mutex.synchronize do
+          keys = @peers.keys.dup
+          keys.empty? ? peer_urls : keys
+        end
+      end
+
+      def peer_urls
+        urls = Array(@config.peer_urls).map { |u| normalize_url(u) }.reject(&:empty?)
+        primary = normalize_url(@config.local_node_base_url)
+        ([primary] + urls).uniq
+      end
+
+      def each_peer
+        seed_from_config!
+        @mutex.synchronize { @peers.values.map(&:dup) }.each { |peer| yield peer }
+      end
+
+      def clear!
+        @mutex.synchronize { @peers.clear }
+      end
+
+      private
+
+      def seed_from_config!
+        peer_urls.each { |url| register(url) }
+      end
+
+      def update_peer(url)
+        normalized = normalize_url(url)
+        @mutex.synchronize do
+          peer = @peers[normalized] || Peer.new(url: normalized, healthy: true)
+          yield peer
+          @peers[normalized] = peer
+        end
+      end
+
+      def normalize_url(url)
+        url.to_s.strip.chomp("/")
+      end
+    end
+  end
+end

data/lib/ruby_llm_mesh/native_core.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RubyLlmMesh
+  # Soft-loaded FFI bridge to the `chimera_core` native library.
+  # When the shared library is missing or `ffi` is unavailable, methods
+  # degrade to pure-Ruby fallbacks instead of crashing on require.
+  module NativeCore
+    class << self
+      def available?
+        !!@native_loaded
+      end
+
+      def start_node(port = RubyLlmMesh.configuration.mesh_port)
+        ensure_boot_attempted!
+        if available?
+          !!@lib.start_node(Integer(port))
+        else
+          Fallback.start_node(port)
+        end
+      end
+
+      def stop_node
+        ensure_boot_attempted!
+        if available?
+          !!@lib.stop_node
+        else
+          Fallback.stop_node
+        end
+      end
+
+      def node_alive?
+        ensure_boot_attempted!
+        if available?
+          !!@lib.node_alive
+        else
+          Fallback.node_alive?
+        end
+      end
+
+      def execute_wasm_payload(intent)
+        ensure_boot_attempted!
+        intent = intent.to_s
+        raw = if available?
+                @lib.execute_wasm_payload_string(intent)
+              else
+                Fallback.execute_wasm_payload(intent)
+              end
+        parse_payload(raw)
+      end
+
+      def version
+        ensure_boot_attempted!
+        return @lib.chimera_core_version_string if available?
+
+        "fallback-#{RubyLlmMesh::VERSION}"
+      end
+
+      def reset!
+        stop_node if node_alive?
+        @boot_attempted = false
+        @native_loaded = false
+        @lib = nil
+        Fallback.reset!
+      end
+
+      private
+
+      def ensure_boot_attempted!
+        return if @boot_attempted
+
+        @boot_attempted = true
+        @native_loaded = try_load_native!
+      end
+
+      def try_load_native!
+        begin
+          require "ffi"
+        rescue LoadError
+          return false
+        end
+
+        path = shared_library_path
+        return false unless path && File.exist?(path)
+
+        lib = Module.new
+        lib.extend(FFI::Library)
+        lib.ffi_lib path
+        lib.attach_function :start_node, [:uint16], :bool
+        lib.attach_function :stop_node, [], :bool
+        lib.attach_function :node_alive, [], :bool
+        lib.attach_function :execute_wasm_payload, [:string], :pointer
+        lib.attach_function :chimera_free_string, [:pointer], :void
+        lib.attach_function :chimera_core_version, [], :pointer
+
+        def lib.execute_wasm_payload_string(intent)
+          ptr = execute_wasm_payload(intent)
+          return "{\"ok\":false,\"error\":\"null pointer\"}" if ptr.null?
+
+          str = ptr.read_string
+          chimera_free_string(ptr)
+          str
+        end
+
+        def lib.chimera_core_version_string
+          ptr = chimera_core_version
+          return "unknown" if ptr.null?
+
+          str = ptr.read_string
+          chimera_free_string(ptr)
+          str
+        end
+
+        @lib = lib
+        true
+      rescue StandardError
+        false
+      end
+
+      def shared_library_path
+        root = File.expand_path("../..", __dir__)
+        crate = File.join(root, "ext", "chimera_core")
+        candidates = [
+          ENV["CHIMERA_CORE_LIB"],
+          File.join(crate, "target", "release", library_basename),
+          File.join(crate, "target", "debug", library_basename),
+          File.join(root, "lib", "ruby_llm_mesh", "native", library_basename)
+        ].compact
+        candidates.find { |p| File.exist?(p) }
+      end
+
+      def library_basename
+        case RbConfig::CONFIG["host_os"]
+        when /mswin|mingw|cygwin/i then "chimera_core.dll"
+        when /darwin/i then "libchimera_core.dylib"
+        else "libchimera_core.so"
+        end
+      end
+
+      def parse_payload(raw)
+        data = JSON.parse(raw.to_s)
+        data.is_a?(Hash) ? data : { "ok" => true, "output" => raw.to_s, "raw" => data }
+      rescue JSON::ParserError
+        { "ok" => true, "output" => raw.to_s, "engine" => available? ? "chimera_core" : "ruby_fallback" }
+      end
+    end
+
+    # Pure-Ruby stand-in when the native library is not compiled.
+    module Fallback
+      @alive = false
+      @port = nil
+      @mutex = Mutex.new
+
+      class << self
+        def start_node(port)
+          @mutex.synchronize do
+            @port = Integer(port)
+            @alive = true
+          end
+          true
+        end
+
+        def stop_node
+          @mutex.synchronize do
+            @alive = false
+            @port = nil
+          end
+          true
+        end
+
+        def node_alive?
+          @mutex.synchronize { @alive }
+        end
+
+        def execute_wasm_payload(intent)
+          port = @mutex.synchronize { @port }
+          alive = @mutex.synchronize { @alive }
+          JSON.generate(
+            ok: true,
+            engine: "ruby_fallback",
+            mode: "pure_ruby",
+            alive: alive,
+            port: port,
+            intent: intent.to_s,
+            output: "Fallback mesh executed intent (#{intent.to_s[0, 64]})"
+          )
+        end
+
+        def reset!
+          @mutex.synchronize do
+            @alive = false
+            @port = nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm_mesh/providers/base.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "net/http"
+require "openssl"
 require "uri"
 
 module RubyLlmMesh
@@ -41,7 +42,10 @@ module RubyLlmMesh
         [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
+      rescue SocketError, EOFError, IOError, OpenSSL::SSL::SSLError,
+             Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH,
+             Errno::ENETUNREACH, Errno::ETIMEDOUT, Errno::EPIPE => e
+        # Wrap transport failures so the router can trip circuits / fall back
         raise ProviderError.new(e.message, provider: name)
       end
 

data/lib/ruby_llm_mesh/providers/local_node.rb

@@ -2,7 +2,8 @@
 
 module RubyLlmMesh
   module Providers
-    # OpenAI-compatible local runtime (Ollama, LM Studio, vLLM, llama.cpp server, etc.)
+    # OpenAI-compatible local runtime (Ollama, LM Studio, vLLM, llama.cpp server, etc.).
+    # When peer discovery is enabled, tries healthy peers from Mesh::PeerRegistry.
     class LocalNode < Base
       def name
         :local_node
@@ -22,8 +23,37 @@ module RubyLlmMesh
         }
         body[:options] = { num_predict: options[:max_tokens] } if options[:max_tokens]
 
+        errors = []
+        peer_bases.each do |base_url|
+          begin
+            return complete_against(base_url, model: model, body: body, messages: messages)
+          rescue RateLimitError, TimeoutError, ProviderError => e
+            registry.mark_unhealthy(base_url, error: e.message)
+            errors << e
+            next
+          end
+        end
+
+        raise errors.last || ProviderError.new("No healthy local peers available", provider: name)
+      end
+
+      private
+
+      def registry
+        @registry ||= Mesh::PeerRegistry.instance(config: config)
+      end
+
+      def peer_bases
+        urls = registry.healthy_urls
+        urls = [config.local_node_base_url.to_s.chomp("/")] if urls.empty?
+        urls
+      end
+
+      def complete_against(base_url, model:, body:, messages:)
+        base = base_url.to_s.chomp("/")
+
         response, latency_ms = http_post(
-          "#{config.local_node_base_url.chomp('/')}/v1/chat/completions",
+          "#{base}/v1/chat/completions",
           headers: { "Content-Type" => "application/json" },
           body: body
         )
@@ -31,19 +61,20 @@ module RubyLlmMesh
         # 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",
+            "#{base}/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
+          registry.mark_healthy(base)
           return Response.new(
             content: content,
             provider: name,
             model: model,
             usage: {},
-            raw: data,
+            raw: data.merge("_peer" => base),
             latency_ms: latency_ms
           )
         end
@@ -51,13 +82,14 @@ module RubyLlmMesh
         raise_for_status!(response)
         data = parse_json(response)
         content = data.dig("choices", 0, "message", "content").to_s
+        registry.mark_healthy(base)
 
         Response.new(
           content: content,
           provider: name,
           model: data["model"] || model,
           usage: data["usage"] || {},
-          raw: data,
+          raw: data.merge("_peer" => base),
           latency_ms: latency_ms
         )
       end

data/lib/ruby_llm_mesh/response.rb

@@ -2,9 +2,10 @@
 
 module RubyLlmMesh
   class Response
-    attr_reader :content, :provider, :model, :usage, :raw, :latency_ms, :fallback_used
+    attr_reader :content, :provider, :model, :usage, :raw, :latency_ms, :fallback_used, :cache_hit
 
-    def initialize(content:, provider:, model: nil, usage: {}, raw: nil, latency_ms: nil, fallback_used: false)
+    def initialize(content:, provider:, model: nil, usage: {}, raw: nil, latency_ms: nil,
+                   fallback_used: false, cache_hit: false)
       @content = content
       @provider = provider
       @model = model
@@ -12,6 +13,7 @@ module RubyLlmMesh
       @raw = raw
       @latency_ms = latency_ms
       @fallback_used = fallback_used
+      @cache_hit = cache_hit
     end
 
     def text
@@ -29,7 +31,8 @@ module RubyLlmMesh
         model: model,
         usage: usage,
         latency_ms: latency_ms,
-        fallback_used: fallback_used
+        fallback_used: fallback_used,
+        cache_hit: cache_hit
       }
     end
   end