llm_classifier 0.1.0

data/lib/llm_classifier/classifier.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LlmClassifier
+  # Base classifier class that provides a DSL for defining LLM-powered classifiers
+  class Classifier
+    class << self
+      attr_reader :defined_categories, :defined_system_prompt, :defined_model,
+                  :defined_adapter, :defined_multi_label, :defined_knowledge,
+                  :before_classify_callbacks, :after_classify_callbacks
+
+      def categories(*cats)
+        if cats.empty?
+          @defined_categories || []
+        else
+          @defined_categories = cats.map(&:to_s)
+        end
+      end
+
+      def system_prompt(prompt = nil)
+        if prompt.nil?
+          @defined_system_prompt
+        else
+          @defined_system_prompt = prompt
+        end
+      end
+
+      def model(model_name = nil)
+        if model_name.nil?
+          @defined_model || LlmClassifier.configuration.default_model
+        else
+          @defined_model = model_name
+        end
+      end
+
+      def adapter(adapter_name = nil)
+        if adapter_name.nil?
+          @defined_adapter || LlmClassifier.configuration.adapter
+        else
+          @defined_adapter = adapter_name
+        end
+      end
+
+      def multi_label(value = nil)
+        if value.nil?
+          @defined_multi_label || false
+        else
+          @defined_multi_label = value
+        end
+      end
+
+      def knowledge(&)
+        if block_given?
+          @defined_knowledge = Knowledge.new
+          @defined_knowledge.instance_eval(&)
+        end
+        @defined_knowledge
+      end
+
+      def before_classify(&block)
+        @before_classify_callbacks ||= []
+        @before_classify_callbacks << block
+      end
+
+      def after_classify(&block)
+        @after_classify_callbacks ||= []
+        @after_classify_callbacks << block
+      end
+
+      def classify(input, **options)
+        new(input, **options).classify
+      end
+    end
+
+    attr_reader :input, :options
+
+    def initialize(input, **options)
+      @input = input
+      @options = options
+    end
+
+    def classify
+      processed_input = run_before_callbacks(@input)
+      result = perform_classification(processed_input)
+      run_after_callbacks(result)
+      result
+    rescue StandardError => e
+      Result.failure(error: e.message)
+    end
+
+    private
+
+    def run_before_callbacks(input)
+      callbacks = self.class.before_classify_callbacks || []
+      callbacks.reduce(input) { |acc, callback| instance_exec(acc, &callback) || acc }
+    end
+
+    def run_after_callbacks(result)
+      callbacks = self.class.after_classify_callbacks || []
+      callbacks.each { |callback| instance_exec(result, &callback) }
+    end
+
+    def perform_classification(processed_input)
+      adapter_instance = build_adapter
+      response = adapter_instance.chat(
+        model: self.class.model,
+        system_prompt: build_system_prompt,
+        user_prompt: build_user_prompt(processed_input)
+      )
+
+      parse_response(response)
+    end
+
+    def build_adapter
+      adapter_name = self.class.adapter
+      adapter_class = case adapter_name
+                      when :ruby_llm then Adapters::RubyLlm
+                      when :openai then Adapters::OpenAI
+                      when :anthropic then Adapters::Anthropic
+                      when Class then adapter_name
+                      else
+                        raise AdapterError, "Unknown adapter: #{adapter_name}"
+                      end
+      adapter_class.new
+    end
+
+    def build_system_prompt
+      prompt = self.class.system_prompt || default_system_prompt
+      knowledge = self.class.knowledge
+
+      prompt = "#{prompt}\n\n#{knowledge.to_prompt}" if knowledge
+
+      prompt
+    end
+
+    def default_system_prompt
+      categories = self.class.categories.join(", ")
+      multi = self.class.multi_label
+
+      <<~PROMPT
+        You are a classifier. Classify the given input into #{multi ? "one or more of" : "exactly one of"} these categories: #{categories}.
+
+        Respond with ONLY a JSON object in this format:
+        {
+          "categories": [#{multi ? '"category1", "category2"' : '"category"'}],
+          "confidence": 0.0-1.0,
+          "reasoning": "Brief explanation"
+        }
+      PROMPT
+    end
+
+    def build_user_prompt(processed_input)
+      case processed_input
+      when String
+        processed_input
+      when Hash
+        processed_input.map { |k, v| "#{k}: #{v}" }.join("\n")
+      else
+        processed_input.to_s
+      end
+    end
+
+    def parse_response(response)
+      json = JSON.parse(response)
+      valid_categories = extract_valid_categories(json)
+
+      return build_failure_result(response, json) if should_fail?(valid_categories)
+
+      build_success_result(json, valid_categories, response)
+    rescue JSON::ParserError => e
+      Result.failure(error: "Failed to parse response: #{e.message}", raw_response: response)
+    end
+
+    def extract_valid_categories(json)
+      raw_categories = Array(json["categories"] || json["category"])
+      raw_categories.select { |c| self.class.categories.include?(c.to_s) }
+    end
+
+    def should_fail?(valid_categories)
+      valid_categories.empty? && !self.class.categories.empty? && !self.class.multi_label
+    end
+
+    def build_failure_result(response, json)
+      Result.failure(
+        error: "No valid categories returned",
+        raw_response: response,
+        metadata: { parsed: json }
+      )
+    end
+
+    def build_success_result(json, valid_categories, response)
+      categories = self.class.multi_label ? valid_categories : [valid_categories.first].compact
+      excluded_keys = %w[categories category confidence reasoning]
+      metadata = json.reject { |k, _| excluded_keys.include?(k) }
+
+      Result.success(
+        categories: categories,
+        confidence: json["confidence"]&.to_f,
+        reasoning: json["reasoning"],
+        raw_response: response,
+        metadata: metadata
+      )
+    end
+  end
+end

data/lib/llm_classifier/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module LlmClassifier
+  # Configuration object for LlmClassifier settings
+  class Configuration
+    attr_accessor :adapter, :default_model, :openai_api_key, :anthropic_api_key,
+                  :web_fetch_timeout, :web_fetch_user_agent, :default_queue,
+                  :logger
+
+    def initialize
+      @adapter = :ruby_llm
+      @default_model = "gpt-4o-mini"
+      @openai_api_key = ENV.fetch("OPENAI_API_KEY", nil)
+      @anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
+      @web_fetch_timeout = 10
+      @web_fetch_user_agent = "LlmClassifier/#{VERSION}"
+      @default_queue = :classification
+      @logger = defined?(::Rails) ? ::Rails.logger : Logger.new($stdout)
+    end
+
+    def adapter_class
+      case adapter
+      when :ruby_llm
+        Adapters::RubyLlm
+      when :openai
+        Adapters::OpenAI
+      when :anthropic
+        Adapters::Anthropic
+      when Class
+        adapter
+      else
+        raise ConfigurationError, "Unknown adapter: #{adapter}"
+      end
+    end
+  end
+end

data/lib/llm_classifier/content_fetchers/base.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module LlmClassifier
+  module ContentFetchers
+    # Base content fetcher class
+    class Base
+      def fetch(source)
+        raise NotImplementedError, "Subclasses must implement #fetch"
+      end
+
+      protected
+
+      def config
+        LlmClassifier.configuration
+      end
+    end
+  end
+end

data/lib/llm_classifier/content_fetchers/null.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module LlmClassifier
+  module ContentFetchers
+    # Null content fetcher that returns nothing
+    class Null < Base
+      def fetch(_source)
+        nil
+      end
+    end
+  end
+end

data/lib/llm_classifier/content_fetchers/web.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "resolv"
+require "ipaddr"
+
+module LlmClassifier
+  module ContentFetchers
+    # Web content fetcher with SSRF protection
+    class Web < Base
+      PRIVATE_IP_RANGES = [
+        IPAddr.new("10.0.0.0/8"),
+        IPAddr.new("172.16.0.0/12"),
+        IPAddr.new("192.168.0.0/16"),
+        IPAddr.new("127.0.0.0/8"),
+        IPAddr.new("169.254.0.0/16"),
+        IPAddr.new("::1/128"),
+        IPAddr.new("fc00::/7"),
+        IPAddr.new("fe80::/10")
+      ].freeze
+
+      attr_reader :debug_info
+
+      def initialize(timeout: nil, user_agent: nil)
+        super()
+        @timeout = timeout || config.web_fetch_timeout
+        @user_agent = user_agent || config.web_fetch_user_agent
+        @debug_info = {}
+      end
+
+      def fetch(url)
+        return nil if url.nil? || url.empty?
+
+        url = normalize_url(url)
+        @debug_info[:url] = url
+
+        response = fetch_url(url)
+        return handle_empty_response if response.nil? || response.empty?
+
+        process_successful_response(response)
+      rescue StandardError => e
+        handle_error(e)
+      end
+
+      private
+
+      def normalize_url(url)
+        url.match?(%r{\Ahttps?://}i) ? url : "https://#{url}"
+      end
+
+      def fetch_url(url, redirect_limit = 3)
+        return nil if redirect_limit.zero?
+
+        uri = URI.parse(url)
+        return nil unless validate_host_is_public(uri)
+
+        response = send_http_request(uri)
+        handle_http_response(response, url, redirect_limit)
+      end
+
+      def validate_host_is_public(uri)
+        return false unless %w[http https].include?(uri.scheme)
+        return false if uri.host.nil?
+
+        addresses = Resolv.getaddresses(uri.host)
+        addresses.any? { |addr| !private_ip?(addr) }
+      rescue Resolv::ResolvError
+        false
+      end
+
+      def private_ip?(address)
+        ip = IPAddr.new(address)
+        PRIVATE_IP_RANGES.any? { |range| range.include?(ip) }
+      rescue IPAddr::InvalidAddressError
+        true
+      end
+
+      def normalize_redirect_url(base_url, redirect_url)
+        return nil if redirect_url.blank?
+
+        if redirect_url.start_with?("http://", "https://")
+          redirect_url
+        elsif redirect_url.start_with?("//")
+          uri = URI.parse(base_url)
+          "#{uri.scheme}:#{redirect_url}"
+        else
+          URI.join(base_url, redirect_url).to_s
+        end
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def handle_empty_response
+        @debug_info[:status] = "failed_empty_response"
+        nil
+      end
+
+      def process_successful_response(response)
+        content = extract_text_content(response)
+        @debug_info[:status] = "success"
+        @debug_info[:content_length] = content&.length || 0
+        @debug_info[:content_preview] = content ? truncate_string(content, 500) : nil
+        content
+      end
+
+      def handle_error(error)
+        @debug_info[:status] = "error"
+        @debug_info[:error] = error.message
+        nil
+      end
+
+      def send_http_request(uri)
+        http = build_http_client(uri)
+        request = build_http_request(uri)
+        http.request(request)
+      end
+
+      def build_http_client(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        http
+      end
+
+      def build_http_request(uri)
+        request = Net::HTTP::Get.new(uri.request_uri)
+        request["Host"] = uri.host
+        request["User-Agent"] = @user_agent
+        request
+      end
+
+      def handle_http_response(response, url, redirect_limit)
+        return response.body if response.is_a?(Net::HTTPSuccess)
+        return handle_redirect(response, url, redirect_limit) if response.is_a?(Net::HTTPRedirection)
+
+        nil
+      end
+
+      def handle_redirect(response, url, redirect_limit)
+        redirect_url = normalize_redirect_url(url, response["location"])
+        return fetch_url(redirect_url, redirect_limit - 1) if redirect_url
+
+        nil
+      end
+
+      def extract_text_content(html)
+        return nil if html.nil? || html.empty?
+
+        require_nokogiri!
+
+        doc = Nokogiri::HTML(html)
+        doc.css("script, style, nav, footer, header").remove
+
+        text = doc.css("body").text
+        text = text.gsub(/\s+/, " ").strip
+        truncate_string(text, 2000)
+      end
+
+      def truncate_string(str, max_length)
+        return str if str.length <= max_length
+
+        "#{str[0...max_length]}..."
+      end
+
+      def require_nokogiri!
+        return if defined?(Nokogiri)
+
+        begin
+          require "nokogiri"
+        rescue LoadError
+          raise Error, "nokogiri gem is required for web content fetching. Add it to your Gemfile."
+        end
+      end
+    end
+  end
+end

data/lib/llm_classifier/knowledge.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module LlmClassifier
+  # Domain knowledge container that converts structured data into LLM prompts
+  class Knowledge
+    def initialize
+      @entries = {}
+    end
+
+    def method_missing(name, *args, &)
+      if args.any?
+        @entries[name] = args.first
+      elsif @entries.key?(name)
+        @entries[name]
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @entries.key?(name) || super
+    end
+
+    def to_prompt
+      return "" if @entries.empty?
+
+      sections = @entries.map do |key, value|
+        formatted_key = key.to_s.tr("_", " ").upcase
+        formatted_value = case value
+                          when Array then value.join(", ")
+                          when Hash then value.map { |k, v| "#{k}: #{v}" }.join("\n  ")
+                          else value.to_s
+                          end
+        "#{formatted_key}:\n#{formatted_value}"
+      end
+
+      "DOMAIN KNOWLEDGE:\n\n#{sections.join("\n\n")}"
+    end
+
+    def to_h
+      @entries.dup
+    end
+  end
+end

data/lib/llm_classifier/rails/concerns/classifiable.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module LlmClassifier
+  module Rails
+    module Concerns
+      # Rails concern for adding classification capabilities to ActiveRecord models
+      module Classifiable
+        extend ActiveSupport::Concern
+
+        class_methods do
+          def classifies(attribute, with:, from:, store_in: nil)
+            classifier_class = with
+            source = from
+            storage_column = store_in
+
+            # Define the classify method
+            define_method("classify_#{attribute}!") do
+              input = build_classification_input(source)
+              result = classifier_class.classify(input)
+
+              store_classification_result(attribute, result, storage_column) if result.success?
+
+              result
+            end
+
+            # Define getter for category
+            define_method("#{attribute}_category") do
+              get_stored_classification(attribute, storage_column)&.dig("category")
+            end
+
+            # Define getter for categories (multi-label)
+            define_method("#{attribute}_categories") do
+              get_stored_classification(attribute, storage_column)&.dig("categories") || []
+            end
+
+            # Define getter for full classification data
+            define_method("#{attribute}_classification") do
+              get_stored_classification(attribute, storage_column)
+            end
+          end
+        end
+
+        private
+
+        def build_classification_input(source)
+          case source
+          when Symbol
+            send(source)
+          when Proc
+            source.call(self)
+          when Array
+            source.to_h { |attr| [attr, send(attr)] }
+          else
+            source
+          end
+        end
+
+        def store_classification_result(attribute, result, storage_column)
+          data = {
+            "category" => result.category,
+            "categories" => result.categories,
+            "confidence" => result.confidence,
+            "reasoning" => result.reasoning,
+            "classified_at" => Time.current.iso8601
+          }
+
+          if storage_column
+            current = send(storage_column) || {}
+            updated = current.merge("#{attribute}_classification" => data)
+            send("#{storage_column}=", updated)
+            save! if persisted?
+          else
+            @classification_results ||= {}
+            @classification_results[attribute] = data
+          end
+        end
+
+        def get_stored_classification(attribute, storage_column)
+          if storage_column
+            send(storage_column)&.dig("#{attribute}_classification")
+          else
+            @classification_results&.dig(attribute)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llm_classifier/rails/generators/classifier_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module LlmClassifier
+  module Generators
+    # Rails generator for creating classifier classes
+    class ClassifierGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an LlmClassifier classifier class"
+
+      argument :categories, type: :array, default: [], banner: "category1 category2 ..."
+
+      def create_classifier_file
+        template "classifier.rb.erb", File.join("app/classifiers", "#{file_name}.rb")
+      end
+
+      def create_spec_file
+        return unless File.exist?("spec")
+
+        template "classifier_spec.rb.erb", File.join("spec/classifiers", "#{file_name}_spec.rb")
+      end
+
+      private
+
+      def categories_array
+        return %w[category_a category_b] if categories.empty?
+
+        categories
+      end
+    end
+  end
+end

data/lib/llm_classifier/rails/generators/install_generator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module LlmClassifier
+  module Generators
+    # Rails generator for installing LlmClassifier configuration
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an LlmClassifier initializer"
+
+      def create_initializer_file
+        create_file "config/initializers/llm_classifier.rb", <<~RUBY
+          # frozen_string_literal: true
+
+          LlmClassifier.configure do |config|
+            # LLM adapter to use. Options: :ruby_llm, :openai, :anthropic
+            config.adapter = :ruby_llm
+
+            # Default model for classification
+            config.default_model = "gpt-4o-mini"
+
+            # API keys (reads from ENV by default)
+            # config.openai_api_key = ENV["OPENAI_API_KEY"]
+            # config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+
+            # Content fetching settings
+            config.web_fetch_timeout = 10
+            config.web_fetch_user_agent = "LlmClassifier/#{LlmClassifier::VERSION}"
+
+            # Rails integration
+            config.default_queue = :classification
+          end
+        RUBY
+      end
+
+      def create_classifiers_directory
+        empty_directory "app/classifiers"
+        create_file "app/classifiers/.keep", ""
+      end
+
+      def show_post_install_message
+        say "\n"
+        say "LlmClassifier installed successfully!", :green
+        say "\n"
+        say "Next steps:"
+        say "  1. Configure your API keys in config/initializers/llm_classifier.rb"
+        say "  2. Generate a classifier: rails g llm_classifier:classifier SentimentClassifier"
+        say "\n"
+      end
+    end
+  end
+end