ruby_llm_mesh 0.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f335121a2c16a9ca428f4d5110b69f6caf999d4534358cd6c68d668382c9130
-  data.tar.gz: ec867f6d775e2ba68d5922136ebc7e6a3af52dbf213fad8016c0f613e92a25ca
+  metadata.gz: 31ce7f20e5d73fed9453fd89263d03eda29cff41fc4d4d28da6d815f9870841e
+  data.tar.gz: e83f9c1bb73712fa1a89660670d6e20efad8cb9985e21c8a7bd6d4f2bb5b5e7b
 SHA512:
-  metadata.gz: 4c094b33bdaa1f55997d3f3719d25d4591b0daeaf23930e6868dab33b65a745560fc6bc43aadd711303d3b8cbb12ce4856f149825104d8d96401b2818c340ec7
-  data.tar.gz: 1b99d7efe252cacc5074257ac8c950d5bd6e84d68beb5a15edd3bc05c64c0499283a98befdfa74a09a2494182e6d68690a1ab69710a799a08bef9b924fd087c1
+  metadata.gz: 605e9074bd646d136d3f8bd68f306d052bb4b71571e6c40f72715d2ebf2b7623088a4b5838e41a04d344e3002dd1992eea7d3d053883c4ffa79c94973c7b7c7c
+  data.tar.gz: b69e55002426df41be4cac00907c8c4c1c93dea524614875bf731ee12acb3915c852d380aa12a123585e278d463d5380ed4b37ff3aa620b8cc817579029c03e2

data/CHANGELOG.md

@@ -5,6 +5,59 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0] - 2026-08-14
+
+### Added
+
+- **Provider retries with exponential backoff** — `max_retries` now retries transient `TimeoutError`, `RateLimitError`, and 5xx/transport `ProviderError`s before falling over
+- `retry_backoff` (default `0.1s`, env `RUBY_LLM_MESH_RETRY_BACKOFF`) doubles after each failed attempt
+- Authentication failures are never retried; they fail over immediately when fallback is enabled
+
+## [2.1.0] - 2026-08-11
+
+### Added
+
+- **Token/cost budget guard** — opt-in via `budget_enabled`, `budget_max_tokens`, `budget_max_usd`, and `budget_prices`
+- `RubyLlmMesh::Budget` pre-checks estimated usage before provider calls and consumes actual usage from `Response#usage` after success
+- `RubyLlmMesh::BudgetExceededError` when token or USD limits would be exceeded
+- `RubyLlmMesh.budget_status` / `AiAgentRouter.budget_status` for runtime budget telemetry
+- Full Contributor Covenant 2.1 [Code of Conduct](CODE_OF_CONDUCT.md) with enforcement guidelines
+- [Privacy Policy](PRIVACY.md) for the OSS LLM routing gem (no phone-home; data stays with configured endpoints)
+- README, CONTRIBUTING, and docs site links to Code of Conduct and Privacy Policy
+
+### Fixed
+
+- Router now honors `fallback: false` when a provider circuit is open or the provider name is unknown (no longer silently continues the ladder)
+- `PeerRegistry#healthy_urls` no longer reintroduces unhealthy peers when the healthy set is empty (LocalNode uses its primary URL as last resort)
+- Circuit breaker half-open state allows a single probe (not unbounded concurrent probes)
+- HTTP client wraps connection reset / SSL / EOF transport errors as `ProviderError` so failover works
+- Redis semantic-cache index cleans up stale entry IDs after TTL expiry
+
+## [2.0.0] - 2026-08-07
+
+### Added
+
+- **Sovereign Mesh Core** — optional Rust `chimera_core` cdylib under `ext/chimera_core/` with FFI exports `start_node`, `node_alive`, `execute_wasm_payload`, `stop_node`
+- **`RubyLlmMesh.execute` / `AiAgentRouter.execute`** — strategy-based intent execution (`:auto`, `:p2p_mesh`, `:cloud`, `:openai`, `:anthropic`, `:local_node`, `:local_mesh`)
+- Pure-Ruby **NativeCore fallback** when the shared library or `ffi` load fails (require never hard-crashes)
+- Mesh config: `mesh_port` (default `4233`), `auto_boot_mesh`, `fallback_providers`
+- Optional **semantic cache** (in-memory or Redis when `REDIS_URL` + `redis` gem present)
+- Optional **peer health monitoring** for multi-URL local node meshes (`peer_urls`, `HealthMonitor`)
+- `rake compile` to build chimera_core via cargo
+- Trusted publishing workflow `.github/workflows/release.yml` (OIDC + GitHub Release)
+
+### Changed
+
+- Version jump to **2.0.0** (Sovereign Mesh / FFI major)
+- Gem dependency: `ffi ~> 1.17`
+- Cloud failover remains real HTTP (OpenAI / Anthropic / local_node) — not stubbed
+
+### Breaking
+
+- Major version bump; consumers pinning `~> 0.1` must opt into `2.0.0`
+- New default mesh settings (`auto_boot_mesh: true`, `mesh_port: 4233`) affect `:auto` / `:p2p_mesh` strategies only — `complete` API behavior is unchanged when semantic cache stays off (default)
+- Trusted publisher workflow filename is now **`release.yml`** (was `push_gem.yml`)
+
 ## [0.1.0] - 2026-08-07
 
 ### Added
@@ -16,5 +69,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - RAG helpers: text chunker, bag-of-words embeddings, tool schema adapters
 - Optional ActiveRecord `acts_as_ai_agent` for memory, semantic cache, and audit logging
 - Rails railtie that loads only when Rails is present
+- Documentation site on GitHub Pages
+- Trusted publishing workflow for RubyGems OIDC releases
 
+[2.2.0]: https://github.com/theworker02/ruby_llm_mesh/releases/tag/v2.2.0
+[2.1.0]: https://github.com/theworker02/ruby_llm_mesh/releases/tag/v2.1.0
+[2.0.0]: https://github.com/theworker02/ruby_llm_mesh/releases/tag/v2.0.0
 [0.1.0]: https://github.com/theworker02/ruby_llm_mesh/releases/tag/v0.1.0

data/CODE_OF_CONDUCT.md

@@ -43,21 +43,95 @@ acceptable behavior and will take appropriate and fair corrective action in
 response to any behavior that they deem inappropriate, threatening, offensive,
 or harmful.
 
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
 ## Scope
 
 This Code of Conduct applies within all community spaces, and also applies when
 an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
 
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by opening a GitHub issue or contacting the maintainers via the
-repository. All complaints will be reviewed and investigated promptly and fairly.
+reported by:
+
+* Opening a [GitHub issue](https://github.com/theworker02/ruby_llm_mesh/issues)
+  on this repository (prefer a private report when the matter is sensitive), or
+* Contacting the maintainer via their GitHub profile:
+  [theworker02](https://github.com/theworker02)
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
 
 ## Attribution
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.1, available at
-https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
 
 [homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/CONTRIBUTING.md

@@ -22,18 +22,24 @@ bundle exec rake test
 ## Testing
 
 Unit tests must not require live provider credentials. Stub HTTP with WebMock or inject stub providers.
+Native FFI tests skip automatically when `chimera_core` is not compiled.
 
 ```bash
 bundle exec rake test
+bundle exec rake compile   # optional — requires Rust/cargo
 ```
 
 ## Releases
 
 Maintainers cut releases by tagging `vX.Y.Z` on `main`, which triggers the
-RubyGems Trusted Publisher workflow (`.github/workflows/push_gem.yml`).
+RubyGems Trusted Publisher workflow (`.github/workflows/release.yml`).
 
 See the README for Trusted Publisher setup details.
 
 ## Code of Conduct
 
 By participating, you agree to uphold our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Privacy
+
+See [PRIVACY.md](PRIVACY.md) for how this gem handles data (no phone-home telemetry; prompts go only to endpoints you configure).

data/PRIVACY.md

@@ -0,0 +1,56 @@
+# Privacy Policy
+
+**Effective date:** 2026-08-07  
+**Applies to:** the open-source `ruby_llm_mesh` Ruby gem and its companion documentation at [github.com/theworker02/ruby_llm_mesh](https://github.com/theworker02/ruby_llm_mesh)
+
+## Summary
+
+`ruby_llm_mesh` is a **library you run in your own Ruby/Rails process**. The maintainers of this project do **not** operate a hosted routing service, do **not** receive your prompts by default, and do **not** collect telemetry, analytics, or crash reports from gem usage.
+
+## What this gem does with data
+
+When you call APIs such as `AiAgentRouter.execute` / `RubyLlmMesh.complete`, the gem may:
+
+1. **Send prompts and related options** to LLM HTTP endpoints **you configure** (for example OpenAI, Anthropic, or a local OpenAI-compatible node such as Ollama / LM Studio), using API keys and base URLs from your environment or configuration.
+2. **Run intents through the optional native mesh / pure-Ruby fallback** entirely **inside your process** (and any peers **you** configure).
+3. **Optionally store prompt/response material** in an in-process or Redis semantic cache **only if you enable** semantic caching and point it at infrastructure you control.
+4. **Optionally record conversational memory / audits** when you use Rails `acts_as_ai_agent` helpers — that data lives in **your** database attributes.
+
+The gem does not phone home to the `ruby_llm_mesh` authors.
+
+## What we do not collect
+
+- No usage analytics or phone-home telemetry from the gem
+- No automatic upload of prompts, completions, embeddings, or API keys to project maintainers
+- No account system or user database operated by this project for gem runtime traffic
+
+## Third-party providers
+
+If you configure cloud providers, **those providers’ privacy policies apply** to data you send them (prompts, system messages, tools, etc.). Review and configure:
+
+- [OpenAI Privacy](https://openai.com/policies/privacy-policy/) (or your compatible endpoint’s policy)
+- [Anthropic Privacy](https://www.anthropic.com/legal/privacy) (or your configured Anthropic-compatible endpoint)
+
+Local nodes and peer URLs you list are under **your** operational control and policies.
+
+## Credentials and secrets
+
+API keys (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, Redis URLs, etc.) are read from your environment or configuration and used only to talk to endpoints you choose. Do not commit secrets to git. This repository’s tests are designed to run **without** live credentials.
+
+## GitHub / project website
+
+Visiting the GitHub repository, Issues, Discussions, or GitHub Pages docs is subject to [GitHub’s Privacy Statement](https://docs.github.com/en/site-policy/privacy-policies/github-privacy-statement). Maintainers may see information you voluntarily provide in issues, PRs, or emails (for example contact details in a Code of Conduct report).
+
+## Children
+
+This project is a developer library and is not directed at children.
+
+## Changes
+
+Privacy practices for the gem may change as the project evolves. Material updates will be reflected in this file in the repository. Continued use of a newer gem version after an update constitutes awareness of the revised policy for that version’s documented behavior.
+
+## Contact
+
+Privacy questions about **this open-source project** (not about third-party LLM vendors): open a GitHub issue in [theworker02/ruby_llm_mesh](https://github.com/theworker02/ruby_llm_mesh/issues) or contact the maintainers via the repository.
+
+For Code of Conduct enforcement, see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

data/README.md

@@ -5,22 +5,32 @@
 <h1 align="center">ruby_llm_mesh</h1>
 
 <p align="center">
-  Unified multi-provider AI routing for Ruby &amp; Rails<br/>
-  <code>AiAgentRouter</code> · circuit breaking · fallback · RAG helpers
+  Sovereign multi-provider AI mesh for Ruby &amp; Rails<br/>
+  <code>AiAgentRouter</code> · native FFI core · circuit breaking · cloud failover
 </p>
 
 <p align="center">
   <a href="https://rubygems.org/gems/ruby_llm_mesh"><img src="https://img.shields.io/gem/v/ruby_llm_mesh?color=9B1B30" alt="Gem Version" /></a>
-  <a href="https://github.com/theworker02/ruby_llm_mesh/actions/workflows/ci.yml"><img src="https://github.com/theworker02/ruby_llm_mesh/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/theworker02/ruby_llm_mesh/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/CI-GitHub%20Actions-1A1A1A" alt="CI" /></a>
   <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-E85D4C" alt="License: MIT" /></a>
   <a href="https://theworker02.github.io/ruby_llm_mesh/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-1A1A1A" alt="GitHub Pages" /></a>
 </p>
 
-**Official RubyGems page:** [https://rubygems.org/gems/ruby_llm_mesh](https://rubygems.org/gems/ruby_llm_mesh)
+<p align="center">
+  <strong>Install from RubyGems:</strong>
+  <a href="https://rubygems.org/gems/ruby_llm_mesh">https://rubygems.org/gems/ruby_llm_mesh</a>
+</p>
+
+> **Gem name:** `ruby_llm_mesh` (underscores) — matches this GitHub repo and the official RubyGems listing. Do not confuse with hyphenated names in design sketches.
+
+## What it does (v2.0.0)
 
-## What it does
+`ruby_llm_mesh` routes intents across:
 
-`ruby_llm_mesh` routes prompts across OpenAI, Anthropic, and local OpenAI-compatible nodes with a single DSL. When a provider fails or its circuit is open, the router can fall through the rest of the ladder. Lightweight RAG helpers and an optional ActiveRecord mixin are included for Rails apps.
+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.
 
 ## Install
 
@@ -36,6 +46,19 @@ gem "ruby_llm_mesh"
 
 Then `bundle install`.
 
+Gem page: [rubygems.org/gems/ruby_llm_mesh](https://rubygems.org/gems/ruby_llm_mesh)
+
+### Compile the native core (optional)
+
+Requires [Rust](https://rustup.rs) / `cargo`:
+
+```bash
+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`.
+
 ## Quickstart
 
 ```ruby
@@ -44,133 +67,135 @@ 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.local_node_base_url = "http://127.0.0.1:11434"
-  c.default_providers = %i[anthropic openai local_node]
-  c.fallback = true
+  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: "Summarize circuit breakers in one sentence.",
+  prompt: "Hello from the mesh",
   providers: %i[anthropic openai local_node],
   fallback: true
 )
-
-puts response.content
-puts response.provider      # => :anthropic (or next healthy provider)
-puts response.fallback_used # => true if a later provider was used
 ```
 
-`RubyLlmMesh.complete` is the same entry point; `AiAgentRouter` is the public product alias.
+## Strategies (`execute`)
+
+| Strategy | Behavior |
+|----------|----------|
+| `:auto` | Boot native mesh if `auto_boot_mesh`; use P2P when alive, else real cloud ladder |
+| `:p2p_mesh` | Native `chimera_core` (or Ruby fallback) only |
+| `:cloud` | HTTP via `fallback_providers` / `default_providers` |
+| `:openai` / `:anthropic` / `:local_node` / `:local_mesh` | Single-provider routing |
+
+Cloud paths call the real provider HTTP clients — they are **not** stubbed simulation strings.
 
 ## Configuration
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `default_providers` | `%i[openai anthropic local_node]` | Provider ladder order |
+| `mesh_port` | `4233` | Native mesh listen port |
+| `auto_boot_mesh` | `true` | Auto-start node for `:auto` / `:p2p_mesh` |
+| `fallback_providers` | `%i[openai anthropic local_node]` | Ladder for `:cloud` / `:auto` failover |
+| `default_providers` | `%i[openai anthropic local_node]` | Ladder for `complete` |
 | `fallback` | `true` | Continue to next provider on failure |
 | `timeout` | `30` | HTTP open/read timeout (seconds) |
-| `openai_api_key` / `openai_base_url` / `openai_model` | env / `https://api.openai.com/v1` / `gpt-4o-mini` | OpenAI settings |
-| `anthropic_api_key` / `anthropic_base_url` / `anthropic_model` | env / `https://api.anthropic.com` / `claude-sonnet-4-5` | Anthropic settings |
-| `local_node_base_url` / `local_node_model` | `http://127.0.0.1:11434` / `llama3.2` | Local node settings |
-| `circuit_failure_threshold` | `3` | Failures before opening a circuit |
-| `circuit_reset_timeout` | `60` | Seconds before half-open retry |
-| `logger` | `nil` | Object responding to `#info` / `#warn` / `#error` or `#call` |
-
-Environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `LOCAL_NODE_BASE_URL`, etc.) are read automatically when present.
-
-## Providers
+| `max_retries` | `1` | Extra attempts on timeout, 5xx, and rate-limit errors |
+| `retry_backoff` | `0.1` | Base delay (seconds) doubled after each retry |
+| `openai_*` / `anthropic_*` / `local_node_*` | env-backed | Provider credentials & endpoints |
+| `circuit_failure_threshold` / `circuit_reset_timeout` | `3` / `60` | Circuit breaker |
+| `semantic_cache_enabled` | `false` | Opt-in vector similarity cache |
+| `semantic_cache_threshold` / `semantic_cache_ttl` | `0.92` / `3600` | Cache match & TTL |
+| `redis_url` | `ENV["REDIS_URL"]` | Optional Redis for distributed cache |
+| `peer_discovery_enabled` / `peer_urls` | off / `[]` | Multi-peer local node health |
+| `logger` | `nil` | `#info` / `#warn` / `#error` or `#call` |
 
-- **`:openai`** — Chat Completions API
-- **`:anthropic`** — Messages API
-- **`:local_node`** — OpenAI-compatible `/v1/chat/completions`, with a fallback to Ollama’s `/api/chat` on 404
+## Native FFI surface
 
-Unknown providers raise `RubyLlmMesh::ProviderError` and are skipped in the ladder when fallback is enabled.
+| C export | Ruby |
+|----------|------|
+| `start_node(port)` | `RubyLlmMesh.boot_mesh!` / `NativeCore.start_node` |
+| `node_alive()` | `RubyLlmMesh.mesh_alive?` / `NativeCore.node_alive?` |
+| `execute_wasm_payload(intent)` | `NativeCore.execute_wasm_payload` → Hash |
+| `stop_node()` | `NativeCore.stop_node` |
 
-## Circuit breaker & fallback
+## Circuit breaker & providers
 
-Each provider has an independent circuit. After `circuit_failure_threshold` consecutive failures (or a failure while half-open), the circuit opens for `circuit_reset_timeout` seconds. Open circuits are skipped; the router continues down the ladder when `fallback: true`.
-
-If every provider fails, `RubyLlmMesh::AllProvidersFailedError` is raised with a per-provider error map.
-
-```ruby
-breaker = RubyLlmMesh::Router.circuit_breaker
-breaker.state_for(:openai) # => :closed | :open | :half_open
-RubyLlmMesh::Router.reset_circuit_breaker!
-```
+Same as 0.1.x: per-provider circuits, fallback ladders, `AllProvidersFailedError`. Providers: `:openai`, `:anthropic`, `:local_node` (alias `:local_mesh` for peer-aware local routing).
 
 ## RAG helpers
 
 ```ruby
 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)
-
-tool = RubyLlmMesh::Rag::Tools.define(
-  name: "lookup_order",
-  description: "Fetch an order by id",
-  parameters: { order_id: { type: "string" } },
-  required: [:order_id]
-)
-openai_tools = RubyLlmMesh::Rag::Tools.for_openai([tool])
 ```
 
-The built-in embedder is a local bag-of-words helper for prototyping. Swap in a production embedding API when you need higher quality vectors.
-
 ## Rails: `acts_as_ai_agent`
 
-The railtie loads only when Rails is present. On ActiveRecord models:
-
 ```ruby
 class Conversation < ApplicationRecord
   acts_as_ai_agent
-  # expects JSON/text columns: messages, semantic_cache, ai_audits (configurable)
 end
-
-conversation = Conversation.create!
-response = conversation.ai_complete("What did we discuss last?", providers: %i[openai])
 ```
 
-Hooks provide conversational memory, a simple prompt→response cache, and an audit trail. Attribute names are configurable via `acts_as_ai_agent(memory_attribute:, cache_attribute:, audit_attribute:)`.
-
-## Branding
-
-Primary colors from the project logo:
-
-| Token | Hex |
-|-------|-----|
-| Ruby | `#9B1B30` |
-| Coral | `#E85D4C` |
-| Charcoal | `#1A1A1A` |
+## Upgrading from 0.1.0 → 2.0.0
 
-Docs site: [https://theworker02.github.io/ruby_llm_mesh/](https://theworker02.github.io/ruby_llm_mesh/)
+- 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`**.
 
 ## Development
 
 ```bash
 bundle install
-bundle exec rake test
+bundle exec rake test          # no Rust required
+bundle exec rake compile       # optional native build
+bundle exec rake test:native   # cargo test
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md).
-
 ## Trusted publishing (RubyGems)
 
-Releases are intended to publish via [RubyGems Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) using `.github/workflows/push_gem.yml` on tags matching `v*`.
-
-Configure a **pending trusted publisher** (first release) or trusted publisher at:
-
-[https://rubygems.org/profile/oidc_pending_trusted_publishers](https://rubygems.org/profile/oidc_pending_trusted_publishers)
+Releases publish via [RubyGems Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) using `.github/workflows/release.yml` on tags matching `v*`.
 
 | Field | Value |
 |-------|-------|
 | Gem name | `ruby_llm_mesh` |
 | GitHub repository owner | `theworker02` |
 | GitHub repository name | `ruby_llm_mesh` |
-| Workflow filename | `push_gem.yml` |
+| Workflow filename | `release.yml` |
 | Environment name | `release` |
 
-Also create a GitHub Environment named `release` on the repository (Settings → Environments). Pushing tag `v0.1.0` (or later) runs the workflow with `id-token: write` and publishes via `rubygems/release-gem`.
+Create a GitHub Environment named `release`. Pushing tag `v2.0.0` runs OIDC publish via `rubygems/release-gem@v1`.
+
+## Branding
+
+| Token | Hex |
+|-------|-----|
+| Ruby | `#9B1B30` |
+| Coral | `#E85D4C` |
+| Charcoal | `#1A1A1A` |
+
+Docs: [https://theworker02.github.io/ruby_llm_mesh/](https://theworker02.github.io/ruby_llm_mesh/)
+
+## Built with
+
+Designed with [Cursor](https://cursor.com) models Opus and Fable 5.
+
+## Community & policies
+
+- [Code of Conduct](CODE_OF_CONDUCT.md) — Contributor Covenant 2.1; see also [CONTRIBUTING.md](CONTRIBUTING.md)
+- [Privacy Policy](PRIVACY.md) — no phone-home telemetry; prompts and API keys stay with endpoints you configure
 
 ## License
 

data/Rakefile

@@ -10,4 +10,32 @@ Rake::TestTask.new(:test) do |t|
   t.warning = true
 end
 
+desc "Compile chimera_core native library (requires Rust/cargo)"
+task :compile do
+  crate = File.expand_path("ext/chimera_core", __dir__)
+  unless system("cargo", "--version", out: File::NULL, err: File::NULL)
+    abort "cargo not found — install Rust from https://rustup.rs to compile chimera_core"
+  end
+  Dir.chdir(crate) do
+    sh "cargo", "build", "--release"
+  end
+  puts "chimera_core built under ext/chimera_core/target/release/"
+end
+
+desc "Compile chimera_core in debug mode"
+task "compile:debug" do
+  crate = File.expand_path("ext/chimera_core", __dir__)
+  Dir.chdir(crate) do
+    sh "cargo", "build"
+  end
+end
+
+desc "Run Rust unit tests for chimera_core"
+task "test:native" do
+  crate = File.expand_path("ext/chimera_core", __dir__)
+  Dir.chdir(crate) do
+    sh "cargo", "test"
+  end
+end
+
 task default: :test

data/ext/chimera_core/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "chimera_core"
+version = "2.0.0"
+edition = "2021"
+description = "Sovereign mesh core for ruby_llm_mesh — native node + intent execution"
+license = "MIT"
+
+[lib]
+name = "chimera_core"
+crate-type = ["cdylib"]
+
+[profile.release]
+lto = true
+opt-level = 3