durable-llm 0.1.4 → 0.1.6

data/lib/durable/llm/providers/groq.rb

@@ -1,11 +1,20 @@
+# frozen_string_literal: true
+
+# Groq provider for OpenAI-compatible API access.
+
 require 'faraday'
 require 'json'
 require 'durable/llm/errors'
 require 'durable/llm/providers/base'
+require 'event_stream_parser'
 
 module Durable
   module Llm
     module Providers
+      # Groq provider for accessing language models via OpenAI-compatible API.
+      #
+      # Provides completion, embedding, and streaming capabilities with proper
+      # error handling and response normalization.
       class Groq < Durable::Llm::Providers::Base
         BASE_URL = 'https://api.groq.com/openai/v1'
 
@@ -15,21 +24,16 @@ module Durable
 
         attr_accessor :api_key
 
-        def self.conn
-          Faraday.new(url: BASE_URL) do |faraday|
+        def initialize(api_key: nil)
+          super
+          @conn = Faraday.new(url: BASE_URL) do |faraday|
             faraday.request :json
             faraday.response :json
             faraday.adapter Faraday.default_adapter
           end
         end
 
-        def conn
-          self.class.conn
-        end
-
-        def initialize(api_key: nil)
-          @api_key = api_key || default_api_key
-        end
+        attr_reader :conn
 
         def completion(options)
           response = conn.post('chat/completions') do |req|
@@ -46,7 +50,7 @@ module Durable
             req.body = { model: model, input: input, **options }
           end
 
-          handle_response(response)
+          handle_response(response, GroqEmbeddingResponse)
         end
 
         def models
@@ -60,28 +64,94 @@ module Durable
         end
 
         def self.stream?
-          false
+          true
+        end
+
+        def stream(options)
+          options[:stream] = true
+
+          response = conn.post('chat/completions') do |req|
+            req.headers['Authorization'] = "Bearer #{@api_key}"
+            req.headers['Accept'] = 'text/event-stream'
+
+            options['temperature'] = options['temperature'].to_f if options['temperature']
+
+            req.body = options
+
+            user_proc = proc do |chunk, _size, _total|
+              yield GroqStreamResponse.new(chunk)
+            end
+
+            req.options.on_data = to_json_stream(user_proc: user_proc)
+          end
+
+          handle_response(response)
         end
 
         private
 
-        def handle_response(response)
+        # CODE-FROM: ruby-openai @ https://github.com/alexrudall/ruby-openai/blob/main/lib/openai/http.rb
+        # MIT License: https://github.com/alexrudall/ruby-openai/blob/main/LICENSE.md
+        # Given a proc, returns an outer proc that can be used to iterate over a JSON stream of chunks.
+        # For each chunk, the inner user_proc is called giving it the JSON object. The JSON object could
+        # be a data object or an error object as described in the OpenAI API documentation.
+        #
+        # @param user_proc [Proc] The inner proc to call for each JSON object in the chunk.
+        # @return [Proc] An outer proc that iterates over a raw stream, converting it to JSON.
+        def to_json_stream(user_proc:)
+          parser = EventStreamParser::Parser.new
+
+          proc do |chunk, _bytes, env|
+            if env && env.status != 200
+              raise_error = Faraday::Response::RaiseError.new
+              raise_error.on_complete(env.merge(body: try_parse_json(chunk)))
+            end
+
+            parser.feed(chunk) do |_type, data|
+              user_proc.call(JSON.parse(data)) unless data == '[DONE]'
+            end
+          end
+        end
+
+        def try_parse_json(maybe_json)
+          JSON.parse(maybe_json)
+        rescue JSON::ParserError
+          maybe_json
+        end
+
+        def parse_error_message(response)
+          body = begin
+            JSON.parse(response.body)
+          rescue StandardError
+            nil
+          end
+          message = body&.dig('error', 'message') || response.body
+          "#{response.status} Error: #{message}"
+        end
+
+        # END-CODE-FROM
+
+        def handle_response(response, response_class = GroqResponse)
           case response.status
           when 200..299
-            GroqResponse.new(response.body)
+            response_class.new(response.body)
           when 401
-            raise Durable::Llm::AuthenticationError, response.body['error']['message']
+            raise Durable::Llm::AuthenticationError, parse_error_message(response)
           when 429
-            raise Durable::Llm::RateLimitError, response.body['error']['message']
+            raise Durable::Llm::RateLimitError, parse_error_message(response)
           when 400..499
-            raise Durable::Llm::InvalidRequestError, response.body['error']['message']
+            raise Durable::Llm::InvalidRequestError, parse_error_message(response)
           when 500..599
-            raise Durable::Llm::ServerError, response.body['error']['message']
+            raise Durable::Llm::ServerError, parse_error_message(response)
           else
             raise Durable::Llm::APIError, "Unexpected response code: #{response.status}"
           end
         end
 
+        # Response object for Groq chat API responses.
+        #
+        # Wraps the raw response and provides a consistent interface for accessing
+        # message content, embeddings, and metadata.
         class GroqResponse
           attr_reader :raw_response
 
@@ -93,6 +163,14 @@ module Durable
             @raw_response['choices'].map { |choice| GroqChoice.new(choice) }
           end
 
+          def data
+            @raw_response['data']
+          end
+
+          def embedding
+            @raw_response.dig('data', 0, 'embedding')
+          end
+
           def to_s
             choices.map(&:to_s).join(' ')
           end
@@ -102,6 +180,9 @@ module Durable
           end
         end
 
+        # Represents a single choice in a Groq response.
+        #
+        # Contains the message and finish reason for the choice.
         class GroqChoice
           attr_reader :message, :finish_reason
 
@@ -115,6 +196,9 @@ module Durable
           end
         end
 
+        # Represents a message in a Groq conversation.
+        #
+        # Messages have a role (user, assistant, system) and text content.
         class GroqMessage
           attr_reader :role, :content
 
@@ -128,27 +212,31 @@ module Durable
           end
         end
 
+        # Response object for streaming Groq chat chunks.
+        #
+        # Wraps individual chunks from the Server-Sent Events stream.
         class GroqStreamResponse
           attr_reader :choices
 
-          def initialize(fragment)
-            json_frag = fragment.split('data: ').last.strip
-            puts json_frag
-            parsed = JSON.parse(json_frag)
-            @choices = parsed['choices'].map { |choice| GroqStreamChoice.new(choice) }
+          def initialize(parsed)
+            @choices = GroqStreamChoice.new(parsed['choices'])
           end
 
           def to_s
-            @choices.map(&:to_s).join(' ')
+            @choices.to_s
           end
         end
 
+        # Represents a single choice in a streaming Groq response chunk.
+        #
+        # Contains the delta (incremental content) and finish reason for the choice.
         class GroqStreamChoice
           attr_reader :delta, :finish_reason
 
           def initialize(choice)
-            @delta = GroqStreamDelta.new(choice['delta'])
-            @finish_reason = choice['finish_reason']
+            @choice = [choice].flatten.first
+            @delta = GroqStreamDelta.new(@choice['delta'])
+            @finish_reason = @choice['finish_reason']
           end
 
           def to_s
@@ -156,6 +244,9 @@ module Durable
           end
         end
 
+        # Represents the incremental content delta in a streaming response.
+        #
+        # Contains the role and text content of the delta.
         class GroqStreamDelta
           attr_reader :role, :content
 
@@ -168,7 +259,24 @@ module Durable
             @content || ''
           end
         end
+
+        # Response object for Groq embedding API responses.
+        #
+        # Wraps embedding data and provides array access to the vector representation.
+        class GroqEmbeddingResponse
+          attr_reader :embedding
+
+          def initialize(data)
+            @embedding = data.dig('data', 0, 'embedding')
+          end
+
+          def to_a
+            @embedding
+          end
+        end
       end
     end
   end
 end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.

data/lib/durable/llm/providers/huggingface.rb

@@ -1,13 +1,22 @@
+# frozen_string_literal: true
+
+# This file implements the Hugging Face provider for accessing Hugging Face's inference API models.
+
 require 'faraday'
 require 'json'
 require 'durable/llm/errors'
 require 'durable/llm/providers/base'
+require 'event_stream_parser'
 
 module Durable
   module Llm
     module Providers
+      # Hugging Face provider for accessing Hugging Face's inference API models.
+      #
+      # Provides completion, embedding, and streaming capabilities with authentication
+      # handling, error management, and response normalization.
       class Huggingface < Durable::Llm::Providers::Base
-        BASE_URL = 'https://api-inference.huggingface.co/models'
+        BASE_URL = 'https://api-inference.huggingface.co'
 
         def default_api_key
           Durable::Llm.configuration.huggingface&.api_key || ENV['HUGGINGFACE_API_KEY']
@@ -22,11 +31,12 @@ module Durable
             faraday.response :json
             faraday.adapter Faraday.default_adapter
           end
+          super()
         end
 
         def completion(options)
           model = options.delete(:model) || 'gpt2'
-          response = @conn.post("/#{model}") do |req|
+          response = @conn.post("models/#{model}") do |req|
             req.headers['Authorization'] = "Bearer #{@api_key}"
             req.body = options
           end
@@ -34,33 +44,84 @@ module Durable
           handle_response(response)
         end
 
+        def embedding(model:, input:, **options)
+          response = @conn.post("models/#{model}") do |req|
+            req.headers['Authorization'] = "Bearer #{@api_key}"
+            req.body = { inputs: input, **options }
+          end
+
+          handle_response(response, HuggingfaceEmbeddingResponse)
+        end
+
         def models
           self.class.models
         end
 
+        def self.stream?
+          true
+        end
+
+        def stream(options)
+          model = options.delete(:model) || 'gpt2'
+          options[:stream] = true
+
+          @conn.post("models/#{model}") do |req|
+            req.headers['Authorization'] = "Bearer #{@api_key}"
+            req.headers['Accept'] = 'text/event-stream'
+            req.body = options
+            req.options.on_data = to_json_stream(user_proc: proc { |chunk|
+              yield HuggingfaceStreamResponse.new(chunk)
+            })
+          end
+        end
+
         def self.models
           %w[gpt2 bert-base-uncased distilbert-base-uncased] # could use expansion
         end
 
         private
 
-        def handle_response(response)
-          case response.status
-          when 200..299
-            HuggingfaceResponse.new(response.body)
-          when 401
-            raise Durable::Llm::AuthenticationError, response.body['error']
-          when 429
-            raise Durable::Llm::RateLimitError, response.body['error']
-          when 400..499
-            raise Durable::Llm::InvalidRequestError, response.body['error']
-          when 500..599
-            raise Durable::Llm::ServerError, response.body['error']
-          else
-            raise Durable::Llm::APIError, "Unexpected response code: #{response.status}"
+        # CODE-FROM: ruby-openai @ https://github.com/alexrudall/ruby-openai/blob/main/lib/openai/http.rb
+        # MIT License: https://github.com/alexrudall/ruby-openai/blob/main/LICENSE.md
+        def to_json_stream(user_proc:)
+          parser = EventStreamParser::Parser.new
+
+          proc do |chunk, _bytes, env|
+            if env && env.status != 200
+              raise_error = Faraday::Response::RaiseError.new
+              raise_error.on_complete(env.merge(body: try_parse_json(chunk)))
+            end
+
+            parser.feed(chunk) do |_type, data|
+              user_proc.call(JSON.parse(data)) unless data == '[DONE]'
+            end
+          end
+        end
+
+        def try_parse_json(maybe_json)
+          JSON.parse(maybe_json)
+        rescue JSON::ParserError
+          maybe_json
+        end
+
+        def handle_response(response, response_class = HuggingfaceResponse)
+          return response_class.new(response.body) if (200..299).cover?(response.status)
+
+          error_class = error_class_for_status(response.status)
+          raise error_class, response.body['error'] || "HTTP #{response.status}"
+        end
+
+        def error_class_for_status(status)
+          case status
+          when 401 then Durable::Llm::AuthenticationError
+          when 429 then Durable::Llm::RateLimitError
+          when 400..499 then Durable::Llm::InvalidRequestError
+          when 500..599 then Durable::Llm::ServerError
+          else Durable::Llm::APIError
           end
         end
 
+        # Response wrapper for Hugging Face completion API responses.
         class HuggingfaceResponse
           attr_reader :raw_response
 
@@ -69,7 +130,7 @@ module Durable
           end
 
           def choices
-            [@raw_response.first].map { |choice| HuggingfaceChoice.new(choice) }
+            [HuggingfaceChoice.new(@raw_response)]
           end
 
           def to_s
@@ -77,6 +138,7 @@ module Durable
           end
         end
 
+        # Individual choice from Hugging Face completion response.
         class HuggingfaceChoice
           attr_reader :text
 
@@ -88,7 +150,48 @@ module Durable
             @text
           end
         end
+
+        # Response wrapper for Hugging Face embedding API responses.
+        class HuggingfaceEmbeddingResponse
+          attr_reader :embedding
+
+          def initialize(data)
+            @embedding = data
+          end
+
+          def to_a
+            @embedding
+          end
+        end
+
+        # Response wrapper for Hugging Face streaming API responses.
+        class HuggingfaceStreamResponse
+          attr_reader :token
+
+          def initialize(parsed)
+            @token = HuggingfaceStreamToken.new(parsed)
+          end
+
+          def to_s
+            @token.to_s
+          end
+        end
+
+        # Individual token from Hugging Face streaming response.
+        class HuggingfaceStreamToken
+          attr_reader :text
+
+          def initialize(token)
+            @text = token['token']['text']
+          end
+
+          def to_s
+            @text || ''
+          end
+        end
       end
     end
   end
 end
+
+# Copyright (c) 2025 Durable Programming, LLC. All rights reserved.