llm_classifier 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 983b48d9d7882b918eb73b68d28aa49134e4aed1cdeb242a92eb9b7301767a89
-  data.tar.gz: ebe5c1dd0a365ecb63b27991fb2f19775a20efd70f1141e348a84cace9d93a8e
+  metadata.gz: 2740f212b3f80944530c9b0ca84d18828499d8cc6d66de231bac734d2f83fc43
+  data.tar.gz: 1a9c8211890f2a74c16d6883a28a58c8a6be4d7340e62d8c1b8aafc89746fe7e
 SHA512:
-  metadata.gz: b75468e630400fd04b59c2e9765c2bc504a3c8cc8cc0f652d1249661ff574b18c320851496a35c500c86ccf3e1cb5d416bc2533e8c9ff87d63d89e1ef614ab38
-  data.tar.gz: 4513b387bb5a03a5ee06ec7feeb3b2f026408cd82abb20585dfac62e2551b171be90329b96c1078f39e54001275479e065ab5b6d8ddf37b3c40383e55cadc7a5
+  metadata.gz: 8332595d0ecb1390cda51139c745be5bc2f3c407e545594f2b9c57e22cd52f7ec0c42d2d08cf252c4e2d08a9def41b34ae31aed8062e45f4eee484776be8b4f2
+  data.tar.gz: 3bd39aaf2842079e629046a8bf3afda9ec01d41e850eaf9be39a5d958513f63c0e51603dada50aeac1f560f3d469740d2fddeea59c9e1acc559c1dc34e4cc5e4

data/.rubocop.yml

@@ -1,8 +1,8 @@
-require:
+plugins:
   - rubocop-rspec
 
 AllCops:
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.2
   NewCops: enable
   SuggestExtensions: false
   Exclude:
@@ -42,4 +42,4 @@ RSpec/ExampleLength:
   Max: 15
 
 RSpec/MultipleExpectations:
-  Max: 5
+  Max: 6

data/README.md

@@ -100,6 +100,27 @@ result = TopicClassifier.classify("Building a Rails API with React frontend")
 result.categories  # => ["rails", "javascript"]
 ```
 
+### Requiring Categories
+
+By default, multi-label classifiers return `Result.success` even when no categories match (empty array). Use `require_categories` to treat empty results as failures:
+
+```ruby
+class StrictClassifier < LlmClassifier::Classifier
+  categories :mechanic, :instructor, :gear
+  multi_label true
+  require_categories true  # Result.failure when no categories match
+
+  system_prompt "Classify this business..."
+end
+
+result = StrictClassifier.classify("Joe's Pizza Shop")
+result.success?    # => false (no motorcycle categories matched)
+result.failure?    # => true
+result.error       # => "No valid categories returned"
+```
+
+This is useful when classification is a filtering step and you need to distinguish "no match" from "classification succeeded."
+
 ### Domain Knowledge
 
 Inject domain-specific knowledge into your prompts:
@@ -281,7 +302,7 @@ This project includes a [Dev Container](https://containers.dev/) configuration f
 3. Press `Cmd+Shift+P` and select "Dev Containers: Reopen in Container"
 4. Wait for the container to build and start
 
-The container includes Ruby 3.3.2, GitHub CLI, and useful VS Code extensions.
+The container includes Ruby, GitHub CLI, and useful VS Code extensions.
 
 ### Local Setup
 

data/lib/llm_classifier/adapters/ruby_llm.rb

@@ -11,7 +11,11 @@ module LlmClassifier
         chat_instance.with_instructions(system_prompt)
         response = chat_instance.ask(user_prompt)
 
-        response.content
+        {
+          content: response.content,
+          input_tokens: response.input_tokens,
+          output_tokens: response.output_tokens
+        }
       end
 
       private

data/lib/llm_classifier/classifier.rb

@@ -7,7 +7,8 @@ module LlmClassifier
   class Classifier
     class << self
       attr_reader :defined_categories, :defined_system_prompt, :defined_model,
-                  :defined_adapter, :defined_multi_label, :defined_knowledge,
+                  :defined_adapter, :defined_multi_label, :defined_require_categories,
+                  :defined_knowledge,
                   :before_classify_callbacks, :after_classify_callbacks
 
       def categories(*cats)
@@ -50,6 +51,14 @@ module LlmClassifier
         end
       end
 
+      def require_categories(value = nil)
+        if value.nil?
+          @defined_require_categories || false
+        else
+          @defined_require_categories = value
+        end
+      end
+
       def knowledge(&)
         if block_given?
           @defined_knowledge = Knowledge.new
@@ -68,8 +77,8 @@ module LlmClassifier
         @after_classify_callbacks << block
       end
 
-      def classify(input, **options)
-        new(input, **options).classify
+      def classify(input, **)
+        new(input, **).classify
       end
     end
 
@@ -103,13 +112,23 @@ module LlmClassifier
 
     def perform_classification(processed_input)
       adapter_instance = build_adapter
+      resolved_model = options[:model] || self.class.model
       response = adapter_instance.chat(
-        model: self.class.model,
+        model: resolved_model,
         system_prompt: build_system_prompt,
         user_prompt: build_user_prompt(processed_input)
       )
 
-      parse_response(response)
+      content, token_data = extract_response_data(response)
+      parse_response(content, resolved_model, token_data)
+    end
+
+    def extract_response_data(response)
+      if response.is_a?(Hash)
+        [response[:content], { input_tokens: response[:input_tokens], output_tokens: response[:output_tokens] }]
+      else
+        [response, {}]
+      end
     end
 
     def build_adapter
@@ -161,24 +180,31 @@ module LlmClassifier
       end
     end
 
-    def parse_response(response)
-      json = JSON.parse(response)
+    def parse_response(response, resolved_model = nil, token_data = {})
+      json = JSON.parse(strip_code_fences(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)
+      build_success_result(json, valid_categories, response, resolved_model, token_data)
     rescue JSON::ParserError => e
       Result.failure(error: "Failed to parse response: #{e.message}", raw_response: response)
     end
 
+    def strip_code_fences(text)
+      text.sub(/\A\s*```\w*\R?/, "").sub(/\R?```\s*\z/, "")
+    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
+      return false if valid_categories.any?
+      return false if self.class.categories.empty?
+
+      !self.class.multi_label || self.class.require_categories
     end
 
     def build_failure_result(response, json)
@@ -189,7 +215,7 @@ module LlmClassifier
       )
     end
 
-    def build_success_result(json, valid_categories, response)
+    def build_success_result(json, valid_categories, response, resolved_model = nil, token_data = {})
       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) }
@@ -199,7 +225,10 @@ module LlmClassifier
         confidence: json["confidence"]&.to_f,
         reasoning: json["reasoning"],
         raw_response: response,
-        metadata: metadata
+        metadata: metadata,
+        model: resolved_model,
+        input_tokens: token_data[:input_tokens],
+        output_tokens: token_data[:output_tokens]
       )
     end
   end

data/lib/llm_classifier/content_fetchers/web.rb

@@ -77,7 +77,7 @@ module LlmClassifier
       end
 
       def normalize_redirect_url(base_url, redirect_url)
-        return nil if redirect_url.blank?
+        return nil if redirect_url.nil? || redirect_url.empty?
 
         if redirect_url.start_with?("http://", "https://")
           redirect_url

data/lib/llm_classifier/result.rb

@@ -3,15 +3,21 @@
 module LlmClassifier
   # Result object returned from classification operations
   class Result
-    attr_reader :categories, :confidence, :reasoning, :raw_response, :metadata, :error
+    attr_reader :categories, :confidence, :reasoning, :raw_response, :metadata, :error, :model,
+                :input_tokens, :output_tokens
 
-    def initialize(categories: [], confidence: nil, reasoning: nil, raw_response: nil, error: nil, metadata: {})
+    def initialize(categories: [], confidence: nil, reasoning: nil,
+                   raw_response: nil, error: nil, metadata: {},
+                   model: nil, input_tokens: nil, output_tokens: nil)
       @categories = Array(categories)
       @confidence = confidence
       @reasoning = reasoning
       @raw_response = raw_response
       @metadata = metadata
       @error = error
+      @model = model
+      @input_tokens = input_tokens
+      @output_tokens = output_tokens
     end
 
     def success?
@@ -38,18 +44,26 @@ module LlmClassifier
         confidence: @confidence,
         reasoning: @reasoning,
         metadata: @metadata,
-        error: @error
+        error: @error,
+        model: @model,
+        input_tokens: @input_tokens,
+        output_tokens: @output_tokens
       }
     end
 
     class << self
-      def success(categories:, confidence: nil, reasoning: nil, raw_response: nil, metadata: {})
+      def success(categories:, confidence: nil, reasoning: nil,
+                  raw_response: nil, metadata: {},
+                  model: nil, input_tokens: nil, output_tokens: nil)
         new(
           categories: categories,
           confidence: confidence,
           reasoning: reasoning,
           raw_response: raw_response,
-          metadata: metadata
+          metadata: metadata,
+          model: model,
+          input_tokens: input_tokens,
+          output_tokens: output_tokens
         )
       end
 

data/lib/llm_classifier/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LlmClassifier
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: llm_classifier
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Dmitry Sychev
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -68,6 +69,7 @@ metadata:
   source_code_uri: https://github.com/AxiumFoundry/llm_classifier
   changelog_uri: https://github.com/AxiumFoundry/llm_classifier/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -75,14 +77,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.4.20
+signing_key:
 specification_version: 4
 summary: LLM-powered classification for Ruby with pluggable adapters and Rails integration
 test_files: []