zuno 0.1.4 → 1.0.0

data/lib/zuno.rb

@@ -1,19 +1,1424 @@
 # frozen_string_literal: true
 
+require "json"
+require "securerandom"
+require "cgi"
+require "typhoeus"
+
 require_relative "zuno/version"
-require_relative "zuno/configuration"
-require "zuno/chat"
-require "zuno/transcription"
-require "zuno/translation"
-require "faraday"
 
 module Zuno
-  class << self
-    attr_accessor :configuration
+  class Error < StandardError; end
+  class ProviderError < Error; end
+  class ToolError < Error; end
+  class MaxIterationsExceeded < Error; end
+  class StreamingError < Error; end
+  class CallbackControl
+    attr_reader :stop_reason
+
+    def initialize
+      @stopped = false
+      @stop_reason = nil
+    end
+
+    def stop!(reason: nil)
+      @stopped = true
+      @stop_reason = reason
+    end
+
+    def stopped?
+      @stopped
+    end
+  end
+
+  ModelDescriptor = Struct.new(:id, :provider, :provider_options, keyword_init: true) do
+    def initialize(id:, provider:, provider_options: {})
+      super(
+        id: id.to_s,
+        provider: provider.to_sym,
+        provider_options: provider_options.is_a?(Hash) ? provider_options : {}
+      )
+    end
+  end
+
+  ToolDefinition = Struct.new(:name, :description, :input_schema, :execute_proc, keyword_init: true) do
+    def initialize(name:, description:, input_schema:, execute_proc:)
+      super(
+        name: name.to_s,
+        description: description.to_s,
+        input_schema: input_schema.is_a?(Hash) ? input_schema : {},
+        execute_proc: execute_proc
+      )
+    end
+
+    def as_provider_tool
+      {
+        type: "function",
+        function: {
+          name: name,
+          description: description,
+          parameters: input_schema
+        }
+      }
+    end
+
+    def execute(arguments)
+      raise ToolError, "Tool '#{name}' is missing an execute block" unless execute_proc.respond_to?(:call)
+
+      symbolized_args = arguments.each_with_object({}) { |(key, value), acc| acc[key.to_sym] = value }
+
+      begin
+        execute_proc.call(arguments)
+      rescue ArgumentError, TypeError
+        execute_proc.call(**symbolized_args)
+      end
+    end
+  end
+
+  OPENROUTER_ADAPTER_CONFIG_KEYS = %i[api_key app_url title timeout].freeze
+  REPLICATE_ADAPTER_CONFIG_KEYS = %i[api_key timeout].freeze
+  DEFAULT_MAX_ITERATIONS = 1
+  REPLICATE_PREFER_WAIT_SECONDS = 60
+  REPLICATE_POLL_INTERVAL_SECONDS = 1
+  REPLICATE_WAIT_TIMEOUT_SECONDS = 600
+  REPLICATE_TERMINAL_STATUSES = %w[succeeded failed canceled aborted].freeze
+
+  module_function
+
+  def default_provider_options
+    @default_provider_options ||= {}
+  end
+
+  def default_provider_options=(options)
+    @default_provider_options = options.is_a?(Hash) ? options : {}
+  end
+
+  def model(id, provider: :openrouter, provider_options: {})
+    ModelDescriptor.new(id: id, provider: provider, provider_options: provider_options)
+  end
+
+  def openrouter(api_key: nil, app_url: nil, title: nil, timeout: Providers::OpenRouter::DEFAULT_TIMEOUT)
+    Providers::OpenRouter.new(
+      api_key: api_key,
+      app_url: app_url,
+      title: title,
+      timeout: timeout
+    )
+  end
+
+  def replicate(api_key: nil, timeout: Providers::Replicate::DEFAULT_TIMEOUT)
+    Providers::Replicate.new(
+      api_key: api_key,
+      timeout: timeout
+    )
+  end
+
+  def tool(name:, description:, input_schema:, &execute)
+    raise ToolError, "A block is required for tool '#{name}'" unless block_given?
+
+    ToolDefinition.new(
+      name: name,
+      description: description,
+      input_schema: input_schema,
+      execute_proc: execute
+    )
+  end
+
+  def generate(
+    model:,
+    messages: nil,
+    system: nil,
+    prompt: nil,
+    input: nil,
+    tools: {},
+    tool_choice: nil,
+    temperature: nil,
+    max_tokens: nil,
+    provider_options: {},
+    before_tool_execution: nil,
+    after_tool_execution: nil,
+    before_generation: nil,
+    after_generation: nil
+  )
+    callback_control = nil
+    after_generation_called = false
+    callback_control = CallbackControl.new
+
+    model_descriptor = normalize_model(model)
+    resolved_provider_options = merge_provider_options(
+      model_descriptor.provider_options,
+      provider_options
+    )
+    provider = model_descriptor.provider.to_sym
+
+    call_callback!(
+      before_generation,
+      {
+        model: model_descriptor,
+        mode: "single",
+        provider: provider
+      },
+      callback_control
+    )
+
+    if callback_control.stopped?
+      result = callback_stopped_result(
+        control: callback_control,
+        iterations: [],
+        message: {},
+        usage: nil,
+        raw_response: nil
+      )
+      after_generation_called = true
+      call_callback!(after_generation, { ok: true, result: result }, callback_control)
+      return result
+    end
+
+    result =
+      case provider
+      when :openrouter
+        adapter = provider_adapter(provider, resolved_provider_options)
+        generate_openrouter_single(
+          model_descriptor: model_descriptor,
+          adapter: adapter,
+          messages: messages,
+          system: system,
+          prompt: prompt,
+          tools: tools,
+          tool_choice: tool_choice,
+          temperature: temperature,
+          max_tokens: max_tokens,
+          provider_options: resolved_provider_options,
+          before_tool_execution: before_tool_execution,
+          after_tool_execution: after_tool_execution
+        )
+      when :replicate
+        raise Error, "tools are not supported for replicate generate" unless normalize_tools(tools).empty?
+        raise Error, "tool_choice is not supported for replicate generate" unless tool_choice.nil?
+
+        validate_no_webhook_support!(resolved_provider_options)
+        adapter = provider_adapter(provider, resolved_provider_options)
+        generate_replicate_single(
+          model_descriptor: model_descriptor,
+          adapter: adapter,
+          input: input,
+          provider_options: resolved_provider_options
+        )
+      else
+        raise ProviderError, "Unsupported provider: #{provider}"
+      end
+
+    after_generation_called = true
+    call_callback!(after_generation, { ok: true, result: result }, callback_control)
+    result
+  rescue ProviderError => e
+    unless after_generation_called
+      after_generation_called = true
+      call_callback!(after_generation, { ok: false, error: e }, callback_control)
+    end
+    raise
+  rescue StandardError => e
+    unless after_generation_called
+      after_generation_called = true
+      call_callback!(after_generation, { ok: false, error: e }, callback_control)
+    end
+    raise Error, e.message
+  end
+
+  def loop(
+    model:,
+    messages: nil,
+    system: nil,
+    prompt: nil,
+    tools: {},
+    tool_choice: nil,
+    stop_when: nil,
+    max_iterations: DEFAULT_MAX_ITERATIONS,
+    temperature: nil,
+    max_tokens: nil,
+    provider_options: {},
+    before_tool_execution: nil,
+    after_tool_execution: nil,
+    before_iteration: nil,
+    after_iteration: nil,
+    before_generation: nil,
+    after_generation: nil
+  )
+    callback_control = nil
+    model_descriptor = normalize_model(model)
+    raise Error, "loop only supports openrouter provider" unless model_descriptor.provider.to_sym == :openrouter
+
+    resolved_provider_options = merge_provider_options(
+      model_descriptor.provider_options,
+      provider_options
+    )
+    adapter = provider_adapter(model_descriptor.provider, resolved_provider_options)
+    tool_map = normalize_tools(tools)
+    llm_messages = normalize_messages(messages: messages, system: system, prompt: prompt)
+    resolved_tool_choice = normalize_tool_choice(
+      explicit_tool_choice: tool_choice,
+      provider_options: resolved_provider_options,
+      tools: tool_map
+    )
+    resolved_stop_when = normalize_stop_when(stop_when)
+    resolved_max_iterations = normalize_max_iterations(max_iterations)
+    after_generation_called = false
+    callback_control = CallbackControl.new
+
+    call_callback!(
+      before_generation,
+      {
+        model: model_descriptor,
+        messages: llm_messages,
+        tool_names: tool_map.keys,
+        tool_choice: resolved_tool_choice,
+        max_iterations: resolved_max_iterations,
+        stop_when: resolved_stop_when
+      },
+      callback_control
+    )
+    if callback_control.stopped?
+      result = callback_stopped_result(
+        control: callback_control,
+        iterations: [],
+        message: {},
+        usage: nil,
+        raw_response: nil
+      )
+      after_generation_called = true
+      call_callback!(after_generation, { ok: true, result: result }, callback_control)
+      return result
+    end
+
+    iterations = []
+    iteration_count = 0
+
+    infinite_iterations = resolved_max_iterations == :infinite
+
+    while infinite_iterations || iteration_count < resolved_max_iterations
+      current_iteration = iteration_count + 1
+      call_callback!(
+        before_iteration,
+        {
+          iteration_index: current_iteration,
+          messages: llm_messages
+        },
+        callback_control
+      )
+      if callback_control.stopped?
+        result = callback_stopped_result(
+          control: callback_control,
+          iterations: iterations,
+          message: {},
+          usage: nil,
+          raw_response: nil
+        )
+        after_generation_called = true
+        call_callback!(after_generation, { ok: true, result: result }, callback_control)
+        return result
+      end
+
+      payload = build_payload(
+        model_id: model_descriptor.id,
+        messages: llm_messages,
+        tools: tool_map,
+        tool_choice: resolved_tool_choice,
+        temperature: temperature,
+        max_tokens: max_tokens,
+        provider_options: resolved_provider_options
+      )
+
+      response = adapter.chat(payload)
+      message = response.dig("choices", 0, "message") || {}
+      tool_calls = Array(message["tool_calls"])
+
+      iteration_record = {
+        index: current_iteration,
+        message: message,
+        tool_calls: tool_calls,
+        usage: response["usage"],
+        finish_reason: response.dig("choices", 0, "finish_reason"),
+        tool_results: []
+      }
+
+      if tool_calls.empty?
+        iterations << iteration_record
+        call_callback!(
+          after_iteration,
+          {
+            iteration_index: current_iteration,
+            iteration: iteration_record
+          },
+          callback_control
+        )
+        if callback_control.stopped?
+          result = callback_stopped_result(
+            control: callback_control,
+            iterations: iterations,
+            message: message,
+            usage: response["usage"],
+            raw_response: response
+          )
+          after_generation_called = true
+          call_callback!(after_generation, { ok: true, result: result }, callback_control)
+          return result
+        end
+
+        result = {
+          text: extract_message_text(message),
+          message: message,
+          usage: response["usage"],
+          finish_reason: response.dig("choices", 0, "finish_reason"),
+          iterations: iterations,
+          raw_response: response
+        }
+
+        after_generation_called = true
+        call_callback!(after_generation, { ok: true, result: result }, callback_control)
+        return result
+      end
+
+      llm_messages << build_assistant_tool_call_message(message: message, tool_calls: tool_calls)
+      stop_triggered = false
+      stop_triggered_tool_name = nil
+
+      tool_calls.each do |tool_call|
+        tool_call_id = normalize_tool_call_id(tool_call["id"])
+        arguments = parse_arguments(tool_call.dig("function", "arguments"))
+        tool_name = tool_call.dig("function", "name").to_s
+
+        call_callback!(
+          before_tool_execution,
+          {
+            iteration_index: current_iteration,
+            tool_call_id: tool_call_id,
+            tool_name: tool_name,
+            input: arguments,
+            raw_tool_call: tool_call
+          },
+          callback_control
+        )
+
+        tool_result = execute_tool_call(
+          tool_call: tool_call,
+          tools: tool_map,
+          tool_call_id: tool_call_id,
+          arguments: arguments
+        )
+
+        iteration_record[:tool_results] << tool_result
+        call_callback!(
+          after_tool_execution,
+          tool_result.merge(iteration_index: current_iteration),
+          callback_control
+        )
+        if tool_stop_condition_met?(resolved_stop_when, tool_result)
+          stop_triggered = true
+          stop_triggered_tool_name ||= tool_result[:tool_name]
+        end
+
+        llm_messages << {
+          "role" => "tool",
+          "tool_call_id" => tool_result[:tool_call_id],
+          "content" => serialize_tool_content(tool_result[:output])
+        }
+      end
+
+      iterations << iteration_record
+      call_callback!(
+        after_iteration,
+        {
+          iteration_index: current_iteration,
+          iteration: iteration_record
+        },
+        callback_control
+      )
+      if callback_control.stopped?
+        result = callback_stopped_result(
+          control: callback_control,
+          iterations: iterations,
+          message: message,
+          usage: response["usage"],
+          raw_response: response
+        )
+        after_generation_called = true
+        call_callback!(after_generation, { ok: true, result: result }, callback_control)
+        return result
+      end
+
+      if stop_triggered
+        result = {
+          text: extract_message_text(message),
+          message: message,
+          usage: response["usage"],
+          finish_reason: "stop_when_tool_called",
+          stop_reason: {
+            type: "tool_called",
+            tool_name: stop_triggered_tool_name
+          },
+          iterations: iterations,
+          raw_response: response
+        }
+
+        after_generation_called = true
+        call_callback!(after_generation, { ok: true, result: result }, callback_control)
+        return result
+      end
+
+      iteration_count += 1
+    end
+
+    raise MaxIterationsExceeded,
+      "Reached max_iterations=#{resolved_max_iterations} without a final assistant response" unless infinite_iterations
+  rescue ProviderError, MaxIterationsExceeded => e
+    unless after_generation_called
+      after_generation_called = true
+      call_callback!(after_generation, { ok: false, error: e }, callback_control)
+    end
+    raise
+  rescue StandardError => e
+    unless after_generation_called
+      after_generation_called = true
+      call_callback!(after_generation, { ok: false, error: e }, callback_control)
+    end
+    raise Error, e.message
+  end
+
+  def stream(
+    model:,
+    messages: nil,
+    system: nil,
+    prompt: nil,
+    temperature: nil,
+    max_tokens: nil,
+    provider_options: {},
+    &block
+  )
+    raise ArgumentError, "stream requires a block callback" unless block_given?
+
+    model_descriptor = normalize_model(model)
+    raise ProviderError, "stream only supports openrouter provider" unless model_descriptor.provider.to_sym == :openrouter
+
+    resolved_provider_options = merge_provider_options(
+      model_descriptor.provider_options,
+      provider_options
+    )
+    adapter = provider_adapter(model_descriptor.provider, resolved_provider_options)
+    llm_messages = normalize_messages(messages: messages, system: system, prompt: prompt)
+
+    payload = build_payload(
+      model_id: model_descriptor.id,
+      messages: llm_messages,
+      tools: {},
+      tool_choice: nil,
+      temperature: temperature,
+      max_tokens: max_tokens,
+      provider_options: resolved_provider_options
+    ).merge("stream" => true)
+
+    block.call(type: :start, model: model_descriptor.id, provider: model_descriptor.provider)
+
+    emitted_finish = false
+
+    adapter.stream(payload) do |raw_data|
+      next if raw_data == "[DONE]"
+
+      parsed = parse_json(raw_data)
+      raise StreamingError, "Malformed SSE payload: #{raw_data}" if parsed.nil?
+
+      usage = parsed["usage"]
+      block.call(type: :usage, usage: usage, raw: parsed) if usage.is_a?(Hash)
+
+      choice = Array(parsed["choices"]).first || {}
+      delta = choice["delta"] || {}
+
+      text_delta = extract_text_delta(delta)
+      block.call(type: :text_delta, text: text_delta, raw: parsed) if text_delta && !text_delta.empty?
+
+      Array(delta["tool_calls"]).each do |tool_call_delta|
+        tool_delta = {
+          index: tool_call_delta["index"],
+          id: tool_call_delta["id"],
+          type: tool_call_delta["type"],
+          name: tool_call_delta.dig("function", "name"),
+          arguments_delta: tool_call_delta.dig("function", "arguments")
+        }
+        block.call(type: :tool_call_delta, tool_call: tool_delta, raw: parsed)
+      end
+
+      finish_reason = choice["finish_reason"]
+      next if finish_reason.nil? || finish_reason.to_s.empty?
+
+      emitted_finish = true
+      block.call(type: :finish, finish_reason: finish_reason, raw: parsed)
+    end
+
+    block.call(type: :finish, finish_reason: "stop") unless emitted_finish
+    true
+  rescue ProviderError => e
+    wrapped_error = StreamingError.new(e.message)
+    block.call(type: :error, error: wrapped_error.message) if block_given?
+    raise wrapped_error
+  rescue StreamingError => e
+    block.call(type: :error, error: e.message) if block_given?
+    raise
+  rescue StandardError => e
+    wrapped_error = StreamingError.new(e.message)
+    block.call(type: :error, error: wrapped_error.message) if block_given?
+    raise wrapped_error
+  end
+
+  def normalize_model(input)
+    return input if input.is_a?(ModelDescriptor)
+    return model(input, provider: :openrouter) if input.is_a?(String)
+
+    if input.is_a?(Hash)
+      return model(
+        input[:id] || input["id"],
+        provider: input[:provider] || input["provider"] || :openrouter,
+        provider_options: input[:provider_options] || input["provider_options"] || {}
+      )
+    end
+
+    raise Error, "Unsupported model value: #{input.inspect}"
+  end
+  private_class_method :normalize_model
+
+  def generate_openrouter_single(
+    model_descriptor:,
+    adapter:,
+    messages:,
+    system:,
+    prompt:,
+    tools:,
+    tool_choice:,
+    temperature:,
+    max_tokens:,
+    provider_options:,
+    before_tool_execution:,
+    after_tool_execution:
+  )
+    tool_map = normalize_tools(tools)
+    llm_messages = normalize_messages(messages: messages, system: system, prompt: prompt)
+    resolved_tool_choice = normalize_tool_choice(
+      explicit_tool_choice: tool_choice,
+      provider_options: provider_options,
+      tools: tool_map
+    )
+
+    payload = build_payload(
+      model_id: model_descriptor.id,
+      messages: llm_messages,
+      tools: tool_map,
+      tool_choice: resolved_tool_choice,
+      temperature: temperature,
+      max_tokens: max_tokens,
+      provider_options: provider_options
+    )
+
+    response = adapter.chat(payload)
+    message = response.dig("choices", 0, "message") || {}
+    tool_calls = Array(message["tool_calls"])
+    tool_results = []
+
+    unless tool_calls.empty? || tool_map.empty?
+      tool_calls.each do |tool_call|
+        tool_call_id = normalize_tool_call_id(tool_call["id"])
+        arguments = parse_arguments(tool_call.dig("function", "arguments"))
+        tool_name = tool_call.dig("function", "name").to_s
+
+        call_callback!(
+          before_tool_execution,
+          {
+            iteration_index: 1,
+            tool_call_id: tool_call_id,
+            tool_name: tool_name,
+            input: arguments,
+            raw_tool_call: tool_call
+          }
+        )
+
+        tool_result = execute_tool_call(
+          tool_call: tool_call,
+          tools: tool_map,
+          tool_call_id: tool_call_id,
+          arguments: arguments
+        )
+        tool_results << tool_result
+
+        call_callback!(
+          after_tool_execution,
+          tool_result.merge(iteration_index: 1)
+        )
+      end
+    end
+
+    result = {
+      text: extract_message_text(message),
+      message: message,
+      usage: response["usage"],
+      finish_reason: response.dig("choices", 0, "finish_reason"),
+      tool_calls: tool_calls,
+      raw_response: response
+    }
+    result[:tool_results] = tool_results unless tool_results.empty?
+    result
+  end
+  private_class_method :generate_openrouter_single
+
+  def generate_replicate_single(model_descriptor:, adapter:, input:, provider_options:)
+    raise Error, "generate with replicate requires input: Hash" unless input.is_a?(Hash)
+
+    reference = normalize_replicate_reference(
+      model_descriptor: model_descriptor,
+      provider_options: provider_options
+    )
+
+    prediction = adapter.create_prediction(
+      reference: reference,
+      input: input
+    )
+
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + REPLICATE_WAIT_TIMEOUT_SECONDS
+
+    until replicate_terminal_status?(prediction["status"])
+      if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+        raise ProviderError, "Replicate prediction did not finish within #{REPLICATE_WAIT_TIMEOUT_SECONDS} seconds"
+      end
+
+      sleep(REPLICATE_POLL_INTERVAL_SECONDS)
+      prediction = adapter.get_prediction(prediction: prediction)
+    end
+
+    {
+      id: prediction["id"],
+      status: prediction["status"],
+      output: prediction["output"],
+      error: prediction["error"],
+      logs: prediction["logs"],
+      metrics: prediction["metrics"],
+      urls: prediction["urls"],
+      raw_response: prediction
+    }
+  end
+  private_class_method :generate_replicate_single
+
+  def normalize_replicate_reference(model_descriptor:, provider_options:)
+    type = provider_options[:replicate_target] || provider_options["replicate_target"] || :model
+    normalized_type = type.to_sym
+    model_id = model_descriptor.id.to_s.strip
+    raise Error, "Replicate model id is required" if model_id.empty?
+
+    if normalized_type == :model || normalized_type == :deployment
+      owner, name, extra = model_id.split("/", 3)
+      if owner.to_s.empty? || name.to_s.empty? || !extra.nil?
+        raise Error, "Replicate #{normalized_type} id must be in 'owner/name' format"
+      end
+    elsif normalized_type != :version
+      raise Error, "Unsupported replicate_target: #{normalized_type}"
+    end
+
+    {
+      type: normalized_type,
+      id: model_id
+    }
+  end
+  private_class_method :normalize_replicate_reference
+
+  def replicate_terminal_status?(status)
+    REPLICATE_TERMINAL_STATUSES.include?(status.to_s)
+  end
+  private_class_method :replicate_terminal_status?
+
+  def validate_no_webhook_support!(provider_options)
+    return unless provider_options.is_a?(Hash)
+
+    webhook_set = provider_options.key?(:webhook) || provider_options.key?("webhook")
+    events_set =
+      provider_options.key?(:webhook_events_filter) ||
+      provider_options.key?("webhook_events_filter")
+    return unless webhook_set || events_set
+
+    raise Error, "webhook and webhook_events_filter are not supported"
+  end
+  private_class_method :validate_no_webhook_support!
+
+  def normalize_tools(tools)
+    return {} if tools.nil?
+
+    if tools.is_a?(Array)
+      return tools.each_with_object({}) do |entry, acc|
+        next unless entry.is_a?(ToolDefinition)
+
+        acc[entry.name] = entry
+      end
+    end
+
+    raise ToolError, "tools must be a Hash or Array" unless tools.is_a?(Hash)
+
+    tools.each_with_object({}) do |(name, value), acc|
+      tool_name = name.to_s
+      acc[tool_name] = normalize_tool_entry(tool_name, value)
+    end
+  end
+  private_class_method :normalize_tools
+
+  def normalize_tool_entry(name, value)
+    return value if value.is_a?(ToolDefinition)
+
+    if value.is_a?(Hash)
+      execute_proc = value[:execute] || value["execute"]
+      return ToolDefinition.new(
+        name: name,
+        description: value[:description] || value["description"] || "",
+        input_schema: value[:input_schema] || value["input_schema"] || value[:parameters] || value["parameters"] || {},
+        execute_proc: execute_proc
+      )
+    end
+
+    raise ToolError, "Tool '#{name}' has invalid definition"
+  end
+  private_class_method :normalize_tool_entry
+
+  def normalize_messages(messages:, system:, prompt:)
+    if messages.nil? || messages.empty?
+      normalized = []
+      normalized << { "role" => "system", "content" => system.to_s } if system
+      normalized << { "role" => "user", "content" => prompt.to_s } if prompt
+      return normalized
+    end
+
+    normalized = deep_stringify(messages)
+    normalized.unshift({ "role" => "system", "content" => system.to_s }) if system
+    normalized << { "role" => "user", "content" => prompt.to_s } if prompt
+    normalized
+  end
+  private_class_method :normalize_messages
+
+  def build_payload(model_id:, messages:, tools:, tool_choice:, temperature:, max_tokens:, provider_options:)
+    payload = {
+      "model" => model_id,
+      "messages" => messages
+    }
+
+    payload["temperature"] = temperature unless temperature.nil?
+    payload["max_tokens"] = max_tokens unless max_tokens.nil?
+    payload["tools"] = tools.values.map(&:as_provider_tool) unless tools.empty?
+    payload["tool_choice"] = deep_stringify(tool_choice) unless tool_choice.nil?
+
+    request_options = reject_keys(provider_options, OPENROUTER_ADAPTER_CONFIG_KEYS + [ :tool_choice ])
+    payload.merge!(deep_stringify(request_options)) if request_options.is_a?(Hash)
+    payload
+  end
+  private_class_method :build_payload
+
+  def merge_provider_options(model_provider_options, call_provider_options)
+    merged = {}
+    merged.merge!(default_provider_options) if default_provider_options.is_a?(Hash)
+    merged.merge!(model_provider_options) if model_provider_options.is_a?(Hash)
+    merged.merge!(call_provider_options) if call_provider_options.is_a?(Hash)
+    merged
+  end
+  private_class_method :merge_provider_options
+
+  def provider_adapter(provider, provider_options)
+    case provider.to_sym
+    when :openrouter
+      config = pick_keys(provider_options, OPENROUTER_ADAPTER_CONFIG_KEYS)
+      Providers::OpenRouter.new(**config)
+    when :replicate
+      config = pick_keys(provider_options, REPLICATE_ADAPTER_CONFIG_KEYS)
+      Providers::Replicate.new(**config)
+    else
+      raise ProviderError, "Unsupported provider: #{provider}"
+    end
+  end
+  private_class_method :provider_adapter
+
+  def build_assistant_tool_call_message(message:, tool_calls:)
+    {
+      "role" => "assistant",
+      "content" => extract_message_text(message),
+      "tool_calls" => tool_calls
+    }
+  end
+  private_class_method :build_assistant_tool_call_message
+
+  def execute_tool_call(tool_call:, tools:, tool_call_id: nil, arguments: nil)
+    tool_name = tool_call.dig("function", "name").to_s
+    tool_call_id = normalize_tool_call_id(tool_call_id || tool_call["id"])
+    arguments = parse_arguments(tool_call.dig("function", "arguments")) if arguments.nil?
+    tool = tools[tool_name]
+
+    unless tool
+      return {
+        tool_call_id: tool_call_id,
+        tool_name: tool_name,
+        input: arguments,
+        ok: false,
+        output: { "ok" => false, "error" => "Unknown tool: #{tool_name}" }
+      }
+    end
+
+    output = normalize_output_payload(tool.execute(arguments))
+    {
+      tool_call_id: tool_call_id,
+      tool_name: tool_name,
+      input: arguments,
+      ok: true,
+      output: output
+    }
+  rescue StandardError => e
+    {
+      tool_call_id: tool_call_id,
+      tool_name: tool_name,
+      input: arguments,
+      ok: false,
+      output: { "ok" => false, "error" => "Tool execution failed: #{e.message}" }
+    }
+  end
+  private_class_method :execute_tool_call
+
+  def normalize_tool_call_id(value)
+    normalized = value.to_s.strip
+    return normalized unless normalized.empty?
+
+    "call_#{SecureRandom.uuid}"
+  end
+  private_class_method :normalize_tool_call_id
+
+  def normalize_max_iterations(value)
+    return DEFAULT_MAX_ITERATIONS if value.nil?
+    return :infinite if value == :infinite || value == Float::INFINITY
+    return value if value.is_a?(Integer) && value.positive?
+
+    raise Error, "max_iterations must be a positive Integer or :infinite"
+  end
+  private_class_method :normalize_max_iterations
+
+  def normalize_tool_choice(explicit_tool_choice:, provider_options:, tools:)
+    requested_tool_choice = if explicit_tool_choice.nil? && provider_options.is_a?(Hash)
+      provider_options[:tool_choice] || provider_options["tool_choice"]
+    else
+      explicit_tool_choice
+    end
+
+    if requested_tool_choice.nil?
+      return nil if tools.empty?
+
+      return "auto"
+    end
+
+    normalized = normalize_tool_choice_value(requested_tool_choice)
+
+    if tools.empty?
+      return nil if normalized == "auto" || normalized == "none"
+
+      raise Error, "tool_choice requires at least one tool"
+    end
+
+    if normalized.is_a?(Hash)
+      tool_name = normalized.dig("function", "name").to_s
+      raise Error, "tool_choice references unknown tool '#{tool_name}'" unless tools.key?(tool_name)
+    end
+
+    normalized
+  end
+  private_class_method :normalize_tool_choice
+
+  def normalize_tool_choice_value(value)
+    case value
+    when Symbol, String
+      normalized = value.to_s.strip
+      return normalized if %w[auto required none].include?(normalized)
+
+      raise Error, "tool_choice must be one of auto, required, none, or { type: 'tool', toolName: '...' }"
+    when Hash
+      type = (value[:type] || value["type"]).to_s
+
+      if type == "tool"
+        tool_name =
+          value[:tool_name] || value["tool_name"] ||
+          value[:toolName] || value["toolName"]
+        normalized_tool_name = tool_name.to_s.strip
+        raise Error, "tool_choice[:toolName] is required when type is 'tool'" if normalized_tool_name.empty?
+
+        return {
+          "type" => "function",
+          "function" => {
+            "name" => normalized_tool_name
+          }
+        }
+      end
+
+      if type == "function"
+        tool_name = value.dig(:function, :name) || value.dig("function", "name")
+        normalized_tool_name = tool_name.to_s.strip
+        raise Error, "tool_choice function name is required when type is 'function'" if normalized_tool_name.empty?
+
+        return {
+          "type" => "function",
+          "function" => {
+            "name" => normalized_tool_name
+          }
+        }
+      end
+
+      raise Error, "tool_choice hash must use type: 'tool' (or provider-native type: 'function')"
+    else
+      raise Error, "tool_choice must be a String, Symbol, or Hash"
+    end
+  end
+  private_class_method :normalize_tool_choice_value
+
+  def normalize_stop_when(value)
+    return {} if value.nil?
+    raise Error, "stop_when must be a Hash when provided" unless value.is_a?(Hash)
+
+    unknown_keys = value.keys.map(&:to_sym) - [ :tool_called ]
+    raise Error, "stop_when only supports :tool_called" unless unknown_keys.empty?
+
+    tool_called = value[:tool_called] || value["tool_called"]
+    return {} if tool_called.nil?
+
+    tool_names =
+      case tool_called
+      when String, Symbol
+        [ tool_called.to_s ]
+      when Array
+        tool_called.map(&:to_s)
+      else
+        raise Error, "stop_when[:tool_called] must be a String, Symbol, or Array"
+      end
+
+    normalized_names = tool_names.map(&:strip).reject(&:empty?).uniq
+    raise Error, "stop_when[:tool_called] must include at least one tool name" if normalized_names.empty?
+
+    { tool_called: normalized_names }
+  end
+  private_class_method :normalize_stop_when
+
+  def tool_stop_condition_met?(stop_when, tool_result)
+    return false unless stop_when.is_a?(Hash)
+
+    tool_names = Array(stop_when[:tool_called])
+    return false if tool_names.empty?
+    return false unless tool_result[:ok]
+
+    tool_names.include?(tool_result[:tool_name].to_s)
+  end
+  private_class_method :tool_stop_condition_met?
+
+  def callback_stopped_result(control:, iterations:, message:, usage:, raw_response:)
+    {
+      text: extract_message_text(message),
+      message: message,
+      usage: usage,
+      finish_reason: "stopped_by_callback",
+      stop_reason: {
+        type: "callback",
+        reason: control.stop_reason
+      },
+      iterations: iterations,
+      raw_response: raw_response
+    }
   end
+  private_class_method :callback_stopped_result
+
+  def call_callback!(callback, payload, control = nil)
+    return if callback.nil?
+    raise Error, "Callback must respond to #call" unless callback.respond_to?(:call)
+
+    if control && callback_accepts_control?(callback)
+      callback.call(payload, control)
+    else
+      callback.call(payload)
+    end
+  end
+  private_class_method :call_callback!
+
+  def callback_accepts_control?(callback)
+    return true unless callback.lambda?
+
+    params = callback.parameters
+    return true if params.any? { |param_type, _| param_type == :rest }
+
+    positional_count = params.count { |param_type, _| param_type == :req || param_type == :opt }
+    positional_count >= 2
+  end
+  private_class_method :callback_accepts_control?
+
+  def normalize_output_payload(payload)
+    case payload
+    when Hash, Array
+      deep_stringify(payload)
+    else
+      payload
+    end
+  end
+  private_class_method :normalize_output_payload
+
+  def extract_message_text(message)
+    content = message["content"]
+    return content if content.is_a?(String)
+
+    if content.is_a?(Array)
+      return content.filter_map { |part| part["text"] if part.is_a?(Hash) && part["text"] }.join
+    end
+
+    return content["text"].to_s if content.is_a?(Hash) && content["text"]
+
+    content.to_s
+  end
+  private_class_method :extract_message_text
+
+  def extract_text_delta(delta)
+    content = delta["content"]
+    return content if content.is_a?(String)
+
+    if content.is_a?(Array)
+      return content.filter_map { |part| part["text"] if part.is_a?(Hash) && part["text"] }.join
+    end
+
+    nil
+  end
+  private_class_method :extract_text_delta
+
+  def parse_arguments(arguments)
+    return arguments if arguments.is_a?(Hash)
+    return {} if arguments.nil? || arguments.to_s.strip.empty?
+
+    parse_json(arguments) || {}
+  end
+  private_class_method :parse_arguments
+
+  def parse_json(value)
+    JSON.parse(value)
+  rescue JSON::ParserError, TypeError
+    nil
+  end
+  private_class_method :parse_json
+
+  def serialize_tool_content(output)
+    return output if output.is_a?(String)
+
+    JSON.generate(output)
+  rescue StandardError
+    output.to_s
+  end
+  private_class_method :serialize_tool_content
+
+  def pick_keys(hash, keys)
+    return {} unless hash.is_a?(Hash)
+
+    hash.each_with_object({}) do |(key, value), acc|
+      symbol_key = key.to_sym
+      acc[symbol_key] = value if keys.include?(symbol_key)
+    end
+  end
+  private_class_method :pick_keys
+
+  def reject_keys(hash, keys)
+    return {} unless hash.is_a?(Hash)
+
+    hash.each_with_object({}) do |(key, value), acc|
+      symbol_key = key.to_sym
+      acc[key] = value unless keys.include?(symbol_key)
+    end
+  end
+  private_class_method :reject_keys
+
+  def deep_stringify(value)
+    case value
+    when Hash
+      value.each_with_object({}) do |(key, item), acc|
+        acc[key.to_s] = deep_stringify(item)
+      end
+    when Array
+      value.map { |item| deep_stringify(item) }
+    else
+      value
+    end
+  end
+  private_class_method :deep_stringify
+
+  module Providers
+    class OpenRouter
+      CHAT_COMPLETIONS_URL = "https://openrouter.ai/api/v1/chat/completions".freeze
+      DEFAULT_TIMEOUT = 120_000
+
+      def initialize(api_key: nil, app_url: nil, title: nil, timeout: DEFAULT_TIMEOUT)
+        @api_key = api_key
+        raise ProviderError, "OpenRouter API key not configured" if @api_key.nil? || @api_key.to_s.empty?
+
+        @app_url = app_url || "http://localhost"
+        @title = title || "zuno-ruby"
+        @timeout = timeout
+      end
+
+      def model(model_id)
+        ModelDescriptor.new(
+          id: model_id,
+          provider: :openrouter,
+          provider_options: provider_options
+        )
+      end
+
+      def chat(payload)
+        response = Typhoeus.post(
+          CHAT_COMPLETIONS_URL,
+          headers: headers,
+          body: JSON.generate(payload),
+          timeout: @timeout
+        )
+
+        validate_response!(response)
+        parsed = JSON.parse(response.body)
+        raise ProviderError, "OpenRouter returned invalid JSON" unless parsed.is_a?(Hash)
+
+        parsed
+      rescue JSON::ParserError => e
+        raise ProviderError, "Failed to parse OpenRouter response: #{e.message}"
+      end
+
+      def stream(payload)
+        raise ArgumentError, "stream requires a block callback" unless block_given?
+
+        request = Typhoeus::Request.new(
+          CHAT_COMPLETIONS_URL,
+          method: :post,
+          headers: headers,
+          body: JSON.generate(payload),
+          timeout: @timeout
+        )
+
+        parser = SseParser.new { |data| yield(data) }
+        request.on_body do |chunk|
+          parser.push(chunk)
+          nil
+        end
+
+        request.run
+        validate_response!(request.response)
+        parser.flush
+      end
+
+      private
+
+      def provider_options
+        {
+          api_key: @api_key,
+          app_url: @app_url,
+          title: @title,
+          timeout: @timeout
+        }
+      end
+
+      def headers
+        {
+          "Authorization" => "Bearer #{@api_key}",
+          "Content-Type" => "application/json",
+          "HTTP-Referer" => @app_url,
+          "X-Title" => @title
+        }
+      end
+
+      def validate_response!(response)
+        raise ProviderError, "No response returned from OpenRouter" if response.nil?
+        raise ProviderError, "OpenRouter request timed out" if response.timed_out?
+
+        status = response.code.to_i
+        body = response.body.to_s
+        message = body.length > 300 ? "#{body[0, 300]}..." : body
+
+        return if status >= 200 && status < 300
+
+        if status.positive?
+          raise ProviderError, "OpenRouter responded with HTTP #{status}: #{message}"
+        end
+
+        suffix = message.empty? ? "" : ": #{message}"
+        raise ProviderError, "OpenRouter request failed: #{response.return_code}#{suffix}"
+      end
+
+    end
+
+    class Replicate
+      API_BASE_URL = "https://api.replicate.com/v1".freeze
+      DEFAULT_TIMEOUT = 120_000
+
+      def initialize(api_key: nil, timeout: DEFAULT_TIMEOUT)
+        @api_key = api_key
+        raise ProviderError, "Replicate API key not configured" if @api_key.nil? || @api_key.to_s.empty?
+
+        @timeout = timeout
+      end
+
+      def model(model_id)
+        model_descriptor(model_id: model_id, target: :model)
+      end
+
+      def version(version_id)
+        model_descriptor(model_id: version_id, target: :version)
+      end
+
+      def deployment(deployment_id)
+        model_descriptor(model_id: deployment_id, target: :deployment)
+      end
+
+      def create_prediction(reference:, input:)
+        path, payload = build_create_request(reference: reference, input: input)
+
+        response = Typhoeus.post(
+          "#{API_BASE_URL}#{path}",
+          headers: headers.merge("Prefer" => "wait=#{REPLICATE_PREFER_WAIT_SECONDS}"),
+          body: JSON.generate(payload),
+          timeout: @timeout
+        )
+        parse_response(response)
+      end
+
+      def get_prediction(prediction:)
+        url = prediction.dig("urls", "get")
+
+        if url.nil? || url.to_s.strip.empty?
+          prediction_id = prediction["id"].to_s
+          raise ProviderError, "Replicate prediction id is missing" if prediction_id.empty?
+
+          url = "#{API_BASE_URL}/predictions/#{CGI.escape(prediction_id)}"
+        end
+
+        response = Typhoeus.get(
+          url,
+          headers: headers,
+          timeout: @timeout
+        )
+        parse_response(response)
+      end
+
+      private
+
+      def model_descriptor(model_id:, target:)
+        ModelDescriptor.new(
+          id: model_id,
+          provider: :replicate,
+          provider_options: provider_options(target: target)
+        )
+      end
+
+      def provider_options(target:)
+        {
+          api_key: @api_key,
+          timeout: @timeout,
+          replicate_target: target
+        }
+      end
+
+      def build_create_request(reference:, input:)
+        type = reference[:type].to_sym
+        id = reference[:id].to_s
+
+        case type
+        when :version
+          ["/predictions", { "version" => id, "input" => input }]
+        when :model
+          ["/models/#{escape_owner_and_name(id)}/predictions", { "input" => input }]
+        when :deployment
+          ["/deployments/#{escape_owner_and_name(id)}/predictions", { "input" => input }]
+        else
+          raise ProviderError, "Unsupported Replicate reference type: #{type}"
+        end
+      end
+
+      def escape_owner_and_name(value)
+        owner, name = value.split("/", 2)
+        "#{CGI.escape(owner.to_s)}/#{CGI.escape(name.to_s)}"
+      end
+
+      def parse_response(response)
+        validate_response!(response)
+        parsed = JSON.parse(response.body)
+        raise ProviderError, "Replicate returned invalid JSON" unless parsed.is_a?(Hash)
+
+        parsed
+      rescue JSON::ParserError => e
+        raise ProviderError, "Failed to parse Replicate response: #{e.message}"
+      end
+
+      def headers
+        {
+          "Authorization" => "Bearer #{@api_key}",
+          "Content-Type" => "application/json"
+        }
+      end
+
+      def validate_response!(response)
+        raise ProviderError, "No response returned from Replicate" if response.nil?
+        raise ProviderError, "Replicate request timed out" if response.timed_out?
+
+        status = response.code.to_i
+        body = response.body.to_s
+        message = body.length > 300 ? "#{body[0, 300]}..." : body
+
+        return if status >= 200 && status < 300
+
+        if status.positive?
+          raise ProviderError, "Replicate responded with HTTP #{status}: #{message}"
+        end
+
+        suffix = message.empty? ? "" : ": #{message}"
+        raise ProviderError, "Replicate request failed: #{response.return_code}#{suffix}"
+      end
+    end
+  end
+
+  class SseParser
+    def initialize(&on_data)
+      @on_data = on_data
+      @buffer = +""
+    end
+
+    def push(chunk)
+      return if chunk.nil? || chunk.empty?
+
+      @buffer << chunk
+      parse_buffer
+    end
+
+    def flush
+      parse_buffer(final: true)
+    end
+
+    private
+
+    def parse_buffer(final: false)
+      delimiter = "\n\n"
+
+      loop do
+        index = @buffer.index(delimiter)
+        break if index.nil?
+
+        raw_event = @buffer.slice!(0, index + delimiter.length)
+        emit_event(raw_event)
+      end
+
+      emit_event(@buffer.dup) if final && !@buffer.empty?
+      @buffer.clear if final
+    end
+
+    def emit_event(raw_event)
+      lines = raw_event.split("\n")
+      payload_lines = lines.filter_map do |line|
+        stripped = line.strip
+        next if stripped.empty?
+        next unless stripped.start_with?("data:")
+
+        stripped.sub(/^data:\s?/, "")
+      end
+
+      return if payload_lines.empty?
 
-  def self.configure
-    self.configuration ||= Configuration.new
-    yield(configuration)
+      @on_data.call(payload_lines.join("\n"))
+    end
   end
 end