feather-ai 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0fe728ff2f69d47cd1c9d89a9d8a4752dce0ea05ada463168fcca4496496981
-  data.tar.gz: 36931f778f677cd40e01472a282a1fb44370ea587bee3faef8a76ea543a3c59e
+  metadata.gz: fa4e06ced9d8d48c533d41f97148fba4c26f3ffa478a603c4562960d50e6594f
+  data.tar.gz: 6f04ec946376b964fbf0a049a7837f20bae6eab45690e802b22e4f03b3789bc3
 SHA512:
-  metadata.gz: 3db402c6f71e32084333e0730e2850941f439ce92e54c142b3228c1eb25f024ab64eaf69251412038b3a5c8598598f771a717eb45ccc75b570717e46927c218d
-  data.tar.gz: 18c4afdb60659f9e7b1604062e68ed967d6b65df7db96ac4309f8dc3ff0d2be783a6e53d292f2a2188841eee783a1a7a263137deaa648de58e96c06c93ac853c
+  metadata.gz: 943e45ed67690b5791d953ff443e3d94ba9b1866f1143373ca08dc2ef59826720cbdd4a34eeb6d91cf8d2a626822738e068a9cae4750f92fbe8a4aa2a91b2cb7
+  data.tar.gz: 903b3b7968b1ebebc411e5e8c518649ca8b5cf617461cb630725b861a3dfaba8eed7e914b01803ff5b65c05d92d1806ac6607e4cc5ce235db5f74a9ed59d0d9e

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.5.0 - 2026-10-02
+
+- **Breaking:** requires `ruby_llm` 2.x (fixes the ReDoS advisory in 1.x). Dev dependencies updated to clear all `bundle-audit` findings (rubocop no longer pulls in `mcp`).
+- `Result#cost` now comes from RubyLLM's per-model pricing registry instead of a hardcoded Anthropic-only table, so Haiku and non-Anthropic models are priced correctly; `nil` when the registry has no price.
+- `config.provider` is now a no-op kept for compatibility; RubyLLM 2 resolves the provider from the model.
+- Fix: `media_resolution` (a Gemini `generationConfig` field) is only sent to Gemini models. It was previously sent to every provider, which Anthropic rejects.
+- Fix: audio transcripts are now interpolated as text; previously the `RubyLLM::Transcription` object was interpolated.
+
 ## 0.4.0 - 2026-07-05
 
 - Identification now returns ranked `candidates` (up to 3, each `{common_name:, species:, score:}`) on every `Result`, populated straight from the structured-output schema.

data/CLAUDE.md

@@ -42,35 +42,51 @@ bundle exec rake release
 
 ## Architecture
 
-The gem's only runtime dependency is `ruby_llm`. All classes live under the `FeatherAi` module in `lib/feather_ai/`.
+The gem's only runtime dependency is `ruby_llm` 2.x (which pulls in `schematist` for the schema DSL). All classes live under the `FeatherAi` module in `lib/feather_ai/`.
 
 ### Data Flow
 
-`FeatherAi.identify(image, audio, location:, consensus:)` is the top-level entry point defined in `lib/feather_ai.rb`. It delegates to:
+`FeatherAi.identify(image, audio, location:, consensus:)` is the top-level entry point defined in `lib/feather_ai.rb`. `image` accepts a single path or an array of paths (multiple angles of the same bird). It delegates to:
 
-1. **Identifier** (`lib/feather_ai/identifier.rb`) — Core identification logic. Uses RubyLLM's vision for images and `RubyLLM.transcribe` for audio. When both inputs are provided, they're combined into a single multi-modal prompt. Uses `RubyLLM::Schema` for structured output so results are always clean `Result` objects, not raw LLM prose.
+1. **Identifier** (`lib/feather_ai/identifier.rb`) — Core identification logic. Uses RubyLLM's vision for images and `RubyLLM.transcribe` for audio. When both inputs are provided, they're combined into a single multi-modal prompt. Uses `Schematist::Schema` for structured output (including a `reasoning` field that forces step-by-step visual analysis before the identification); the parsed Hash is read via `response.parsed`, tokens via `response.tokens`, and USD cost via `response.cost.total` (RubyLLM's pricing registry). `config.media_resolution` is only sent to Gemini models.
 
-2. **Consensus** (`lib/feather_ai/consensus.rb`) — When `consensus: true`, runs identification through two configurable models independently. If they agree on species, returns `confident: true`. If they disagree, returns both as `candidates` with uncertain confidence.
+2. **Consensus** (`lib/feather_ai/consensus.rb`) — When `consensus: true`, runs identification through the configured `consensus_models` in parallel threads. Agreement is compared on normalized species name. If they agree, returns `confident: true`; if they disagree, returns both as `candidates` with low confidence. Token counts, cost, and duration are summed across models.
 
-3. **Result** (`lib/feather_ai/result.rb`) — Immutable value object wrapping all identification output. Exposes `common_name`, `species`, `family`, `confidence` (`:high`/`:medium`/`:low`), `confident?`, `region_native?`, `candidates`, `photography_tips`, and `to_h`. Photography tips are lazy-loaded via a second cheap LLM call only when accessed.
+3. **Result** (`lib/feather_ai/result.rb`) — Immutable value object wrapping all identification output. Identification fields: `common_name`, `species`, `family`, `confidence` (`:high`/`:medium`/`:low`), `confident?`, `region_native?`, `reasoning`, `candidates`, `photography_tips`, `to_h`. Observability fields from the LLM call: `model_id`, `input_tokens`, `output_tokens`, `cost`, `duration_ms`, `source` (`:vision`/`:audio`/`:multimodal`), `consensus_models`. Photography tips are lazy-loaded via a second cheap LLM call only when accessed.
 
-4. **PhotographyTips** (`lib/feather_ai/photography_tips.rb`) — Separate LLM call (small model) returning structured shooting advice for the identified species. Only invoked when `result.photography_tips` is called.
+4. **PhotographyTips** (`lib/feather_ai/photography_tips.rb`) — Separate LLM call (uses `tips_model`, a small model) returning structured shooting advice for the identified species. Only invoked when `result.photography_tips` is called.
+
+### Instrumentation
+
+`Instrumentation.instrument` (`lib/feather_ai/instrumentation.rb`) wraps identification in `ActiveSupport::Notifications` when ActiveSupport is loaded, and is a plain `yield` otherwise. Events: `identify.feather_ai` (Identifier) and `consensus.feather_ai` (Consensus); the `Result` is added to the payload after the call completes.
+
+### Errors
+
+All errors inherit from `FeatherAi::Error`: `ConfigurationError` (e.g. no image or audio provided) and `IdentificationError` (LLM call failure).
 
 ### Configuration
 
 ```ruby
 FeatherAi.configure do |c|
-  c.provider  = :anthropic
-  c.location  = "Perth, Western Australia"  # biases results to local species
-  c.model     = "claude-sonnet-4"
+  c.provider         = :anthropic                             # default
+  c.model            = "claude-sonnet-4"                      # default
+  c.location         = "Perth, Western Australia"             # biases results to local species
+  c.consensus_models = ["claude-sonnet-4", "claude-haiku-4"]  # default
+  c.tips_model       = "claude-haiku-4"                       # default
+  c.media_resolution = :high                                  # default; Gemini-only image resolution
 end
 ```
 
-Location can be set globally or per-call via `location:` keyword. It's injected into the system prompt to reduce false positives.
+`FeatherAi.configuration` is a lazily-initialized process singleton; `FeatherAi.reset!` clears it (used before every spec). Location can be set globally or per-call via the `location:` keyword. It's injected into the system prompt to reduce false positives.
 
 ### Rails Integration
 
-`lib/feather_ai/rails/` contains a Railtie and `acts_as_sighting` mixin. When included in an ActiveRecord model, it expects `photo` (ActiveStorage) and `location` (string) attributes, and adds an `identify!` method that populates species fields on the record. A generator (`bin/rails generate feather_ai:install`) scaffolds the migration.
+`lib/feather_ai/rails/` contains a Railtie and `acts_as_sighting` mixin. When included in an ActiveRecord model, it expects `photo` (ActiveStorage) and `location` (string) attributes, and adds:
+
+- `identify!` — downloads the photo, runs identification, persists species fields, returns the `Result`.
+- `correct!(attrs)` / `corrected?` / `correction_delta` — human corrections of AI identifications, stored in `corrected_*` columns with a `corrected_at` timestamp. `correction_delta` always diffs against the original AI values.
+
+Generators: `rails generate feather_ai:install [model_name]` scaffolds the identification-columns migration; `rails generate feather_ai:add_corrections [model_name]` adds the correction columns. Templates live in `lib/generators/feather_ai/templates/`.
 
 ## Code Style
 
@@ -81,7 +97,8 @@ Location can be set globally or per-call via `location:` keyword. It's injected
 
 ## Testing
 
-- Tests use VCR + WebMock to record/replay real LLM responses — no API keys needed in CI
-- Sample bird images (WA birds) live in `spec/support/fixtures/`
+- Specs stub RubyLLM directly with `instance_double`s (e.g. `allow(RubyLLM).to receive(:chat)`) — no API keys needed. VCR + WebMock are configured in `spec_helper.rb` but mainly serve to block real HTTP; there are no recorded cassettes.
+- `spec/support/helpers.rb` provides `build_result(overrides)` for constructing `FeatherAi::Result` test objects.
+- `FeatherAi.reset!` runs before every example, so config is always at defaults unless the spec configures it.
 - SimpleCov for coverage reporting
 - Dev test dependencies go in the `Gemfile`, not the gemspec

data/README.md

@@ -22,17 +22,17 @@ gem install feather-ai
 
 ```ruby
 FeatherAi.configure do |c|
-  c.provider         = :anthropic           # Default: :anthropic
+  c.provider         = :anthropic           # Deprecated no-op; RubyLLM 2 resolves the provider from the model
   c.model            = "claude-sonnet-4-5"  # Default: "claude-sonnet-4-5"
   c.location         = "Perth, WA"          # Optional: biases results to local species
   c.consensus_models = ["claude-sonnet-4-5", "claude-haiku-4-5"]  # Models used in consensus mode
   c.tips_model       = "claude-haiku-4-5"   # Model for photography tips (default)
-  c.media_resolution = :high                # Image resolution sent to provider (default)
+  c.media_resolution = :high                # Gemini only (generationConfig.mediaResolution); ignored elsewhere
   c.tools            = []                   # RubyLLM tools available to every identification (default: none)
 end
 ```
 
-RubyLLM must be configured with your provider credentials before using FeatherAi. See the [RubyLLM docs](https://github.com/coelacanth/ruby_llm) for setup.
+Requires RubyLLM 2.x. RubyLLM must be configured with your provider credentials before using FeatherAi. See the [RubyLLM docs](https://rubyllm.com) for setup.
 
 ## Usage
 
@@ -100,7 +100,7 @@ Pass RubyLLM tools so the model can verify its identification against real data
 ```ruby
 class SpeciesLookupTool < RubyLLM::Tool
   description "Looks up whether a species occurs in a region"
-  param :species, desc: "Scientific species name"
+  parameter :species, description: "Scientific species name"
 
   def execute(species:)
     Species.find_by(scientific_name: species)&.slice(:regions, :description) || { found: false }
@@ -114,7 +114,7 @@ Tools can also be set globally via `c.tools` in configuration. Note: Gemini reje
 
 ### Consensus Mode
 
-Run identification through two models independently. When both agree on species, you get high confidence. When they disagree, you get the candidates:
+Run identification through two models independently. When both agree on species, you get high confidence. When they disagree, the top-vote candidate (ties break in `consensus_models` order) is still returned as the primary identification with `:low` confidence, and `candidates` carries the full ranked list:
 
 ```ruby
 result = FeatherAi.identify("path/to/bird.jpg", consensus: true)
@@ -122,7 +122,7 @@ result = FeatherAi.identify("path/to/bird.jpg", consensus: true)
 if result.confident?
   puts "Both models agree: #{result.species}"
 else
-  puts "Models disagree:"
+  puts "Models disagree — best guess: #{result.species}"
   result.candidates.each { |c| puts "  #{c[:common_name]} (#{c[:species]}) — #{c[:score]}" }
 end
 ```
@@ -172,7 +172,7 @@ Every result also carries observability data from the LLM call:
 | `model_id` | String | Model that produced the identification |
 | `input_tokens` | Integer | Tokens sent to the model |
 | `output_tokens` | Integer | Tokens received from the model |
-| `cost` | Float | Estimated USD cost (based on built-in rate tables, or `nil`) |
+| `cost` | Float | USD cost from RubyLLM's model pricing registry, or `nil` when unknown |
 | `duration_ms` | Integer | Wall-clock time of the LLM call in milliseconds |
 | `source` | Symbol | `:vision`, `:audio`, or `:multimodal` |
 | `consensus_models` | Array | Models used when consensus mode was enabled |
@@ -303,8 +303,7 @@ after { FeatherAi.reset! }
 ```ruby
 # In an initialiser or boot file — before any threads are created
 FeatherAi.configure do |c|
-  c.provider = :anthropic
-  c.model    = "claude-sonnet-4"
+  c.model = "claude-sonnet-4-5"
 end
 ```
 

data/lib/feather_ai/configuration.rb

@@ -3,6 +3,8 @@
 module FeatherAi
   # Configuration object for FeatherAi gem settings.
   class Configuration
+    # provider: kept for backwards compatibility; RubyLLM 2 resolves the provider from the model.
+    # media_resolution: Gemini-only (generationConfig.mediaResolution); ignored for other providers.
     attr_accessor :provider, :model, :location, :consensus_models, :tips_model, :media_resolution, :tools
 
     def initialize

data/lib/feather_ai/consensus.rb

@@ -2,7 +2,7 @@
 
 module FeatherAi
   # Multi-model consensus identification to improve accuracy.
-  # rubocop:disable Metrics/ClassLength
+  # rubocop:disable-next Metrics/ClassLength
   class Consensus
     def initialize(config: FeatherAi.configuration)
       @config = config
@@ -74,24 +74,29 @@ module FeatherAi
       }
     end
 
+    # On disagreement the top-ranked candidate is promoted to the primary
+    # identification (still :low confidence) so consumers always get a usable
+    # name — the full ranked list stays in candidates.
     def disagreed_result_attrs(results)
+      candidates = ranked_candidates(results)
       {
-        common_name: nil,
-        species: nil,
+        common_name: candidates.first[:common_name],
+        species: candidates.first[:species],
         family: calculate_agreed_family(results),
         confidence: :low,
         region_native: false,
         model_id: nil,
-        candidates: ranked_candidates(results)
+        candidates: candidates
       }
     end
 
-    # Rank disagreeing identifications by vote share across the consensus models.
+    # Rank disagreeing identifications by vote share across the consensus
+    # models. Ties break by consensus_models order (sort_by isn't stable).
     def ranked_candidates(results)
       results.group_by { |r| r.species&.strip&.downcase }
              .values
              .map { |group| vote_candidate(group, results.size) }
-             .sort_by { |candidate| -candidate[:score] }
+             .sort_by.with_index { |candidate, index| [-candidate[:score], index] }
     end
 
     def vote_candidate(group, total)
@@ -133,5 +138,4 @@ module FeatherAi
       dup_config
     end
   end
-  # rubocop:enable Metrics/ClassLength
 end

data/lib/feather_ai/identifier.rb

@@ -2,9 +2,9 @@
 
 module FeatherAi
   # Core bird identification using LLM vision and audio transcription.
-  # rubocop:disable Metrics/ClassLength
+  # rubocop:disable-next Metrics/ClassLength
   class Identifier
-    SCHEMA = RubyLLM::Schema.create do
+    SCHEMA = Schematist::Schema.create do
       string :reasoning,
              description: "Step-by-step visual analysis: describe body size, bill shape, " \
                           "plumage, markings, and rule out similar species before identifying"
@@ -24,12 +24,6 @@ module FeatherAi
       end
     end
 
-    # Approximate mid-2025 rates (USD per 1M tokens).
-    # Use your provider's dashboard for billing accuracy — these are estimates.
-    PROVIDER_RATES = {
-      anthropic: { input: 3.00, output: 15.00 }
-    }.freeze
-
     def initialize(config: FeatherAi.configuration)
       @config = config
     end
@@ -99,21 +93,20 @@ module FeatherAi
       chat.with_instructions(system_prompt(location, tools))
       chat.with_schema(SCHEMA)
       chat.with_tools(*tools) if tools.any?
-      chat.with_params(**generation_params) if generation_params.any?
+      apply_media_resolution(chat)
       chat
     end
 
-    def generation_params
-      params = {}
-      if @config.media_resolution
-        resolution = "MEDIA_RESOLUTION_#{@config.media_resolution.to_s.upcase}"
-        params[:generationConfig] = { mediaResolution: resolution }
-      end
-      params
+    # generationConfig.mediaResolution is a Gemini request field; other providers reject unknown keys.
+    def apply_media_resolution(chat)
+      return unless @config.media_resolution && chat.provider.slug == "gemini"
+
+      resolution = "MEDIA_RESOLUTION_#{@config.media_resolution.to_s.upcase}"
+      chat.with_provider_options(generationConfig: { mediaResolution: resolution })
     end
 
     def build_result(response, duration_ms, source)
-      parsed = response.content
+      parsed = response.parsed
       Result.new(
         **parsed_identification_attrs(parsed),
         **response_observability_attrs(response, duration_ms, source)
@@ -145,10 +138,10 @@ module FeatherAi
 
     def response_observability_attrs(response, duration_ms, source)
       {
-        model_id: response.model_id,
-        input_tokens: response.input_tokens,
-        output_tokens: response.output_tokens,
-        cost: compute_cost(response.input_tokens, response.output_tokens),
+        model_id: response.model,
+        input_tokens: response.tokens.input,
+        output_tokens: response.tokens.output,
+        cost: response.cost.total,
         duration_ms: duration_ms,
         source: source
       }
@@ -174,17 +167,6 @@ module FeatherAi
       end
     end
 
-    # Returns a USD cost estimate based on token counts, or nil when the count
-    # is unavailable or the configured provider has no rate table defined here.
-    def compute_cost(input_tokens, output_tokens)
-      return nil if input_tokens.nil? || output_tokens.nil?
-
-      rates = PROVIDER_RATES[@config.provider]
-      return nil if rates.nil?
-
-      ((input_tokens * rates[:input]) + (output_tokens * rates[:output])) / 1_000_000.0
-    end
-
     def system_prompt(location, tools = [])
       prompt = base_system_prompt
       if location
@@ -214,7 +196,7 @@ module FeatherAi
     def build_text_prompt(images, audio)
       parts = []
       if audio
-        transcript = RubyLLM.transcribe(audio)
+        transcript = RubyLLM.transcribe(audio).text
         parts << "Bird call/song transcript: #{transcript}"
       end
       parts << identification_prompt(images.size, has_audio: !audio.nil?)
@@ -231,5 +213,4 @@ module FeatherAi
       end
     end
   end
-  # rubocop:enable Metrics/ClassLength
 end

data/lib/feather_ai/photography_tips.rb

@@ -3,7 +3,7 @@
 module FeatherAi
   # Generates photography tips for identified bird species.
   class PhotographyTips
-    SCHEMA = RubyLLM::Schema.create do
+    SCHEMA = Schematist::Schema.create do
       string :time_of_day, description: "Best time of day to photograph this species"
       string :approach, description: "How to approach without disturbing the bird"
       string :settings, description: "Recommended camera settings (shutter speed, aperture, ISO)"
@@ -32,7 +32,7 @@ module FeatherAi
     def fetch_from_llm
       chat = RubyLLM.chat(model: @config.tips_model)
       chat.with_schema(SCHEMA)
-      chat.ask(prompt).content
+      chat.ask(prompt).parsed
     end
 
     def build_tips_hash(parsed)

data/lib/feather_ai/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FeatherAi
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/feather_ai.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "ruby_llm"
-require "ruby_llm/schema"
 
 require_relative "feather_ai/version"
 require_relative "feather_ai/configuration"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: feather-ai
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Brandyn Britton
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
 description: A Ruby gem for identifying birds from photos and audio using RubyLLM.
   Adds multi-modal identification, location-aware results, multi-model consensus,
   and a Rails integration.