Raix (Ruby AI eXtensions)

The Raix::MCP module (experimental) allows connecting to remote Model Context Protocol (MCP) servers. When included, it automatically fetches tools from the server via tools/list, registers them as OpenAI-compatible function schemas, and provides proxy methods to call them via tools/call.

To use it, include Raix::MCP along with Raix::ChatCompletion and Raix::FunctionDispatch.

You can filter tools using the only: or except: options in the mcp DSL.

class FilteredMcpConsumer
  include Raix::ChatCompletion
  include Raix::FunctionDispatch
  include Raix::MCP

  # Only include specific tools
  mcp "https://server.example.com/sse", only: [:tool_one, :tool_two]

  # Or exclude specific tools
  mcp "https://server.example.com/sse", except: [:tool_to_exclude]
end

Include Raix::FunctionDispatch to allow the AI to call specific Ruby functions during a conversation.

• Use the function keyword to declare a function name, description, and argument schema.
• Use chat_completion(loop: true) to enable an autonomous loop where the AI can call multiple functions sequentially until it reaches a final text response.
• To manually terminate the loop from within a function, call stop_tool_calls_and_respond!.

class WhatIsTheWeather
  include Raix::ChatCompletion
  include Raix::FunctionDispatch

  function :check_weather, "Check the weather for a location", location: { type: "string" } do |args|
    "The weather in #{args[:location]} is hot and sunny"
  end
end

# To trigger the loop:
# weather_ai.chat_completion(loop: true)

The Raix::Predicate module allows you to handle AI responses to questions that can be answered with 'Yes', 'No', or 'Maybe'. You define handlers using yes?, no?, or maybe? blocks. Each block receives the full AI response (including the explanation) as an argument.

Requirements:

• You must define at least one handler.
• If no handlers are defined, ask will raise a RuntimeError.
• The AI response is expected to start with "Yes, ", "No, ", or "Maybe, ".

class Question
  include Raix::Predicate

  yes? do |explanation|
    puts "Affirmative: #{explanation}"
  end

  no? do |explanation|
    puts "Negative: #{explanation}"
  end

  maybe? do |explanation|
    puts "Uncertain: #{explanation}"
  end
end

question = Question.new
question.ask("Is Ruby a programming language?")
# => Affirmative: Yes, Ruby is a dynamic, object-oriented programming language...

Configure your AI provider (OpenAI or OpenRouter) using the Raix.configure block. This is typically done in an initializer file like config/initializers/raix.rb.

# config/initializers/raix.rb
Raix.configure do |config|
  config.openrouter_client = OpenRouter::Client.new
end

Raix 2.0 uses RubyLLM as its backend. You must configure your API keys through RubyLLM.configure. Raix automatically routes models starting with gpt- or o1 to OpenAI, while all other models are routed through OpenRouter.

# config/initializers/raix.rb
RubyLLM.configure do |config|
  config.openrouter_api_key = ENV["OPENROUTER_API_KEY"]
  config.openai_api_key = ENV["OPENAI_API_KEY"]
end

To use Raix in your Ruby application, install the gem using Bundler or by running the gem command directly.

Using Bundler:

$ bundle add raix

Using gem command:

$ gem install raix

To use Raix in your Ruby project, add the gem to your Gemfile or install it via the command line. Raix supports OpenAI and OpenRouter. It can be used in non-Rails applications as long as ActiveSupport is included.

# Add to Gemfile
gem "raix"

# Or run via terminal
gem install raix

The Raix::Predicate module allows you to perform yes/no/maybe questions using AI chat completion. When included in a class, it provides DSL methods to define handlers for different response types.

Responses are evaluated based on whether they start with yes, or no, . Any response that does not match these patterns is treated as a maybe.

To use it, include the module, define your response blocks using yes?, no?, or maybe?, and then call ask(question) on an instance of the class.

class Question
  include Raix::Predicate

  yes? do |explanation|
    puts "Yes: #{explanation}"
  end

  no? do |explanation|
    puts "No: #{explanation}"
  end

  maybe? do |explanation|
    puts "Maybe: #{explanation}"
  end
end

question = Question.new
question.ask("Is Ruby a programming language?")

The before_completion configuration option accepts a callable object (like a Proc) that executes before every chat completion request. This hook is useful for:

• Dynamic parameter resolution
• Logging request metadata
• Content filtering
• PII redaction (e.g., redacting SSN patterns)

The hook receives a CompletionContext object, which allows you to either modify the context.messages directly or return a hash of parameters to be merged into the request.

The TranscriptAdapter handles the translation between two distinct message representations:

1. Raix Abbreviated Format: Used for easy construction. It uses the role as a key: { role: "content" } (e.g., { user: "hi" }).
2. Standard/RubyLLM Format: Used for actual API calls. It uses the standard { role: "...", content: "..." } structure.

Tool Messages: Note that messages involving tool_calls or tool_call_id are treated as special cases and maintain their full structure (including role, content, and tool_calls/tool_call_id keys) to ensure compatibility with LLM tool-calling requirements.