ai-lite 0.6.1 → 1.0.0

data/lib/ai_lite/gemini/streaming.rb

@@ -0,0 +1,148 @@
+class AiLite
+  class Gemini
+    module Streaming
+      def chat_stream(message, model: nil, instructions: nil, previous_response_id: nil, max_output_tokens: nil, debug: false, options: {}, &block)
+        raise ArgumentError, "chat_stream requires a block" unless block
+
+        status = "unknown"
+        text = +""
+        response_id = nil
+        events = debug ? [] : nil
+        interaction = nil
+        raw = nil
+        callback_error = nil
+        begin
+          payload = chat_payload(message, model: model, instructions: instructions,
+                                 previous_response_id: previous_response_id,
+                                 max_output_tokens: max_output_tokens, options: options, stream: true)
+          uri = URI.parse("#{API_BASE_URL}/interactions")
+          request = Net::HTTP::Post.new(uri)
+          headers.each { |key, value| request[key] = value }
+          request["Accept"] = "text/event-stream"
+          request.body = JSON.generate(payload)
+          result = nil
+          step_types = {}
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+            http.open_timeout = timeout
+            http.read_timeout = timeout
+            catch(:ai_lite_gemini_finished) do
+              http.request(request) do |response|
+                status = response.code.to_i
+                unless status.between?(200, 299)
+                  raw = +""
+                  response.read_body { |chunk| raw << chunk }
+                  raw = JSON.parse(raw)
+                  result = result_envelope(status: status, error: error_message(raw), raw: raw, debug: debug)
+                  throw :ai_lite_gemini_finished
+                end
+                each_gemini_stream_event(response) do |event|
+                  events << event if events
+                  raw = { "interaction" => interaction, "events" => events } if debug
+                  case event["event_type"]
+                  when "interaction.created"
+                    interaction = event.fetch("interaction")
+                    response_id = interaction["id"] || response_id
+                  when "step.start"
+                    step_types[event.fetch("index")] = event.fetch("step").fetch("type")
+                  when "step.delta"
+                    delta = event.fetch("delta")
+                    if step_types[event["index"]] == "model_output" && delta["type"] == "text"
+                      chunk = delta.fetch("text")
+                      text << chunk
+                      begin
+                        block.call(chunk)
+                      rescue StandardError => e
+                        callback_error = e
+                        raise
+                      end
+                    end
+                  when "interaction.status_update"
+                    response_id = event["interaction_id"] || response_id
+                    if %w[failed cancelled incomplete requires_action].include?(event["status"])
+                      result = result_envelope(status: status, content: text.empty? ? nil : text,
+                        response_id: response_id, error: "Gemini interaction #{event['status']}", raw: raw, debug: debug)
+                      throw :ai_lite_gemini_finished
+                    end
+                  when "interaction.completed"
+                    interaction = event.fetch("interaction")
+                    response_id = interaction["id"] || response_id
+                    raw = { "interaction" => interaction, "events" => events } if debug
+                    error = if interaction["error"]
+                              error_message(interaction)
+                            elsif interaction["status"] != "completed"
+                              "Gemini interaction #{interaction['status'] || 'has no status'}"
+                            end
+                    content = text.empty? ? nil : text
+                    unless error || content.nil?
+                      begin
+                        content = JSON.parse(text.strip)
+                      rescue JSON::ParserError
+                        content = text.strip
+                      end
+                    end
+                    result = result_envelope(status: status, content: content, response_id: response_id,
+                                             error: error, raw: raw, debug: debug)
+                    throw :ai_lite_gemini_finished
+                  when "error"
+                    result = result_envelope(status: status, content: text.empty? ? nil : text,
+                      response_id: response_id, error: error_message(event), raw: raw, debug: debug)
+                    throw :ai_lite_gemini_finished
+                  end
+                end
+              end
+            end
+          end
+          result || result_envelope(status: status, content: text.empty? ? nil : text, response_id: response_id,
+            error: "Stream ended before a terminal interaction event", raw: raw, debug: debug)
+        rescue StandardError => e
+          raise if callback_error.equal?(e)
+
+          result_envelope(status: status, content: text.empty? ? nil : text, response_id: response_id,
+                          error: e.message, raw: raw, debug: debug)
+        end
+      end
+
+      private
+
+      def each_gemini_stream_event(response)
+        buffer = +"".b
+        data = []
+        consume = lambda do
+          while (boundary = buffer.index(/[\r\n]/))
+            # A trailing CR might be the first byte of a CRLF split across reads.
+            break if buffer.getbyte(boundary) == 13 && boundary == buffer.bytesize - 1
+
+            width = buffer.byteslice(boundary, 2) == "\r\n" ? 2 : 1
+            line = buffer.slice!(0, boundary + width).byteslice(0, boundary)
+            if line.empty?
+              unless data.empty?
+                payload = data.join("\n").force_encoding(Encoding::UTF_8)
+                data.clear
+                unless payload == "[DONE]"
+                  event = JSON.parse(payload)
+                  raise "Invalid streaming event: expected an object" unless event.is_a?(Hash)
+                  yield event
+                end
+              end
+            elsif line.start_with?("data:")
+              data << line.sub(/\Adata: ?/, "")
+            end
+          end
+        end
+        response.read_body do |chunk|
+          buffer << chunk.b
+          consume.call
+        end
+        # A final lone CR is a complete line delimiter at EOF.
+        if buffer.end_with?("\r")
+          buffer << "\n"
+          consume.call
+        end
+      end
+
+    end
+
+    include Streaming
+    private_constant :Streaming
+  end
+end

data/lib/ai_lite/gemini/youtube.rb

@@ -0,0 +1,36 @@
+class AiLite
+  class Gemini
+    module YouTube
+      def youtube(url, prompt:, **kwargs)
+        unless prompt.is_a?(String) && !prompt.strip.empty?
+          raise ArgumentError, "prompt must be a nonempty string"
+        end
+        uri = URI.parse(url) if url.is_a?(String)
+        unless uri.is_a?(URI::HTTPS) && !uri.userinfo && uri.port == 443
+          raise ArgumentError, "Expected an HTTPS YouTube video URL"
+        end
+        video_id = case uri.host&.downcase
+                   when "youtu.be"
+                     uri.path.delete_prefix("/")
+                   when "youtube.com", "www.youtube.com", "m.youtube.com"
+                     if uri.path == "/watch"
+                       ids = URI.decode_www_form(uri.query.to_s).select { |key, _| key == "v" }
+                       ids.first[1] if ids.length == 1
+                     else
+                       uri.path.match(%r{\A/(?:shorts|embed|live)/([^/]+)\z})&.captures&.first
+                     end
+                   end
+        unless video_id && video_id.match?(/\A[A-Za-z0-9_-]{11}\z/)
+          raise ArgumentError, "Expected a YouTube video URL with a valid video ID"
+        end
+
+        chat([{ type: "video", uri: url }, { type: "text", text: prompt }], **kwargs)
+      rescue ArgumentError, URI::InvalidURIError => e
+        result_envelope(status: "unknown", error: e.message, debug: kwargs[:debug])
+      end
+    end
+
+    include YouTube
+    private_constant :YouTube
+  end
+end

data/lib/ai_lite/gemini.rb

@@ -0,0 +1,92 @@
+require "json"
+require "net/http"
+require "uri"
+require_relative "version"
+require_relative "gemini/configuration"
+require_relative "gemini/chat"
+require_relative "gemini/streaming"
+require_relative "gemini/youtube"
+require_relative "gemini/models"
+
+class AiLite
+  class Gemini
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+        reset_client!
+        configuration
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+        reset_client!
+        configuration
+      end
+
+      def client
+        @client ||= new
+      end
+
+      def reset_client!
+        @client = nil
+      end
+
+      def youtube(url, prompt:, **kwargs)
+        client.youtube(url, prompt: prompt, **kwargs)
+      end
+
+      def chat_stream(message, **kwargs, &block)
+        client.chat_stream(message, **kwargs, &block)
+      end
+
+      def chat(message, **kwargs)
+        client.chat(message, **kwargs)
+      end
+    end
+
+    attr_reader :api_key, :model, :timeout, :max_output_tokens, :headers
+
+    def initialize(api_key: nil, model: nil, timeout: nil, max_output_tokens: nil)
+      config = self.class.configuration
+      @api_key = api_key || config.api_key || ENV["GEMINI_API_KEY"]
+      raise ArgumentError, "Missing Gemini API key" if @api_key.to_s.strip.empty?
+
+      @model = model || config.model
+      @timeout = timeout || config.timeout
+      @max_output_tokens = max_output_tokens || config.max_output_tokens
+      @headers = { "x-goog-api-key" => @api_key, "Content-Type" => "application/json" }
+    end
+
+    private
+
+    def post_interaction(payload)
+      uri = URI.parse("#{API_BASE_URL}/interactions")
+      request = Net::HTTP::Post.new(uri)
+      headers.each { |key, value| request[key] = value }
+      request.body = JSON.generate(payload)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.request(request)
+      end
+    end
+
+    def result_envelope(status:, content: nil, error: nil, response_id: nil, raw: nil, debug: false)
+      {
+        "content" => content, "response_id" => response_id, "status" => status,
+        "error" => error, "raw" => debug ? raw : nil
+      }
+    end
+
+    def error_message(raw)
+      return raw.to_s unless raw.is_a?(Hash)
+
+      error = raw["error"]
+      error.is_a?(Hash) ? (error["message"] || error["status"] || error.to_s) : (error || raw["message"] || raw.to_s)
+    end
+  end
+end

data/lib/ai_lite/openai/configuration.rb

@@ -0,0 +1,51 @@
+class AiLite
+  class OpenAI
+    API_BASE_URL = "https://api.openai.com/v1".freeze
+    DEFAULT_MODEL = "gpt-5.5".freeze
+    DEFAULT_MODERATION_MODEL = "omni-moderation-latest".freeze
+    DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small".freeze
+    DEFAULT_IMAGE_MODEL = "gpt-image-2".freeze
+    DEFAULT_SPEECH_MODEL = "gpt-4o-mini-tts".freeze
+    DEFAULT_SPEECH_VOICE = "alloy".freeze
+    DEFAULT_SPEECH_FORMAT = "mp3".freeze
+    DEFAULT_TRANSCRIPTION_MODEL = "gpt-transcribe".freeze
+    DEFAULT_TIMEOUT = 120
+    DEFAULT_MAX_OUTPUT_TOKENS = 2000
+    IMAGE_MIME_TYPES = {
+      ".gif" => "image/gif",
+      ".jpeg" => "image/jpeg",
+      ".jpg" => "image/jpeg",
+      ".png" => "image/png",
+      ".webp" => "image/webp"
+    }.freeze
+    AUDIO_MIME_TYPES = {
+      ".flac" => "audio/flac",
+      ".m4a" => "audio/mp4",
+      ".mp3" => "audio/mpeg",
+      ".mp4" => "audio/mp4",
+      ".mpeg" => "audio/mpeg",
+      ".mpga" => "audio/mpeg",
+      ".ogg" => "audio/ogg",
+      ".wav" => "audio/wav",
+      ".webm" => "audio/webm"
+    }.freeze
+
+    class Configuration
+      attr_accessor :api_key, :model, :moderation_model, :embedding_model, :image_model, :speech_model, :speech_voice, :transcription_model, :timeout, :max_output_tokens
+
+      def initialize
+        @api_key = nil
+        @model = DEFAULT_MODEL
+        @moderation_model = DEFAULT_MODERATION_MODEL
+        @embedding_model = DEFAULT_EMBEDDING_MODEL
+        @image_model = DEFAULT_IMAGE_MODEL
+        @speech_model = DEFAULT_SPEECH_MODEL
+        @speech_voice = DEFAULT_SPEECH_VOICE
+        @transcription_model = DEFAULT_TRANSCRIPTION_MODEL
+        @timeout = DEFAULT_TIMEOUT
+        @max_output_tokens = DEFAULT_MAX_OUTPUT_TOKENS
+      end
+    end
+
+  end
+end

data/lib/ai_lite/openai/models.rb

@@ -0,0 +1,96 @@
+class AiLite
+  class OpenAI
+    module Models
+      def self.configuration_snapshot(source)
+        {
+          "chat" => source.model,
+          "moderation" => source.moderation_model,
+          "embedding" => source.embedding_model,
+          "image" => source.image_model,
+          "speech" => source.speech_model,
+          "transcription" => source.transcription_model
+        }.transform_values { |value| value.is_a?(String) ? value.dup : value }
+      end
+
+      def configured_models
+        Models.configuration_snapshot(self)
+      end
+
+      def available_models(debug: false)
+        response = nil
+        raw = nil
+        uri = URI.parse("#{API_BASE_URL}/models")
+        request = Net::HTTP::Get.new(uri)
+        headers.each { |key, value| request[key] = value }
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+          http.open_timeout = timeout
+          http.read_timeout = timeout
+          http.request(request)
+        end
+        raw = response.body
+        raw = JSON.parse(raw)
+        unless success_status?(response.code.to_i)
+          return prettify_data(status: response.code.to_i, error: error_message(raw), raw: raw, debug: debug)
+        end
+
+        unless raw.is_a?(Hash) && raw["data"].is_a?(Array) && raw["data"].all? { |item|
+          item.is_a?(Hash) && item["id"].is_a?(String) && !item["id"].empty?
+        }
+          raise "Invalid model list response"
+        end
+
+        prettify_data(status: response.code.to_i, content: raw["data"].map { |item| item["id"] }.uniq,
+                      raw: raw, debug: debug)
+      rescue StandardError => e
+        prettify_data(status: response_status(response), error: e.message, raw: raw, debug: debug)
+      end
+
+      # nil means the lookup failed; false means a successful lookup did not find it.
+      def model_available?(model_id)
+        unless model_id.is_a?(String) && !model_id.strip.empty?
+          raise ArgumentError, "model_id must be a nonempty string"
+        end
+
+        result = available_models
+        return nil if result["error"]
+
+        result["content"].include?(model_id)
+      end
+
+      def check_configured_models(debug: false)
+        configured = configured_models
+        result = available_models(debug: debug)
+        report = configured.each_with_object({}) do |(usage, model), entries|
+          entries[usage] = {
+            "model" => model,
+            "usage" => usage,
+            "available" => result["error"] ? nil : result["content"].include?(model),
+            "error" => result["error"]
+          }
+        end
+        result.merge("content" => report)
+      end
+    end
+
+    include Models
+    private_constant :Models
+
+    class << self
+      def configured_models
+        Models.configuration_snapshot(configuration)
+      end
+
+      def available_models(**kwargs)
+        client.available_models(**kwargs)
+      end
+
+      def model_available?(model_id)
+        client.model_available?(model_id)
+      end
+
+      def check_configured_models(**kwargs)
+        client.check_configured_models(**kwargs)
+      end
+    end
+  end
+end

data/lib/ai_lite/openai/streaming.rb

@@ -0,0 +1,130 @@
+class AiLite
+  class OpenAI
+    module Streaming
+      # Text deltas are yielded immediately; the return value is the final envelope.
+      def chat_stream(message, model: nil, instructions: nil, previous_response_id: nil, max_output_tokens: nil, debug: false, options: {}, &block)
+        raise ArgumentError, "chat_stream requires a block" unless block
+
+        status = "unknown"
+        text = +""
+        response_id = nil
+        raw = nil
+        callback_error = nil
+        begin
+          payload = options.reject { |key, _| key.to_s == "stream" }.merge(
+            model: model || self.model, input: message, stream: true,
+            max_output_tokens: max_output_tokens || self.max_output_tokens
+          )
+          payload[:instructions] = instructions if instructions
+          payload[:previous_response_id] = previous_response_id if previous_response_id
+          uri = URI.parse(response_endpoint)
+          request = Net::HTTP::Post.new(uri)
+          headers.each { |key, value| request[key] = value }
+          request["Accept"] = "text/event-stream"
+          request.body = JSON.generate(payload)
+          result = nil
+
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+            http.open_timeout = timeout
+            http.read_timeout = timeout
+            # Exit the request block at the terminal event, closing the connection.
+            catch(:ai_lite_stream_finished) do
+              http.request(request) do |response|
+                status = response.code.to_i
+                unless success_status?(status)
+                  body = +""
+                  response.read_body { |chunk| body << chunk }
+                  raw = body
+                  raw = JSON.parse(body)
+                  result = prettify_data(status: status, error: error_message(raw), raw: raw, debug: debug)
+                  throw :ai_lite_stream_finished
+                end
+
+                each_stream_event(response) do |event|
+                  raw = event
+                  response_id = event.dig("response", "id") || response_id
+                  case event["type"]
+                  when "response.output_text.delta"
+                    delta = event.fetch("delta")
+                    text << delta
+                    begin
+                      block.call(delta)
+                    rescue StandardError => e
+                      callback_error = e
+                      raise
+                    end
+                  when "response.completed", "response.failed", "response.incomplete"
+                    raw = event.fetch("response")
+                    error = case event["type"]
+                            when "response.failed"
+                              raw["error"] ? error_message(raw) : "Response failed"
+                            when "response.incomplete"
+                              "Response incomplete: #{raw.dig('incomplete_details', 'reason') || 'unknown reason'}"
+                            end
+                    content = error ? text : parse_content(extract_output_text(raw))
+                    result = prettify_data(status: status, content: content, error: error,
+                                           response_id: response_id, raw: raw, debug: debug)
+                    throw :ai_lite_stream_finished
+                  when "error"
+                    result = prettify_data(status: status, content: text, error: error_message(event),
+                                           response_id: response_id, raw: raw, debug: debug)
+                    throw :ai_lite_stream_finished
+                  end
+                end
+              end
+            end
+          end
+          result || prettify_data(status: status, content: text, response_id: response_id,
+                                  error: "Stream ended before a terminal response event", raw: raw, debug: debug)
+        rescue StandardError => e
+          raise if callback_error.equal?(e)
+
+          prettify_data(status: status, content: text.empty? ? nil : text, response_id: response_id,
+                        error: e.message, raw: raw, debug: debug)
+        end
+      end
+
+      private
+
+      def each_stream_event(response)
+        buffer = +"".b
+        data = []
+        consume = lambda do
+          while (boundary = buffer.index(/[\r\n]/))
+            # A trailing CR might be the first byte of a CRLF split across reads.
+            break if buffer.getbyte(boundary) == 13 && boundary == buffer.bytesize - 1
+
+            width = buffer.byteslice(boundary, 2) == "\r\n" ? 2 : 1
+            line = buffer.slice!(0, boundary + width).byteslice(0, boundary)
+            if line.empty?
+              unless data.empty?
+                payload = data.join("\n").force_encoding(Encoding::UTF_8)
+                data.clear
+                unless payload == "[DONE]"
+                  event = JSON.parse(payload)
+                  raise "Invalid streaming event: expected an object" unless event.is_a?(Hash)
+                  yield event
+                end
+              end
+            elsif line.start_with?("data:")
+              data << line.sub(/\Adata: ?/, "")
+            end
+          end
+        end
+        response.read_body do |chunk|
+          buffer << chunk.b
+          consume.call
+        end
+        # A final lone CR is a complete line delimiter at EOF.
+        if buffer.end_with?("\r")
+          buffer << "\n"
+          consume.call
+        end
+      end
+
+    end
+
+    include Streaming
+    private_constant :Streaming
+  end
+end