OmniAI

OmniAI supports the Model Context Protocol (MCP) via the stdio transport. You can build an MCP server by defining tools (inheriting from OmniAI::Tool) and running an OmniAI::MCP::Server with an OmniAI::MCP::Transport::Stdio instance.

class Weather < OmniAI::Tool
  description "Lookup the weather for a location"
  parameter :location, :string, description: "A location (e.g. 'London')."
  required %i[location]

  def execute(location:)
    location == 'London' ? 'Rainy' : 'Sunny'
  end
end

transport = OmniAI::MCP::Transport::Stdio.new
mcp = OmniAI::MCP::Server.new(tools: [Weather.new])
mcp.run(transport:)

OmniAI provides specialized gems for different AI providers. To use a specific provider, require its corresponding gem and initialize its client.

Supported providers include:

• Anthropic: OmniAI::Anthropic::Client
• DeepSeek: OmniAI::DeepSeek::Client
• Llama: OmniAI::Llama::Client
• Google: OmniAI::Google::Client
• Mistral: OmniAI::Mistral::Client
• OpenAI: OmniAI::OpenAI::Client

For OpenAI-compatible gateways (like LocalAI or Ollama), you can configure a custom host.

require 'omniai/openai'

# Standard OpenAI usage
client = OmniAI::OpenAI::Client.new(api_key: ENV.fetch('OPENAI_API_KEY'))

# Custom host (e.g., for LocalAI, Ollama, or private gateways)
client = OmniAI::OpenAI::Client.new(
  api_key: ENV.fetch('OPENAI_API_KEY'),
  host: ENV.fetch('OPENAI_HOST', 'https://api.openai.com')
)

To use OmniAI, install the main gem and the specific provider gem for the AI service you wish to use (e.g., Anthropic, OpenAI, Google, etc.).

Install the core gem:

gem install omniai

Install provider-specific gems as needed:

gem install omniai-anthropic
gem install omniai-deepseek
gem install omniai-mistral
gem install omniai-google
gem install omniai-openai

OmniAI automatically generates a tool name from the class name using the namify method. This converts CamelCase class names into snake_case strings and removes the Tool suffix.

Example mapping:

• WeatherTool $\rightarrow$ weather
• IBM::Watson::SearchTool $\rightarrow$ ibm_watson_search

You can customize client behavior by passing a logger or timeout settings during initialization.

• Logging: Pass any Ruby Logger instance to log requests and responses.
• Timeouts: Pass an integer for a total request/response timeout, or a hash for granular control over read, write, and connect durations.

require 'omniai/openai'
require 'logger'

# Logging requests/responses
logger = Logger.new(STDOUT)
client = OmniAI::OpenAI::Client.new(logger: logger)

# Simple integer timeout (seconds)
client = OmniAI::OpenAI::Client.new(timeout: 8)

# Granular timeout hash
client = OmniAI::OpenAI::Client.new(timeout: {
  read: 2,
  write: 3,
  connect: 4
})

To add support for a new embedding provider, you must create a subclass of OmniAI::Embed. Your implementation must define the payload and path methods to specify how the request is structured and where it is sent.

When implementing, you can also override context to provide serializers or deserializers specific to your provider, and params if the request requires additional query parameters.

class MyProvider::Embed < OmniAI::Embed
  module Model
    MY_MODEL = "my-model-name"
  end

  protected

  # Returns the JSON body for the request
  def payload
    { input: @input, model: @model }
  end

  # Returns the API endpoint path
  def path
    "/v1/embeddings"
  end
end

When using tools, OmniAI::Chat#process! automatically detects if the model requests a tool call. If tools are present, it executes them and continues the conversation to get a final response.

Error Handling

If a tool call fails or is misconfigured, the following errors may be raised:

• OmniAI::Chat::ToolCallError: A general error raised for tool-call issues.
• OmniAI::Chat::ToolCallMissingError: Raised when the model requests a tool that was not provided in the tools array.

The OmniAI::Chat::Stream class transforms fragmented JSON chunks into a coherent response. It handles the following logic:

1. Content Merging: It accumulates delta content into a single message["content"] string.
2. Tool Call Merging: If the model uses tools, it merges tool_calls by index and concatenates the function["arguments"] strings, which are typically sent in fragments.
3. Payload Structure: It converts a sequence of delta chunks like this:
   • { "id":"...", "choices": [{ "index": 0, "delta": { "role" :"assistant", "content":"" } }] }
   • { "id":"...", "choices": [{ "index": 0, "delta": { "content" :"A" } }] }
   • { "id":"...", "choices": [{ "index": 0, "delta": { "content" :"B" } }] }

Into a single combined payload structure containing the full message and tool call data.