zuno 0.1.6 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0b1a60f13b8d0f649d5a00df65846d3a35597f6298927c2e07b36f6f042528a
-  data.tar.gz: a6312c76748d3fe27bc50e70fac5c7922f240ac7b61eee6ed6ab1e7e90639e2a
+  metadata.gz: d1dea919bc404d8bafb4e970ffd4d2d418d5ea38123bc78abc4668fc72ce985d
+  data.tar.gz: 4953724ce6061eb7641d7e4c5ee7564204d4647968822fd8d88303b481cf09c1
 SHA512:
-  metadata.gz: d9d1ce4c9e83825b6a227f6442865d7983a43fc31ca7956d09c38214a428ce1ea8c83f8852f24e66302f6906824f288d6fb0a8fbbad4253fd0d1d920fe16e603
-  data.tar.gz: 54110db116e05eed86ac94eebd7416c2955a78fe691cafcff7ad39a733fd7e54245bfc659261aeb09dbeb20f26d5a836f433f1deefd6deda8242166947ac39d8
+  metadata.gz: 16d264d3143fca0a55bb4a2ed1ad4cc08e0f8dbbb6effdf8ed75c7425b5087fd1a8763135117bcc3b1ea8cf9061a579fa95b21e813b81d90c7de1076978d3a32
+  data.tar.gz: 8f19a868f736ec65ddf5484affe0a538a54690fc420c234afa7ead82f6943040441bce2336b334becb14fedad7babaaec03025854bf7e638ee31330f4eadddbb

data/README.md

@@ -3,8 +3,9 @@
 Standalone Ruby SDK for:
 
 - provider/model abstraction
-- tool calling with iterative loop execution
-- streaming via SSE
+- single-shot generation
+- iterative tool loops
+- streaming via SSE (OpenRouter)
 
 ## Install (local development)
 
@@ -13,22 +14,96 @@ bundle install
 bundle exec rspec
 ```
 
-## Basic usage
+## Breaking change: `generate` vs `loop`
+
+- `Zuno.generate` is now single-shot.
+- `Zuno.loop` contains the previous iterative tool-loop behavior.
+
+If you previously relied on iterative tool calls in `generate`, move that code to `loop`.
+
+## Providers
+
+### OpenRouter
 
 ```ruby
 require "zuno"
 
+openrouter = Zuno.openrouter(
+  api_key: "your-openrouter-key", # required
+  app_url: "https://example.com",
+  title: "my-app"
+)
+```
+
+### Replicate
+
+```ruby
+replicate = Zuno.replicate(api_key: "your-replicate-key") # required
+```
+
+## Single-shot generation (`generate`)
+
+### OpenRouter
+
+```ruby
 result = Zuno.generate(
-  model: "openai/gpt-5-mini",
+  model: openrouter.model("openai/gpt-5-mini"),
   prompt: "Say hello"
 )
 
 puts result[:text]
 ```
 
-## Callbacks
+`generate` supports tool definitions and executes returned tool calls once, without a follow-up LLM request.
+
+### Replicate
+
+`generate` with Replicate requires `input:` and waits for completion using:
+
+- `Prefer: wait=60` on create
+- polling every 1 second
+- hard timeout at 10 minutes
+
+```ruby
+result = Zuno.generate(
+  model: replicate.model("owner/model"),
+  input: { prompt: "A watercolor fox" }
+)
+
+puts result[:status]
+pp result[:output]
+```
+
+Replicate reference types:
+
+```ruby
+replicate.version("version-id")
+replicate.model("owner/model")
+replicate.deployment("owner/deployment")
+```
+
+Webhooks are not supported. Passing `webhook` or `webhook_events_filter` raises an error.
 
-`generate` supports:
+## Iterative tool execution (`loop`)
+
+`loop` is OpenRouter-only and preserves the previous iterative behavior.
+
+```ruby
+ping = Zuno.tool(
+  name: "ping",
+  description: "Ping tool",
+  input_schema: { type: "object", properties: {} }
+) { { ok: true } }
+
+result = Zuno.loop(
+  model: openrouter.model("openai/gpt-5-mini"),
+  prompt: "Run tools until done",
+  tools: { ping: ping },
+  max_iterations: 24
+)
+```
+
+`loop` supports:
 
 - `before_generation`
 - `after_generation`
@@ -36,3 +111,48 @@ puts result[:text]
 - `after_iteration`
 - `before_tool_execution`
 - `after_tool_execution`
+- `max_iterations` (`Integer`, `:infinite`, or `Float::INFINITY`)
+- `stop_when: { tool_called: ... }`
+
+Callbacks can accept a second argument (`control`) and call `control.stop!(reason: "...")`.
+
+## Tool choice
+
+`generate` and `loop` support AI SDK-style tool choice when tools are present:
+
+- `"auto"` (default)
+- `"required"`
+- `"none"`
+- `{ type: "tool", toolName: "my_tool" }`
+
+## Streaming (`stream`)
+
+`stream` is OpenRouter-only.
+
+```ruby
+Zuno.stream(
+  model: openrouter.model("openai/gpt-5-mini"),
+  prompt: "Stream hello"
+) do |event|
+  p event
+end
+```
+
+## Automated releases
+
+This repo includes `.github/workflows/release.yml` to automate versioning and gem publication:
+
+- `release-please` inspects Conventional Commits on `main`, opens/updates a release PR, and bumps `lib/zuno/version.rb` when the release PR is merged.
+- When a new GitHub release/tag is created, the workflow builds the gem and publishes it to RubyGems.
+
+### One-time setup
+
+Add this GitHub repository secret:
+
+- `RUBYGEMS_API_KEY`
+
+### Commit format for version bumping
+
+- `fix: ...` -> patch
+- `feat: ...` -> minor
+- `feat!: ...` or any commit with `BREAKING CHANGE:` -> major

data/lib/zuno/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zuno
-  VERSION = "0.1.6"
+  VERSION = "1.0.0"
 end

data/lib/zuno.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "securerandom"
+require "cgi"
 require "typhoeus"
 
 require_relative "zuno/version"
@@ -10,12 +11,33 @@ module Zuno
   class Error < StandardError; end
   class ProviderError < Error; end
   class ToolError < Error; end
-  class MaxStepsExceeded < Error; end
+  class MaxIterationsExceeded < Error; end
   class StreamingError < Error; end
+  class CallbackControl
+    attr_reader :stop_reason
 
-  ModelDescriptor = Struct.new(:id, :provider, keyword_init: true) do
-    def initialize(id:, provider:)
-      super(id: id.to_s, provider: provider.to_sym)
+    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
 
@@ -53,13 +75,42 @@ module Zuno
     end
   end
 
-  ADAPTER_CONFIG_KEYS = %i[api_key app_url title timeout].freeze
-  DEFAULT_MAX_STEPS = 8
+  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 model(id, provider: :openrouter)
-    ModelDescriptor.new(id: id, provider: provider)
+  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)
@@ -78,8 +129,111 @@ module Zuno
     messages: nil,
     system: nil,
     prompt: nil,
+    input: nil,
     tools: {},
-    max_steps: DEFAULT_MAX_STEPS,
+    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: {},
@@ -90,41 +244,88 @@ module Zuno
     before_generation: nil,
     after_generation: nil
   )
+    callback_control = nil
     model_descriptor = normalize_model(model)
-    adapter = provider_adapter(model_descriptor.provider, provider_options)
+    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_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
 
-    while iteration_count < max_steps
+    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: provider_options
+        provider_options: resolved_provider_options
       )
 
       response = adapter.chat(payload)
@@ -147,8 +348,21 @@ module Zuno
           {
             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),
@@ -160,11 +374,13 @@ module Zuno
         }
 
         after_generation_called = true
-        call_callback!(after_generation, { ok: true, result: result })
+        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"])
@@ -179,7 +395,8 @@ module Zuno
             tool_name: tool_name,
             input: arguments,
             raw_tool_call: tool_call
-          }
+          },
+          callback_control
         )
 
         tool_result = execute_tool_call(
@@ -190,7 +407,15 @@ module Zuno
         )
 
         iteration_record[:tool_results] << tool_result
-        call_callback!(after_tool_execution, tool_result.merge(iteration_index: current_iteration))
+        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",
@@ -205,23 +430,56 @@ module Zuno
         {
           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 MaxStepsExceeded, "Reached max_steps=#{max_steps} without a final assistant response"
-  rescue ProviderError, MaxStepsExceeded => e
+    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 })
+      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 })
+      call_callback!(after_generation, { ok: false, error: e }, callback_control)
     end
     raise Error, e.message
   end
@@ -239,16 +497,23 @@ module Zuno
     raise ArgumentError, "stream requires a block callback" unless block_given?
 
     model_descriptor = normalize_model(model)
-    adapter = provider_adapter(model_descriptor.provider, provider_options)
+    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: provider_options
+      provider_options: resolved_provider_options
     ).merge("stream" => true)
 
     block.call(type: :start, model: model_descriptor.id, provider: model_descriptor.provider)
@@ -310,7 +575,8 @@ module Zuno
     if input.is_a?(Hash)
       return model(
         input[:id] || input["id"],
-        provider: input[:provider] || input["provider"] || :openrouter
+        provider: input[:provider] || input["provider"] || :openrouter,
+        provider_options: input[:provider_options] || input["provider_options"] || {}
       )
     end
 
@@ -318,6 +584,165 @@ module Zuno
   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?
 
@@ -370,7 +795,7 @@ module Zuno
   end
   private_class_method :normalize_messages
 
-  def build_payload(model_id:, messages:, tools:, temperature:, max_tokens:, provider_options:)
+  def build_payload(model_id:, messages:, tools:, tool_choice:, temperature:, max_tokens:, provider_options:)
     payload = {
       "model" => model_id,
       "messages" => messages
@@ -379,19 +804,31 @@ module Zuno
     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, ADAPTER_CONFIG_KEYS)
+    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 provider_adapter(provider, provider_options)
-    config = pick_keys(provider_options, ADAPTER_CONFIG_KEYS)
+  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
@@ -450,14 +887,167 @@ module Zuno
   end
   private_class_method :normalize_tool_call_id
 
-  def call_callback!(callback, payload)
+  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)
 
-    callback.call(payload)
+    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
@@ -558,14 +1148,22 @@ module Zuno
       DEFAULT_TIMEOUT = 120_000
 
       def initialize(api_key: nil, app_url: nil, title: nil, timeout: DEFAULT_TIMEOUT)
-        @api_key = api_key || resolve_api_key
+        @api_key = api_key
         raise ProviderError, "OpenRouter API key not configured" if @api_key.nil? || @api_key.to_s.empty?
 
-        @app_url = app_url || ENV["OPENROUTER_HTTP_REFERER"] || "http://localhost"
-        @title = title || ENV["OPENROUTER_APP_TITLE"] || "zuno-ruby"
+        @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,
@@ -607,6 +1205,15 @@ module Zuno
 
       private
 
+      def provider_options
+        {
+          api_key: @api_key,
+          app_url: @app_url,
+          title: @title,
+          timeout: @timeout
+        }
+      end
+
       def headers
         {
           "Authorization" => "Bearer #{@api_key}",
@@ -619,18 +1226,148 @@ module Zuno
       def validate_response!(response)
         raise ProviderError, "No response returned from OpenRouter" if response.nil?
         raise ProviderError, "OpenRouter request timed out" if response.timed_out?
-        raise ProviderError, "OpenRouter request failed: #{response.return_code}" unless response.success?
 
         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
-        raise ProviderError, "OpenRouter responded with HTTP #{status}: #{message}"
-      end
 
-      def resolve_api_key
-        ENV["OPENROUTER_API_KEY"]
+        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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zuno
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 1.0.0
 platform: ruby
 authors:
 - Hyperaide
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-19 00:00:00.000000000 Z
+date: 2026-03-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: typhoeus
@@ -52,7 +52,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
-description: Standalone Ruby SDK for AI generation with tool loops and SSE streaming.
+description: Standalone Ruby SDK for AI generation across OpenRouter and Replicate,
+  with iterative tool loops and SSE streaming.
 email:
 - team@hyperaide.dev
 executables: []
@@ -86,5 +87,6 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Ruby Agent SDK with provider/model abstraction, tools, and streaming
+summary: Ruby SDK with provider/model abstraction, single-shot generation, loops,
+  and streaming
 test_files: []