ruby_llm 1.16.0 → 2.0.0.rc2

data/lib/ruby_llm/moderation.rb

@@ -1,56 +1,169 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  # Identify potentially harmful content in text.
-  # https://platform.openai.com/docs/guides/moderation
+  # A Moderation holds the result of screening text or images for
+  # potentially harmful content. Most code obtains one through
+  # RubyLLM.moderate.
+  #
+  #   result = RubyLLM.moderate("This is a safe message about Ruby programming")
+  #   result.flagged?  # => false
+  #
+  #   RubyLLM.moderate(with: "profile.png").flagged?
+  #
   class Moderation
-    attr_reader :id, :model, :results
+    include Support::Inspectable
+    include Accounting::Usage::Result
 
-    def initialize(id:, model:, results:)
+    # A Result is the verdict for a single moderated input. Providers return
+    # results in different shapes. RubyLLM normalizes all of them into Result
+    # objects on Moderation#results.
+    #
+    #   result = RubyLLM.moderate("Some user input").results.first
+    #   result.flagged?               # => false
+    #   result.categories             # => []
+    #   result.category_scores["violence"]  # => 0.0004
+    #
+    class Result
+      # The names of the categories flagged for this input, as an array of
+      # strings, empty when nothing was flagged.
+      attr_reader :categories
+
+      # The confidence scores for this input, as a hash of category name to
+      # a score between 0.0 and 1.0. Empty when the provider reports none.
+      attr_reader :category_scores
+
+      def initialize(flagged:, categories:, category_scores:) # :nodoc:
+        @flagged = flagged
+        @categories = categories
+        @category_scores = category_scores
+      end
+
+      def self.from_h(data) # :nodoc:
+        flagged_names = (data['categories'] || {}).select { |_category, flagged| flagged }.keys
+        new(
+          flagged: data.fetch('flagged', flagged_names.any?),
+          categories: flagged_names,
+          category_scores: data['category_scores'] || {}
+        )
+      end
+
+      # Returns +true+ if this input was flagged as potentially harmful,
+      # +false+ otherwise.
+      def flagged?
+        @flagged
+      end
+    end
+
+    # The provider-assigned identifier of the moderation request.
+    attr_reader :id
+
+    # The id of the model that performed the moderation, or +nil+ for an
+    # operation that does not select a model.
+    attr_reader :model
+
+    # The per-input verdicts, as an array of Result objects, one per
+    # moderated input.
+    attr_reader :results
+
+    # The original provider response, or an array of responses when each
+    # input requires a separate request.
+    attr_reader :raw
+
+    def initialize(id:, model:, results:, raw: nil) # :nodoc:
       @id = id
       @model = model
       @results = results
+      @raw = raw
     end
 
-    def self.moderate(input,
+    # Screens +input+ and optional image attachments and returns a Moderation with the
+    # provider's verdict. Uses the configured default moderation model when
+    # +model+ is not given. Pass +provider:+ and <tt>assume_model_exists: true</tt>
+    # to use a model that is not in the registry. An explicitly selected
+    # provider may instead use a configured resource without a model.
+    #
+    #   RubyLLM.moderate("User message")
+    #   RubyLLM.moderate(["First comment", "Second comment"]).results
+    #   RubyLLM.moderate("Caption", with: "screenshot.png")
+    #
+    def self.moderate(input = nil,
                       model: nil,
+                      with: nil,
                       provider: nil,
                       assume_model_exists: false,
-                      context: nil)
+                      context: nil,
+                      provider_options: {},
+                      metadata: nil)
+      attachments = Attachment.wrap(with)
+      raise ArgumentError, 'must provide input text, image attachment, or both' if input.nil? && attachments.empty?
+
       config = context&.config || RubyLLM.config
-      model ||= config.default_moderation_model || 'omni-moderation-latest'
-      model, provider_instance = Models.resolve(model, provider: provider, assume_exists: assume_model_exists,
-                                                       config: config)
-      model_id = model.id
+      model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
+                                                       config: config, operation: :moderate,
+                                                       default_model: config.default_moderation_model)
+      empty_tokens = Tokens.new
+      payload = {
+        provider: provider_instance.slug,
+        provider_class: provider_instance.class.display_name,
+        model: model&.id,
+        model_info: model,
+        input: input,
+        attachment_count: attachments.size,
+        provider_options: provider_options,
+        metadata: metadata,
+        tokens: empty_tokens,
+        cost: Cost.new(tokens: empty_tokens, model:)
+      }
 
-      provider_instance.moderate(input, model: model_id)
+      RubyLLM.instrument('moderation.ruby_llm', payload, config: config) do |event|
+        result = provider_instance.moderate(input, model:, with: attachments, provider_options:)
+        event[:result] = result
+        event[:flagged] = result.flagged?
+        event[:tokens] = result.tokens
+        event[:cost] = result.cost
+        result
+      end
     end
 
-    # Convenience method to get content from moderation result
-    def content
-      results
+    # Returns +true+ if any input was flagged as potentially harmful,
+    # +false+ otherwise.
+    def flagged?
+      results.any?(&:flagged?)
     end
 
-    # Check if any content was flagged
-    def flagged?
-      results.any? { |result| result['flagged'] }
+    # Returns provider-reported usage across every attempt. Its fields are
+    # +nil+ when the provider did not report any.
+    def tokens
+      ruby_llm_usage_tokens
+    end
+
+    # Returns the moderation cost across every provider attempt.
+    def cost
+      ruby_llm_usage_cost
     end
 
-    # Get all flagged categories across all results
+    # Returns the unique names of the categories flagged across all results.
+    #
+    #   result.flagged_categories  # => ["harassment", "violence"]
+    #
     def flagged_categories
-      results.flat_map do |result|
-        result['categories']&.select { |_category, flagged| flagged }&.keys || []
-      end.uniq
+      results.flat_map(&:categories).uniq
     end
 
-    # Get category scores for the first result (most common case)
+    # Returns the confidence scores across all results, as a hash of category
+    # name to a score between 0.0 and 1.0. Keeps the highest score per
+    # category when there are multiple results.
+    #
+    #   result.category_scores["violence"]  # => 0.0001
+    #
     def category_scores
-      results.first&.dig('category_scores') || {}
+      results.map(&:category_scores).reduce({}) do |merged, scores|
+        merged.merge(scores) { |_category, left, right| [left, right].max }
+      end
     end
 
-    # Get categories for the first result (most common case)
-    def categories
-      results.first&.dig('categories') || {}
+    def inspect_attributes # :nodoc:
+      { id: id, model: model, flagged: flagged? }
     end
   end
 end

data/lib/ruby_llm/ocr.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # An OCR is the text a document AI model extracted from a file.
+  # RubyLLM.ocr returns one. Each page carries the extracted markdown along
+  # with any images and tables the provider reports.
+  #
+  #   ocr = RubyLLM.ocr("contract.pdf")
+  #   ocr.markdown             # => "# Contract\n\n..."
+  #   ocr.pages.first.markdown # => "# Contract\n..."
+  #
+  class OCR
+    include Support::Inspectable
+    include Accounting::Usage::Result
+
+    # One page of an OCR result: the zero-based page +index+, the extracted
+    # +markdown+, and the +images+ and +tables+ the provider reports for the
+    # page, or +nil+ when it reports none. +raw+ holds the provider's
+    # unmodified page hash, including any fields beyond these.
+    Page = Struct.new(:index, :markdown, :images, :tables, :raw, keyword_init: true)
+
+    # The id of the model that performed the OCR.
+    attr_reader :model
+
+    # The provider's usage block for the request, such as the number of
+    # pages processed, or +nil+ when the provider does not report one.
+    attr_reader :usage # :nodoc:
+
+    # The provider's raw response hash.
+    attr_reader :raw
+
+    # Extracts the text of +file+ and returns an OCR result. Most code calls
+    # this through RubyLLM.ocr. The file may be a path, URL, IO object, or
+    # Attachment; accepted document and image formats depend on the provider.
+    #
+    # +model:+ selects the OCR model and defaults to the configured
+    # +default_ocr_model+. +provider:+ forces a specific provider, and
+    # +assume_model_exists:+ skips the registry lookup. +context:+ supplies
+    # a Context whose configuration replaces the global one. +metadata:+ is
+    # included in the instrumentation payload. +pages:+ limits the read to
+    # the given zero-based page indexes. +provider_options:+ merges options
+    # into the request in the provider's own vocabulary, such as Mistral's
+    # +include_image_base64:+ or +table_format:+.
+    #
+    #   RubyLLM.ocr("report.pdf")
+    #   RubyLLM.ocr("https://example.com/scan.png")
+    #   RubyLLM.ocr("report.pdf", pages: [0, 1], provider_options: { table_format: "html" })
+    #
+    # Raises RubyLLM::ModelNotFoundError if +model:+ is not in the registry,
+    # and RubyLLM::Error when the provider has no OCR support.
+    def self.ocr(file,
+                 model: nil,
+                 provider: nil,
+                 assume_model_exists: false,
+                 context: nil,
+                 pages: nil,
+                 provider_options: {},
+                 metadata: nil)
+      config = context&.config || RubyLLM.config
+      model ||= config.default_ocr_model
+      model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
+                                                       config: config)
+      payload = {
+        provider: provider_instance.slug,
+        provider_class: provider_instance.class.display_name,
+        model: model.id,
+        model_info: model,
+        pages: pages,
+        provider_options: provider_options,
+        metadata: metadata
+      }
+
+      RubyLLM.instrument('ocr.ruby_llm', payload, config: config) do |event|
+        result = provider_instance.ocr(file, model:, pages:, provider_options:)
+        event[:result] = result
+        event[:response_model] = result.model
+        result
+      end
+    end
+
+    def initialize(pages:, model:, usage: nil, raw: nil) # :nodoc:
+      @page_hashes = Array(pages)
+      @model = model
+      @usage = usage
+      @raw = raw
+    end
+
+    # Returns the pages of the document as an array of Page structs.
+    def pages
+      @pages ||= @page_hashes.map.with_index do |page, position|
+        next page if page.is_a?(Page)
+
+        Page.new(
+          index: page['index'] || position,
+          markdown: page['markdown'],
+          images: page['images'],
+          tables: page['tables'],
+          raw: page
+        )
+      end
+    end
+
+    # Returns the markdown of every page, joined with blank lines.
+    def markdown
+      pages.filter_map(&:markdown).join("\n\n")
+    end
+
+    def inspect_attributes # :nodoc:
+      { model: model, pages: pages.length }
+    end
+  end
+end

data/lib/ruby_llm/prompt.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'pathname'
+
+module RubyLLM
+  # Resolves prompt templates from the application and registered engine directories.
+  class Prompt
+    # The ordered directories searched for prompt files. The application's
+    # prompt directory is always first, so an application can override any
+    # prompt an engine ships by placing a file at the same relative path.
+    # Engines append their own directory in an initializer:
+    #
+    #   initializer "my_engine.prompts" do
+    #     RubyLLM::Prompt.roots << MyEngine::Engine.root.join("app/prompts")
+    #   end
+    #
+    class Roots
+      include Enumerable
+
+      def initialize(&default) # :nodoc:
+        @default = default
+        @registered = []
+      end
+
+      # Appends a prompt directory and returns +self+.
+      def <<(path)
+        @registered << Pathname.new(path)
+        self
+      end
+      alias push <<
+
+      # Yields each prompt directory in lookup order. Returns an Enumerator without a block.
+      def each(&)
+        [@default.call, *@registered].each(&)
+      end
+    end
+
+    attr_reader :name # :nodoc:
+
+    def initialize(name) # :nodoc:
+      @name = name.to_s
+      @filename = @name.end_with?('.txt.erb') ? @name : "#{@name}.txt.erb"
+    end
+
+    def path # :nodoc:
+      @path ||= candidates.find { |candidate| File.exist?(candidate) } || candidates.first
+    end
+
+    def render(**locals) # :nodoc:
+      raise PromptNotFoundError, "Prompt file not found: #{path}" unless File.exist?(path)
+
+      ERB.new(File.read(path)).result_with_hash(locals)
+    end
+
+    def self.render(name, **locals) # :nodoc:
+      new(name).render(**locals)
+    end
+
+    # Returns the ordered prompt directories. Append engine directories with +<<+.
+    def self.roots
+      @roots ||= Roots.new { root }
+    end
+
+    def self.root # :nodoc:
+      if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+        Rails.root.join('app/prompts')
+      else
+        Pathname.new(Dir.pwd).join('app/prompts')
+      end
+    end
+
+    private
+
+    def candidates
+      self.class.roots.map { |root| Pathname.new(root).join(@filename) }
+    end
+  end
+end

data/lib/ruby_llm/protocol/binary_streaming.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Protocol
+    module BinaryStreaming # :nodoc: all
+      def stream_binary(url, payload, &)
+        progress = {}
+        fallback = Streaming::StreamState.new
+        on_data = binary_on_data(fallback, progress, &)
+
+        response = @connection.post(url, payload, usage: @usage_tracker) do |request|
+          (request.options.context ||= {})[Transport::Connection::STREAM_PROGRESS_KEY] = progress
+          if faraday_1?
+            request.options[:on_data] = on_data
+          else
+            request.options.on_data = on_data
+          end
+        end
+        state = response.env[:streaming_state] || fallback
+        validate_binary_response(response, state.buffer)
+        yield state.buffer.dup unless progress[:started] || state.buffer.empty?
+        response.env.body = state.buffer.b
+        response
+      end
+
+      private
+
+      def binary_on_data(fallback, progress)
+        lambda do |chunk, bytes, env = nil|
+          next if chunk.empty?
+
+          state = stream_state(env, fallback)
+          state.buffer.clear if env.nil? && bytes && bytes <= state.buffer.bytesize
+          if failed_http_status(env)
+            handle_failed_response(chunk, state.buffer, env)
+          else
+            state.buffer << chunk.b
+            next unless binary_response?(env)
+
+            progress[:started] = true
+            yield chunk.b
+          end
+        end
+      end
+
+      def binary_response?(env)
+        return false unless env&.status&.between?(200, 299)
+
+        content_type = env.response_headers&.fetch('content-type', '').to_s.split(';').first
+        content_type&.start_with?('audio/') || content_type == 'application/octet-stream'
+      end
+
+      def validate_binary_response(response, data)
+        return if binary_response?(response.env)
+
+        begin
+          raise_stream_error(data, JSON.parse(data), response.env)
+        rescue JSON::ParserError
+          nil
+        end
+        raise Error.new('Expected an audio response from the speech endpoint', response: response)
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocol/stream_accumulator.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+
+module RubyLLM
+  class Protocol
+    class StreamAccumulator # :nodoc:
+      attr_reader :content, :model, :tool_calls
+
+      def initialize
+        @content = +''
+        @citations = []
+        @thinking_text = nil
+        @thinking_signature = nil
+        @tool_calls = {}
+        @input_tokens = nil
+        @output_tokens = nil
+        @cache_read_tokens = nil
+        @cache_write_tokens = nil
+        @thinking_tokens = nil
+        @server_tool_use = nil
+        @reported_cost = nil
+        @server_tool_calls = []
+        @raw_content = nil
+        @raw_reasoning = nil
+        @finish_reason = nil
+        @latest_tool_call_id = nil
+        @tool_call_ids_by_index = {}
+      end
+
+      def add(chunk)
+        RubyLLM.logger.debug { chunk.inspect } if RubyLLM.config.log_stream_debug
+        @model = chunk.model if @model.to_s.empty?
+
+        handle_chunk_content(chunk)
+        accumulate_citations(chunk.citations)
+        append_thinking_from_chunk(chunk)
+        accumulate_server_tool_calls(chunk.server_tool_calls)
+        @raw_content = chunk.raw_content if chunk.raw_content
+        @raw_reasoning = chunk.raw_reasoning if chunk.raw_reasoning
+        @finish_reason = chunk.finish_reason if chunk.finish_reason
+        count_tokens chunk
+        RubyLLM.logger.debug { inspect } if RubyLLM.config.log_stream_debug
+      end
+
+      def to_message(response)
+        Message.new(
+          role: :assistant,
+          content: content.empty? ? nil : content,
+          citations: resolved_citations,
+          thinking: Thinking.build(
+            text: @thinking_text,
+            signature: @thinking_signature
+          ),
+          tokens: Tokens.new(
+            input: @input_tokens,
+            output: @output_tokens,
+            cache_read: @cache_read_tokens,
+            cache_write: @cache_write_tokens,
+            thinking: @thinking_tokens,
+            server_tool_use: @server_tool_use,
+            reported_cost: @reported_cost
+          ),
+          server_tool_calls: @server_tool_calls,
+          raw_content: @raw_content,
+          raw_reasoning: @raw_reasoning,
+          finish_reason: @finish_reason,
+          model: model,
+          tool_calls: tool_calls_from_stream(response),
+          raw: response
+        )
+      end
+
+      private
+
+      # Providers like Perplexity repeat the full citation list on every chunk.
+      def accumulate_citations(new_citations)
+        new_citations.each do |citation|
+          @citations << citation unless @citations.include?(citation)
+        end
+      end
+
+      def accumulate_server_tool_calls(calls)
+        calls.each do |call|
+          index = @server_tool_calls.index do |existing|
+            call.id && existing.id == call.id && existing.type == call.type
+          end
+          if index
+            @server_tool_calls[index] = call
+          else
+            @server_tool_calls << call
+          end
+        end
+      end
+
+      def resolved_citations
+        @citations.map { |citation| resolve_citation_text(citation) }
+      end
+
+      def resolve_citation_text(citation)
+        return citation if citation.text || citation.start_index.nil? || citation.end_index.nil?
+
+        span = content[citation.start_index...citation.end_index]
+        span ? Citation.new(citation.to_h.merge(text: span)) : citation
+      end
+
+      def tool_calls_from_stream(response)
+        tool_calls.transform_values do |tc|
+          arguments = if tc.arguments.is_a?(String) && !tc.arguments.empty?
+                        parse_tool_call_arguments(tc.arguments, response)
+                      elsif tc.arguments.is_a?(String)
+                        {}
+                      else
+                        tc.arguments
+                      end
+
+          ToolCall.new(
+            id: tc.id,
+            name: tc.name,
+            arguments: arguments,
+            thought_signature: tc.thought_signature,
+            remote: tc.remote?
+          )
+        end
+      end
+
+      def parse_tool_call_arguments(arguments, response)
+        JSON.parse(arguments)
+      rescue JSON::ParserError => e
+        raise ToolCallParseError.new(response: response, finish_reason: @finish_reason), cause: e
+      end
+
+      def accumulate_tool_calls(new_tool_calls)
+        RubyLLM.logger.debug { "Accumulating tool calls: #{new_tool_calls}" } if RubyLLM.config.log_stream_debug
+        new_tool_calls.each do |stream_key, tool_call|
+          if tool_call.id
+            start_tool_call(stream_key, tool_call)
+          else
+            append_tool_call_fragment(stream_key, tool_call)
+          end
+        end
+      end
+
+      def start_tool_call(stream_key, tool_call)
+        tool_call_id = tool_call.id.empty? ? SecureRandom.uuid : tool_call.id
+
+        @tool_calls[tool_call_id] = ToolCall.new(
+          id: tool_call_id,
+          name: tool_call.name,
+          arguments: initial_tool_call_arguments(tool_call),
+          thought_signature: tool_call.thought_signature,
+          remote: tool_call.remote?
+        )
+        @tool_call_ids_by_index[stream_key] = tool_call_id unless stream_key.nil?
+        @latest_tool_call_id = tool_call_id
+      end
+
+      def initial_tool_call_arguments(tool_call)
+        arguments = tool_call.arguments
+        return +'' if arguments.nil? || (arguments.respond_to?(:empty?) && arguments.empty?)
+
+        arguments.dup
+      end
+
+      def append_tool_call_fragment(stream_key, tool_call)
+        existing = find_tool_call(stream_key)
+        return unless existing
+
+        fragment = tool_call.arguments
+        fragment = '' if fragment.nil?
+        existing.arguments << fragment
+        return unless tool_call.thought_signature && existing.thought_signature.nil?
+
+        existing.thought_signature = tool_call.thought_signature
+      end
+
+      def find_tool_call(stream_key)
+        return @tool_calls[@latest_tool_call_id] if stream_key.nil?
+
+        @tool_calls[@tool_call_ids_by_index[stream_key]] || @tool_calls[stream_key]
+      end
+
+      def count_tokens(chunk)
+        tokens = chunk.tokens
+        @input_tokens = tokens.input if tokens.input
+        @output_tokens = tokens.output if tokens.output
+        @cache_read_tokens = tokens.cache_read if tokens.cache_read
+        @cache_write_tokens = tokens.cache_write if tokens.cache_write
+        @thinking_tokens = tokens.thinking if tokens.thinking
+        @server_tool_use = tokens.server_tool_use if tokens.server_tool_use
+        @reported_cost = tokens.reported_cost if tokens.reported_cost
+      end
+
+      def handle_chunk_content(chunk)
+        accumulate_tool_calls(chunk.tool_calls) if chunk.tool_call?
+
+        content_text = chunk.content || ''
+        @content << (content_text.is_a?(String) ? content_text : content_text.to_s)
+      end
+
+      def append_thinking_from_chunk(chunk)
+        thinking = chunk.thinking
+        return unless thinking
+
+        unless thinking.text.nil?
+          @thinking_text ||= +''
+          @thinking_text << thinking.text.to_s
+        end
+        @thinking_signature ||= thinking.signature # rubocop:disable Naming/MemoizedInstanceVariableName
+      end
+    end
+  end
+end