zuno 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d6d4d8dd97c7ac8743ddc66545aeda41ed824357965c693ac244fcf46de5df2
-  data.tar.gz: d7e0a1a6029482af54dbf7bc6e5196b39dd60e424b1fb18b4003543cfbe79867
+  metadata.gz: cf9be3e305d36fb21db7c92926787237b8db4322a993d3e8c8a38448c439d7b4
+  data.tar.gz: b004707c8eb242a35c631defafd13a13f0bf3533f9959e4b8ec2c62829097337
 SHA512:
-  metadata.gz: 4862131a38d657f175bbc488599d5cbcd97899b43bdac7a26117a437c081bfdaa365e4a2e5255e7e48464aa5e5d129e14106364727b19bae4b8166ff779cd621
-  data.tar.gz: 96340e7d0b4a2153d58b328cbdcbec5836ddd76724941fd8efa39343de14c052a51c2031e916562e0b66de5044832a429f2332c92e4325f40d6eefc2d1e67454
+  metadata.gz: 4153961f2ece3493d232af7f742c40be7fa09adbf76a82fb2722923630033e778f846c7489582f1e4bc06afafdc40663dcd237c4f70f6af0a4004da6dad5b09b
+  data.tar.gz: 486f38c407011327c5a9c336341bcc742233cfda7112b8596f9f5050565791d7ab24a36777c6061fe14dbfc65126e310c9ad69f372423b221726533ab8c37fa9

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [1.1.0](https://github.com/dqnamo/zuno/compare/v1.0.2...v1.1.0) (2026-04-04)
+
+### Features
+
+* add `Zuno.embed` for OpenAI-compatible embedding providers including OpenRouter and AI Gateway
+* add mutable loop callback context for tools, messages, and system prompt updates
+* refresh callback, loop, tools, and API reference documentation for the split `generate` and `loop` APIs
+
+## [1.0.2](https://github.com/dqnamo/zuno/compare/v1.0.1...v1.0.2) (2026-04-01)
+
+### Features
+
+* Add ElevenLabs Scribe batch transcription via `Zuno.transcribe` and `Zuno.elevenlabs` ([ElevenLabs speech-to-text API](https://elevenlabs.io/docs/api-reference/speech-to-text/convert)).

data/README.md

@@ -3,6 +3,7 @@
 Standalone Ruby SDK for:
 
 - provider/model abstraction
+- embeddings via OpenAI-compatible providers
 - single-shot generation
 - iterative tool loops
 - streaming via SSE (OpenRouter)
@@ -54,6 +55,19 @@ result = Zuno.generate(
 puts result[:text]
 ```
 
+## Embeddings (`embed`)
+
+`embed` supports OpenAI-compatible embedding providers such as OpenRouter and AI Gateway.
+
+```ruby
+result = Zuno.embed(
+  model: openrouter.model("openai/text-embedding-3-small"),
+  content: "Sunny day at the beach"
+)
+
+pp result[:embedding]
+```
+
 `generate` supports tool definitions and executes returned tool calls once, without a follow-up LLM request.
 
 ### Replicate
@@ -114,7 +128,25 @@ result = Zuno.loop(
 - `max_iterations` (`Integer`, `:infinite`, or `Float::INFINITY`)
 - `stop_when: { tool_called: ... }`
 
-Callbacks can accept a second argument (`control`) and call `control.stop!(reason: "...")`.
+Loop callbacks can accept:
+
+- a second argument (`control`) and call `control.stop!(reason: "...")`
+- a third argument (`context`) to mutate the next LLM request state
+
+`context` supports:
+
+- `context.system = "..."` or `context.clear_system!`
+- `context.messages = [...]`, `context.add_message(...)`, `context.add_messages(...)`
+- `context.tools = {...}`, `context.add_tool(:name, tool)`, `context.add_tools(...)`, `context.remove_tool(:name)`
+
+Example:
+
+```ruby
+before_iteration: ->(_payload, _control, context) {
+  context.system = "Be concise"
+  context.add_message(role: "user", content: "Answer in bullet points")
+}
+```
 
 ## Tool choice
 

data/lib/zuno/version.rb

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

data/lib/zuno.rb

@@ -31,6 +31,88 @@ module Zuno
     end
   end
 
+  class CallbackContext
+    attr_reader :messages, :tools
+    attr_accessor :system
+
+    def initialize(messages:, system:, tools:)
+      @messages = messages
+      @system = system
+      @tools = tools
+    end
+
+    def messages=(messages)
+      @messages = messages
+    end
+
+    def tools=(tools)
+      @tools = tools
+    end
+
+    def add_message(message = nil, role: nil, content: nil, **attributes)
+      if message
+        raise ArgumentError, "Provide either a message hash or role/content attributes" unless role.nil? && content.nil? && attributes.empty?
+
+        entry = message
+      elsif role.nil? && content.nil? && !attributes.empty?
+        entry = attributes
+      else
+        raise ArgumentError, "add_message requires role:" if role.nil?
+
+        entry = { role: role, content: content }.merge(attributes)
+      end
+
+      @messages = [] unless @messages.is_a?(Array)
+      @messages << entry
+      self
+    end
+
+    def add_messages(messages)
+      @messages = [] unless @messages.is_a?(Array)
+      @messages.concat(Array(messages))
+      self
+    end
+
+    def add_tool(name, tool)
+      @tools = {} unless @tools.is_a?(Hash)
+      @tools[name] = tool
+      self
+    end
+
+    def add_tools(tools)
+      @tools = {} unless @tools.is_a?(Hash)
+
+      case tools
+      when Hash
+        @tools.merge!(tools)
+      when Array
+        tools.each do |entry|
+          raise ToolError, "tools must be a Hash or Array of ToolDefinition entries" unless entry.is_a?(ToolDefinition)
+
+          @tools[entry.name] = entry
+        end
+      else
+        raise ToolError, "tools must be a Hash or Array"
+      end
+
+      self
+    end
+
+    def remove_tool(name)
+      return self unless @tools.is_a?(Hash)
+
+      @tools.delete(name)
+      @tools.delete(name.to_s)
+      @tools.delete(name.to_sym)
+      self
+    end
+
+    def clear_system!
+      @system = nil
+      self
+    end
+  end
+
   ModelDescriptor = Struct.new(:id, :provider, :provider_options, keyword_init: true) do
     def initialize(id:, provider:, provider_options: {})
       super(
@@ -78,6 +160,7 @@ module Zuno
   OPENROUTER_ADAPTER_CONFIG_KEYS = %i[api_key app_url title timeout].freeze
   AI_GATEWAY_ADAPTER_CONFIG_KEYS = %i[api_key timeout base_url].freeze
   REPLICATE_ADAPTER_CONFIG_KEYS = %i[api_key timeout].freeze
+  ELEVENLABS_ADAPTER_CONFIG_KEYS = %i[api_key timeout base_url].freeze
   DEFAULT_MAX_ITERATIONS = 1
   REPLICATE_PREFER_WAIT_SECONDS = 60
   REPLICATE_POLL_INTERVAL_SECONDS = 1
@@ -126,6 +209,18 @@ module Zuno
     )
   end
 
+  def elevenlabs(
+    api_key: nil,
+    timeout: Providers::ElevenLabs::DEFAULT_TIMEOUT,
+    base_url: Providers::ElevenLabs::DEFAULT_BASE_URL
+  )
+    Providers::ElevenLabs.new(
+      api_key: api_key,
+      timeout: timeout,
+      base_url: base_url
+    )
+  end
+
   def tool(name:, description:, input_schema:, &execute)
     raise ToolError, "A block is required for tool '#{name}'" unless block_given?
 
@@ -137,6 +232,98 @@ module Zuno
     )
   end
 
+  def transcribe(
+    model_id: "scribe_v2",
+    file: nil,
+    cloud_storage_url: nil,
+    source_url: nil,
+    provider_options: {},
+    **options
+  )
+    validate_transcription_input!(
+      model_id: model_id,
+      file: file,
+      cloud_storage_url: cloud_storage_url,
+      source_url: source_url
+    )
+    resolved_provider_options = merge_provider_options({}, provider_options)
+    adapter = provider_adapter(:elevenlabs, resolved_provider_options)
+    response = adapter.transcribe(
+      model_id: model_id,
+      file: file,
+      cloud_storage_url: cloud_storage_url,
+      source_url: source_url,
+      options: options
+    )
+
+    result = {
+      text: response["text"],
+      language_code: response["language_code"],
+      language_probability: response["language_probability"],
+      words: response["words"],
+      transcripts: response["transcripts"],
+      transcription_id: response["transcription_id"],
+      raw_response: response
+    }
+    result.reject { |_key, value| value.nil? }
+  rescue ProviderError
+    raise
+  rescue StandardError => e
+    raise Error, e.message
+  end
+
+  def embed(
+    model:,
+    content:,
+    dimensions: nil,
+    encoding_format: nil,
+    provider_options: {},
+    **options
+  )
+    validate_embedding_input!(content: content)
+
+    model_descriptor = normalize_model(model)
+    resolved_provider_options = merge_provider_options(
+      model_descriptor.provider_options,
+      provider_options
+    )
+    provider = model_descriptor.provider.to_sym
+
+    case provider
+    when :openrouter, :ai_gateway
+      adapter = provider_adapter(provider, resolved_provider_options)
+      response = adapter.embed(
+        build_embedding_payload(
+          model_id: model_descriptor.id,
+          provider: provider,
+          content: content,
+          dimensions: dimensions,
+          encoding_format: encoding_format,
+          provider_options: resolved_provider_options,
+          options: options
+        )
+      )
+
+      embeddings = Array(response["data"]).filter_map do |item|
+        item["embedding"] if item.is_a?(Hash)
+      end
+      result = {
+        embeddings: embeddings,
+        usage: response["usage"],
+        model: response["model"],
+        raw_response: response
+      }
+      result[:embedding] = embeddings.first if embeddings.length == 1
+      result
+    else
+      raise ProviderError, "embed only supports openrouter or ai_gateway provider"
+    end
+  rescue ProviderError
+    raise
+  rescue StandardError => e
+    raise Error, e.message
+  end
+
   def generate(
     model:,
     messages: nil,
@@ -258,6 +445,7 @@ module Zuno
     after_generation: nil
   )
     callback_control = nil
+    callback_context = nil
     model_descriptor = normalize_model(model)
     unless %i[openrouter ai_gateway].include?(model_descriptor.provider.to_sym)
       raise Error, "loop only supports openrouter or ai_gateway provider"
@@ -268,12 +456,11 @@ module Zuno
       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
+    callback_context = build_callback_context(
+      messages: messages,
+      system: system,
+      prompt: prompt,
+      tools: tools
     )
     resolved_stop_when = normalize_stop_when(stop_when)
     resolved_max_iterations = normalize_max_iterations(max_iterations)
@@ -284,14 +471,20 @@ module Zuno
       before_generation,
       {
         model: model_descriptor,
-        messages: llm_messages,
-        tool_names: tool_map.keys,
-        tool_choice: resolved_tool_choice,
+        messages: materialize_messages(messages: callback_context.messages, system: callback_context.system),
+        tool_names: callback_context.tools.keys,
+        tool_choice: normalize_tool_choice(
+          explicit_tool_choice: tool_choice,
+          provider_options: resolved_provider_options,
+          tools: callback_context.tools
+        ),
         max_iterations: resolved_max_iterations,
         stop_when: resolved_stop_when
       },
-      callback_control
+      callback_control,
+      callback_context
     )
+    normalize_callback_context!(callback_context)
     if callback_control.stopped?
       result = callback_stopped_result(
         control: callback_control,
@@ -301,7 +494,7 @@ module Zuno
         raw_response: nil
       )
       after_generation_called = true
-      call_callback!(after_generation, { ok: true, result: result }, callback_control)
+      call_callback!(after_generation, { ok: true, result: result }, callback_control, callback_context)
       return result
     end
 
@@ -316,10 +509,12 @@ module Zuno
         before_iteration,
         {
           iteration_index: current_iteration,
-          messages: llm_messages
+          messages: materialize_messages(messages: callback_context.messages, system: callback_context.system)
         },
-        callback_control
+        callback_control,
+        callback_context
       )
+      normalize_callback_context!(callback_context)
       if callback_control.stopped?
         result = callback_stopped_result(
           control: callback_control,
@@ -329,15 +524,20 @@ module Zuno
           raw_response: nil
         )
         after_generation_called = true
-        call_callback!(after_generation, { ok: true, result: result }, callback_control)
+        call_callback!(after_generation, { ok: true, result: result }, callback_control, callback_context)
         return result
       end
 
+      resolved_tool_choice = normalize_tool_choice(
+        explicit_tool_choice: tool_choice,
+        provider_options: resolved_provider_options,
+        tools: callback_context.tools
+      )
       payload = build_payload(
         model_id: model_descriptor.id,
         provider: model_descriptor.provider,
-        messages: llm_messages,
-        tools: tool_map,
+        messages: materialize_messages(messages: callback_context.messages, system: callback_context.system),
+        tools: callback_context.tools,
         tool_choice: resolved_tool_choice,
         temperature: temperature,
         max_tokens: max_tokens,
@@ -365,8 +565,10 @@ module Zuno
             iteration_index: current_iteration,
             iteration: iteration_record
           },
-          callback_control
+          callback_control,
+          callback_context
         )
+        normalize_callback_context!(callback_context)
         if callback_control.stopped?
           result = callback_stopped_result(
             control: callback_control,
@@ -376,7 +578,7 @@ module Zuno
             raw_response: response
           )
           after_generation_called = true
-          call_callback!(after_generation, { ok: true, result: result }, callback_control)
+          call_callback!(after_generation, { ok: true, result: result }, callback_control, callback_context)
           return result
         end
 
@@ -390,11 +592,11 @@ module Zuno
         }
 
         after_generation_called = true
-        call_callback!(after_generation, { ok: true, result: result }, callback_control)
+        call_callback!(after_generation, { ok: true, result: result }, callback_control, callback_context)
         return result
       end
 
-      llm_messages << build_assistant_tool_call_message(message: message, tool_calls: tool_calls)
+      callback_context.add_message(build_assistant_tool_call_message(message: message, tool_calls: tool_calls))
       stop_triggered = false
       stop_triggered_tool_name = nil
 
@@ -412,12 +614,14 @@ module Zuno
             input: arguments,
             raw_tool_call: tool_call
           },
-          callback_control
+          callback_control,
+          callback_context
         )
+        normalize_callback_context!(callback_context)
 
         tool_result = execute_tool_call(
           tool_call: tool_call,
-          tools: tool_map,
+          tools: callback_context.tools,
           tool_call_id: tool_call_id,
           arguments: arguments
         )
@@ -426,29 +630,33 @@ module Zuno
         call_callback!(
           after_tool_execution,
           tool_result.merge(iteration_index: current_iteration),
-          callback_control
+          callback_control,
+          callback_context
         )
+        normalize_callback_context!(callback_context)
         if tool_stop_condition_met?(resolved_stop_when, tool_result)
           stop_triggered = true
           stop_triggered_tool_name ||= tool_result[:tool_name]
         end
 
-        llm_messages << {
+        callback_context.add_message(
           "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
-      )
+          {
+            iteration_index: current_iteration,
+            iteration: iteration_record
+          },
+          callback_control,
+          callback_context
+        )
+      normalize_callback_context!(callback_context)
       if callback_control.stopped?
         result = callback_stopped_result(
           control: callback_control,
@@ -458,7 +666,7 @@ module Zuno
           raw_response: response
         )
         after_generation_called = true
-        call_callback!(after_generation, { ok: true, result: result }, callback_control)
+        call_callback!(after_generation, { ok: true, result: result }, callback_control, callback_context)
         return result
       end
 
@@ -477,7 +685,7 @@ module Zuno
         }
 
         after_generation_called = true
-        call_callback!(after_generation, { ok: true, result: result }, callback_control)
+        call_callback!(after_generation, { ok: true, result: result }, callback_control, callback_context)
         return result
       end
 
@@ -489,13 +697,13 @@ module Zuno
   rescue ProviderError, MaxIterationsExceeded => e
     unless after_generation_called
       after_generation_called = true
-      call_callback!(after_generation, { ok: false, error: e }, callback_control)
+      call_callback!(after_generation, { ok: false, error: e }, callback_control, callback_context)
     end
     raise
   rescue StandardError => e
     unless after_generation_called
       after_generation_called = true
-      call_callback!(after_generation, { ok: false, error: e }, callback_control)
+      call_callback!(after_generation, { ok: false, error: e }, callback_control, callback_context)
     end
     raise Error, e.message
   end
@@ -763,6 +971,53 @@ module Zuno
   end
   private_class_method :validate_no_webhook_support!
 
+  def validate_transcription_input!(model_id:, file:, cloud_storage_url:, source_url:)
+    model_id_value = model_id.to_s.strip
+    raise Error, "model_id is required" if model_id_value.empty?
+
+    inputs = []
+    inputs << :file unless file.nil?
+    inputs << :cloud_storage_url unless cloud_storage_url.nil? || cloud_storage_url.to_s.strip.empty?
+    inputs << :source_url unless source_url.nil? || source_url.to_s.strip.empty?
+
+    if inputs.empty?
+      raise Error, "transcribe requires one input: file, cloud_storage_url, or source_url"
+    end
+
+    return if inputs.length == 1
+
+    raise Error, "transcribe accepts exactly one input: file, cloud_storage_url, or source_url"
+  end
+  private_class_method :validate_transcription_input!
+
+  def validate_embedding_input!(content:)
+    case content
+    when String
+      raise Error, "content is required" if content.strip.empty?
+    when Array
+      raise Error, "content must include at least one item" if content.empty?
+    when nil
+      raise Error, "content is required"
+    end
+  end
+  private_class_method :validate_embedding_input!
+
+  def build_embedding_payload(model_id:, provider:, content:, dimensions:, encoding_format:, provider_options:, options:)
+    payload = {
+      "model" => model_id,
+      "input" => deep_stringify(content)
+    }
+
+    payload["dimensions"] = dimensions unless dimensions.nil?
+    payload["encoding_format"] = encoding_format unless encoding_format.nil?
+
+    request_options = reject_keys(provider_options, provider_adapter_config_keys(provider) + [:tool_choice])
+    payload.merge!(deep_stringify(request_options)) if request_options.is_a?(Hash)
+    payload.merge!(deep_stringify(options)) if options.is_a?(Hash) && !options.empty?
+    payload
+  end
+  private_class_method :build_embedding_payload
+
   def normalize_tools(tools)
     return {} if tools.nil?
 
@@ -801,19 +1056,57 @@ module Zuno
   private_class_method :normalize_tool_entry
 
   def normalize_messages(messages:, system:, prompt:)
+    materialize_messages(
+      messages: normalize_callback_messages(messages: messages, prompt: prompt),
+      system: normalize_callback_system(system)
+    )
+  end
+  private_class_method :normalize_messages
+
+  def build_callback_context(messages:, system:, prompt:, tools:)
+    CallbackContext.new(
+      messages: normalize_callback_messages(messages: messages, prompt: prompt),
+      system: normalize_callback_system(system),
+      tools: normalize_tools(tools)
+    )
+  end
+  private_class_method :build_callback_context
+
+  def normalize_callback_context!(context)
+    context.messages = normalize_callback_messages(messages: context.messages, prompt: nil)
+    context.system = normalize_callback_system(context.system)
+    context.tools = normalize_tools(context.tools)
+    context
+  end
+  private_class_method :normalize_callback_context!
+
+  def normalize_callback_messages(messages:, 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
+    else
+      raise Error, "messages must be an Array" unless messages.is_a?(Array)
+
+      normalized = deep_stringify(messages)
     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
+  private_class_method :normalize_callback_messages
+
+  def normalize_callback_system(system)
+    return nil if system.nil?
+
+    system.to_s
+  end
+  private_class_method :normalize_callback_system
+
+  def materialize_messages(messages:, system:)
+    normalized = normalize_callback_messages(messages: messages, prompt: nil)
+    normalized.unshift({ "role" => "system", "content" => system.to_s }) if system
+    normalized
+  end
+  private_class_method :materialize_messages
 
   def build_payload(model_id:, provider:, messages:, tools:, tool_choice:, temperature:, max_tokens:, provider_options:)
     payload = {
@@ -840,6 +1133,8 @@ module Zuno
       AI_GATEWAY_ADAPTER_CONFIG_KEYS
     when :replicate
       REPLICATE_ADAPTER_CONFIG_KEYS
+    when :elevenlabs
+      ELEVENLABS_ADAPTER_CONFIG_KEYS
     else
       []
     end
@@ -866,6 +1161,9 @@ module Zuno
     when :replicate
       config = pick_keys(provider_options, REPLICATE_ADAPTER_CONFIG_KEYS)
       Providers::Replicate.new(**config)
+    when :elevenlabs
+      config = pick_keys(provider_options, ELEVENLABS_ADAPTER_CONFIG_KEYS)
+      Providers::ElevenLabs.new(**config)
     else
       raise ProviderError, "Unsupported provider: #{provider}"
     end
@@ -1062,28 +1360,33 @@ module Zuno
   end
   private_class_method :callback_stopped_result
 
-  def call_callback!(callback, payload, control = nil)
+  def call_callback!(callback, payload, control = nil, context = 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)
+    unless callback.lambda?
+      args = [payload]
+      args << control if control
+      args << context if context
+      callback.call(*args)
+      return
     end
+
+    args = [payload]
+    args << control if control && callback_accepts_argument_count?(callback, 2)
+    args << context if context && callback_accepts_argument_count?(callback, 3)
+    callback.call(*args)
   end
   private_class_method :call_callback!
 
-  def callback_accepts_control?(callback)
-    return true unless callback.lambda?
-
+  def callback_accepts_argument_count?(callback, count)
     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
+    positional_count >= count
   end
-  private_class_method :callback_accepts_control?
+  private_class_method :callback_accepts_argument_count?
 
   def normalize_output_payload(payload)
     case payload
@@ -1182,6 +1485,7 @@ module Zuno
   module Providers
     class OpenRouter
       CHAT_COMPLETIONS_URL = "https://openrouter.ai/api/v1/chat/completions".freeze
+      EMBEDDINGS_URL = "https://openrouter.ai/api/v1/embeddings".freeze
       DEFAULT_TIMEOUT = 120_000
 
       def initialize(api_key: nil, app_url: nil, title: nil, timeout: DEFAULT_TIMEOUT)
@@ -1218,6 +1522,23 @@ module Zuno
         raise ProviderError, "Failed to parse OpenRouter response: #{e.message}"
       end
 
+      def embed(payload)
+        response = Typhoeus.post(
+          EMBEDDINGS_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?
 
@@ -1317,6 +1638,23 @@ module Zuno
         raise ProviderError, "Failed to parse Vercel Gateway response: #{e.message}"
       end
 
+      def embed(payload)
+        response = Typhoeus.post(
+          embeddings_url,
+          headers: headers,
+          body: JSON.generate(payload),
+          timeout: @timeout
+        )
+
+        validate_response!(response)
+        parsed = JSON.parse(response.body)
+        raise ProviderError, "Vercel Gateway returned invalid JSON" unless parsed.is_a?(Hash)
+
+        parsed
+      rescue JSON::ParserError => e
+        raise ProviderError, "Failed to parse Vercel Gateway response: #{e.message}"
+      end
+
       def stream(payload)
         raise ArgumentError, "stream requires a block callback" unless block_given?
 
@@ -1353,6 +1691,10 @@ module Zuno
         "#{@base_url}/chat/completions"
       end
 
+      def embeddings_url
+        "#{@base_url}/embeddings"
+      end
+
       def headers
         {
           "Authorization" => "Bearer #{@api_key}",
@@ -1506,6 +1848,106 @@ module Zuno
         raise ProviderError, "Replicate request failed: #{response.return_code}#{suffix}"
       end
     end
+
+    class ElevenLabs
+      DEFAULT_BASE_URL = "https://api.elevenlabs.io".freeze
+      SPEECH_TO_TEXT_PATH = "/v1/speech-to-text".freeze
+      DEFAULT_TIMEOUT = 120_000
+
+      def initialize(api_key: nil, timeout: DEFAULT_TIMEOUT, base_url: DEFAULT_BASE_URL)
+        @api_key = api_key
+        raise ProviderError, "ElevenLabs API key not configured" if @api_key.nil? || @api_key.to_s.empty?
+
+        @timeout = timeout
+        @base_url = base_url.to_s.empty? ? DEFAULT_BASE_URL : base_url.to_s
+      end
+
+      def transcribe(model_id:, file:, cloud_storage_url:, source_url:, options:)
+        opened_file = nil
+        body = build_body(
+          model_id: model_id,
+          file: file,
+          cloud_storage_url: cloud_storage_url,
+          source_url: source_url,
+          options: options
+        ) do |candidate|
+          opened_file = candidate
+        end
+
+        response = Typhoeus.post(
+          speech_to_text_url,
+          headers: headers,
+          body: body,
+          multipart: true,
+          timeout: @timeout
+        )
+
+        validate_response!(response)
+        parsed = JSON.parse(response.body)
+        raise ProviderError, "ElevenLabs returned invalid JSON" unless parsed.is_a?(Hash)
+
+        parsed
+      rescue JSON::ParserError => e
+        raise ProviderError, "Failed to parse ElevenLabs response: #{e.message}"
+      ensure
+        opened_file.close if opened_file.is_a?(File) && !opened_file.closed?
+      end
+
+      private
+
+      def speech_to_text_url
+        "#{@base_url}#{SPEECH_TO_TEXT_PATH}"
+      end
+
+      def headers
+        { "xi-api-key" => @api_key }
+      end
+
+      def build_body(model_id:, file:, cloud_storage_url:, source_url:, options:)
+        body = {
+          "model_id" => model_id.to_s
+        }
+
+        normalized_options = options.is_a?(Hash) ? options : {}
+        normalized_options.each do |key, value|
+          next if value.nil?
+
+          body[key.to_s] = value
+        end
+
+        if file.is_a?(String)
+          opened_file = File.open(file, "rb")
+          body["file"] = opened_file
+          yield(opened_file) if block_given?
+        elsif !file.nil?
+          body["file"] = file
+        end
+
+        body["cloud_storage_url"] = cloud_storage_url.to_s unless cloud_storage_url.nil? || cloud_storage_url.to_s.strip.empty?
+        body["source_url"] = source_url.to_s unless source_url.nil? || source_url.to_s.strip.empty?
+        body
+      rescue Errno::ENOENT => e
+        raise ProviderError, "Failed to open transcription file: #{e.message}"
+      end
+
+      def validate_response!(response)
+        raise ProviderError, "No response returned from ElevenLabs" if response.nil?
+        raise ProviderError, "ElevenLabs 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, "ElevenLabs responded with HTTP #{status}: #{message}"
+        end
+
+        suffix = message.empty? ? "" : ": #{message}"
+        raise ProviderError, "ElevenLabs request failed: #{response.return_code}#{suffix}"
+      end
+    end
   end
 
   class SseParser

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zuno
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Hyperaide
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: typhoeus
@@ -53,13 +53,14 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.13'
 description: Standalone Ruby SDK for AI generation across OpenRouter and Replicate,
-  with iterative tool loops and SSE streaming.
+  ElevenLabs speech-to-text, with iterative tool loops and SSE streaming.
 email:
-- team@hyperaide.dev
+- team@hyperaide.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - README.md
 - lib/zuno.rb
 - lib/zuno/version.rb