ruby_llm_mesh

Sovereign multi-provider AI mesh for Ruby & Rails
AiAgentRouter · native FFI core · circuit breaking · cloud failover

Install from RubyGems: https://rubygems.org/gems/ruby_llm_mesh

Gem name: ruby_llm_mesh (underscores) — matches this GitHub repo and the official RubyGems listing. Do not confuse with hyphenated names in design sketches.

ruby_llm_mesh routes intents across:

1. A native sovereign mesh (chimera_core Rust cdylib via FFI) for local P2P-style execution
2. Real cloud / local LLM HTTP — OpenAI, Anthropic, and OpenAI-compatible nodes (Ollama, LM Studio, …)

When the native library is not compiled, a pure-Ruby fallback keeps the API working. Circuit breaking, optional semantic cache, peer health for multi-node local meshes, RAG helpers, and Rails hooks remain available.

gem install ruby_llm_mesh

Or in a Gemfile:

gem "ruby_llm_mesh"

Then bundle install.

Gem page: rubygems.org/gems/ruby_llm_mesh

Requires Rust / cargo:

bundle exec rake compile
# → ext/chimera_core/target/release/libchimera_core.so (or .dylib / .dll)

Without compile, NativeCore uses an in-process Ruby fallback. require "ruby_llm_mesh" never crashes on a missing .so.

require "ruby_llm_mesh"

AiAgentRouter.configure do |c|
  c.openai_api_key = ENV["OPENAI_API_KEY"]
  c.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
  c.mesh_port = 4233
  c.auto_boot_mesh = true
  c.fallback_providers = %i[openai anthropic local_node]
end

# Strategy-based execution (v2)
response = AiAgentRouter.execute(
  intent: "Summarize circuit breakers in one sentence.",
  strategy: :auto # :p2p_mesh | :cloud | :openai | :anthropic | :local_node
)
puts response.content
puts response.provider # => :p2p_mesh or a cloud provider

# Classic complete API (unchanged shape from 0.1.x)
response = AiAgentRouter.complete(
  prompt: "Hello from the mesh",
  providers: %i[anthropic openai local_node],
  fallback: true
)

Cloud paths call the real provider HTTP clients — they are not stubbed simulation strings.

Same as 0.1.x: per-provider circuits, fallback ladders, AllProvidersFailedError. Providers: :openai, :anthropic, :local_node (alias :local_mesh for peer-aware local routing).

chunks = RubyLlmMesh::Rag::Chunker.new(size: 500, overlap: 50).chunk(long_text)
embedder = RubyLlmMesh::Rag::Embeddings.new(dimensions: 256)
hits = embedder.top_k("billing refunds", documents, k: 3)

class Conversation < ApplicationRecord
  acts_as_ai_agent
end

• Bump the gem to 2.0.0 (~> 0.1 will not pick this up).
• complete / AiAgentRouter.complete remain; prefer execute for mesh strategies.
• Install ffi (declared dependency). Compile native core only if you want the Rust engine.
• If you configured RubyGems trusted publishing against push_gem.yml, update the workflow filename to release.yml.

bundle install
bundle exec rake test          # no Rust required
bundle exec rake compile       # optional native build
bundle exec rake test:native   # cargo test

Releases publish via RubyGems Trusted Publishing using .github/workflows/release.yml on tags matching v*.

Create a GitHub Environment named release. Pushing tag v2.0.0 runs OIDC publish via rubygems/release-gem@v1.

Docs: https://theworker02.github.io/ruby_llm_mesh/

Designed with Cursor models Opus and Fable 5.

• Code of Conduct — Contributor Covenant 2.1; see also CONTRIBUTING.md
• Privacy Policy — no phone-home telemetry; prompts and API keys stay with endpoints you configure

MIT — see LICENSE.txt.