ruby_llm_mesh 0.1.0 → 2.2.0

data/lib/ruby_llm_mesh/router.rb

@@ -5,7 +5,8 @@ module RubyLlmMesh
     PROVIDER_MAP = {
       openai: Providers::Openai,
       anthropic: Providers::Anthropic,
-      local_node: Providers::LocalNode
+      local_node: Providers::LocalNode,
+      local_mesh: Providers::LocalNode # alias — multi-peer aware via PeerRegistry
     }.freeze
 
     class << self
@@ -19,16 +20,43 @@ module RubyLlmMesh
       def reset_circuit_breaker!
         @circuit_breaker = nil
       end
+
+      def semantic_cache
+        Cache::SemanticCache.instance
+      end
+
+      def peer_registry
+        Mesh::PeerRegistry.instance
+      end
+
+      def health_monitor
+        Mesh::HealthMonitor.instance
+      end
     end
 
-    def initialize(config: RubyLlmMesh.configuration, circuit_breaker: self.class.circuit_breaker)
+    def initialize(config: RubyLlmMesh.configuration, circuit_breaker: self.class.circuit_breaker,
+                   semantic_cache: nil, budget: nil)
       @config = config
       @circuit_breaker = circuit_breaker
+      @semantic_cache = semantic_cache
+      @budget = budget
     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?
 
+      skip_cache = options.delete(:skip_cache)
+      cache = resolve_cache
+      unless skip_cache
+        cached = cache&.lookup(prompt, system: system)
+        if cached
+          log(:info, "Semantic cache hit")
+          return cached
+        end
+      end
+
+      maybe_refresh_peer_health!
+
       provider_list = Array(providers || @config.default_providers).map(&:to_sym)
       raise ArgumentError, "providers list cannot be empty" if provider_list.empty?
 
@@ -37,37 +65,66 @@ module RubyLlmMesh
       attempted = 0
 
       provider_list.each_with_index do |provider_name, index|
+        circuit_key = circuit_key_for(provider_name)
+
         unless PROVIDER_MAP.key?(provider_name)
           errors[provider_name] = ProviderError.new("Unknown provider: #{provider_name}", provider: provider_name)
+          break unless use_fallback
           next
         end
 
-        unless @circuit_breaker.allow?(provider_name)
+        unless @circuit_breaker.allow?(circuit_key)
           errors[provider_name] = CircuitOpenError.new(
             "Circuit open for #{provider_name}",
             provider: provider_name
           )
           log(:warn, "Skipping #{provider_name} — circuit open")
+          break unless use_fallback
           next
         end
 
         begin
           attempted += 1
           log(:info, "Routing to #{provider_name}")
+          budget = resolve_budget
+          estimated_tokens = Budget.estimate_tokens(prompt: prompt, system: system, max_tokens: options[:max_tokens])
+          estimated_usd = Budget.estimate_usd(tokens: estimated_tokens, model: model, config: @config)
+          budget.check!(estimated_tokens: estimated_tokens, estimated_usd: estimated_usd)
+
           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(
+          response = with_retries(provider_name) do
+            provider.complete(prompt: prompt, system: system, model: model, **options)
+          end
+          budget.consume!(usage: response.usage, provider: provider_name, model: response.model || model)
+          @circuit_breaker.record_success(circuit_key)
+
+          result = 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?
+            fallback_used: index.positive?,
+            cache_hit: false
           )
+          cache&.store_response(prompt, result, system: system) unless skip_cache
+          return result
+        rescue BudgetExceededError
+          raise
+        rescue AuthenticationError => e
+          @circuit_breaker.record_failure(circuit_key)
+          errors[provider_name] = e
+          log(:error, "#{provider_name} authentication failed: #{e.message}")
+          break unless use_fallback
+        rescue RateLimitError => e
+          # Trip circuit immediately so subsequent requests skip this provider
+          force_open_circuit!(circuit_key)
+          errors[provider_name] = e
+          log(:error, "#{provider_name} rate limited: #{e.message}")
+          break unless use_fallback
         rescue ProviderError => e
-          @circuit_breaker.record_failure(provider_name)
+          @circuit_breaker.record_failure(circuit_key)
           errors[provider_name] = e
           log(:error, "#{provider_name} failed: #{e.message}")
           break unless use_fallback
@@ -79,6 +136,74 @@ module RubyLlmMesh
 
     private
 
+    def resolve_cache
+      return @semantic_cache if @semantic_cache
+      return nil unless @config.semantic_cache_enabled
+
+      Cache::SemanticCache.instance(config: @config)
+    end
+
+    def resolve_budget
+      return @budget if @budget
+
+      Budget.instance(config: @config)
+    end
+
+    def circuit_key_for(provider_name)
+      provider_name == :local_mesh ? :local_node : provider_name
+    end
+
+    def maybe_refresh_peer_health!
+      return unless @config.peer_discovery_enabled
+
+      monitor = Mesh::HealthMonitor.instance(config: @config)
+      monitor.start!
+      # Opportunistic sync check so first request after enable sees fresh state
+      monitor.check_all!
+    end
+
+    def force_open_circuit!(circuit_key)
+      threshold = @config.circuit_failure_threshold
+      threshold.times { @circuit_breaker.record_failure(circuit_key) }
+    end
+
+    def with_retries(provider_name)
+      attempts = 1 + [Integer(@config.max_retries || 0), 0].max
+      last_error = nil
+
+      attempts.times do |index|
+        return yield
+      rescue AuthenticationError, BudgetExceededError
+        raise
+      rescue RateLimitError, TimeoutError, ProviderError => error
+        last_error = error
+        remaining = attempts - index - 1
+        unless retryable_error?(error) && remaining.positive?
+          raise error
+        end
+
+        delay = retry_delay(index)
+        log(:warn, "#{provider_name} attempt #{index + 1}/#{attempts} failed (#{error.class}): #{error.message}; retrying in #{delay}s")
+        sleep(delay) if delay.positive?
+      end
+
+      raise last_error
+    end
+
+    def retryable_error?(error)
+      return false if error.is_a?(AuthenticationError)
+      return true if error.is_a?(TimeoutError) || error.is_a?(RateLimitError)
+      return false unless error.is_a?(ProviderError)
+
+      status = error.status
+      status.nil? || status >= 500 || status == 429
+    end
+
+    def retry_delay(attempt)
+      base = Float(@config.retry_backoff || 0)
+      base * (2**attempt)
+    end
+
     def log(level, message)
       logger = @config.logger
       return unless logger

data/lib/ruby_llm_mesh/sovereign_mesh.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RubyLlmMesh
+  # Sovereign mesh orchestrator — native P2P node + cloud failover strategies.
+  class SovereignMesh
+    STRATEGIES = %i[auto p2p_mesh cloud openai anthropic local_node local_mesh].freeze
+
+    def initialize(config: RubyLlmMesh.configuration, router: nil)
+      @config = config
+      @router = router || Router.new(config: config)
+    end
+
+    def boot!(port: @config.mesh_port)
+      NativeCore.start_node(port)
+    end
+
+    def shutdown!
+      NativeCore.stop_node
+    end
+
+    def alive?
+      NativeCore.node_alive?
+    end
+
+    # Execute an intent with a routing strategy.
+    #
+    # Strategies:
+    # - +:auto+ — native mesh when alive (or auto-boot), else cloud ladder
+    # - +:p2p_mesh+ — native chimera_core only
+    # - +:cloud+ — real HTTP via +fallback_providers+ / +default_providers+
+    # - +:openai+ / +:anthropic+ / +:local_node+ / +:local_mesh+ — single-provider cloud/local
+    def execute(intent:, strategy: :auto, **options)
+      raise ArgumentError, "intent is required" if intent.nil? || intent.to_s.strip.empty?
+
+      strategy = strategy.to_sym
+      unless STRATEGIES.include?(strategy)
+        raise ArgumentError, "Unknown strategy: #{strategy.inspect} (expected one of #{STRATEGIES.join(', ')})"
+      end
+
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = case strategy
+               when :p2p_mesh
+                 execute_p2p(intent)
+               when :cloud
+                 execute_cloud(intent, **options)
+               when :openai, :anthropic, :local_node, :local_mesh
+                 execute_cloud(intent, providers: [strategy], **options)
+               else # :auto
+                 execute_auto(intent, **options)
+               end
+
+      latency_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+      normalize_result(result, latency_ms: latency_ms, strategy: strategy)
+    end
+
+    private
+
+    def execute_auto(intent, **options)
+      if @config.auto_boot_mesh && !NativeCore.node_alive?
+        NativeCore.start_node(@config.mesh_port)
+      end
+
+      if NativeCore.node_alive?
+        begin
+          return execute_p2p(intent)
+        rescue ProviderError
+          # fall through to cloud
+        end
+      end
+
+      execute_cloud(intent, **options)
+    end
+
+    def execute_p2p(intent)
+      unless NativeCore.node_alive?
+        booted = NativeCore.start_node(@config.mesh_port)
+        unless booted && NativeCore.node_alive?
+          raise ProviderError.new(
+            "Native mesh node is not alive (compile chimera_core or enable fallback)",
+            provider: :p2p_mesh
+          )
+        end
+      end
+
+      payload = NativeCore.execute_wasm_payload(intent)
+      if payload["ok"] == false
+        raise ProviderError.new(
+          payload["error"] || "native execute failed",
+          provider: :p2p_mesh,
+          body: payload
+        )
+      end
+
+      Response.new(
+        content: payload["output"].to_s,
+        provider: :p2p_mesh,
+        model: payload["engine"] || "chimera_core",
+        usage: {},
+        raw: payload,
+        latency_ms: nil,
+        fallback_used: false,
+        cache_hit: false
+      )
+    end
+
+    def execute_cloud(intent, providers: nil, **options)
+      providers ||= @config.fallback_providers
+      providers = Array(providers).map(&:to_sym)
+      providers = @config.default_providers if providers.empty?
+
+      @router.complete(
+        prompt: intent,
+        providers: providers,
+        fallback: options.key?(:fallback) ? options[:fallback] : @config.fallback,
+        system: options[:system],
+        model: options[:model],
+        **options.reject { |k, _| %i[system model fallback providers].include?(k) }
+      )
+    end
+
+    def normalize_result(response, latency_ms:, strategy:)
+      return response if response.is_a?(Response) && response.latency_ms
+
+      Response.new(
+        content: response.content,
+        provider: response.provider,
+        model: response.model,
+        usage: response.usage,
+        raw: (response.raw.is_a?(Hash) ? response.raw : { data: response.raw }).merge("strategy" => strategy.to_s),
+        latency_ms: response.latency_ms || latency_ms,
+        fallback_used: response.fallback_used,
+        cache_hit: response.cache_hit
+      )
+    end
+  end
+end

data/lib/ruby_llm_mesh/version.rb

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

data/lib/ruby_llm_mesh.rb

@@ -5,14 +5,22 @@ 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/budget"
 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"
+require_relative "ruby_llm_mesh/cache/memory_store"
+require_relative "ruby_llm_mesh/cache/redis_store"
+require_relative "ruby_llm_mesh/cache/semantic_cache"
+require_relative "ruby_llm_mesh/mesh/peer_registry"
+require_relative "ruby_llm_mesh/mesh/health_monitor"
+require_relative "ruby_llm_mesh/native_core"
+require_relative "ruby_llm_mesh/router"
+require_relative "ruby_llm_mesh/sovereign_mesh"
 
 # Optional Rails integration — only load railtie when Rails is already present
 if defined?(Rails::Railtie)
@@ -28,6 +36,23 @@ module RubyLlmMesh
     def chat(**)
       complete(**)
     end
+
+    # Sovereign mesh entrypoint — native P2P and/or real cloud failover.
+    def execute(intent:, strategy: :auto, **options)
+      SovereignMesh.new.execute(intent: intent, strategy: strategy, **options)
+    end
+
+    def boot_mesh!(port: configuration.mesh_port)
+      NativeCore.start_node(port)
+    end
+
+    def mesh_alive?
+      NativeCore.node_alive?
+    end
+
+    def budget_status
+      Budget.instance(config: configuration).status
+    end
   end
 end
 
@@ -37,6 +62,10 @@ module AiAgentRouter
     RubyLlmMesh.complete(...)
   end
 
+  def self.execute(...)
+    RubyLlmMesh.execute(...)
+  end
+
   def self.configure(&)
     RubyLlmMesh.configure(&)
   end
@@ -44,4 +73,16 @@ module AiAgentRouter
   def self.configuration
     RubyLlmMesh.configuration
   end
+
+  def self.boot_mesh!(...)
+    RubyLlmMesh.boot_mesh!(...)
+  end
+
+  def self.mesh_alive?
+    RubyLlmMesh.mesh_alive?
+  end
+
+  def self.budget_status
+    RubyLlmMesh.budget_status
+  end
 end

data/ruby_llm_mesh.gemspec

@@ -8,11 +8,15 @@ Gem::Specification.new do |spec|
   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.summary = "Sovereign multi-provider AI mesh with native FFI core, circuit-breaking, and cloud failover 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.
+    ruby_llm_mesh (AiAgentRouter) is a Ruby gem that routes AI intents across a native
+    chimera_core mesh (Rust FFI), OpenAI, Anthropic, and local node runtimes with
+    automatic circuit-breaking, fallback ladders, optional semantic caching, peer health
+    monitoring, lightweight RAG helpers, and optional ActiveRecord hooks.
+
+    Gem name uses underscores (ruby_llm_mesh) to match the GitHub repository and
+    RubyGems listing at https://rubygems.org/gems/ruby_llm_mesh.
   DESC
   spec.homepage = "https://github.com/theworker02/ruby_llm_mesh"
   spec.license = "MIT"
@@ -29,13 +33,14 @@ Gem::Specification.new do |spec|
   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")
+        f.end_with?(".gem") ||
+        f.include?("/target/")
     end
   end
-  # Ensure packaging works before the first commit
   if spec.files.empty?
     spec.files = Dir[
       "lib/**/*",
+      "ext/**/*",
       "sig/**/*",
       "exe/**/*",
       "assets/**/*",
@@ -43,14 +48,22 @@ Gem::Specification.new do |spec|
       "README*",
       "CHANGELOG*",
       "CODE_OF_CONDUCT*",
-      "*.gemspec"
-    ]
+      "PRIVACY*",
+      "CONTRIBUTING*",
+      "*.gemspec",
+      "Rakefile"
+    ].reject { |f| f.include?("/target/") || f.end_with?(".gem") }
   end
 
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  # Optional native compile — documented via `rake compile`; gem works without it.
+  # spec.extensions = []  # cargo-based; use rake compile instead of mkmf
+
+  spec.add_dependency "ffi", "~> 1.17"
+
   spec.add_development_dependency "minitest", "~> 5.25"
   spec.add_development_dependency "rake", "~> 13.2"
   spec.add_development_dependency "webmock", "~> 3.24"

data/sig/ruby_llm_mesh.rbs

@@ -8,6 +8,7 @@ module RubyLlmMesh
     attr_accessor fallback: bool
     attr_accessor timeout: Integer
     attr_accessor max_retries: Integer
+    attr_accessor retry_backoff: Float
     attr_accessor openai_api_key: String?
     attr_accessor openai_base_url: String
     attr_accessor openai_model: String
@@ -19,6 +20,12 @@ module RubyLlmMesh
     attr_accessor circuit_failure_threshold: Integer
     attr_accessor circuit_reset_timeout: Integer
     attr_accessor logger: untyped
+    attr_accessor mesh_port: Integer
+    attr_accessor fallback_providers: Array[Symbol]
+    attr_accessor auto_boot_mesh: bool
+    attr_accessor semantic_cache_enabled: bool
+    attr_accessor peer_discovery_enabled: bool
+    attr_accessor peer_urls: Array[String]
   end
 
   def self.configuration: () -> Configuration
@@ -31,6 +38,9 @@ module RubyLlmMesh
     **untyped
   ) -> Response
   def self.chat: (**untyped) -> Response
+  def self.execute: (intent: String, ?strategy: Symbol, **untyped) -> Response
+  def self.boot_mesh!: (?port: Integer) -> bool
+  def self.mesh_alive?: () -> bool
 
   class Response
     attr_reader content: String
@@ -40,6 +50,7 @@ module RubyLlmMesh
     attr_reader raw: untyped
     attr_reader latency_ms: Integer?
     attr_reader fallback_used: bool
+    attr_reader cache_hit: bool
 
     def initialize: (
       content: String,
@@ -48,7 +59,8 @@ module RubyLlmMesh
       ?usage: Hash[untyped, untyped],
       ?raw: untyped,
       ?latency_ms: Integer?,
-      ?fallback_used: bool
+      ?fallback_used: bool,
+      ?cache_hit: bool
     ) -> void
     def text: () -> String
     def to_s: () -> String
@@ -66,6 +78,20 @@ module RubyLlmMesh
     ) -> Response
   end
 
+  class SovereignMesh
+    def execute: (intent: String, ?strategy: Symbol, **untyped) -> Response
+    def boot!: (?port: Integer) -> bool
+    def alive?: () -> bool
+  end
+
+  module NativeCore
+    def self.available?: () -> bool
+    def self.start_node: (?Integer) -> bool
+    def self.stop_node: () -> bool
+    def self.node_alive?: () -> bool
+    def self.execute_wasm_payload: (String) -> Hash[String, untyped]
+  end
+
   class CircuitBreaker
     def allow?: (Symbol) -> bool
     def record_success: (Symbol) -> void
@@ -77,6 +103,9 @@ end
 
 module AiAgentRouter
   def self.complete: (**untyped) -> RubyLlmMesh::Response
+  def self.execute: (**untyped) -> RubyLlmMesh::Response
   def self.configure: () { (RubyLlmMesh::Configuration) -> void } -> void
   def self.configuration: () -> RubyLlmMesh::Configuration
+  def self.boot_mesh!: (**untyped) -> bool
+  def self.mesh_alive?: () -> bool
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm_mesh
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - theworker02
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -52,9 +66,13 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.24'
 description: |
-  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.
+  ruby_llm_mesh (AiAgentRouter) is a Ruby gem that routes AI intents across a native
+  chimera_core mesh (Rust FFI), OpenAI, Anthropic, and local node runtimes with
+  automatic circuit-breaking, fallback ladders, optional semantic caching, peer health
+  monitoring, lightweight RAG helpers, and optional ActiveRecord hooks.
+
+  Gem name uses underscores (ruby_llm_mesh) to match the GitHub repository and
+  RubyGems listing at https://rubygems.org/gems/ruby_llm_mesh.
 email:
 - theworker02@users.noreply.github.com
 executables: []
@@ -66,14 +84,24 @@ files:
 - CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
+- PRIVACY.md
 - README.md
 - Rakefile
 - assets/logo.png
+- ext/chimera_core/Cargo.toml
+- ext/chimera_core/src/lib.rs
 - lib/ruby_llm_mesh.rb
 - lib/ruby_llm_mesh/active_record/acts_as_ai_agent.rb
+- lib/ruby_llm_mesh/budget.rb
+- lib/ruby_llm_mesh/cache/memory_store.rb
+- lib/ruby_llm_mesh/cache/redis_store.rb
+- lib/ruby_llm_mesh/cache/semantic_cache.rb
 - lib/ruby_llm_mesh/circuit_breaker.rb
 - lib/ruby_llm_mesh/configuration.rb
 - lib/ruby_llm_mesh/errors.rb
+- lib/ruby_llm_mesh/mesh/health_monitor.rb
+- lib/ruby_llm_mesh/mesh/peer_registry.rb
+- lib/ruby_llm_mesh/native_core.rb
 - lib/ruby_llm_mesh/providers/anthropic.rb
 - lib/ruby_llm_mesh/providers/base.rb
 - lib/ruby_llm_mesh/providers/local_node.rb
@@ -84,6 +112,7 @@ files:
 - lib/ruby_llm_mesh/railtie.rb
 - lib/ruby_llm_mesh/response.rb
 - lib/ruby_llm_mesh/router.rb
+- lib/ruby_llm_mesh/sovereign_mesh.rb
 - lib/ruby_llm_mesh/version.rb
 - ruby_llm_mesh.gemspec
 - sig/ruby_llm_mesh.rbs
@@ -114,6 +143,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: Unified multi-provider AI routing with circuit-breaking and local fallback
-  for Ruby & Rails
+summary: Sovereign multi-provider AI mesh with native FFI core, circuit-breaking,
+  and cloud failover for Ruby & Rails
 test_files: []