zuno 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 375f446f6d41ed1c8f05361915316c3da7fbc571ee5ec4d59316739f9fd6a14f
-  data.tar.gz: 641e201f64dc3076185e2a6593932e67847f05ce4c5a66866b200b8db4d38241
+  metadata.gz: cf9be3e305d36fb21db7c92926787237b8db4322a993d3e8c8a38448c439d7b4
+  data.tar.gz: b004707c8eb242a35c631defafd13a13f0bf3533f9959e4b8ec2c62829097337
 SHA512:
-  metadata.gz: 76d4be87dad8f35fc9e879a14705035344823f43c0ba45c6d8317d5b8e0a273c6349db11294b8e17c5dfb901dec9006fa488b8ebe8633baec33aa66e74be9166
-  data.tar.gz: 8555df550de0513330c086ec4b676d584a1908feb983d2ca59d32c8d685f626d2c767960e6e1dde23dbb17ac0cfc903aee251bef71519ffde27f8c1524cd2d68
+  metadata.gz: 4153961f2ece3493d232af7f742c40be7fa09adbf76a82fb2722923630033e778f846c7489582f1e4bc06afafdc40663dcd237c4f70f6af0a4004da6dad5b09b
+  data.tar.gz: 486f38c407011327c5a9c336341bcc742233cfda7112b8596f9f5050565791d7ab24a36777c6061fe14dbfc65126e310c9ad69f372423b221726533ab8c37fa9

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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

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.2"
+  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(
@@ -190,6 +272,58 @@ module Zuno
     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,
@@ -311,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"
@@ -321,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)
@@ -337,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,
@@ -354,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
 
@@ -369,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,
@@ -382,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,
@@ -418,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,
@@ -429,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
 
@@ -443,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
 
@@ -465,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
         )
@@ -479,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,
@@ -511,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
 
@@ -530,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
 
@@ -542,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
@@ -835,6 +990,34 @@ module Zuno
   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?
 
@@ -873,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 = {
@@ -1139,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
@@ -1259,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)
@@ -1295,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?
 
@@ -1394,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?
 
@@ -1430,6 +1691,10 @@ module Zuno
         "#{@base_url}/chat/completions"
       end
 
+      def embeddings_url
+        "#{@base_url}/embeddings"
+      end
+
       def headers
         {
           "Authorization" => "Bearer #{@api_key}",

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zuno
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Hyperaide
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-01 00:00:00.000000000 Z
+date: 2026-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: typhoeus
@@ -55,7 +55,7 @@ dependencies:
 description: Standalone Ruby SDK for AI generation across OpenRouter and Replicate,
   ElevenLabs speech-to-text, with iterative tool loops and SSE streaming.
 email:
-- team@hyperaide.dev
+- team@hyperaide.com
 executables: []
 extensions: []
 extra_rdoc_files: []