llm_classifier 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 983b48d9d7882b918eb73b68d28aa49134e4aed1cdeb242a92eb9b7301767a89
-  data.tar.gz: ebe5c1dd0a365ecb63b27991fb2f19775a20efd70f1141e348a84cace9d93a8e
+  metadata.gz: ae693cd210a9623a0a4eb201458683ab6d1a407d80a5e8b8f75ad7c08ad21f0c
+  data.tar.gz: ef0f86cfce90ba06a6acd264ef9219c0ed5fa61ae739fd4f992d79365b3ee03a
 SHA512:
-  metadata.gz: b75468e630400fd04b59c2e9765c2bc504a3c8cc8cc0f652d1249661ff574b18c320851496a35c500c86ccf3e1cb5d416bc2533e8c9ff87d63d89e1ef614ab38
-  data.tar.gz: 4513b387bb5a03a5ee06ec7feeb3b2f026408cd82abb20585dfac62e2551b171be90329b96c1078f39e54001275479e065ab5b6d8ddf37b3c40383e55cadc7a5
+  metadata.gz: db55a9e72578fdb7ff9f1ccf0321ddfb08f63cf60c7774e0f53968edf4e9c75f625ecab82a2a269f771e00744f9545fca1c28d6405ec564ecbfd883dc2c84eef
+  data.tar.gz: e69e4f57501a6d8371af21ec29d2edf76147da230fab8066121fb5471bb7217473e1c26193b0f5daadbafe0d4473d3f1c091bd3fe5aecec49b7bb2fa6bd5299a

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/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-29
+
+### Added
+- Structured output: every request sends a JSON Schema generated from the classifier's
+  categories (`Classifier.output_schema`), enforced by the provider via ruby_llm's `with_schema`.
+  Single-label classifiers get a `category` enum; multi-label get a `categories` enum array.
+- `output_field` DSL to declare extra response fields (e.g. `output_field :evidence, description: "..."`).
+  Their values are returned in `Result#metadata`.
+- `Result#model` reports the model ruby_llm actually used when the classifier doesn't set one.
+- Support for ruby_llm 2.x (1.14+ remains supported).
+
+### Changed
+- **Breaking:** `ruby_llm` (>= 1.14, < 3) is now a runtime dependency and the only built-in adapter.
+  Configure provider API keys with `RubyLLM.configure`.
+- **Breaking:** the model must support structured outputs (for Anthropic: Claude Haiku 4.5, Sonnet 4.5,
+  Opus 4.5 and newer). Older models such as `claude-sonnet-4-20250514` reject the request, and the
+  classifier returns a failed `Result`.
+- **Breaking:** `Adapters::Base#chat` now takes a `schema:` keyword. Custom adapters must accept it.
+- **Breaking:** an adapter's Hash return value is treated as the `{ content:, input_tokens:, output_tokens: }`
+  wrapper only when it has a `:content` key; any other Hash is read as the parsed response itself.
+  (Previously every Hash was treated as the wrapper.)
+- **Breaking:** single-label classifiers can no longer abstain. `category` is a required enum, so the
+  model always picks one; 0.2.0 returned a failed `Result` when the model returned no category. Use
+  `multi_label true` with `require_categories true` if "none of these" must be possible.
+- `config.default_model` defaults to `nil`, deferring to `RubyLLM.config.default_model`
+  (was `"gpt-4o-mini"`).
+- **Breaking:** the schema forbids undeclared fields, so extra fields a prompt asks for (which used
+  to land in `Result#metadata`) must now be declared with `output_field`.
+- **Breaking:** single-label responses use a `category` key rather than a one-element `categories`
+  array. Prompts that describe the old JSON format can drop it; the schema takes precedence.
+- Categories are matched case-insensitively and returned as defined.
+- The default system prompt no longer includes JSON format instructions, and tells multi-label
+  classifiers that no category is a valid answer. The schema's `categories` description says the same,
+  so custom prompts get the hint too.
+
+### Removed
+- **Breaking:** the direct `:openai` and `:anthropic` adapters, `config.openai_api_key` /
+  `config.anthropic_api_key`, and `Configuration#adapter_class`. Selecting a removed adapter returns a failed `Result` explaining the change.
+- Markdown code-fence stripping of responses (unnecessary with schema-constrained output).
+
 ## [0.1.0] - 2024-12-02
 
 ### Added

data/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+LlmClassifier - Ruby gem for building LLM-powered classifiers with a clean DSL. Talks to LLMs through ruby_llm (>= 1.14, < 3) with schema-constrained structured output, plus optional Rails integration.
+
+- Ruby >= 3.2, RSpec, RuboCop, Zeitwerk autoloading
+- No Rails dependency in core; Rails integration is opt-in via `lib/llm_classifier/rails/`
+- CI tests against Ruby 3.4 and 4.0, each with ruby_llm 1.14.0 (the floor), `~> 1.16`, and `~> 2.0` (`RUBY_LLM_VERSION` env var pins the version in the Gemfile)
+
+## Development with Docker
+
+Ruby is not installed on the host. Use Docker to run tests and linting:
+
+```bash
+# Run tests and rubocop (Ruby 3.4)
+docker.exe run --rm -v "$(wslpath -w "$(pwd)"):/app" -w /app ruby:3.4-slim \
+  bash -c "apt-get update -qq && apt-get install -y -qq build-essential git 2>/dev/null && \
+  gem install bundler --no-document && bundle install --quiet && \
+  bundle exec rspec && bundle exec rubocop"
+
+# Rubocop only
+docker.exe run --rm -v "$(wslpath -w "$(pwd)"):/app" -w /app ruby:3.4-slim \
+  bash -c "apt-get update -qq && apt-get install -y -qq build-essential git 2>/dev/null && \
+  gem install bundler --no-document && bundle install --quiet && \
+  bundle exec rubocop"
+
+# Single spec file
+docker.exe run --rm -v "$(wslpath -w "$(pwd)"):/app" -w /app ruby:3.4-slim \
+  bash -c "apt-get update -qq && apt-get install -y -qq build-essential git 2>/dev/null && \
+  gem install bundler --no-document && bundle install --quiet && \
+  bundle exec rspec spec/llm_classifier/classifier_spec.rb"
+```
+
+Docker Desktop must be running on Windows. The `docker.exe` command is used because Docker runs via WSL2 integration. The `-v` flag bind-mounts the project so edits on host are immediately visible.
+
+A `.devcontainer/` setup also exists for VS Code Dev Containers.
+
+## Quick Commands (inside Docker)
+
+```bash
+bundle exec rspec                                    # all tests
+bundle exec rspec spec/llm_classifier/classifier_spec.rb  # single file
+bundle exec rubocop                                  # all files
+bundle exec rubocop -a                               # auto-correct
+gem build llm_classifier.gemspec                     # build gem
+```
+
+## Project Structure
+
+All sibling projects are located in `/home/axium/projects/`. The `prospector` gem depends on `llm_classifier`.
+
+## Code Standards
+
+- Double-quoted strings (enforced by RuboCop)
+- Max line length: 120 characters
+- Max method length: 20 lines
+- RSpec example max: 15 lines, max 6 expectations per example
+- `Style/HashExcept` disabled (requires ActiveSupport)
+- `Metrics/ClassLength` exempted for `classifier.rb` and `content_fetchers/web.rb`
+
+## Git Workflow
+
+- Never push directly to main. Always create a feature branch and PR.
+- Run the full test suite and rubocop before creating a PR.
+- Version bumps in `lib/llm_classifier/version.rb` go in the feature PR, not separately.
+
+## Key Classes
+
+- `LlmClassifier::Classifier` - Core DSL and classification pipeline; `.output_schema` builds the JSON Schema sent with every request
+- `LlmClassifier::Result` - Value object returned from every classification
+- `LlmClassifier::Knowledge` - Domain knowledge DSL container (`method_missing`-based)
+- `LlmClassifier::Configuration` - Global config (adapter, default model, web fetch, queue). API keys live in `RubyLLM.configure`
+- `LlmClassifier::Adapters::Base` - Abstract adapter interface
+- `LlmClassifier::ContentFetchers::Web` - HTTP fetcher with SSRF protection
+- `LlmClassifier::Rails::Concerns::Classifiable` - ActiveRecord integration
+
+## Component Documentation
+
+- [lib/llm_classifier/adapters/CLAUDE.md](lib/llm_classifier/adapters/CLAUDE.md) - LLM adapter contract and implementations
+- [lib/llm_classifier/content_fetchers/CLAUDE.md](lib/llm_classifier/content_fetchers/CLAUDE.md) - Content fetchers and SSRF protection
+- [lib/llm_classifier/rails/CLAUDE.md](lib/llm_classifier/rails/CLAUDE.md) - Rails integration (Zeitwerk-excluded)
+- [spec/CLAUDE.md](spec/CLAUDE.md) - Testing conventions

data/README.md

@@ -1,6 +1,6 @@
 # LlmClassifier
 
-A flexible Ruby gem for building LLM-powered classifiers. Define categories, system prompts, and domain knowledge using a clean DSL. Supports multiple LLM backends and integrates seamlessly with Rails.
+A flexible Ruby gem for building LLM-powered classifiers. Define categories, system prompts, and domain knowledge using a clean DSL. Responses are constrained to a JSON Schema generated from your categories, so the model can only answer with a category you defined. Works with any provider [ruby_llm](https://rubyllm.com) supports and integrates with Rails.
 
 ## Installation
 
@@ -8,10 +8,16 @@ Add this line to your application's Gemfile:
 
 ```ruby
 gem 'llm_classifier'
+```
+
+`llm_classifier` talks to LLMs through [ruby_llm](https://rubyllm.com) (1.14+ or 2.x), which is installed as a dependency. Configure your provider credentials there:
 
-# Add your preferred LLM adapter
-gem 'ruby_llm'  # recommended
-# or use direct API adapters (no additional gem needed)
+```ruby
+# config/initializers/ruby_llm.rb
+RubyLLM.configure do |config|
+  config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+  config.default_model = "claude-opus-5-5"
+end
 ```
 
 And then execute:
@@ -41,17 +47,12 @@ class SentimentClassifier < LlmClassifier::Classifier
     - positive: Expresses satisfaction, happiness, or approval
     - negative: Expresses dissatisfaction, unhappiness, or criticism
     - neutral: Neither positive nor negative, factual or balanced
-
-    Respond with ONLY a JSON object:
-    {
-      "categories": ["category"],
-      "confidence": 0.0-1.0,
-      "reasoning": "Brief explanation"
-    }
   PROMPT
 end
 ```
 
+You don't need to describe the response format in the prompt. The gem sends a JSON Schema with every request (see [Structured Output](#structured-output)).
+
 ### 2. Use It
 
 ```ruby
@@ -68,15 +69,8 @@ result.reasoning   # => "Strong positive language with 'love' and 'absolutely'"
 ```ruby
 # config/initializers/llm_classifier.rb
 LlmClassifier.configure do |config|
-  # LLM adapter: :ruby_llm (default), :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"]
+  # Default model for classification. nil (the default) uses RubyLLM.config.default_model.
+  config.default_model = "claude-opus-5-5"
 
   # Content fetching settings
   config.web_fetch_timeout = 10
@@ -86,6 +80,44 @@ end
 
 ## Features
 
+### Structured Output
+
+Every request carries a JSON Schema built from the classifier's categories. ruby_llm passes it to the provider's native structured-output feature (for example, Anthropic's `output_config.format`), and the provider enforces it during generation. The model can't return malformed JSON or a category you didn't define. A refused or truncated response still comes back as a failed `Result`.
+
+```ruby
+SentimentClassifier.output_schema
+# => {
+#      type: "object",
+#      properties: {
+#        reasoning: { type: "string", ... },
+#        category: { type: "string", enum: ["positive", "negative", "neutral"] },
+#        confidence: { type: "number", ... }
+#      },
+#      required: ["reasoning", "category", "confidence"],
+#      additionalProperties: false
+#    }
+```
+
+### Extra Output Fields
+
+The schema doesn't allow fields you haven't declared. To have the model return more than the category, declare each extra field with `output_field`. Options are JSON Schema keywords, and `type` defaults to `"string"`. The values come back in `result.metadata`:
+
+```ruby
+class BusinessClassifier < LlmClassifier::Classifier
+  categories :dealership, :mechanic, :parts
+  multi_label true
+  output_field :evidence, description: "Words or brands that confirmed the category"
+  output_field :brands, type: "array", items: { type: "string" }
+end
+
+result = BusinessClassifier.classify("Joe's Harley-Davidson Service")
+result.metadata  # => { "evidence" => "Harley-Davidson, Service", "brands" => ["Harley-Davidson"] }
+```
+
+Single-label classifiers get a `category` string, so the model must pick exactly one. Multi-label classifiers get a `categories` array, which may be empty. Categories are matched case-insensitively, because providers guarantee enum membership but not capitalization.
+
+The model needs to support structured outputs. Current Claude and OpenAI models do.
+
 ### Multi-label Classification
 
 ```ruby
@@ -100,6 +132,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:
@@ -138,16 +191,20 @@ class AuditedClassifier < LlmClassifier::Classifier
 end
 ```
 
-### Override Adapter Per-Classifier
+### Override Model Per-Classifier
 
 ```ruby
 class CriticalClassifier < LlmClassifier::Classifier
   categories :high, :medium, :low
-  adapter :anthropic      # Use Anthropic for this classifier
-  model "claude-sonnet-4-20250514"  # Specific model
+  model "claude-opus-5-5"
 end
+
+# Or per call
+CriticalClassifier.classify(text, model: "claude-haiku-4-5")
 ```
 
+If ruby_llm raises `ModelNotFoundError` for a newly released model, refresh its registry with `RubyLLM.models.refresh!`.
+
 ## Rails Integration
 
 ### ActiveRecord Concern
@@ -226,22 +283,20 @@ Features:
 
 ## Adapters
 
-### Built-in Adapters
-
-- **`:ruby_llm`** - Uses the [ruby_llm](https://github.com/crmne/ruby_llm) gem (recommended)
-- **`:openai`** - Direct OpenAI API integration
-- **`:anthropic`** - Direct Anthropic API integration
+The built-in `:ruby_llm` adapter (the default) routes requests through [ruby_llm](https://rubyllm.com), so any provider it supports works.
 
 ### Custom Adapter
 
 ```ruby
 class MyCustomAdapter < LlmClassifier::Adapters::Base
-  def chat(model:, system_prompt:, user_prompt:)
-    # Make API call and return response text
+  def chat(model:, system_prompt:, user_prompt:, schema:)
+    # `schema` is the classifier's JSON Schema. Constrain the response to it and
+    # return the parsed Hash or the JSON string.
     MyLlmClient.complete(
       model: model,
       system: system_prompt,
-      prompt: user_prompt
+      prompt: user_prompt,
+      json_schema: schema
     )
   end
 end
@@ -264,8 +319,9 @@ result.category      # => "primary_category" (first)
 result.categories    # => ["cat1", "cat2"] (all)
 result.confidence    # => 0.95
 result.reasoning     # => "Explanation from LLM"
-result.raw_response  # => Original JSON string
-result.metadata      # => Additional data from response
+result.raw_response  # => Response JSON string
+result.model         # => Model used (the classifier's, or ruby_llm's default)
+result.metadata      # => Values of declared output_field entries
 result.error         # => Error message if failed
 result.to_h          # => Hash representation
 ```
@@ -281,7 +337,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/CLAUDE.md

@@ -0,0 +1,24 @@
+# Adapters
+
+LLM provider adapters. All inherit from `Adapters::Base` and implement `#chat(model:, system_prompt:, user_prompt:, schema:)`.
+
+## Inventory
+
+- `Base` - Abstract interface. Provides `#config` helper for accessing `LlmClassifier.configuration`
+- `RubyLlm` - The only built-in adapter. Calls `RubyLLM.chat(...).with_instructions(...).with_schema(...).ask(...)` and returns a Hash with `:content`, `:input_tokens`, `:output_tokens`, `:model` (`chat.model.id`, the model actually used)
+
+## Conventions
+
+- `schema:` is the classifier's `output_schema` (JSON Schema, symbol keys), including any `output_field` declarations. Adapters must constrain the response to it
+- `#chat` returns the content (a parsed Hash or a JSON String) or a wrapper Hash `{ content:, input_tokens:, output_tokens:, model: }`. `Classifier#extract_response_data` treats a Hash as the wrapper only when it has a `:content` key
+- ruby_llm 1.x returns structured content as a Hash; 2.x returns a JSON String (`response.parsed` holds the Hash). `Classifier#parse_response` accepts both
+- Token counts come from `response.tokens.input` / `.output`, which exist in ruby_llm 1.13+ and 2.x (`input_tokens` readers were removed in 2.0)
+- `model: nil` lets ruby_llm fall back to `RubyLLM.config.default_model`
+- Provider credentials are configured in `RubyLLM.configure`, not in this gem
+- Custom adapters are passed as a Class to `config.adapter` or the `adapter` DSL
+- Anthropic schema limits: no `minimum`/`maximum`, no `maxItems`, `minItems` only 0 or 1, `additionalProperties: false` required. Don't add `minItems: 1` for `require_categories`: an empty array is how the model signals "no match"
+
+## Related
+
+- [../content_fetchers/CLAUDE.md](../content_fetchers/CLAUDE.md) - Content fetchers
+- [../../spec/CLAUDE.md](../../spec/CLAUDE.md) - Testing conventions

data/lib/llm_classifier/adapters/base.rb

@@ -4,7 +4,10 @@ module LlmClassifier
   module Adapters
     # Base adapter class for LLM providers
     class Base
-      def chat(model:, system_prompt:, user_prompt:)
+      # schema is a JSON Schema Hash the response must conform to. Return the response
+      # content (a parsed Hash or a JSON String), or a wrapper Hash with a :content key:
+      # { content:, input_tokens:, output_tokens:, model: }.
+      def chat(model:, system_prompt:, user_prompt:, schema:)
         raise NotImplementedError, "Subclasses must implement #chat"
       end
 

data/lib/llm_classifier/adapters/ruby_llm.rb

@@ -2,28 +2,24 @@
 
 module LlmClassifier
   module Adapters
-    # Adapter for the ruby_llm gem
+    # Adapter for the ruby_llm gem. Provider credentials and the fallback model come from
+    # RubyLLM's own configuration.
     class RubyLlm < Base
-      def chat(model:, system_prompt:, user_prompt:)
-        ensure_ruby_llm_loaded!
+      def chat(model:, system_prompt:, user_prompt:, schema:)
+        require "ruby_llm" unless defined?(::RubyLLM)
 
-        chat_instance = ::RubyLLM.chat(model: model)
-        chat_instance.with_instructions(system_prompt)
-        response = chat_instance.ask(user_prompt)
+        chat = ::RubyLLM.chat(model: model)
+        response = chat.with_instructions(system_prompt)
+                       .with_schema(name: "classification", schema: schema, strict: true)
+                       .ask(user_prompt)
 
-        response.content
-      end
-
-      private
-
-      def ensure_ruby_llm_loaded!
-        return if defined?(::RubyLLM)
-
-        begin
-          require "ruby_llm"
-        rescue LoadError
-          raise AdapterError, "ruby_llm gem is not installed. Add it to your Gemfile: gem 'ruby_llm'"
-        end
+        # ruby_llm 1.x returns structured content as a Hash, 2.x as a JSON String.
+        {
+          content: response.content,
+          input_tokens: response.tokens&.input,
+          output_tokens: response.tokens&.output,
+          model: chat.model&.id
+        }
       end
     end
   end

data/lib/llm_classifier/classifier.rb

@@ -5,9 +5,16 @@ require "json"
 module LlmClassifier
   # Base classifier class that provides a DSL for defining LLM-powered classifiers
   class Classifier
+    # Response fields the classifier itself defines.
+    BUILT_IN_FIELDS = %w[reasoning category categories confidence].freeze
+    # Names output_field can't take. "content" would make an adapter's bare parsed Hash
+    # look like the { content: } response wrapper.
+    RESERVED_FIELDS = (BUILT_IN_FIELDS + %w[content]).freeze
+
     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 +57,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
@@ -58,6 +73,19 @@ module LlmClassifier
         @defined_knowledge
       end
 
+      # Declares an extra response field, returned in Result#metadata. Options are JSON Schema
+      # keywords for the field (type defaults to "string").
+      def output_field(name, **schema)
+        name = name.to_s
+        raise ArgumentError, "#{name} is a reserved output field name" if RESERVED_FIELDS.include?(name)
+
+        output_fields[name] = { type: "string" }.merge(schema)
+      end
+
+      def output_fields
+        @output_fields ||= {}
+      end
+
       def before_classify(&block)
         @before_classify_callbacks ||= []
         @before_classify_callbacks << block
@@ -68,8 +96,31 @@ module LlmClassifier
         @after_classify_callbacks << block
       end
 
-      def classify(input, **options)
-        new(input, **options).classify
+      def classify(input, **)
+        new(input, **).classify
+      end
+
+      # JSON Schema the LLM response is constrained to. Reasoning comes first so the
+      # model explains itself before committing to a label.
+      def output_schema
+        label_key = multi_label ? :categories : :category
+        properties = {
+          reasoning: { type: "string", description: "Brief explanation of the classification" },
+          label_key => label_schema,
+          confidence: { type: "number", description: "Confidence from 0.0 to 1.0" }
+        }.merge(output_fields.transform_keys(&:to_sym))
+
+        { type: "object", properties: properties, required: properties.keys.map(&:to_s), additionalProperties: false }
+      end
+
+      private
+
+      def label_schema
+        category = { type: "string" }
+        category[:enum] = categories if categories.any?
+        return category unless multi_label
+
+        { type: "array", items: category, description: "Every category that applies. Empty if none apply." }
       end
     end
 
@@ -103,26 +154,36 @@ 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)
+        user_prompt: build_user_prompt(processed_input),
+        schema: self.class.output_schema
       )
 
-      parse_response(response)
+      content, response_meta = extract_response_data(response)
+      parse_response(content, resolved_model || response_meta[:model], response_meta)
+    end
+
+    # Adapters return the content itself, or wrap it as { content:, input_tokens:, output_tokens:, model: }.
+    def extract_response_data(response)
+      return [response, {}] unless response.is_a?(Hash) && response.key?(:content)
+
+      [response[:content], response.slice(:input_tokens, :output_tokens, :model)]
     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
+      case adapter_name
+      when :ruby_llm then Adapters::RubyLlm.new
+      when Class then adapter_name.new
+      when :openai, :anthropic
+        raise AdapterError, "The :#{adapter_name} adapter was removed in 0.3.0. " \
+                            "Configure the provider in RubyLLM and use the :ruby_llm adapter."
+      else
+        raise AdapterError, "Unknown adapter: #{adapter_name}"
+      end
     end
 
     def build_system_prompt
@@ -138,16 +199,8 @@ module LlmClassifier
       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
+      scope = multi ? "every category that applies (none if none apply)" : "exactly one of these categories"
+      "You are a classifier. Classify the given input into #{scope}: #{categories}."
     end
 
     def build_user_prompt(processed_input)
@@ -161,24 +214,31 @@ module LlmClassifier
       end
     end
 
-    def parse_response(response)
-      json = JSON.parse(response)
+    # Adapters return structured output either already parsed (a Hash) or as JSON text.
+    def parse_response(content, resolved_model = nil, token_data = {})
+      json = content.is_a?(Hash) ? content.transform_keys(&:to_s) : JSON.parse(content.to_s)
+      raw_response = content.is_a?(String) ? content : JSON.generate(json)
       valid_categories = extract_valid_categories(json)
 
-      return build_failure_result(response, json) if should_fail?(valid_categories)
+      return build_failure_result(raw_response, json) if should_fail?(valid_categories)
 
-      build_success_result(json, valid_categories, response)
+      build_success_result(json, valid_categories, raw_response, resolved_model, token_data)
     rescue JSON::ParserError => e
-      Result.failure(error: "Failed to parse response: #{e.message}", raw_response: response)
+      Result.failure(error: "Failed to parse response: #{e.message}", raw_response: content)
     end
 
+    # Structured outputs guarantee enum membership but not capitalization, so match
+    # case-insensitively and return the category as defined.
     def extract_valid_categories(json)
-      raw_categories = Array(json["categories"] || json["category"])
-      raw_categories.select { |c| self.class.categories.include?(c.to_s) }
+      defined = self.class.categories.to_h { |c| [c.downcase, c] }
+      Array(json["categories"] || json["category"]).filter_map { |c| defined[c.to_s.downcase] }.uniq
     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,17 +249,19 @@ 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) }
+      metadata = json.reject { |k, _| BUILT_IN_FIELDS.include?(k) }
 
       Result.success(
         categories: categories,
         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/configuration.rb

@@ -5,34 +5,16 @@ 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
+    attr_accessor :adapter, :default_model, :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)
+      @default_model = nil # nil defers to RubyLLM.config.default_model
       @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/CLAUDE.md

@@ -0,0 +1,27 @@
+# Content Fetchers
+
+Utilities for fetching external content to use as classification input. Not wired into `Classifier` automatically -- callers fetch content and pass it in.
+
+## Inventory
+
+- `Base` - Abstract interface. Subclasses implement `#fetch(source)`
+- `Web` - HTTP fetcher with SSRF protection, redirect following, and HTML text extraction
+- `Null` - No-op fetcher, always returns `nil`
+
+## SSRF Protection (`Web`)
+
+- Validates resolved IPs against private/loopback CIDR ranges before connecting
+- Follows up to 3 redirects, re-validating each redirect target
+- `normalize_redirect_url` handles relative and absolute redirect URLs
+- Uses `nil? || empty?` guards (not ActiveSupport `.blank?`) to avoid the dependency
+
+## HTML Processing (`Web`)
+
+- Nokogiri is lazily loaded (`require "nokogiri"` inside the method) since it's an optional dependency
+- Strips `<script>`, `<style>`, `<nav>`, `<footer>`, `<header>` elements
+- Truncates extracted text to 2000 characters
+
+## Related
+
+- [../adapters/CLAUDE.md](../adapters/CLAUDE.md) - LLM adapters
+- [../../spec/CLAUDE.md](../../spec/CLAUDE.md) - Testing conventions

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/rails/CLAUDE.md

@@ -0,0 +1,25 @@
+# Rails Integration
+
+This entire subtree is excluded from Zeitwerk autoloading (`loader.ignore` in `lib/llm_classifier.rb`) and loaded manually only when `Rails::Railtie` is defined. This keeps Rails as an optional dependency.
+
+## Inventory
+
+- `Railtie` - Sets `Rails.logger` as the default LlmClassifier logger
+- `Concerns::Classifiable` - ActiveRecord concern adding a `classifies` macro
+- `Generators::InstallGenerator` - `rails g llm_classifier:install` scaffolds an initializer
+- `Generators::ClassifierGenerator` - `rails g llm_classifier:classifier Name cat1 cat2` scaffolds a classifier and spec
+
+## Classifiable Concern
+
+The `classifies` macro defines three instance methods per classification:
+
+- `classify_<attr>!` - Runs classification and stores the result
+- `<attr>_category` / `<attr>_categories` - Reads stored category data
+- `<attr>_classification` - Returns the full stored classification hash
+
+Results are written into a JSONB column (via `store_in:`) or a transient instance variable if no column is specified.
+
+## Related
+
+- [../adapters/CLAUDE.md](../adapters/CLAUDE.md) - LLM adapters
+- [../content_fetchers/CLAUDE.md](../content_fetchers/CLAUDE.md) - Content fetchers

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

@@ -14,16 +14,10 @@ module LlmClassifier
         create_file "config/initializers/llm_classifier.rb", <<~RUBY
           # frozen_string_literal: true
 
+          # Provider API keys are configured in RubyLLM (config/initializers/ruby_llm.rb).
           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"]
+            # Default model for classification. nil uses RubyLLM.config.default_model.
+            # config.default_model = "claude-opus-5-5"
 
             # Content fetching settings
             config.web_fetch_timeout = 10
@@ -45,7 +39,7 @@ module LlmClassifier
         say "LlmClassifier installed successfully!", :green
         say "\n"
         say "Next steps:"
-        say "  1. Configure your API keys in config/initializers/llm_classifier.rb"
+        say "  1. Configure your provider API keys with RubyLLM.configure"
         say "  2. Generate a classifier: rails g llm_classifier:classifier SentimentClassifier"
         say "\n"
       end

data/lib/llm_classifier/rails/generators/templates/classifier.rb.erb

@@ -7,10 +7,7 @@ class <%= class_name %> < LlmClassifier::Classifier
   # multi_label true
 
   # Uncomment to override the default model
-  # model "gpt-4o-mini"
-
-  # Uncomment to override the default adapter
-  # adapter :openai
+  # model "claude-opus-5-5"
 
   system_prompt <<~PROMPT
     You are a classifier. Analyze the given input and classify it into the appropriate category.
@@ -19,13 +16,6 @@ class <%= class_name %> < LlmClassifier::Classifier
 <% categories_array.each do |cat| -%>
     - <%= cat %>: [describe what this category means]
 <% end -%>
-
-    Respond with ONLY a JSON object:
-    {
-      "categories": ["category"],
-      "confidence": 0.0-1.0,
-      "reasoning": "Brief explanation"
-    }
   PROMPT
 
   # Uncomment to add domain knowledge

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.3.0"
 end

data/lib/llm_classifier.rb

@@ -3,10 +3,7 @@
 require "zeitwerk"
 
 loader = Zeitwerk::Loader.for_gem
-loader.inflector.inflect(
-  "openai" => "OpenAI",
-  "ruby_llm" => "RubyLlm"
-)
+loader.inflector.inflect("ruby_llm" => "RubyLlm")
 loader.ignore("#{__dir__}/llm_classifier/rails")
 loader.setup
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm_classifier
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Dmitry Sychev
@@ -9,6 +9,26 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.14'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.14'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -24,8 +44,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.6'
 description: A flexible Ruby gem for building LLM-based classifiers. Define categories,
-  system prompts, and domain knowledge using a clean DSL. Supports multiple LLM backends
-  (ruby_llm, OpenAI, Anthropic) and integrates seamlessly with Rails.
+  system prompts, and domain knowledge using a clean DSL. Responses are schema-constrained
+  via ruby_llm structured outputs, with optional Rails integration.
 email:
 - dmitry.sychev@axiumfoundry.com
 executables: []
@@ -38,20 +58,22 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/llm_classifier.rb
-- lib/llm_classifier/adapters/anthropic.rb
+- lib/llm_classifier/adapters/CLAUDE.md
 - lib/llm_classifier/adapters/base.rb
-- lib/llm_classifier/adapters/openai.rb
 - lib/llm_classifier/adapters/ruby_llm.rb
 - lib/llm_classifier/classifier.rb
 - lib/llm_classifier/configuration.rb
+- lib/llm_classifier/content_fetchers/CLAUDE.md
 - lib/llm_classifier/content_fetchers/base.rb
 - lib/llm_classifier/content_fetchers/null.rb
 - lib/llm_classifier/content_fetchers/web.rb
 - lib/llm_classifier/knowledge.rb
+- lib/llm_classifier/rails/CLAUDE.md
 - lib/llm_classifier/rails/concerns/classifiable.rb
 - lib/llm_classifier/rails/generators/classifier_generator.rb
 - lib/llm_classifier/rails/generators/install_generator.rb
@@ -75,7 +97,7 @@ 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:
   - - ">="

data/lib/llm_classifier/adapters/anthropic.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-require "net/http"
-require "json"
-require "uri"
-
-module LlmClassifier
-  module Adapters
-    # Adapter for Anthropic API
-    class Anthropic < Base
-      API_URL = "https://api.anthropic.com/v1/messages"
-      API_VERSION = "2023-06-01"
-
-      def chat(model:, system_prompt:, user_prompt:)
-        api_key = validate_api_key
-        response = send_request(model, system_prompt, user_prompt, api_key)
-        parse_response(response)
-      end
-
-      private
-
-      def validate_api_key
-        api_key = config.anthropic_api_key
-        raise ConfigurationError, "Anthropic API key not configured" unless api_key
-
-        api_key
-      end
-
-      def send_request(model, system_prompt, user_prompt, api_key)
-        uri = URI(API_URL)
-        http = build_http_client(uri)
-        request = build_request(uri, api_key, model, system_prompt, user_prompt)
-        http.request(request)
-      end
-
-      def build_http_client(uri)
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = true
-        http
-      end
-
-      def build_request(uri, api_key, model, system_prompt, user_prompt)
-        request = Net::HTTP::Post.new(uri)
-        request["Content-Type"] = "application/json"
-        request["x-api-key"] = api_key
-        request["anthropic-version"] = API_VERSION
-        request.body = build_request_body(model, system_prompt, user_prompt)
-        request
-      end
-
-      def build_request_body(model, system_prompt, user_prompt)
-        {
-          model: model,
-          max_tokens: 1024,
-          system: system_prompt,
-          messages: [
-            { role: "user", content: user_prompt }
-          ]
-        }.to_json
-      end
-
-      def parse_response(response)
-        unless response.is_a?(Net::HTTPSuccess)
-          raise AdapterError, "Anthropic API error: #{response.code} - #{response.body}"
-        end
-
-        parsed = JSON.parse(response.body)
-        parsed.dig("content", 0, "text")
-      end
-    end
-  end
-end

data/lib/llm_classifier/adapters/openai.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-require "net/http"
-require "json"
-require "uri"
-
-module LlmClassifier
-  module Adapters
-    # Adapter for OpenAI API
-    class OpenAI < Base
-      API_URL = "https://api.openai.com/v1/chat/completions"
-
-      def chat(model:, system_prompt:, user_prompt:)
-        api_key = validate_api_key
-        response = send_request(model, system_prompt, user_prompt, api_key)
-        parse_response(response)
-      end
-
-      private
-
-      def validate_api_key
-        api_key = config.openai_api_key
-        raise ConfigurationError, "OpenAI API key not configured" unless api_key
-
-        api_key
-      end
-
-      def send_request(model, system_prompt, user_prompt, api_key)
-        uri = URI(API_URL)
-        http = build_http_client(uri)
-        request = build_request(uri, api_key, model, system_prompt, user_prompt)
-        http.request(request)
-      end
-
-      def build_http_client(uri)
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = true
-        http
-      end
-
-      def build_request(uri, api_key, model, system_prompt, user_prompt)
-        request = Net::HTTP::Post.new(uri)
-        request["Content-Type"] = "application/json"
-        request["Authorization"] = "Bearer #{api_key}"
-        request.body = build_request_body(model, system_prompt, user_prompt)
-        request
-      end
-
-      def build_request_body(model, system_prompt, user_prompt)
-        {
-          model: model,
-          messages: [
-            { role: "system", content: system_prompt },
-            { role: "user", content: user_prompt }
-          ],
-          temperature: 0.3
-        }.to_json
-      end
-
-      def parse_response(response)
-        unless response.is_a?(Net::HTTPSuccess)
-          raise AdapterError, "OpenAI API error: #{response.code} - #{response.body}"
-        end
-
-        parsed = JSON.parse(response.body)
-        parsed.dig("choices", 0, "message", "content")
-      end
-    end
-  end
-end