### Text-to-Speech Usage Examples

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

Various examples demonstrating voice selection, format conversion, and speed adjustment.

```bash
# Save to file
omniai speak --voice=nova "Welcome to our service" > greeting.mp3

# Different format
omniai speak --voice=alloy --format=wav "Audio file" > output.wav

# Slower speech
omniai speak --speed=0.75 "This is spoken slowly"

# Faster speech
omniai speak --speed=1.5 "This is spoken quickly"
```

--------------------------------

### Install Provider Gems

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/README.md

Installation commands for various AI provider integrations.

```bash
gem install omniai-anthropic
```

```bash
gem install omniai-deepseek
```

```bash
gem install omniai-google
```

```bash
gem install omniai-llama
```

```bash
gem install omniai-mistral
```

```bash
gem install omniai-openai
```

--------------------------------

### Usage examples for Speak.process!

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/speak.md

Demonstrates streaming audio chunks to a file and retrieving a Tempfile.

```ruby
# Stream to file
File.open("output.wav", "wb") do |file|
  OmniAI::Speak.process!(
    "Hello, world!",
    client: client,
    model: "tts-1",
    voice: "alloy",
    format: OmniAI::Speak::Format::WAV
  ) do |chunk|
    file << chunk
  end
end

# Get tempfile
tempfile = OmniAI::Speak.process!(
  "Hello, world!",
  client: client,
  model: "tts-1",
  voice: "nova"
)
```

--------------------------------

### Initialize and process instance example

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/speak.md

Shows how to instantiate Speak and process the request with a block.

```ruby
speak = OmniAI::Speak.new(
  "The quick brown fox jumps over a lazy dog",
  client: client,
  model: "tts-1",
  voice: "alloy",
  format: OmniAI::Speak::Format::MP3
)

response = speak.process! do |chunk|
  # Stream chunks
  file << chunk
end
```

--------------------------------

### Usage examples for instance process!

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/speak.md

Demonstrates streaming with a block or retrieving a Tempfile from an existing instance.

```ruby
speak = OmniAI::Speak.new(
  "Hello world",
  client: client,
  model: "tts-1",
  voice: "nova"
)

# Stream with block
speak.process! do |chunk|
  puts "Got #{chunk.length} bytes"
end

# Or get tempfile
tempfile = speak.process!
```

--------------------------------

### Configure and Use Client

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/configuration.md

Full example demonstrating client initialization with logging and timeout settings, followed by a chat request.

```ruby
require 'omniai/openai'
require 'logger'

# Setup logging
logger = Logger.new(File.open("omniai.log", "a"))

# Configure client
client = OmniAI::OpenAI::Client.new(
  api_key: ENV['OPENAI_API_KEY'],
  logger: logger,
  timeout: {
    connect: 5,
    read: 30,
    write: 5
  }
)

# Use client
response = client.chat(
  "What is the capital of France?",
  model: "gpt-4o",
  temperature: 0.7
)

puts response.text
logger.close
```

--------------------------------

### Example Path Implementation

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/chat.md

Implementation of the path method for an OpenAI chat subclass.

```ruby
class OmniAI::OpenAI::Chat < OmniAI::Chat
  protected

  def path
    "/v1/chat/completions"
  end
end
```

--------------------------------

### Chat Output Example

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

Example output returned by the chat command.

```text
The capital of France is Paris.
```

--------------------------------

### Install OmniAI CLI

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

Install the core gem and necessary provider gems to enable CLI functionality.

```bash
gem install omniai
```

```bash
gem install omniai-openai
gem install omniai-anthropic
gem install omniai-google
# etc.
```

--------------------------------

### Transcribe with options

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

Examples of using language, format, and prompt options for transcription.

```bash
# English transcription
omniai transcribe --language=en interview.wav

# Output as VTT subtitles
omniai transcribe --format=vtt lecture.wav > lecture.vtt

# Output as SRT subtitles
omniai transcribe --format=srt movie.mp4 > movie.srt

# With context
omniai transcribe --prompt="Discussion about machine learning" podcast.mp3
```

--------------------------------

### Implement Basic MCP Server

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/mcp.md

Defines custom tools and starts an MCP server using the stdio transport.

```ruby
require 'omniai'

# Define tools
class Weather < OmniAI::Tool
  description "Get the weather for a location"

  parameter :location, :string, description: "A location (e.g. 'London')"
  required %i[location]

  def execute(location:)
    case location
    when "London" then "Rainy, 15°C"
    when "Paris" then "Sunny, 18°C"
    when "Tokyo" then "Clear, 22°C"
    else "Unknown location"
    end
  end
end

class Calculator < OmniAI::Tool
  description "Perform basic math operations"

  parameter :operation, :string, enum: %w[add subtract multiply divide]
  parameter :a, :number, description: "First number"
  parameter :b, :number, description: "Second number"
  required %i[operation a b]

  def execute(operation:, a:, b:)
    case operation
    when "add" then a + b
    when "subtract" then a - b
    when "multiply" then a * b
    when "divide" then b != 0 ? a / b : "Error: Division by zero"
    end
  end
end

# Create MCP server
transport = OmniAI::MCP::Transport::Stdio.new
server = OmniAI::MCP::Server.new(tools: [Weather.new, Calculator.new])

# Start server
server.run(transport: transport)
```

--------------------------------

### Interactive Chat Prompt Example

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

Example of the interactive prompt interface.

```text
Type 'exit' or 'quit' to abort.
# What is the capital of Spain?
```

--------------------------------

### Install OmniAI gems

Source: https://github.com/ksylvest/omniai/blob/main/README.md

Commands to install the core OmniAI gem and various provider-specific gems.

```sh
gem install omniai
```

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

--------------------------------

### Interactive Chat Response Example

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

Example of the response received in interactive mode.

```text
The capital of Spain is Madrid.
# Who is the current president of Spain?
```

--------------------------------

### Example Payload Implementation

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/chat.md

Implementation of the payload method for an OpenAI chat subclass.

```ruby
class OmniAI::OpenAI::Chat < OmniAI::Chat
  protected

  def payload
    {
      model: @model,
      messages: @prompt.serialize(context:),
      temperature: @temperature,
      tools: @tools&.map { |t| t.serialize(context:) },
    }.compact
  end
end
```

--------------------------------

### Use Chat Role Constants

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/chat.md

Example of using the role constant in a prompt message.

```ruby
prompt.message("Hello", role: OmniAI::Chat::Role::USER)
```

--------------------------------

### Handle ToolCallMissingError

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/chat.md

Example of rescuing a missing tool call error.

```ruby
begin
  # Model tries to call a tool that wasn't provided
  response = client.chat("Call the weather tool", model: "gpt-4")
rescue OmniAI::Chat::ToolCallMissingError => e
  puts "Model called undefined tool: #{e.tool_call.function.name}"
end
```

--------------------------------

### Tool#initialize

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/tool.md

Creates a new Tool instance with optional custom configuration.

```APIDOC
## Tool#initialize

### Description
Creates a new Tool instance with optional custom configuration.

### Parameters
- **function** (Proc) - Optional - Function to call when tool is invoked (Default: method(:execute))
- **name** (String) - Optional - Tool name (Default: class.namify)
- **description** (String) - Optional - Tool description (Default: class.description)
- **parameters** (OmniAI::Schema::Object) - Optional - Parameter schema (Default: class.parameters)
```

--------------------------------

### View CLI Help

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

Access help documentation for the main CLI or specific subcommands.

```bash
omniai --help
omniai chat --help
omniai embed --help
omniai speak --help
omniai transcribe --help
```

--------------------------------

### Client#initialize

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/client.md

Initializes a new client instance with configuration for API keys, logging, host URLs, and request timeouts.

```APIDOC
## Client#initialize

### Description
Initializes a client instance with optional configuration.

### Parameters
- **api_key** (String) - Optional - API key for the provider
- **logger** (Logger) - Optional - Ruby Logger instance
- **host** (String) - Optional - Custom host URL for API
- **timeout** (Integer, Hash) - Optional - Request timeout in seconds or hash with :read, :write, :connect keys

### Returns
- **OmniAI::Client** - The initialized client instance
```

--------------------------------

### Get Response Chain

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/response.md

Returns the sequence of responses from oldest to newest.

```ruby
response.response_chain
```

```ruby
# After tool call chain
chain = response.response_chain
chain.each_with_index do |r, i|
  puts "Turn #{i + 1}: #{r.text}"
end
```

--------------------------------

### Initialize a Tool instance

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/tool.md

Create a new tool instance by providing a function and metadata, or use class defaults.

```ruby
Tool.new(
  function = method(:execute),
  name: self.class.namify,
  description: self.class.description,
  parameters: self.class.parameters
)
```

```ruby
# Use class defaults
tool = WeatherTool.new

# Custom name and function
tool = WeatherTool.new(
  name: "weather_service",
  function: lambda { |location:| "Sunny, 72°F" }
)
```

--------------------------------

### Prompt.build

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/prompt.md

Creates a new Prompt instance and yields it to a block for configuration.

```APIDOC
## Prompt.build

### Description
Creates a new Prompt and yields it to a block for configuration.

### Signature
`OmniAI::Chat::Prompt.build { |prompt| ... }`

### Yields
The prompt instance for building messages.

### Returns
`OmniAI::Chat::Prompt`

### Example
```ruby
prompt = OmniAI::Chat::Prompt.build do |p|
  p.system("You are a helpful assistant.")
  p.user("What is the capital of France?")
end
```
```

--------------------------------

### Handle ToolCallError

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/chat.md

Example of rescuing a tool call error during a chat request.

```ruby
begin
  response = client.chat("Call a tool", model: "gpt-4", tools: [MyTool.new])
rescue OmniAI::Chat::ToolCallError => e
  puts "Tool call failed: #{e.tool_call.inspect}"
end
```

--------------------------------

### Get Finish Reason

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/response.md

Returns the normalized finish reason for the final turn.

```ruby
response.finish_reason
```

```ruby
response = client.chat("Tell a story", model: "gpt-4")
puts response.finish_reason.reason  # => "stop"
```

--------------------------------

### Build and execute a chat prompt

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/prompt.md

Demonstrates building a multi-turn chat prompt with system and user messages, including media attachments and model interaction.

```ruby
require 'omniai/openai'

client = OmniAI::OpenAI::Client.new

prompt = OmniAI::Chat::Prompt.build do |p|
  p.system("You are a helpful biologist.")
  
  p.user do |m|
    m.text("What animals are in these photos?")
    m.url("https://example.com/cat.jpg", "image/jpeg")
    m.url("https://example.com/dog.jpg", "image/jpeg")
  end
end

response = client.chat(prompt, model: "gpt-4-vision")
puts response.text

# Continue the conversation
prompt.assistant(response.text)
prompt.user("Are they domesticated?")

response = client.chat(prompt, model: "gpt-4-vision")
puts response.text
```

--------------------------------

### Initialize AI Clients

Source: https://github.com/ksylvest/omniai/blob/main/README.md

Standard initialization patterns for different AI provider clients.

```ruby
require 'omniai/anthropic'

client = OmniAI::Anthropic::Client.new
```

```ruby
require 'omniai/deepseek'

client = OmniAI::DeepSeek::Client.new
```

```ruby
require 'omniai/llama'

client = OmniAI::Llama::Client.new
```

```ruby
require 'omniai/google'

client = OmniAI::Google::Client.new
```

```ruby
require 'omniai/mistral'

client = OmniAI::Mistral::Client.new
```

```ruby
require 'omniai/openai'

client = OmniAI::OpenAI::Client.new
```

--------------------------------

### Initialize Google Client

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/configuration.md

Requires the GOOGLE_API_KEY environment variable for authentication.

```ruby
require 'omniai/google'

client = OmniAI::Google::Client.new(
  api_key: ENV['GOOGLE_API_KEY']  # Required; or use env var
)
```

--------------------------------

### Initialize OpenAI Client

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/configuration.md

Requires an API key from environment variables and supports custom host endpoints like LocalAI or Ollama.

```ruby
require 'omniai/openai'

client = OmniAI::OpenAI::Client.new(
  api_key: ENV['OPENAI_API_KEY'],  # Required; or use env var
  host: "https://api.openai.com"
)
```

--------------------------------

### Define OmniAI::LoadError class

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/types.md

Exception raised when a required provider gem is not installed.

```ruby
class OmniAI::LoadError < OmniAI::Error
end
```

--------------------------------

### Initialize Llama Client

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/configuration.md

Requires a host URL pointing to the running Llama server instance.

```ruby
require 'omniai/llama'

client = OmniAI::Llama::Client.new(
  host: "http://localhost:8000"  # Required; Llama server URL
)
```

--------------------------------

### JSON-RPC Response Format

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/mcp.md

Example of a successful JSON-RPC 2.0 response returned by the MCP server.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Rainy, 15°C"
}
```

--------------------------------

### Define and Run MCP Server with Tools

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/mcp.md

Demonstrates defining multiple tool classes inheriting from OmniAI::Tool and registering them with an MCP server instance.

```ruby
require 'omniai'

class GetTime < OmniAI::Tool
  description "Get current time"

  def execute
    Time.now.strftime("%Y-%m-%d %H:%M:%S")
  end
end

class Fortune < OmniAI::Tool
  description "Get a random fortune"

  def execute
    fortunes = [
      "A journey of a thousand miles begins with a single step.",
      "The only constant is change.",
      "To be or not to be, that is the question."
    ]
    fortunes.sample
  end
end

class Greeting < OmniAI::Tool
  description "Greet someone"

  parameter :name, :string, description: "Person's name"
  required %i[name]

  def execute(name:)
    "Hello, #{name}! Welcome to the MCP server."
  end
end

# Create and run server
tools = [GetTime.new, Fortune.new, Greeting.new]
transport = OmniAI::MCP::Transport::Stdio.new
server = OmniAI::MCP::Server.new(tools: tools)
server.run(transport: transport)
```

--------------------------------

### Initialize Speak instance

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/speak.md

Defines the signature for creating a new Speak instance.

```ruby
Speak.new(
  input,
  client:,
  model:,
  voice:,
  speed: nil,
  format: "aac"
)
```

--------------------------------

### Explore Models via CLI

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

Test different providers and models by passing flags directly to the chat command.

```bash
# Test different models
omniai chat --provider=openai --model=gpt-4 "Hello"
omniai chat --provider=anthropic --model=claude-3-5-sonnet "Hello"
omniai chat --provider=google --model=gemini-2.0-flash "Hello"
```

--------------------------------

### Interactive Embedding Mode

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

Starts an interactive session for embedding inputs when no text is provided as an argument.

```bash
omniai embed --model=text-embedding-3-small
```

--------------------------------

### Tool.description

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/tool.md

Gets or sets the description for the tool, which is used by the language model to understand the tool's purpose.

```APIDOC
## Tool.description

### Description
Gets or sets the tool description used in serialization for API communication.

### Signature
`Tool.description(description = nil)`

### Parameters
- **description** (String) - Optional - Tool description text

### Returns
- String (if getting) or void (if setting)
```

--------------------------------

### Build a new Prompt

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/prompt.md

Initializes a new prompt instance using a block for configuration.

```ruby
OmniAI::Chat::Prompt.build { |prompt| ... }
```

```ruby
prompt = OmniAI::Chat::Prompt.build do |p|
  p.system("You are a helpful assistant.")
  p.user("What is the capital of France?")
end
```

--------------------------------

### JSON-RPC Request Format

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/mcp.md

Example of a JSON-RPC 2.0 request payload used for calling tools on the MCP server.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "weather",
    "arguments": {
      "location": "London"
    }
  }
}
```

--------------------------------

### Define and retrieve tool description

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/tool.md

Use the description method to set or get the tool's purpose for the model.

```ruby
Tool.description(description = nil)
```

```ruby
class WeatherTool < OmniAI::Tool
  description "Get the weather for a location"
end

WeatherTool.description
# => "Get the weather for a location"
```

--------------------------------

### OmniAI::Chat::Prompt#initialize

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/prompt.md

Creates a new Prompt instance with an optional initial array of messages.

```APIDOC
## OmniAI::Chat::Prompt.new

### Description
Creates a new Prompt with optional initial messages.

### Parameters
- **messages** (Array<Message>) - Optional - Initial array of Message objects (default: [])

### Returns
OmniAI::Chat::Prompt

### Example
```ruby
prompt = OmniAI::Chat::Prompt.new(messages: [])
```
```

--------------------------------

### Configure Claude Desktop for MCP

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/mcp.md

Add the server configuration to the ~/.claude/claude.json file to enable the MCP server in Claude Desktop.

```json
{
  "mcpServers": {
    "my-server": {
      "command": "ruby",
      "args": ["/path/to/mcp_server.rb"]
    }
  }
}
```

--------------------------------

### Implement Comprehensive Error Handling in Ruby

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/errors.md

Use this pattern to catch specific OmniAI exceptions and handle unexpected errors during chat operations. Ensure the appropriate provider gem is installed to avoid LoadError.

```ruby
require 'omniai/openai'

client = OmniAI::OpenAI::Client.new

def handle_chat_safely(client, prompt, model)
  begin
    response = client.chat(prompt, model: model)
    puts "Response: #{response.text}"

  rescue OmniAI::Chat::ToolCallMissingError => e
    puts "ERROR: Model called undefined tool: #{e.tool_call.function.name}"
    puts "Provide the tool or update the system prompt"

  rescue OmniAI::Chat::ToolCallError => e
    puts "ERROR: Tool execution failed: #{e.message}"
    puts "Tool: #{e.tool_call.function.name}"

  rescue OmniAI::HTTPError => e
    puts "ERROR: API request failed: #{e.message}"
    if e.message.include?("401")
      puts "Check your API key"
    elsif e.message.include?("429")
      puts "Rate limited; wait before retrying"
    elsif e.message.include?("404")
      puts "Model not found; check model name"
    end

  rescue OmniAI::SSLError => e
    puts "ERROR: SSL verification failed: #{e.message}"
    puts "Check certificate configuration"

  rescue OmniAI::ParseError => e
    puts "ERROR: Response parsing failed: #{e.message}"

  rescue OmniAI::LoadError => e
    puts "ERROR: Provider not installed: #{e.message}"
    puts "Run: gem install omniai-openai"

  rescue OmniAI::Error => e
    puts "ERROR: OmniAI error: #{e.message}"
    puts e.backtrace.first(5)

  rescue StandardError => e
    puts "ERROR: Unexpected error: #{e.message}"
    puts e.backtrace.first(10)
  end
end

# Usage
handle_chat_safely(client, "What is 2+2?", "gpt-4o")
```

--------------------------------

### Initialize Mistral Client

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/configuration.md

Requires the MISTRAL_API_KEY environment variable for authentication.

```ruby
require 'omniai/mistral'

client = OmniAI::Mistral::Client.new(
  api_key: ENV['MISTRAL_API_KEY']  # Required; or use env var
)
```

--------------------------------

### OmniAI::Chat#initialize

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/chat.md

Constructor for creating a new Chat instance with specific configuration.

```APIDOC
## OmniAI::Chat#initialize

### Description
Creates a new Chat instance with configuration. Requires either a prompt or a block to define the conversation.

### Signature
`Chat.new(prompt = nil, client:, model:, temperature: nil, stream: nil, tools: nil, format: nil, **options, &block)`

### Parameters
- **prompt** (String, OmniAI::Chat::Prompt, nil) - Optional - Prompt text or object
- **client** (OmniAI::Client) - Required - Client instance
- **model** (String) - Required - Model identifier
- **temperature** (Float) - Optional - Sampling temperature (0.0 to 2.0)
- **stream** (Proc, IO) - Optional - Proc or IO for streaming output
- **tools** (Array<OmniAI::Tool>) - Optional - Tools the model can invoke
- **format** (Symbol, OmniAI::Schema::Format) - Optional - Output format
- **options** (Hash) - Optional - Provider-specific options

### Raises
- **ArgumentError** - If neither prompt nor block is provided.
```

--------------------------------

### Client.discover

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/client.md

Automatically discovers and instantiates the first available provider client.

```APIDOC
## Client.discover

### Description
Automatically discovers and instantiates the first available provider client in order: OpenAI, Anthropic, Google, Mistral, DeepSeek.

### Parameters
- **options** (Hash) - Optional - Provider-specific initialization options passed to the client constructor

### Returns
An instance of the first available provider client

### Raises
OmniAI::LoadError if no provider gems are installed
```

--------------------------------

### Define Global Configuration

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

Create a YAML configuration file at ~/.omniai/config.yml to persist settings.

```yaml
provider: openai
model: gpt-4
temperature: 0.7
api_key: sk-...
host: https://api.openai.com
timeout: 15
```

--------------------------------

### Synthesize Audio to Tempfile

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/speak.md

Shows how to generate a temporary audio file that handles cleanup automatically.

```ruby
require 'omniai/openai'

client = OmniAI::OpenAI::Client.new

# Get tempfile (handles cleanup)
tempfile = client.speak(
  "The quick brown fox jumps over the lazy dog",
  model: "tts-1",
  voice: "nova"
)

puts "Audio saved to: #{tempfile.path}"
puts "File size: #{File.size(tempfile.path)} bytes"

# Use the file...
# system("mpv #{tempfile.path}")

# Clean up
tempfile.close
tempfile.unlink
```

--------------------------------

### Implement Spawn Method

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/chat.md

Protected method that creates a new Chat instance with the same configuration but a different prompt.

```ruby
protected

def spawn!(prompt)
  self.class.new(
    prompt,
    client: @client,
    model: @model,
    temperature: @temperature,
    stream: @stream,
    tools: @tools,
    format: @format,
    **@options
  )
end
```

--------------------------------

### Synthesize Audio to File

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/speak.md

Demonstrates how to save synthesized audio to a file using specific formats and iterating through multiple voices.

```ruby
require 'omniai/openai'

client = OmniAI::OpenAI::Client.new

# Synthesize and save as WAV
File.open("greeting.wav", "wb") do |file|
  client.speak(
    "Welcome to the podcast",
    model: "tts-1",
    voice: "alloy",
    format: OmniAI::Speak::Format::WAV
  ) do |chunk|
    file << chunk
  end
end

puts "Saved to greeting.wav"

# Synthesize multiple voices
voices = %w[alloy echo fable onyx nova shimmer]

voices.each do |voice|
  filename = "demo_#{voice}.mp3"
  File.open(filename, "wb") do |file|
    client.speak(
      "Hello! This is the #{voice} voice.",
      model: "tts-1",
      voice: voice,
      format: OmniAI::Speak::Format::MP3
    ) do |chunk|
      file << chunk
    end
  end

  puts "Created #{filename}"
end
```

--------------------------------

### OmniAI::Speak.new

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/speak.md

Initializes a new Speak instance with the required configuration for text-to-speech synthesis.

```APIDOC
## OmniAI::Speak.new

### Description
Creates a new instance of the Speak class to prepare a text-to-speech request.

### Parameters
- **input** (String) - Required - Text to synthesize
- **client** (OmniAI::Client) - Required - Client instance
- **model** (String) - Required - Model identifier
- **voice** (String) - Required - Voice name
- **speed** (Float) - Optional - Speed multiplier
- **format** (String) - Optional - Output format (default: "aac")
```

--------------------------------

### Initialize a Chat instance

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/chat.md

Creates a new chat instance using either a direct prompt or a block for message construction.

```ruby
Chat.new(
  prompt = nil,
  client:,
  model:,
  temperature: nil,
  stream: nil,
  tools: nil,
  format: nil,
  **options,
  &block
)
```

```ruby
# With text prompt
chat = OmniAI::Chat.new(
  "Hello!",
  client: client,
  model: "gpt-4"
)

# With block
chat = OmniAI::Chat.new(client: client, model: "gpt-4") do |prompt|
  prompt.system("You are a helpful assistant.")
  prompt.user("What is 2+2?")
end
```

--------------------------------

### Set Default CLI Settings

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

Configure default provider, model, and temperature settings via environment variables.

```bash
export OMNIAI_PROVIDER="openai"
export OMNIAI_MODEL="gpt-4"
export OMNIAI_TEMPERATURE="0.7"
```

--------------------------------

### Initialize Anthropic Client

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/configuration.md

Requires the ANTHROPIC_API_KEY environment variable for authentication.

```ruby
require 'omniai/anthropic'

client = OmniAI::Anthropic::Client.new(
  api_key: ENV['ANTHROPIC_API_KEY']  # Required; or use env var
)
```

--------------------------------

### Initialize DeepSeek Client

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/configuration.md

Requires the DEEPSEEK_API_KEY environment variable for authentication.

```ruby
require 'omniai/deepseek'

client = OmniAI::DeepSeek::Client.new(
  api_key: ENV['DEEPSEEK_API_KEY']  # Required; or use env var
)
```

--------------------------------

### Set Provider API Keys

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

Export required environment variables to authenticate with various AI providers.

```bash
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="..."
export MISTRAL_API_KEY="..."
export DEEPSEEK_API_KEY="sk-..."
```

--------------------------------

### Initialize a new Response instance

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/response.md

Creates a new instance of the Response class using raw provider data and optional completion choices or usage metrics.

```ruby
OmniAI::Chat::Response.new(data:, choices: [], usage: nil, finish_reason: nil)
```

```ruby
response = OmniAI::Chat::Response.new(
  data: { ... },
  choices: [choice1, choice2],
  usage: usage
)
```

--------------------------------

### Configure OpenAI Gateway

Source: https://github.com/ksylvest/omniai/blob/main/README.md

Initialize an OpenAI client with a custom host for private gateways or local servers.

```ruby
require 'omniai/openai'

client = OmniAI::OpenAI::Client.new(
  api_key: ENV.fetch('OPENAI_API_KEY'),
  host: ENV.fetch('OPENAI_HOST', 'https://api.openai.com')
)
```

--------------------------------

### Adjusting Speech Speed with Ruby

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/speak.md

Demonstrates how to control the playback speed of generated audio using the speed parameter in the speak method.

```ruby
require 'omniai/openai'

client = OmniAI::OpenAI::Client.new

text = "The quick brown fox jumps over a lazy dog"

# Normal speed
File.open("normal.mp3", "wb") do |f|
  client.speak(text, model: "tts-1", voice: "alloy", format: "mp3") do |chunk|
    f << chunk
  end
end

# Faster speech (1.5x)
File.open("fast.mp3", "wb") do |f|
  client.speak(
    text,
    model: "tts-1",
    voice: "alloy",
    speed: 1.5,
    format: "mp3"
  ) do |chunk|
    f << chunk
  end
end

# Slower speech (0.75x)
File.open("slow.mp3", "wb") do |f|
  client.speak(
    text,
    model: "tts-1",
    voice: "alloy",
    speed: 0.75,
    format: "mp3"
  ) do |chunk|
    f << chunk
  end
end
```

--------------------------------

### Initialize and execute a basic chat

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/README.md

Requires the omniai-openai gem. Demonstrates the simplest path to generating a chat response.

```ruby
require 'omniai/openai'

client = OmniAI::OpenAI::Client.new

response = client.chat("What is 2+2?", model: "gpt-4o")
puts response.text
```

--------------------------------

### Initialize a new Prompt

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/prompt.md

Creates a new instance of the Prompt class with an optional initial array of messages.

```ruby
OmniAI::Chat::Prompt.new(messages: [])
```

```ruby
prompt = OmniAI::Chat::Prompt.new(messages: [])
```

--------------------------------

### Initialize and process with Transcribe instance

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/transcribe.md

Creates a new instance for transcription and processes it, useful for handling file objects directly.

```ruby
Transcribe.new(
  io,
  client:,
  model:,
  language: nil,
  prompt: nil,
  temperature: nil,
  format: nil
)
```

```ruby
File.open("audio.wav", "rb") do |file|
  transcribe = OmniAI::Transcribe.new(
    file,
    client: client,
    model: "whisper-1",
    language: "en"
  )

  transcription = transcribe.process!
  puts transcription.text
end
```

--------------------------------

### Discover Available Provider Client

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/client.md

Automatically discovers and instantiates the first available provider client.

```ruby
OmniAI::Client.discover(**options)
```

```ruby
client = OmniAI::Client.discover
response = client.chat("Hello!")
```

--------------------------------

### Implement Safe Tool Error Handling

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/mcp.md

Wrap tool logic in begin-rescue blocks to return descriptive error messages instead of crashing.

```ruby
class SafeTool < OmniAI::Tool
  def execute(...)
    begin
      # Tool logic
    rescue => e
      "Error: #{e.message}"
    end
  end
end
```

--------------------------------

### Compare JSON Mode and Structured Output in Ruby

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/schema.md

Demonstrates the difference between requesting raw JSON output and enforcing a specific schema using OmniAI::Schema.format.

```ruby
# JSON Mode - tells model to output JSON
response = client.chat(
  "Return a contact as JSON",
  model: "gpt-4",
  format: :json
)

# Structured Output - constrains to a schema
contact_schema = OmniAI::Schema.format(
  name: "Contact",
  schema: OmniAI::Schema.object(...)
)

response = client.chat(
  "Extract contact",
  model: "gpt-4",
  format: contact_schema
)
```

--------------------------------

### OmniAI::Chat::Response.new

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/response.md

Initializes a new instance of the Response class with raw data, choices, usage, and finish reason.

```APIDOC
## OmniAI::Chat::Response.new

### Description
Creates a new Response instance to encapsulate chat completion results.

### Parameters
- **data** (Hash) - Required - Raw response data from the provider
- **choices** (Array<Choice>) - Optional - Array of completion choices
- **usage** (Usage) - Optional - Token usage information
- **finish_reason** (FinishReason) - Optional - Response-level finish reason

### Example
```ruby
response = OmniAI::Chat::Response.new(
  data: { ... },
  choices: [choice1, choice2],
  usage: usage
)
```
```

--------------------------------

### Execute instance process method

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/transcribe.md

Triggers the transcription process on an existing instance.

```ruby
transcribe.process!
```

--------------------------------

### Client.google

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/client.md

Returns the Google client class. Requires the omniai-google gem.

```APIDOC
## Client.google

### Description
Returns the Google client class. Requires the omniai-google gem.

### Returns
Class<OmniAI::Google::Client>

### Raises
OmniAI::LoadError if the gem is not installed
```

--------------------------------

### Initialize OmniAI Client

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/client.md

Initializes a new client instance with optional configuration for API keys, logging, and request timeouts.

```ruby
Client.new(api_key: nil, logger: nil, host: nil, timeout: nil)
```

```ruby
require 'omniai/openai'
require 'logger'

logger = Logger.new(STDOUT)

# Simple timeout (all operations)
client = OmniAI::OpenAI::Client.new(
  api_key: ENV.fetch('OPENAI_API_KEY'),
  timeout: 8
)

# Fine-grained timeout control
client = OmniAI::OpenAI::Client.new(
  timeout: {
    read: 2,
    write: 3,
    connect: 4,
  }
)
```

--------------------------------

### Execute Basic Chat

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

Send a prompt to the default AI provider via the chat command.

```bash
omniai chat "What is the capital of France?"
```

--------------------------------

### Define and Run an MCP Server in Ruby

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/mcp.md

Implement custom tools by inheriting from OmniAI::Tool and execute the server using the Stdio transport.

```ruby
require 'omniai'
require 'json'

# Database query tool
class QueryDatabase < OmniAI::Tool
  description "Query the application database"

  parameter :query, :string, description: "SQL query"
  parameter :limit, :integer, description: "Max results"
  required %i[query]

  def execute(query:, limit: 10)
    # Simulated database query
    {
      query: query,
      limit: limit,
      results: [
        { id: 1, name: "Item 1" },
        { id: 2, name: "Item 2" }
      ]
    }.to_json
  end
end

# Email tool
class SendEmail < OmniAI::Tool
  description "Send an email"

  parameter :to, :string, description: "Email recipient"
  parameter :subject, :string, description: "Email subject"
  parameter :body, :string, description: "Email body"
  required %i[to subject body]

  def execute(to:, subject:, body:)
    # Simulated email sending
    "Email sent to #{to} with subject '#{subject}'"
  end
end

# File operations
class ReadFile < OmniAI::Tool
  description "Read file contents"

  parameter :path, :string, description: "File path"
  required %i[path]

  def execute(path:)
    if File.exist?(path)
      File.read(path)
    else
      "Error: File not found: #{path}"
    end
  end
end

# Create and run server with all tools
tools = [
  QueryDatabase.new,
  SendEmail.new,
  ReadFile.new
]

transport = OmniAI::MCP::Transport::Stdio.new
server = OmniAI::MCP::Server.new(tools: tools)
server.run(transport: transport)
```

--------------------------------

### Streaming Audio to Network with Ruby

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/speak.md

Shows how to stream audio chunks directly to an HTTP endpoint using Net::HTTP.

```ruby
require 'omniai/openai'
require 'net/http'

client = OmniAI::OpenAI::Client.new

# Stream audio directly to an HTTP endpoint
uri = URI("http://example.com/audio-upload")
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.path, { "Content-Type" => "audio/mpeg" })

# Use Net::HTTPGenericRequest with streaming body
client.speak(
  "Streaming audio content",
  model: "tts-1",
  voice: "nova",
  format: "mp3"
) do |chunk|
  # Send chunk to network
  http.send_request(request, chunk)
end
```

--------------------------------

### Chat via CLI

Source: https://github.com/ksylvest/omniai/blob/main/README.md

Interact with AI models using prompts or interactive mode with specific provider configurations.

```bash
omniai chat "What is the coldest place on earth?"
```

```bash
omniai chat --provider="openai" --model="gpt-4" --temperature="0.5"
```

--------------------------------

### Text-to-Speech Command Syntax

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

General syntax for the speak command with optional parameters.

```bash
omniai speak [options] [text]
```

--------------------------------

### Audio processing pipeline

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/cli.md

Workflow for recording audio, transcribing it, and summarizing the result.

```bash
# Record, transcribe, and chat about it
# (Requires additional tools like ffmpeg, sox)

# 1. Record audio (5 seconds)
sox -n audio.wav trim 0 5

# 2. Transcribe
transcript=$(omniai transcribe audio.wav)

# 3. Chat about the transcription
echo "Transcription: $transcript"
omniai chat "Summarize this: $transcript"
```

--------------------------------

### Implement and Use Tools

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/chat.md

Defines a custom tool by inheriting from OmniAI::Tool and passes it to the chat client for automatic execution.

```ruby
class WeatherTool < OmniAI::Tool
  description "Get the weather for a location"
  parameter :location, :string, description: "City name"
  required %i[location]

  def execute(location:)
    "Sunny, 75°F"
  end
end

response = client.chat(
  "What's the weather in Paris?",
  model: "gpt-4",
  tools: [WeatherTool.new]
)
# Model automatically calls the tool and continues
puts response.text
```

--------------------------------

### Execute Chat Requests

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/configuration.md

Demonstrates standard chat requests, streaming responses to STDOUT, and requesting structured output using schemas.

```ruby
response = client.chat(
  "What is the capital of France?",
  model: "gpt-4o",
  temperature: 0.7
)

# With streaming
client.chat(
  "Tell me a story",
  model: "gpt-4o",
  stream: $stdout
)

# With structured output
response = client.chat(
  "Extract info",
  model: "gpt-4o",
  format: contact_schema
)
```

--------------------------------

### Perform chat with image inputs

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/README.md

Uses a block-based prompt builder to include system instructions and image URLs.

```ruby
response = client.chat(model: "gpt-4-vision") do |prompt|
  prompt.system("You are a biologist.")
  prompt.user do |message|
    message.text("What animal is this?")
    message.url("https://example.com/cat.jpg", "image/jpeg")
  end
end
```

--------------------------------

### Client.openai

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/client.md

Returns the OpenAI client class. Requires the omniai-openai gem.

```APIDOC
## Client.openai

### Description
Returns the OpenAI client class. Requires the omniai-openai gem.

### Returns
Class<OmniAI::OpenAI::Client>

### Raises
OmniAI::LoadError if the gem is not installed
```

--------------------------------

### Implement an MCP Server

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/README.md

Expose tools to external applications like Claude Desktop by running an MCP server with a defined transport.

```ruby
class WeatherTool < OmniAI::Tool
  # ... tool definition
end

transport = OmniAI::MCP::Transport::Stdio.new
server = OmniAI::MCP::Server.new(tools: [WeatherTool.new])
server.run(transport: transport)
```

--------------------------------

### Test MCP Server via stdin/stdout

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/mcp.md

Use standard input and output streams to manually verify JSON-RPC requests against the server process.

```bash
# Start server
ruby mcp_server.rb &
SERVER_PID=$!

# Send a request
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"weather","arguments":{"location":"London"}}}' | \
  ruby mcp_server.rb

# Kill server
kill $SERVER_PID
```

--------------------------------

### Execute OmniAI CLI Commands

Source: https://github.com/ksylvest/omniai/blob/main/README.md

Use the CLI for quick testing of chat, speech-to-text, text-to-speech, and embedding features.

```bash
# Chat

omniai chat "Who designed the Ruby programming language?"
omniai chat --provider="google" --model="gemini-2.0-flash" "Who are you?"

## Speech to Text

omniai speak "Salley sells sea shells by the sea shore." > ./files/audio.wav

# Text to Speech

omniai transcribe "./files/audio.wav"

# Embed

omniai embed "What is the capital of France?"
```

--------------------------------

### Use OmniAI CLI

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/README.md

Execute common tasks like chatting, embedding, and media processing directly from the command line.

```bash
# Chat
omniai chat "What is 2+2?"
omniai chat --provider=openai --model=gpt-4 "What is AI?"

# Interactive
omniai chat

# Embeddings
omniai embed "Hello world"

# Text-to-speech
omniai speak "Hello" > output.mp3

# Speech-to-text
omniai transcribe audio.wav
```

--------------------------------

### Select Chat Models

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/configuration.md

Constants for specifying models when initializing chat requests.

```ruby
OmniAI::OpenAI::Chat::Model::GPT_4O
OmniAI::OpenAI::Chat::Model::GPT_4_TURBO
OmniAI::OpenAI::Chat::Model::GPT_35_TURBO
```

```ruby
OmniAI::Anthropic::Chat::Model::CLAUDE_3_5_SONNET
OmniAI::Anthropic::Chat::Model::CLAUDE_3_OPUS
OmniAI::Anthropic::Chat::Model::CLAUDE_3_SONNET
```

```ruby
OmniAI::Google::Chat::Model::GEMINI_2_0_FLASH
OmniAI::Google::Chat::Model::GEMINI_1_5_PRO
```

```ruby
OmniAI::Mistral::Chat::Model::LARGE
OmniAI::Mistral::Chat::Model::MEDIUM
```

--------------------------------

### Integrate OmniAI tools with chat

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/mcp.md

Demonstrates using tools with an OpenAI client, which are also compatible with MCP.

```ruby
require 'omniai/openai'

client = OmniAI::OpenAI::Client.new

tools = [Weather.new, Calculator.new]

# Use tools with chat (they also work in MCP)
response = client.chat(
  "What's the weather in Paris and what is 10 + 5?",
  model: "gpt-4o",
  tools: tools
)

puts response.text
```

--------------------------------

### Batch Synthesis with Ruby

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/speak.md

Iterates through a collection of text inputs to generate multiple audio files sequentially.

```ruby
require 'omniai/openai'

client = OmniAI::OpenAI::Client.new

chapters = [
  { title: "Introduction", text: "Welcome to our story..." },
  { title: "Chapter One", text: "It was a dark and stormy night..." },
  { title: "Chapter Two", text: "The sun rose over the horizon..." }
]

chapters.each_with_index do |chapter, idx|
  filename = "chapter_#{idx + 1}_#{chapter[:title].downcase.tr(' ', '_')}.mp3"

  File.open(filename, "wb") do |file|
    client.speak(
      chapter[:text],
      model: "tts-1",
      voice: "nova",
      format: "mp3"
    ) do |chunk|
      file << chunk
    end
  end

  puts "Generated #{filename}"
end
```

--------------------------------

### Initialize and Inspect Chat Message

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/types.md

Creates a new message instance and accesses its properties.

```ruby
message = OmniAI::Chat::Message.new(
  content: "Hello!",
  role: OmniAI::Chat::Role::USER
)

puts message.text
puts message.direction  # => "input"
```

--------------------------------

### Implement and execute a Tool

Source: https://github.com/ksylvest/omniai/blob/main/_autodocs/api-reference/tool.md

Define tool logic by overriding the execute method in a subclass and invoke it with arguments.

```ruby
def execute(...)
  raise NotImplementedError, "#{self.class}#execute undefined"
end
```

```ruby
class WeatherTool < OmniAI::Tool
  description "Get the weather"
  parameter :location, :string
  required %i[location]

  def execute(location:)
    # Your implementation
    "Sunny, 72°F at #{location}"
  end
end

tool = WeatherTool.new
tool.execute(location: "London")
# => "Sunny, 72°F at London"
```