OlympiaAI/raix

OlympiaAI / raix – Ruby AI eXtensions

What it is – Raix is a Ruby library that lets you drop discrete large‑language‑model (LLM) capabilities into any Ruby class. It ships three mix‑in modules:

Raix::ChatCompletion – the core that manages a transcript (the conversation history) and sends chat‑completion requests to an LLM via the underlying RubyLLM wrapper (OpenAI, Anthropic, Google Gemini, etc. through OpenRouter).
Raix::FunctionDispatch – optional DSL for declaring tool (function) definitions that the model can call. Raix automatically executes the function, adds the result to the transcript, and continues the conversation until the model returns plain text.
Raix::PromptDeclarations – optional DSL for building reusable prompt chains (sequential prompts, streaming, conditional loops).

All three modules can be mixed into plain Ruby objects; they also work in non‑Rails apps as long as you include activesupport.

Key Features (as described in the README)

Feature	What the README says	Why it matters
Unified provider access	Powered by `ruby_llm`, supports OpenAI, Anthropic, Google Gemini, and many others via OpenRouter.	Switch models or providers without changing your code.
Transcript handling	`transcript` stores messages in either a short `{ role: "user", content: "…" }` hash or the abbreviated `role => content` form. Auto‑appends AI replies unless `save_response: false` is passed.	Keeps conversation state simple and flexible.
Predicted outputs	Pass `prediction:` param (OpenAI) to get low‑latency speculative responses.
Prompt caching	For Anthropic Claude models you can set `cache_at` to split large messages into cached “breakpoints”.
JSON mode	`json: true` forces the model to return valid JSON; Raix sets `response_format` for OpenAI and extracts JSON from `<json>` tags for other providers.
`before_completion` hook	Global, class‑level, or instance‑level lambdas (or callable objects) that can modify the request, add system prompts, log, redact PII, select models per tenant, etc.
Function (tool) dispatch	Declare functions with `function :name, "description", param_schema do … end`. Raix automatically calls them when the model requests a tool, adds the result to the transcript, and loops until a normal text reply. Supports:

selective exposure via available_tools
multiple tool calls in one response
custom dispatch_tool_function overrides
caching of function results via ActiveSupport cache | | Prompt chain DSL | prompt call: SomePromptClass or prompt text: -> { … } lets you compose multi‑step conversations (e.g., URL detection, memory scan, streaming replies). | | Configuration | Raix.configure for global defaults (e.g., default model, max tool calls, global hook). |

Typical Use Cases

Scenario	How you would use Raix
Add chat‑bot capability to a Rails or Sinatra app	Include `Raix::ChatCompletion` in a service object, push user messages into `transcript`, call `chat_completion` and render the returned string.
Build an AI‑driven assistant that can call internal services	Add `Raix::FunctionDispatch` and declare functions like `check_weather`, `fetch_user_profile`, etc. The LLM will decide when to invoke them, and Raix will handle the round‑trip automatically.
Enforce data‑privacy / PII redaction	Set a global `before_completion` hook that scans `context.messages` and masks SSNs, emails, etc., before the request leaves your server.
Multi‑step processing pipelines	Use `Raix::PromptDeclarations` to run a URL‑fetch check, then a memory‑scan, then the main conversation prompt, all without writing boilerplate loops.
Cost‑aware model selection	In a `before_completion` hook read tenant settings from the DB and inject `model`, `temperature`, `max_tokens` per‑request.
Cache expensive tool calls	Override `dispatch_tool_function` to pass `Rails.cache` and let Raix reuse previous results for the same arguments.

Project Maturity (from the README)

Version – Mentions Raix 2.0 (so at least one major release).
Origin – Extracted from the production‑grade Olympia chat platform, which the author claims is “one of the biggest and most successful AI chat projects written completely in Ruby”.
Dependencies – Relies on ruby_llm (the provider wrapper) and activesupport for caching and utilities.
Testing – The README includes an RSpec example, indicating a test suite exists.
Documentation – The README itself is fairly extensive, covering core APIs, hooks, function dispatch, caching, and prompt chains.
Community – No explicit mention of external contributors, but the library is open‑source and tied to a commercial product (Olympia) and a Leanpub book, suggesting a small but focused user base.

Ecosystem & Compatibility

Item	Details
Ruby version	Not stated, but depends on `ruby_llm` and `activesupport`; likely Ruby 2.7+ or 3.x.
Rails support	Works in any Ruby app; Rails integration is optional but examples use Rails logging and caching.
Provider support	OpenAI, Anthropic, Google Gemini, and “dozens of other providers” via OpenRouter.
Other gems	`ruby_llm`, `activesupport`, optional `rails` for cache/logger.
License	Not mentioned in the README (would need to check the repo).

Getting Started (based on the README)

Add the gem (presumed name raix) to your Gemfile and run bundle install.

Include the core module in any class you want AI power:

class MyAssistant
  include Raix::ChatCompletion
end

Push messages to the transcript and call the completion:

ai = MyAssistant.new
ai.transcript << { user: "What is the meaning of life?" }
puts ai.chat_completion   # => model response string

Optional: add function dispatch if you need tools:

class WeatherBot
  include Raix::ChatCompletion
  include Raix::FunctionDispatch

  function :check_weather, "Check weather", location: {type: "string", required: true} do |args|
    "It is sunny in #{args[:location]}"
  end
end

Configure globally (e.g., default model, hooks):

Raix.configure do |c|
  c.before_completion = ->(ctx) { { temperature: 0.7 } }
end

Run your app – the library will handle request construction, response parsing, tool execution, and transcript management for you.

TL;DR

Raix is a Ruby‑first SDK that abstracts away the boilerplate of talking to LLM APIs. By mixing in a few modules you get:

a managed conversation transcript,
unified multi‑provider access via OpenRouter,
powerful hooks for dynamic request tweaking,
a declarative tool‑call system that lets the model invoke Ruby methods, and
a prompt‑chain DSL for complex multi‑step flows.

It’s aimed at Ruby developers who want to embed LLM‑driven features (chatbots, assistants, RAG pipelines, automation) without leaving the Ruby ecosystem. The README provides enough detail to start building immediately.