cleo_quality_review 0.1.0

data/lib/cleo_quality_review/llm_client.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "llm_config"
+require_relative "llm_logger"
+require_relative "llm_providers"
+
+module CleoQualityReview
+  ##
+  # Client for generating LLM reviews using configured provider
+  class LlmClient
+    ##
+    # @param [LlmConfig] config
+    # @param [Boolean] log whether to log queries and responses
+    def initialize(config: LlmConfig.new, log: false)
+      @config = config
+      @logger = LlmLogger.new(provider_name: config.provider, enabled: log)
+      provider.validate_config(config)
+    end
+
+    ##
+    # Generate a review from the given prompt
+    # @param [String] prompt
+    # @return [String] the generated review
+    def generate_review(prompt)
+      generate_with_logging(prompt)
+    rescue StandardError => e
+      log_error(prompt, e)
+      raise
+    end
+
+    private
+
+    attr_reader :config, :logger
+
+    def generate_with_logging(prompt)
+      provider_client.generate_review(prompt).tap { |response| log_success(prompt, response) }
+    end
+
+    def log_success(prompt, response)
+      logger.log(query: prompt, response: response)
+    end
+
+    def log_error(prompt, error)
+      logger.log(query: prompt, response: format_error(error))
+    end
+
+    def format_error(error)
+      "ERROR: #{error.class}: #{error.message}"
+    end
+
+    def provider_client
+      provider.build_client(config: config)
+    end
+
+    def provider
+      @provider ||= LlmProviders.fetch(config.provider)
+    end
+  end
+end

data/lib/cleo_quality_review/llm_config.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "llm_providers/open_ai_config"
+
+module CleoQualityReview
+  ##
+  # Configuration for LLM provider
+  class LlmConfig
+    PROVIDER = "openai"
+
+    ##
+    # @param [Hash{String => String}] env environment variables
+    def initialize(env: ENV)
+      @env = env
+    end
+
+    ##
+    # @return [String] the provider name
+    def provider
+      PROVIDER
+    end
+
+    ##
+    # @return [LlmProviders::OpenAi::Config]
+    def open_ai_config
+      @open_ai_config ||= LlmProviders::OpenAi::Config.new(env: env)
+    end
+
+    ##
+    # @return [LlmProviders::Stub::Config]
+    def stub_config
+      require_relative "llm_providers/stub"
+      @stub_config ||= LlmProviders::Stub::Config.new(env: env)
+    end
+
+    private
+
+    attr_reader :env
+  end
+end

data/lib/cleo_quality_review/llm_errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CleoQualityReview
+  ##
+  # Base error class for CleoQualityReview
+  class Error < StandardError; end
+
+  ##
+  # Raised when required LLM configuration is missing
+  class MissingLlmConfigurationError < Error; end
+
+  ##
+  # Raised when an unsupported LLM provider is requested
+  class UnsupportedLlmProviderError < Error; end
+
+  ##
+  # Base class for LLM provider-specific errors
+  class LlmProviderError < Error; end
+end

data/lib/cleo_quality_review/llm_logger.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "logger"
+
+module CleoQualityReview
+  ##
+  # Logger for LLM queries and responses
+  class LlmLogger
+    LOG_DIR = "log"
+
+    ##
+    # @param [String] provider_name name of the LLM provider
+    # @param [Boolean] enabled whether logging is enabled
+    def initialize(provider_name:, enabled: false)
+      @provider_name = provider_name
+      @enabled = enabled
+      @logger = nil
+    end
+
+    ##
+    # Log a query and response
+    # @param [String] query the prompt sent to the LLM
+    # @param [String] response the LLM response
+    # @return [void]
+    def log(query:, response:)
+      return unless enabled
+
+      logger.info(format_entry(query: query, response: response))
+    end
+
+    ##
+    # @return [String] path to the log file
+    def log_path
+      File.join(LOG_DIR, "#{provider_name}.log")
+    end
+
+    private
+
+    attr_reader :provider_name, :enabled
+
+    def logger
+      @logger ||= build_logger
+    end
+
+    def build_logger
+      FileUtils.mkdir_p(LOG_DIR)
+      Logger.new(log_path, formatter: proc { |_, _, _, message| "#{message}\n" })
+    end
+
+    def format_entry(query:, response:)
+      timestamp = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+      <<~ENTRY
+        ================================================================================
+        Timestamp: #{timestamp}
+        ================================================================================
+
+        --- QUERY ---
+        #{query}
+
+        --- RESPONSE ---
+        #{response}
+      ENTRY
+    end
+  end
+end

data/lib/cleo_quality_review/llm_providers/open_ai.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "../llm_errors"
+require_relative "open_ai_config"
+
+module CleoQualityReview
+  module LlmProviders
+    ##
+    # OpenAI provider implementation and support classes.
+    module OpenAi
+      ##
+      # Value object representing an HTTP response from OpenAI.
+      #
+      # @!attribute [r] status_code
+      #   @return [Integer] HTTP status code
+      # @!attribute [r] body
+      #   @return [String] response body
+      HttpResponse = Struct.new(:status_code, :body, keyword_init: true) do
+        ##
+        # Check if the response indicates success.
+        # @return [Boolean]
+        def success?
+          (200..299).cover?(status_code.to_i)
+        end
+      end
+
+      ##
+      # Value object for a JSON POST request to OpenAI.
+      HttpRequest = Struct.new(:uri, :headers, :body, :timeout_seconds, keyword_init: true) do
+        ##
+        # Execute the HTTP request.
+        # @param [Net::HTTP::Post] http_request prepared request
+        # @yield [Net::HTTP] yields configured HTTP connection
+        # @return [Object] result of the block
+        def execute(http_request)
+          Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
+            http.open_timeout = timeout_seconds
+            http.read_timeout = timeout_seconds
+            http.write_timeout = timeout_seconds
+            http.request(http_request)
+          end
+        end
+      end
+
+      ##
+      # HTTP transport layer for OpenAI API requests.
+      class HttpTransport
+        ##
+        # Send a POST request with JSON body.
+        # @param [HttpRequest] request JSON POST request options
+        # @return [HttpResponse]
+        def post_json(request)
+          http_request = build_request(request)
+          response = perform_request(request, http_request)
+
+          HttpResponse.new(status_code: response.code.to_i, body: response.body.to_s)
+        end
+
+        private
+
+        def build_request(request)
+          http_request = Net::HTTP::Post.new(request.uri)
+          request.headers.each { |key, value| http_request[key] = value }
+          http_request.body = JSON.generate(request.body)
+          http_request
+        end
+
+        def perform_request(request, http_request)
+          request.execute(http_request)
+        end
+      end
+
+      ##
+      # Client for the OpenAI Responses API.
+      class Client
+        RESPONSES_API_URL = URI("https://api.openai.com/v1/responses")
+
+        ##
+        # @param [Config] config OpenAI configuration
+        # @param [HttpTransport] http_transport transport layer for HTTP requests
+        def initialize(config:, http_transport: HttpTransport.new)
+          @config = config
+          @http_transport = http_transport
+        end
+
+        ##
+        # Generate a review using the OpenAI Responses API.
+        # @param [String] prompt the prompt to send
+        # @return [String] generated review text
+        # @raise [ApiError] if the API request fails
+        def generate_review(prompt)
+          response = execute_request(prompt)
+          parse_response(response)
+        end
+
+        private
+
+        attr_reader :config, :http_transport
+
+        def execute_request(prompt)
+          timeout_seconds = config.timeout_seconds
+          http_transport.post_json(build_request(prompt, timeout_seconds))
+        rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
+          raise ApiError, timeout_error_message(timeout_seconds, e)
+        end
+
+        def parse_response(response)
+          raise ApiError, api_error_message(response) unless response.success?
+
+          extract_text(JSON.parse(response.body))
+        rescue JSON::ParserError => e
+          raise ApiError, "OpenAI Responses API returned invalid JSON: #{e.message}"
+        end
+
+        def build_request(prompt, timeout_seconds)
+          HttpRequest.new(
+            uri: RESPONSES_API_URL,
+            headers: headers,
+            body: { model: config.model, input: prompt },
+            timeout_seconds: timeout_seconds,
+          )
+        end
+
+        def timeout_error_message(timeout_seconds, error)
+          "OpenAI Responses API request timed out after #{timeout_seconds} seconds: #{error.class}: #{error.message}"
+        end
+
+        def headers
+          {
+            "Authorization" => "Bearer #{config.api_key}",
+            "Content-Type" => "application/json",
+          }
+        end
+
+        def extract_text(response)
+          output_text = response["output_text"]
+          return output_text if output_text.to_s.strip != ""
+
+          text = extract_content_text(response)
+          return text unless text.empty?
+
+          JSON.pretty_generate(response)
+        end
+
+        def extract_content_text(response)
+          Array(response["output"]).flat_map { |item| extract_item_texts(item) }.join("\n")
+        end
+
+        def extract_item_texts(item)
+          Array(item["content"]).filter_map { |content| content["text"] }
+        end
+
+        def api_error_message(response)
+          "OpenAI Responses API request failed with status #{response.status_code}: #{response.body}"
+        end
+      end
+
+      ##
+      # OpenAI provider adapter for LlmClient.
+      class Provider
+        ##
+        # Validate that the config has required OpenAI settings.
+        # @param [LlmConfig] config
+        # @raise [MissingLlmConfigurationError] if not configured
+        # @return [void]
+        def validate_config(config)
+          config.open_ai_config.validate
+        end
+
+        ##
+        # Build the client instance.
+        # @param [LlmConfig] config
+        # @return [Client]
+        def build_client(config:)
+          Client.new(config: config.open_ai_config)
+        end
+      end
+
+      ##
+      # Error raised when OpenAI API requests fail.
+      class ApiError < LlmProviderError; end
+    end
+  end
+end

data/lib/cleo_quality_review/llm_providers/open_ai_config.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "../llm_errors"
+
+module CleoQualityReview
+  module LlmProviders
+    module OpenAi
+      ##
+      # Configuration for OpenAI API access.
+      class Config
+        OPEN_AI_API_KEY = "CLEO_QUALITY_REVIEW_OPEN_AI_KEY"
+        TIMEOUT_SECONDS = "CLEO_QUALITY_REVIEW_TIMEOUT_SECONDS"
+        DEFAULT_MODEL = "gpt-5.5"
+        DEFAULT_TIMEOUT_SECONDS = 180
+
+        ##
+        # @param [Hash{String => String}] env environment variables
+        def initialize(env: ENV)
+          @env = env
+        end
+
+        ##
+        # @return [String] environment variable name for the API key
+        def api_key_env
+          OPEN_AI_API_KEY
+        end
+
+        ##
+        # @return [String] environment variable name for the request timeout
+        def timeout_seconds_env
+          TIMEOUT_SECONDS
+        end
+
+        ##
+        # @return [String] the OpenAI API key
+        # @raise [KeyError] if the API key is not set
+        def api_key
+          env.fetch(OPEN_AI_API_KEY)
+        end
+
+        ##
+        # @return [String] the model identifier to use
+        def model = DEFAULT_MODEL
+
+        ##
+        # @return [Integer] timeout in seconds for OpenAI HTTP requests
+        # @raise [ArgumentError] if the configured timeout is not a positive integer
+        def timeout_seconds
+          value = env.fetch(TIMEOUT_SECONDS, "").to_s.strip
+          return DEFAULT_TIMEOUT_SECONDS if value.empty?
+
+          Integer(value, 10).tap do |seconds|
+            raise ArgumentError if seconds <= 0
+          end
+        rescue ArgumentError
+          raise ArgumentError, "#{TIMEOUT_SECONDS} must be a positive integer number of seconds"
+        end
+
+        ##
+        # Check if the OpenAI configuration is complete.
+        # @return [Boolean]
+        def configured?
+          env.fetch(OPEN_AI_API_KEY, "").to_s.strip != ""
+        end
+
+        ##
+        # Validate that the configuration is complete.
+        # @raise [MissingLlmConfigurationError] if API key is missing
+        # @raise [ArgumentError] if timeout is invalid
+        # @return [void]
+        def validate
+          raise MissingLlmConfigurationError, "Missing OpenAI API key. Set #{api_key_env}." unless configured?
+
+          timeout_seconds
+        end
+
+        private
+
+        attr_reader :env
+      end
+    end
+  end
+end

data/lib/cleo_quality_review/llm_providers/registry.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "../llm_errors"
+
+module CleoQualityReview
+  module LlmProviders
+    ##
+    # Registry for available LLM provider implementations.
+    class Registry
+      class << self
+        ##
+        # Register an LLM provider implementation.
+        # @param [String, Symbol] name provider identifier
+        # @param [Class] provider_class provider class that responds to validate_config and build_client
+        # @return [nil]
+        def register(name, provider_class)
+          providers[provider_name(name)] = provider_class
+          nil
+        end
+
+        ##
+        # Resolve a provider name to a provider instance.
+        # @param [String, Symbol] name provider identifier
+        # @return [Object] provider instance
+        # @raise [UnsupportedLlmProviderError] if provider not found
+        def fetch(name)
+          providers.fetch(provider_name(name)).new
+        rescue KeyError
+          raise UnsupportedLlmProviderError, unsupported_provider_message(name)
+        end
+
+        ##
+        # @return [Array<String>] registered provider names
+        def registered
+          providers.keys.sort
+        end
+
+        ##
+        # @param [String, Symbol] name provider identifier
+        # @return [Boolean]
+        def registered?(name)
+          providers.key?(provider_name(name))
+        end
+
+        private
+
+        def provider_name(name)
+          name.to_s.downcase
+        end
+
+        def unsupported_provider_message(name)
+          "Unsupported LLM provider #{name.inspect}. Available: #{registered.join(', ')}"
+        end
+
+        def providers
+          @providers ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/cleo_quality_review/llm_providers/stub.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module CleoQualityReview
+  module LlmProviders
+    ##
+    # Stub provider implementation for tests and local development.
+    module Stub
+      ##
+      # Configuration for the stub LLM provider.
+      class Config
+        DEFAULT_RESPONSE = "This is a stub review response for testing."
+
+        class << self
+          ##
+          # Configure the response for all stub clients.
+          # @param [String, Proc] response fixed response or callable
+          # @return [void]
+          def response=(response)
+            @response = response
+          end
+
+          ##
+          # @return [String, Proc] the configured response
+          def response
+            @response || DEFAULT_RESPONSE
+          end
+
+          ##
+          # Reset to default response.
+          # @return [void]
+          def reset!
+            @response = nil
+          end
+        end
+
+        ##
+        # @param [Hash{String => String}] env environment variables (unused, for interface compatibility)
+        def initialize(env: ENV)
+        end
+
+        ##
+        # @return [String] the configured response
+        def response
+          self.class.response
+        end
+
+        ##
+        # @return [Boolean] always true for stub
+        def configured?
+          true
+        end
+      end
+
+      ##
+      # Stub LLM client, mirrors OpenAi::Client interface.
+      class Client
+        attr_reader :received_prompts
+
+        ##
+        # @param [Config] config stub configuration
+        def initialize(config:)
+          @config = config
+          @received_prompts = []
+        end
+
+        ##
+        # Generate a review by returning the configured response.
+        # @param [String] prompt the prompt sent
+        # @return [String] the configured response
+        def generate_review(prompt)
+          received_prompts << prompt
+          response = config.response
+
+          case response
+          when Proc
+            response.call(prompt)
+          else
+            response.to_s
+          end
+        end
+
+        private
+
+        attr_reader :config
+      end
+
+      ##
+      # Stub LLM provider adapter for LlmClient.
+      class Provider
+        ##
+        # Validate config - always passes for stub.
+        # @param [LlmConfig] config
+        # @return [void]
+        def validate_config(config)
+        end
+
+        ##
+        # Build the stub client.
+        # @param [LlmConfig] config
+        # @return [Client]
+        def build_client(config:)
+          Client.new(config: config.stub_config)
+        end
+      end
+    end
+  end
+end

data/lib/cleo_quality_review/llm_providers.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module CleoQualityReview
+  ##
+  # Namespace for bundled LLM provider implementations.
+  module LlmProviders
+    require_relative "llm_providers/registry"
+    require_relative "llm_providers/open_ai"
+    require_relative "llm_providers/stub"
+
+    class << self
+      ##
+      # Register a new LLM provider for use.
+      # @param [String, Symbol] provider_name
+      # @param [Class] provider_class
+      # @return [nil]
+      def register(provider_name, provider_class)
+        Registry.register(provider_name.to_s, provider_class)
+      end
+
+      ##
+      # Resolve a registered LLM provider.
+      # @param [String, Symbol] provider_name
+      # @return [Object]
+      def fetch(provider_name)
+        Registry.fetch(provider_name.to_s)
+      end
+
+      ##
+      # @return [Array<String>] registered provider names
+      def registered
+        Registry.registered
+      end
+
+      ##
+      # Has a provider with the given name been registered?
+      # @param [String, Symbol] provider_name
+      # @return [Boolean]
+      def registered?(provider_name)
+        Registry.registered?(provider_name)
+      end
+    end
+  end
+end