llm.rb 15.2.2 → 15.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '01569fad6afcf4d422b666778989e7bafd1c6e994b6e2be7801ccb5842a7aa3d'
-  data.tar.gz: f60ddf02e1a8405cf393e8c581cce61415f459d3207a7c8dc531cbe4e0e87f27
+  metadata.gz: a461691c878ffef8343a8f1ae2dad4298ebb631d379d901110ef8ab8641d9c68
+  data.tar.gz: 95bb85e3debb178ebbe6949cd3cafbb3625d6f20a72d617f08f1a600354911ba
 SHA512:
-  metadata.gz: 8d9f88421f209e72e1631cbe3e4119d80af29aa72dc44a1917a6dfcbaa76b3d8014d70afe1c771177f6a755ea2d840ffaf92a850606fdd9d08db5c0d0283d0d6
-  data.tar.gz: b9d2417b3d2ce4f54ae5c657791518261332508b7dcfe726f19f81d97a27f329220a81ea2ced411fd15625b11c3964c69e1bcfef5df799f9ee0d16f2342cdd56
+  metadata.gz: c9b6e723d1bc16d9cc515a9ae2a3fd34072ce88024804d5b7b0e713cff0b08c26e78e2008641763bbc9a3aabea6f262023fa1f243d9fe155f8d8fdf58215d24f
+  data.tar.gz: e125d9936d34b3550fb504d281760b73bc617aa4b5d42f1f4d1e3b9b3edd98a448c4a7509d010c62b67b1f57def5f3a9f1e088786b860e6d8f08c94bf64aa0f8

data/CHANGELOG.md

@@ -17,6 +17,82 @@
 
 *No unreleased changes yet. Check back after the next release.*
 
+## v15.3.0
+
+Changes since `v15.2.2`.
+
+This release gives contexts, agents, and messages UUIDv7 ids that survive
+persistence and back their `created_at`, scopes per-request headers through a
+block on `LLM::Provider#with`, and pins an OpenRouter session per context. It
+also fixes the OpenAI tool schema sent through OpenRouter and Azure, which
+mixed the Responses and Chat Completions shapes and left nested objects open.
+
+### Core
+
+* **context: give every context an id you can sort and trace** <br>
+  [`LLM::Context#id`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#id-instance_method)
+  returns a UUIDv7 string that encodes its creation time, so contexts and their
+  agents sort by creation order and stay identifiable within and across
+  sessions. The id is generated on creation and restored with the runtime state
+  on load. [`LLM::Agent#id`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#id-instance_method)
+  delegates to the context it wraps; a model and its agent keep separate ids.
+
+* **context: read the creation time without storing it** <br>
+  [`LLM::Context#created_at`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#created_at-instance_method)
+  returns when the context was created, read from the timestamp its UUIDv7 id
+  already carries, so no separate timestamp has to be persisted or kept in sync.
+  `LLM::Agent#created_at` delegates to it. The time is recomputed rather than
+  stored, so it returns `nil` for a context whose id is not a UUIDv7 string.
+
+* **message: give every message an id that survives persistence** <br>
+  [`LLM::Message#id`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html#id-instance_method)
+  returns a UUIDv7 string generated once when the message is created and restored
+  with the runtime state on load, so a message keeps the same identity across
+  saves and loads. `LLM::Message#created_at` is derived from the id rather than
+  stored. `LLM::Message#==` ignores the id, so two messages with the same role
+  and content are equal even when they were created at different times;
+  previously the timestamp took part in the comparison.
+
+* **utils: decode a UUIDv7 timestamp once, in one place** <br>
+  [`LLM::Utils.timestamp`](https://r.uby.dev/api-docs/llm.rb/LLM/Utils.html#timestamp-instance_method)
+  returns the UTC time encoded in a UUIDv7 string, or `nil` when the value is not
+  a UUIDv7. It backs `created_at` on messages, contexts, and agents, so the
+  decoding logic lives in a single method instead of three.
+
+### Provider
+
+* **provider: set a per-request header without leaking it** <br>
+  [`LLM::Provider#with`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#with-instance_method)
+  now takes a block: headers set inside apply to the current fiber only and are
+  restored when the block returns, so a header that varies per request can be set
+  for one call without leaking into the next. Without a block the headers are
+  merged into the provider's defaults as before. The method returns the provider
+  without a block and the block's value with one.
+
+* **openrouter: keep one session so requests reuse a cached model** <br>
+  A context now sends its id as the `x-session-id` header on OpenRouter requests,
+  so consecutive requests share a session and OpenRouter can route them to the
+  same cached model instead of starting fresh each time. Other providers are
+  unaffected.
+
+### Fix
+
+* **openai: make tools callable through OpenRouter and Azure again** <br>
+  Fix a bug where [`LLM::OpenAI`](https://r.uby.dev/api-docs/llm.rb/LLM/OpenAI.html)
+  sent a function schema that mixed the Responses and Chat Completions shapes,
+  carrying a top-level `name` next to a nested `function` object. OpenRouter and
+  OpenAI through Azure read it as a Responses function and could not describe the
+  tool correctly. The name, description, parameters, and `strict: false` now sit
+  under `function:`, the shape chat completions documents.
+
+* **openai: stop Azure rejecting nested schema objects** <br>
+  Tool parameters and structured-output schemas now carry
+  `additionalProperties: false` on every object they contain, not just the root,
+  in the chat completions and Responses paths alike. OpenAI and Azure reject a
+  schema that leaves any object open, so nested objects were failing validation.
+  The chat completions structured-output schema, which was sent open, is now
+  closed too.
+
 ## v15.2.2
 
 Changes since `v15.2.1`.

data/lib/llm/agent.rb

@@ -510,6 +510,22 @@ module LLM
       @ctx.messages
     end
 
+    ##
+    # Returns a stable id for this agent. The id is borrowed from
+    # the context it wraps, so it survives save and restore.
+    # @return [String]
+    def id
+      @ctx.id
+    end
+
+    ##
+    # Returns the time this agent was created. It is derived
+    # from the context id, so it is not persisted separately.
+    # @return [Time, nil]
+    def created_at
+      @ctx.created_at
+    end
+
     ##
     # @return [Integer]
     def retry_budget

data/lib/llm/context/deserializer.rb

@@ -25,6 +25,8 @@ class LLM::Context
       else
         LLM.json.load(string)
       end
+      @id = ctx["id"] || @id
+      @created_at = nil
       @messages.concat [*ctx["messages"]].map { deserialize_message(_1) }
       @compacted = !!ctx["compacted"]
       self
@@ -40,8 +42,8 @@ class LLM::Context
       usage = payload["usage"]
       reasoning_content = payload["reasoning_content"]
       compaction = payload["compaction"]
-      created_at = payload["created_at"]
-      extra = {tool_calls:, original_tool_calls:, tools: @params[:tools], usage:, reasoning_content:, compaction:, created_at:}.compact
+      id = payload["id"]
+      extra = {tool_calls:, original_tool_calls:, tools: @params[:tools], usage:, reasoning_content:, compaction:, id:}.compact
       content = returns.nil? ? deserialize_content(payload["content"]) : returns
       LLM::Message.new(payload["role"], content, extra)
     end

data/lib/llm/context.rb

@@ -55,7 +55,7 @@ module LLM
     # @api private
     # @return [Array<Symbol>]
     def self.params
-      %w[guard retry_budget concurrency transformer compactor record]
+      %w[guard retry_budget concurrency transformer compactor record id]
     end
 
     ##
@@ -78,6 +78,12 @@ module LLM
     # @return [Object, nil]
     attr_reader :record
 
+    ##
+    # Returns a stable id for this context. It is generated once
+    # on creation and restored with the runtime state on load.
+    # @return [String]
+    attr_reader :id
+
     ##
     # @param [LLM::Provider] llm
     #  A provider
@@ -89,6 +95,8 @@ module LLM
     #   Defaults to `:responses` for OpenAI, otherwise it defaults
     #   to `:completions`.
     # @option params [String] :model Defaults to the provider's default model
+    # @option params [String] :id
+    #   A stable id for the context. Defaults to a UUID.
     # @option params [Class<LLM::Compactor>, nil] :compactor
     #   A compactor class to use for context compaction. Defaults to
     #   {LLM::Compactor::Null}.
@@ -109,6 +117,7 @@ module LLM
     def initialize(llm, params = {})
       params = {}.merge!(params)
       @llm = llm
+      @id = params.delete(:id) || SecureRandom.uuid_v7
       @record = params.delete(:record)
       @mode = params.delete(:mode) || (llm.name == :openai ? :responses : :completions)
       tools = [*params.delete(:tools), *load_skills(params.delete(:skills))]
@@ -488,11 +497,20 @@ module LLM
       messages.find(&:assistant?)&.model || @params[:model] || @llm.default_model
     end
 
+    ##
+    # Returns the time this context was created, derived from the
+    # timestamp embedded in its UUIDv7 id, or nil when it is not.
+    # @return [Time, nil]
+    def created_at
+      @created_at ||= LLM::Utils.timestamp(@id)
+    end
+
     ##
     # @return [Hash]
     def to_h
       {
         schema_version: 1,
+        id: @id,
         model:,
         compacted:,
         messages: @messages.map { serialize_message(_1) }
@@ -597,33 +615,37 @@ module LLM
     # Executes a turn through the Responses API.
     # @api private
     def respond(prompt, params)
-      history = @messages.to_a
-      params = @params.merge(params).reject { self.class.params.include?(_1.to_s) }
-      extra = params.slice(:model, :tools).merge!(ctx: self, tracer:, guard: @guard[:klass].new(self))
-      params[:stream] = LLM::Stream.try(params[:stream], extra:)
-      res_id = params[:store] == false ? nil : @messages.find(&:assistant?)&.response&.response_id
-      input = res_id ? [] : history
-      params[:input] = input
-      messages = transform(prompt, params, key: :input)
-      @stream = params[:stream]
-      new_messages = messages[input.size..]
-      params = params.merge(previous_response_id: res_id, input:).compact
-      [new_messages, params, @llm.responses.create(messages, params)]
+      @llm.with(**headers) do
+        history = @messages.to_a
+        params = @params.merge(params).reject { self.class.params.include?(_1.to_s) }
+        extra = params.slice(:model, :tools).merge!(ctx: self, tracer:, guard: @guard[:klass].new(self))
+        params[:stream] = LLM::Stream.try(params[:stream], extra:)
+        res_id = params[:store] == false ? nil : @messages.find(&:assistant?)&.response&.response_id
+        input = res_id ? [] : history
+        params[:input] = input
+        messages = transform(prompt, params, key: :input)
+        @stream = params[:stream]
+        new_messages = messages[input.size..]
+        params = params.merge(previous_response_id: res_id, input:).compact
+        [new_messages, params, @llm.responses.create(messages, params)]
+      end
     end
 
     ##
     # Executes a turn through the chat completions API.
     # @api private
     def complete(prompt, params)
-      history = @messages.to_a
-      params = params.merge(messages: history)
-      params = @params.merge(params).reject { self.class.params.include?(_1.to_s) }
-      extra = params.slice(:model, :tools).merge!(ctx: self, tracer:, guard: @guard[:klass].new(self))
-      params[:stream] = LLM::Stream.try(params[:stream], extra:)
-      messages = transform(prompt, params)
-      @stream = params[:stream]
-      new_messages = messages[history.size..]
-      [new_messages, params, @llm.complete(messages, params)]
+      @llm.with(**headers) do
+        history = @messages.to_a
+        params = params.merge(messages: history)
+        params = @params.merge(params).reject { self.class.params.include?(_1.to_s) }
+        extra = params.slice(:model, :tools).merge!(ctx: self, tracer:, guard: @guard[:klass].new(self))
+        params[:stream] = LLM::Stream.try(params[:stream], extra:)
+        messages = transform(prompt, params)
+        @stream = params[:stream]
+        new_messages = messages[history.size..]
+        [new_messages, params, @llm.complete(messages, params)]
+      end
     end
 
     ##
@@ -652,5 +674,15 @@ module LLM
       end
       messages << LLM::Message.new(@llm.tool_role, cancelled) unless cancelled.empty?
     end
+
+    ##
+    # @return [Hash]
+    def headers
+      if @llm.name == :openrouter
+        {"x-session-id" => @id}
+      else
+        {}
+      end
+    end
   end
 end

data/lib/llm/message.rb

@@ -18,9 +18,10 @@ module LLM
     attr_reader :extra
 
     ##
-    # Returns the time the message was created
-    # @return [Time]
-    attr_reader :created_at
+    # Returns a stable id for this message. It is generated once
+    # on creation and restored with the runtime state on load.
+    # @return [String]
+    attr_reader :id
 
     ##
     # Returns a new message
@@ -32,7 +33,15 @@ module LLM
       @role = role.to_s
       @content = content
       @extra = LLM::Object.from(extra)
-      @created_at = extra[:created_at] ? Time.iso8601(extra[:created_at].to_s) : Time.now.utc
+      @id = extra[:id] || SecureRandom.uuid_v7
+    end
+
+    ##
+    # Returns the time this message was created, derived from the
+    # timestamp embedded in its UUIDv7 id, or nil when it is not.
+    # @return [Time, nil]
+    def created_at
+      @created_at ||= LLM::Utils.timestamp(@id)
     end
 
     ##
@@ -40,10 +49,10 @@ module LLM
     # @return [Hash]
     def to_h
       {
+        id: @id,
         role:,
         content:,
         reasoning_content:,
-        created_at: created_at.utc.iso8601,
         compaction: extra.compaction,
         tools: extra.tool_calls&.map { LLM::Object === _1 ? _1.to_h : _1 },
         usage:,
@@ -58,13 +67,15 @@ module LLM
     end
 
     ##
-    # Returns true when two objects have the same role and content
+    # Returns true when two objects have the same role and content.
+    # The id is ignored, because it identifies a message rather than
+    # describing it.
     # @param [Object] other
     #  The other object to compare
     # @return [Boolean]
     def ==(other)
       if other.respond_to?(:to_h)
-        to_h == other.to_h
+        to_h.except(:id) == other.to_h.except(:id)
       else
         false
       end

data/lib/llm/provider.rb

@@ -263,11 +263,21 @@ class LLM::Provider
   end
 
   ##
-  # Add one or more headers to all requests
-  # @example
+  # Add one or more headers to all requests, or scope them to a block.
+  #
+  # Without a block the headers are merged into the provider's defaults
+  # permanently. With a block the headers apply only to the current fiber,
+  # for the duration of the block, then the previous headers are restored.
+  # This is useful for a header that varies per context, such as
+  # OpenRouter's `x-session-id`.
+  # @example Permanent
   #   llm = LLM.openai(key: ENV["KEY"])
   #   llm.with("OpenAI-Organization" => ENV["ORG"])
   #   llm.with("OpenAI-Project" => ENV["PROJECT"])
+  # @example Scoped
+  #   llm.with("x-session-id" => ctx.id) do
+  #     llm.complete("hello")
+  #   end
   # @param [Hash<String,String>] headers
   #  One or more headers
   # @note
@@ -275,12 +285,26 @@ class LLM::Provider
   #  provided via the `headers:` keyword argument,
   #  or provided directly as a Hash without the
   #  `headers:` key namespace.
+  # @yield
   # @return [LLM::Provider]
-  #  Returns self
-  def with(**headers)
+  #  Returns self without a block, the block's value with one
+  def with(**headers, &block)
     headers = headers.merge(headers.delete(:headers) || {})
-    lock do
-      tap { @headers.merge!(headers) }
+    if block
+      wm = weakmaps.header
+      previous = wm[self]
+      wm[self] = (previous || {}).merge(headers)
+      block.call
+    else
+      lock { tap { @headers.merge!(headers) } }
+    end
+  ensure
+    if block
+      if previous.nil?
+        wm.respond_to?(:delete) ? wm.delete(self) : wm[self] = nil
+      else
+        wm[self] = previous
+      end
     end
   end
 
@@ -349,7 +373,7 @@ class LLM::Provider
   # @return [LLM::Tracer]
   #  Returns the current scoped tracer override or provider default tracer
   def tracer
-    weakmap[self] || @tracer || LLM::Tracer::Null.new(self)
+    weakmaps.tracer[self] || @tracer || LLM::Tracer::Null.new(self)
   end
 
   ##
@@ -378,17 +402,18 @@ class LLM::Provider
   # @yield
   # @return [Object]
   def with_tracer(tracer)
-    had_override = weakmap.key?(self)
-    previous = weakmap[self]
-    weakmap[self] = tracer || LLM::Tracer::Null.new(self)
+    wm = weakmaps.tracer
+    had_override = wm.key?(self)
+    previous = wm[self]
+    wm[self] = tracer || LLM::Tracer::Null.new(self)
     yield
   ensure
     if had_override
-      weakmap[self] = previous
-    elsif weakmap.respond_to?(:delete)
-      weakmap.delete(self)
+      wm[self] = previous
+    elsif wm.respond_to?(:delete)
+      wm.delete(self)
     else
-      weakmap[self] = nil
+      wm[self] = nil
     end
   end
 
@@ -504,8 +529,25 @@ class LLM::Provider
   end
 
   ##
+  # Returns the temporary headers set by {#with}
+  # for the current fiber.
   # @api private
-  def weakmap
-    thread[:"llm.provider.weakmap"] ||= ObjectSpace::WeakMap.new
+  # @return [Hash]
+  def temporary_headers
+    weakmaps.header[self] || {}
+  end
+
+  ##
+  # @return [LLM::Object]
+  def weakmaps
+    if thread["llm.#{name}.weakmaps"]
+      thread["llm.#{name}.weakmaps"]
+    else
+      weakmaps = LLM::Object.from(
+        tracer: ObjectSpace::WeakMap.new,
+        header: ObjectSpace::WeakMap.new
+      )
+      thread["llm.#{name}.weakmaps"] = weakmaps
+    end
   end
 end

data/lib/llm/providers/anthropic.rb

@@ -141,7 +141,9 @@ module LLM
 
     def headers
       lock do
-        (@headers || {}).merge(
+        (@headers || {})
+        .merge(temporary_headers)
+        .merge(
           "Content-Type" => "application/json",
           "x-api-key" => @key,
           "anthropic-version" => "2023-06-01",

data/lib/llm/providers/bedrock.rb

@@ -183,7 +183,9 @@ module LLM
 
     def headers
       lock do
-        (@headers || {}).merge("Content-Type" => "application/json")
+        (@headers || {})
+        .merge(temporary_headers)
+        .merge("Content-Type" => "application/json")
       end
     end
 

data/lib/llm/providers/google.rb

@@ -186,9 +186,9 @@ module LLM
 
     def headers
       lock do
-        (@headers || {}).merge(
-          "Content-Type" => "application/json"
-        )
+        (@headers || {})
+        .merge(temporary_headers)
+        .merge("Content-Type" => "application/json")
       end
     end
 

data/lib/llm/providers/mistral.rb

@@ -136,7 +136,9 @@ module LLM
     # @api private
     def headers
       lock do
-        (@headers || {}).merge(
+        (@headers || {})
+        .merge(temporary_headers)
+        .merge(
           "Authorization" => "Bearer #{@key}",
           "Content-Type" => "application/json"
         )

data/lib/llm/providers/ollama.rb

@@ -113,7 +113,9 @@ module LLM
 
     def headers
       lock do
-        (@headers || {}).merge(
+        (@headers || {})
+        .merge(temporary_headers)
+        .merge(
           "Content-Type" => "application/json",
           "Authorization" => "Bearer #{@key}"
         )

data/lib/llm/providers/openai/request_adapter.rb

@@ -36,7 +36,7 @@ class LLM::OpenAI
       {
         response_format: {
           type: "json_schema",
-          json_schema: {name: "JSONSchema", schema:}
+          json_schema: {name: "JSONSchema", schema: LLM::Schema::Utils.close(schema)}
         }
       }
     end

data/lib/llm/providers/openai/responses.rb

@@ -98,7 +98,7 @@ class LLM::OpenAI
     def adapt_function(fn)
       {
         type: "function", name: fn.name, description: fn.description,
-        parameters: fn.params.to_h.merge(additionalProperties: false), strict: false
+        parameters: LLM::Schema::Utils.close(fn.params), strict: false
       }.compact
     end
 
@@ -112,7 +112,7 @@ class LLM::OpenAI
       return {} unless params && params[:schema]
       schema = params.delete(:schema)
       schema = schema.respond_to?(:object) ? schema.object : schema
-      schema = schema.to_h.merge(additionalProperties: false)
+      schema = LLM::Schema::Utils.close(schema)
       name = "JSONSchema"
       {text: {format: {type: "json_schema", name:, schema:}}}
     end

data/lib/llm/providers/openai.rb

@@ -156,10 +156,10 @@ module LLM
     # @param [LLM::Function] fn
     # @return [Hash]
     def adapt_function(fn)
-      params = fn.params.to_h
+      params = LLM::Schema::Utils.close(fn.params)
       {
-        type: "function", name: fn.name,
-        function: {name: fn.name, description: fn.description, parameters: params}
+        type: "function",
+        function: {name: fn.name, description: fn.description, parameters: params, strict: false}
       }.compact
     end
 
@@ -203,7 +203,9 @@ module LLM
 
     def headers
       lock do
-        (@headers || {}).merge(
+        (@headers || {})
+        .merge(temporary_headers)
+        .merge(
           "Content-Type" => "application/json",
           "Authorization" => "Bearer #{@key}"
         )

data/lib/llm/schema.rb

@@ -81,6 +81,30 @@ class LLM::Schema
     def fetch(properties, name)
       properties[name] || properties.fetch(name.to_s)
     end
+
+    ##
+    # Returns a copy of a JSON schema where every object is
+    # closed with "additionalProperties": false. OpenAI and
+    # Azure reject tool parameters that leave an object open,
+    # and they validate nested objects as well as the root.
+    # @param [Object] node
+    #  A schema, a Hash of properties, or an Array of either
+    # @return [Object]
+    def close(node)
+      case node
+      when LLM::Schema::Leaf
+        close(node.to_h)
+      when LLM::Object
+        close(node.to_h)
+      when Hash
+        node.to_h { |key, value| [key, close(value)] }
+            .then { _1[:type] == "object" ? _1.merge(additionalProperties: false) : _1 }
+      when Array
+        node.map { close(_1) }
+      else
+        node
+      end
+    end
   end
 
   ##

data/lib/llm/utils.rb

@@ -48,6 +48,19 @@ module LLM
       (defined?(::Sequel::Model) and ::Sequel::Model === obj)
     end
 
+    ##
+    # Returns the UTC time encoded in a UUIDv7, or nil when the
+    # given value is not a UUIDv7. The first 48 bits of a UUIDv7
+    # are a Unix millisecond timestamp.
+    # @param [Object] id
+    # @return [Time, nil]
+    def timestamp(id)
+      hex = id.to_s.delete("-")
+      return nil unless hex.match?(/\A\h{32}\z/)
+      return nil unless hex[12] == "7"
+      Time.at(hex[0, 12].to_i(16) / 1000.0).utc
+    end
+
     ##
     # Normalizes an HTTP API base path.
     #

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "15.2.2"
+  VERSION = "15.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 15.2.2
+  version: 15.3.0
 platform: ruby
 authors:
 - Robert Gleeson