llm.rb 4.14.0 → 4.16.0

data/lib/llm/active_record.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "llm/active_record/acts_as_llm"

data/lib/llm/context.rb

@@ -2,16 +2,21 @@
 
 module LLM
   ##
-  # {LLM::Context LLM::Context} represents a stateful interaction with
-  # an LLM, including conversation history, tools, execution state,
-  # and cost tracking. It evolves over time as the system runs.
+  # {LLM::Context LLM::Context} is the stateful execution boundary in
+  # llm.rb.
   #
-  # Context is the stateful environment in which an LLM operates.
-  # This is not just prompt context; it is an active, evolving
-  # execution boundary for LLM workflows.
+  # It holds the evolving runtime state for an LLM workflow:
+  # conversation history, tool calls and returns, schema and streaming
+  # configuration, accumulated usage, and request ownership for
+  # interruption.
   #
-  # A context can use the chat completions API that all providers
-  # support or the responses API that currently only OpenAI supports.
+  # This is broader than prompt context alone. A context is the object
+  # that lets one-off prompts, streaming turns, tool execution,
+  # persistence, retries, and serialized long-lived workflows all run
+  # through the same model.
+  #
+  # A context can drive the chat completions API that all providers
+  # support or the Responses API on providers that expose it.
   #
   # @example
   #   #!/usr/bin/env ruby
@@ -272,13 +277,13 @@ module LLM
     ##
     # @return [Hash]
     def to_h
-      {model:, messages:}
+      {schema_version: 1, model:, messages:}
     end
 
     ##
     # @return [String]
     def to_json(...)
-      {schema_version: 1}.merge!(to_h).to_json(...)
+      to_h.to_json(...)
     end
 
     ##

data/lib/llm/eventstream/parser.rb

@@ -5,6 +5,7 @@ module LLM::EventStream
   # @private
   class Parser
     COMPACT_THRESHOLD = 4096
+    Visitor = Struct.new(:target, :on_data, :on_event, :on_id, :on_retry, :on_chunk)
 
     ##
     # @return [LLM::EventStream::Parser]
@@ -20,7 +21,12 @@ module LLM::EventStream
     # @param [#on_data] visitor
     # @return [void]
     def register(visitor)
-      @visitors << visitor
+      @visitors << Visitor.new(
+        visitor,
+        visitor.respond_to?(:on_data), visitor.respond_to?(:on_event),
+        visitor.respond_to?(:on_id), visitor.respond_to?(:on_retry),
+        visitor.respond_to?(:on_chunk)
+      )
     end
 
     ##
@@ -58,12 +64,16 @@ module LLM::EventStream
 
     private
 
-    def parse!(chunk)
-      field, value = Event.parse(chunk)
+    def parse_event!(chunk, field, value)
       dispatch_visitors(field, value, chunk)
       dispatch_callbacks(field, value, chunk)
     end
 
+    def parse!(chunk)
+      field, value = Event.parse(chunk)
+      parse_event!(chunk, field, value)
+    end
+
     def dispatch_visitors(field, value, chunk)
       @visitors.each { dispatch_visitor(_1, field, value, chunk) }
     end
@@ -76,11 +86,33 @@ module LLM::EventStream
     end
 
     def dispatch_visitor(visitor, field, value, chunk)
-      method = "on_#{field}"
-      if visitor.respond_to?(method)
-        visitor.public_send(method, value, chunk)
-      elsif visitor.respond_to?("on_chunk")
-        visitor.on_chunk(nil, chunk)
+      target = visitor.target
+      if field == "data"
+        if visitor.on_data
+          target.on_data(value, chunk)
+        elsif visitor.on_chunk
+          target.on_chunk(nil, chunk)
+        end
+      elsif field == "event"
+        if visitor.on_event
+          target.on_event(value, chunk)
+        elsif visitor.on_chunk
+          target.on_chunk(nil, chunk)
+        end
+      elsif field == "id"
+        if visitor.on_id
+          target.on_id(value, chunk)
+        elsif visitor.on_chunk
+          target.on_chunk(nil, chunk)
+        end
+      elsif field == "retry"
+        if visitor.on_retry
+          target.on_retry(value, chunk)
+        elsif visitor.on_chunk
+          target.on_chunk(nil, chunk)
+        end
+      elsif visitor.on_chunk
+        target.on_chunk(nil, chunk)
       end
     end
 

data/lib/llm/provider.rb

@@ -22,15 +22,18 @@ class LLM::Provider
   #  The number of seconds to wait for a response
   # @param [Boolean] ssl
   #  Whether to use SSL for the connection
+  # @param [String] base_path
+  #  Optional base path prefix for HTTP API routes.
   # @param [Boolean] persistent
   #  Whether to use a persistent connection.
   #  Requires the net-http-persistent gem.
-  def initialize(key:, host:, port: 443, timeout: 60, ssl: true, persistent: false)
+  def initialize(key:, host:, port: 443, timeout: 60, ssl: true, base_path: "", persistent: false)
     @key = key
     @host = host
     @port = port
     @timeout = timeout
     @ssl = ssl
+    @base_path = normalize_base_path(base_path)
     @base_uri = URI("#{ssl ? "https" : "http"}://#{host}:#{port}/")
     @headers = {"User-Agent" => "llm.rb v#{LLM::VERSION}"}
     @transport = Transport::HTTP.new(host:, port:, timeout:, ssl:, persistent:)
@@ -330,6 +333,18 @@ class LLM::Provider
 
   private
 
+  def path(suffix)
+    return suffix if @base_path.empty?
+    "#{@base_path}#{suffix}"
+  end
+
+  def normalize_base_path(path)
+    path = path.to_s.strip
+    return "" if path.empty? || path == "/"
+    path = "/#{path}" unless path.start_with?("/")
+    path.sub(%r{/+\z}, "")
+  end
+
   attr_reader :base_uri, :host, :port, :timeout, :ssl, :transport
 
   ##

data/lib/llm/providers/anthropic/stream_parser.rb

@@ -16,6 +16,9 @@ class LLM::Anthropic
     def initialize(stream)
       @body = {"role" => "assistant", "content" => []}
       @stream = stream
+      @can_emit_content = stream.respond_to?(:on_content)
+      @can_emit_tool_call = stream.respond_to?(:on_tool_call)
+      @can_push_content = stream.respond_to?(:<<)
     end
 
     ##
@@ -88,15 +91,15 @@ class LLM::Anthropic
     end
 
     def emit_content(value)
-      if @stream.respond_to?(:on_content)
+      if @can_emit_content
         @stream.on_content(value)
-      elsif @stream.respond_to?(:<<)
+      elsif @can_push_content
         @stream << value
       end
     end
 
     def emit_tool(tool)
-      return unless @stream.respond_to?(:on_tool_call)
+      return unless @can_emit_tool_call
       function, error = resolve_tool(tool)
       @stream.on_tool_call(function, error)
     end

data/lib/llm/providers/google/stream_parser.rb

@@ -17,6 +17,9 @@ class LLM::Google
       @body = {"candidates" => []}
       @stream = stream
       @emits = {tools: []}
+      @can_emit_content = stream.respond_to?(:on_content)
+      @can_emit_tool_call = stream.respond_to?(:on_tool_call)
+      @can_push_content = stream.respond_to?(:<<)
     end
 
     ##
@@ -126,15 +129,15 @@ class LLM::Google
     end
 
     def emit_content(value)
-      if @stream.respond_to?(:on_content)
+      if @can_emit_content
         @stream.on_content(value)
-      elsif @stream.respond_to?(:<<)
+      elsif @can_push_content
         @stream << value
       end
     end
 
     def emit_tool(pindex, cindex, part)
-      return unless @stream.respond_to?(:on_tool_call)
+      return unless @can_emit_tool_call
       return unless complete_tool?(part)
       key = [cindex, pindex]
       return if @emits[:tools].include?(key)

data/lib/llm/providers/ollama/stream_parser.rb

@@ -14,6 +14,7 @@ class LLM::Ollama
     def initialize(stream)
       @body = {}
       @stream = stream
+      @can_push_content = stream.respond_to?(:<<)
     end
 
     ##
@@ -36,10 +37,10 @@ class LLM::Ollama
         if key == "message"
           if @body[key]
             @body[key]["content"] << value["content"]
-            @stream << value["content"] if @stream.respond_to?(:<<)
+            @stream << value["content"] if @can_push_content
           else
             @body[key] = value
-            @stream << value["content"] if @stream.respond_to?(:<<)
+            @stream << value["content"] if @can_push_content
           end
         else
           @body[key] = value

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

@@ -32,7 +32,7 @@ class LLM::OpenAI
     # @raise (see LLM::Provider#request)
     # @return [LLM::Response]
     def create_speech(input:, voice: "alloy", model: "gpt-4o-mini-tts", response_format: "mp3", **params)
-      req = Net::HTTP::Post.new("/v1/audio/speech", headers)
+      req = Net::HTTP::Post.new(path("/audio/speech"), headers)
       req.body = LLM.json.dump({input:, voice:, model:, response_format:}.merge!(params))
       io = StringIO.new("".b)
       res, span, tracer = execute(request: req, operation: "request") { _1.read_body { |chunk| io << chunk } }
@@ -55,7 +55,7 @@ class LLM::OpenAI
     # @return [LLM::Response]
     def create_transcription(file:, model: "whisper-1", **params)
       multi = LLM::Multipart.new(params.merge!(file: LLM.File(file), model:))
-      req = Net::HTTP::Post.new("/v1/audio/transcriptions", headers)
+      req = Net::HTTP::Post.new(path("/audio/transcriptions"), headers)
       req["content-type"] = multi.content_type
       set_body_stream(req, multi.body)
       res, span, tracer = execute(request: req, operation: "request")
@@ -79,7 +79,7 @@ class LLM::OpenAI
     # @return [LLM::Response]
     def create_translation(file:, model: "whisper-1", **params)
       multi = LLM::Multipart.new(params.merge!(file: LLM.File(file), model:))
-      req = Net::HTTP::Post.new("/v1/audio/translations", headers)
+      req = Net::HTTP::Post.new(path("/audio/translations"), headers)
       req["content-type"] = multi.content_type
       set_body_stream(req, multi.body)
       res, span, tracer = execute(request: req, operation: "request")
@@ -90,7 +90,7 @@ class LLM::OpenAI
 
     private
 
-    [:headers, :execute, :set_body_stream].each do |m|
+    [:path, :headers, :execute, :set_body_stream].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

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

@@ -40,7 +40,7 @@ class LLM::OpenAI
     # @return [LLM::Response]
     def all(**params)
       query = URI.encode_www_form(params)
-      req = Net::HTTP::Get.new("/v1/files?#{query}", headers)
+      req = Net::HTTP::Get.new(path("/files?#{query}"), headers)
       res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :enumerable)
       tracer.on_request_finish(operation: "request", res:, span:)
@@ -60,7 +60,7 @@ class LLM::OpenAI
     # @return [LLM::Response]
     def create(file:, purpose: "assistants", **params)
       multi = LLM::Multipart.new(params.merge!(file: LLM.File(file), purpose:))
-      req = Net::HTTP::Post.new("/v1/files", headers)
+      req = Net::HTTP::Post.new(path("/files"), headers)
       req["content-type"] = multi.content_type
       set_body_stream(req, multi.body)
       res, span, tracer = execute(request: req, operation: "request")
@@ -83,7 +83,7 @@ class LLM::OpenAI
     def get(file:, **params)
       file_id = file.respond_to?(:id) ? file.id : file
       query = URI.encode_www_form(params)
-      req = Net::HTTP::Get.new("/v1/files/#{file_id}?#{query}", headers)
+      req = Net::HTTP::Get.new(path("/files/#{file_id}?#{query}"), headers)
       res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :file)
       tracer.on_request_finish(operation: "request", res:, span:)
@@ -105,7 +105,7 @@ class LLM::OpenAI
     def download(file:, **params)
       query = URI.encode_www_form(params)
       file_id = file.respond_to?(:id) ? file.id : file
-      req = Net::HTTP::Get.new("/v1/files/#{file_id}/content?#{query}", headers)
+      req = Net::HTTP::Get.new(path("/files/#{file_id}/content?#{query}"), headers)
       io = StringIO.new("".b)
       res, span, tracer = execute(request: req, operation: "request") { |res| res.read_body { |chunk| io << chunk } }
       res = LLM::Response.new(res).tap { _1.define_singleton_method(:file) { io } }
@@ -125,7 +125,7 @@ class LLM::OpenAI
     # @return [LLM::Response]
     def delete(file:)
       file_id = file.respond_to?(:id) ? file.id : file
-      req = Net::HTTP::Delete.new("/v1/files/#{file_id}", headers)
+      req = Net::HTTP::Delete.new(path("/files/#{file_id}"), headers)
       res, span, tracer = execute(request: req, operation: "request")
       res = LLM::Response.new(res)
       tracer.on_request_finish(operation: "request", res:, span:)
@@ -134,7 +134,7 @@ class LLM::OpenAI
 
     private
 
-    [:headers, :execute, :set_body_stream].each do |m|
+    [:path, :headers, :execute, :set_body_stream].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

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

@@ -50,7 +50,7 @@ class LLM::OpenAI
     # @raise (see LLM::Provider#request)
     # @return [LLM::Response]
     def create(prompt:, model: "dall-e-3", response_format: "b64_json", **params)
-      req = Net::HTTP::Post.new("/v1/images/generations", headers)
+      req = Net::HTTP::Post.new(path("/images/generations"), headers)
       req.body = LLM.json.dump({prompt:, n: 1, model:, response_format:}.merge!(params))
       res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :image)
@@ -76,7 +76,7 @@ class LLM::OpenAI
     def create_variation(image:, model: "dall-e-2", response_format: "b64_json", **params)
       image = LLM.File(image)
       multi = LLM::Multipart.new(params.merge!(image:, model:, response_format:))
-      req = Net::HTTP::Post.new("/v1/images/variations", headers)
+      req = Net::HTTP::Post.new(path("/images/variations"), headers)
       req["content-type"] = multi.content_type
       set_body_stream(req, multi.body)
       res, span, tracer = execute(request: req, operation: "request")
@@ -102,7 +102,7 @@ class LLM::OpenAI
     def edit(image:, prompt:, model: "dall-e-2", response_format: "b64_json", **params)
       image = LLM.File(image)
       multi = LLM::Multipart.new(params.merge!(image:, prompt:, model:, response_format:))
-      req = Net::HTTP::Post.new("/v1/images/edits", headers)
+      req = Net::HTTP::Post.new(path("/images/edits"), headers)
       req["content-type"] = multi.content_type
       set_body_stream(req, multi.body)
       res, span, tracer = execute(request: req, operation: "request")
@@ -113,7 +113,7 @@ class LLM::OpenAI
 
     private
 
-    [:headers, :execute, :set_body_stream].each do |m|
+    [:path, :headers, :execute, :set_body_stream].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

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

@@ -39,7 +39,7 @@ class LLM::OpenAI
     # @return [LLM::Response]
     def all(**params)
       query = URI.encode_www_form(params)
-      req = Net::HTTP::Get.new("/v1/models?#{query}", headers)
+      req = Net::HTTP::Get.new(path("/models?#{query}"), headers)
       res, span, tracer = execute(request: req, operation: "request")
       res = ResponseAdapter.adapt(res, type: :models)
       tracer.on_request_finish(operation: "request", res:, span:)
@@ -48,7 +48,7 @@ class LLM::OpenAI
 
     private
 
-    [:headers, :execute, :set_body_stream].each do |m|
+    [:path, :headers, :execute, :set_body_stream].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end

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

@@ -47,7 +47,7 @@ class LLM::OpenAI
     # @param [String, LLM::Model] model The model to use
     # @return [LLM::Response]
     def create(input:, model: "omni-moderation-latest", **params)
-      req = Net::HTTP::Post.new("/v1/moderations", headers)
+      req = Net::HTTP::Post.new(path("/moderations"), headers)
       input = RequestAdapter::Moderation.new(input).adapt
       req.body = LLM.json.dump({input:, model:}.merge!(params))
       res, span, tracer = execute(request: req, operation: "request")
@@ -58,7 +58,7 @@ class LLM::OpenAI
 
     private
 
-    [:headers, :execute].each do |m|
+    [:path, :headers, :execute].each do |m|
       define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
     end
   end