feather-ai 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f2195b84828584d6764f60823b99fbbbe9961c1c0ebee3d26679b6450a0dd53
-  data.tar.gz: '008c505376ab82635e2a8fdae0475a3adab609c5b9bef588f6a48573c238036c'
+  metadata.gz: a0fe728ff2f69d47cd1c9d89a9d8a4752dce0ea05ada463168fcca4496496981
+  data.tar.gz: 36931f778f677cd40e01472a282a1fb44370ea587bee3faef8a76ea543a3c59e
 SHA512:
-  metadata.gz: be14496f9c58080371192aa146f521178f563433e9bb28e4ecd720c3f802e4264e3a5efef7281813e6a1f18d2e03998eb69e4279dee5c156052879cb2510ed2b
-  data.tar.gz: 14f4968e7363d889e2d0590b675141ec4868385cd58138fbb4de4910acabe61385a14b079136ec0c10d93ba709b2a656de76e2e39bc50016b9faa98672134627
+  metadata.gz: 3db402c6f71e32084333e0730e2850941f439ce92e54c142b3228c1eb25f024ab64eaf69251412038b3a5c8598598f771a717eb45ccc75b570717e46927c218d
+  data.tar.gz: 18c4afdb60659f9e7b1604062e68ed967d6b65df7db96ac4309f8dc3ff0d2be783a6e53d292f2a2188841eee783a1a7a263137deaa648de58e96c06c93ac853c

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 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.
+- New `tools:` keyword on `FeatherAi.identify` (and `FeatherAi.configure { |c| c.tools = [...] }`) forwards RubyLLM tools to the chat, so identification can ground itself in real data (e.g. a species/region lookup backed by your app's database).
+- **Breaking:** consensus disagreement `candidates` changed from an array of `Result` objects to the same ranked-hash shape, scored by vote share.
+- `acts_as_sighting`'s `identify!` persists `candidates` when the table has a `candidates` column (new migrations add it as `jsonb`); existing tables without the column are unaffected.
+- Default models bumped to `claude-sonnet-4-5` / `claude-haiku-4-5` (Anthropic structured outputs require Sonnet 4.5+; the old `claude-haiku-4` id no longer resolves).
+
+Note: on Gemini models, combining a response schema with tools is rejected by the API on many models — the `tools:` option is tested against the Anthropic defaults.

data/README.md

@@ -22,10 +22,13 @@ gem install feather-ai
 
 ```ruby
 FeatherAi.configure do |c|
-  c.provider  = :anthropic           # Default: :anthropic
-  c.model     = "claude-sonnet-4"    # Default: "claude-sonnet-4"
-  c.location  = "Perth, WA"          # Optional: biases results to local species
-  c.consensus_models = ["claude-sonnet-4", "claude-haiku-4"]  # Models used in consensus mode
+  c.provider         = :anthropic           # Default: :anthropic
+  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.tools            = []                   # RubyLLM tools available to every identification (default: none)
 end
 ```
 
@@ -54,6 +57,12 @@ Identify from audio:
 result = FeatherAi.identify(nil, "path/to/bird_call.mp3")
 ```
 
+Identify from multiple images at once:
+
+```ruby
+result = FeatherAi.identify(["front.jpg", "side.jpg"])
+```
+
 Identify from both image and audio:
 
 ```ruby
@@ -72,6 +81,37 @@ result.region_native? # => true/false based on species range
 
 A default location can also be set globally in configuration.
 
+### Ranked Candidates
+
+Every identification returns up to three candidate species ranked by likelihood, with the top pick first:
+
+```ruby
+result = FeatherAi.identify("path/to/bird.jpg")
+
+result.candidates
+# => [{ common_name: "Splendid Fairywren", species: "Malurus splendens", score: 0.9 },
+#     { common_name: "Superb Fairywren",   species: "Malurus cyaneus",   score: 0.1 }]
+```
+
+### Grounded Identification (Tools)
+
+Pass RubyLLM tools so the model can verify its identification against real data — for example a species/region lookup backed by your own database:
+
+```ruby
+class SpeciesLookupTool < RubyLLM::Tool
+  description "Looks up whether a species occurs in a region"
+  param :species, desc: "Scientific species name"
+
+  def execute(species:)
+    Species.find_by(scientific_name: species)&.slice(:regions, :description) || { found: false }
+  end
+end
+
+result = FeatherAi.identify("path/to/bird.jpg", location: "Perth, WA", tools: [SpeciesLookupTool])
+```
+
+Tools can also be set globally via `c.tools` in configuration. Note: Gemini rejects structured-output schemas combined with tools on many models — the `tools:` option is tested against the Anthropic defaults.
+
 ### Consensus Mode
 
 Run identification through two models independently. When both agree on species, you get high confidence. When they disagree, you get the candidates:
@@ -83,7 +123,7 @@ if result.confident?
   puts "Both models agree: #{result.species}"
 else
   puts "Models disagree:"
-  result.candidates.each { |c| puts "  #{c.common_name} (#{c.species})" }
+  result.candidates.each { |c| puts "  #{c[:common_name]} (#{c[:species]}) — #{c[:score]}" }
 end
 ```
 
@@ -91,7 +131,7 @@ Consensus models are configurable:
 
 ```ruby
 FeatherAi.configure do |c|
-  c.consensus_models = ["claude-sonnet-4", "claude-haiku-4"]
+  c.consensus_models = ["claude-sonnet-4-5", "claude-haiku-4-5"]
 end
 ```
 
@@ -120,10 +160,23 @@ All identification calls return a `FeatherAi::Result`:
 | `confidence` | Symbol | `:high`, `:medium`, or `:low` |
 | `confident?` | Boolean | `true` when confidence is `:high` |
 | `region_native?` | Boolean | Whether species is native to the given region |
-| `candidates` | Array | Alternative results when consensus disagrees |
+| `candidates` | Array | Ranked candidate hashes (`common_name`, `species`, `score`); vote-share ranked on consensus disagreement |
 | `photography_tips` | Hash | Lazy-loaded shooting advice |
 | `to_h` | Hash | All fields as a plain hash |
 
+Every result also carries observability data from the LLM call:
+
+| Method | Type | Description |
+|---|---|---|
+| `reasoning` | String | Step-by-step visual analysis the model performed |
+| `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`) |
+| `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 |
+
 ## Rails Integration
 
 ### Setup
@@ -153,7 +206,7 @@ class Sighting < ApplicationRecord
 end
 ```
 
-The generator adds these columns to the model's table: `common_name`, `species`, `family`, `confidence`, `region_native`.
+The generator adds these columns to the model's table: `common_name`, `species`, `family`, `confidence`, `region_native`, `candidates` (jsonb). On existing tables, `identify!` persists ranked candidates only when a `candidates` column is present — add one in your own migration or skip it.
 
 ### Identifying Records
 
@@ -170,6 +223,61 @@ sighting.confident?   # => true (delegated through result)
 
 `identify!` downloads the attached photo, calls `FeatherAi.identify`, updates the record's identification columns, and returns the `FeatherAi::Result`.
 
+### Corrections
+
+Users or moderators can correct AI identifications. First, run the corrections generator to add the necessary columns:
+
+```bash
+rails generate feather_ai:add_corrections
+# or with a custom model name:
+rails generate feather_ai:add_corrections observation
+```
+
+Then apply corrections to a record:
+
+```ruby
+sighting.correct!(common_name: "Australian Magpie", species: "Gymnorhina tibicen dorsalis")
+
+sighting.corrected?      # => true
+sighting.corrected_at    # => 2026-03-25 12:00:00 UTC
+
+sighting.correction_delta
+# => { common_name: { from: "Western Magpie", to: "Australian Magpie" },
+#      species:     { from: "Gymnorhina tibicen", to: "Gymnorhina tibicen dorsalis" } }
+```
+
+Correctable fields: `common_name`, `species`, `family`, `confidence`, `region_native`.
+
+## Instrumentation
+
+When `ActiveSupport::Notifications` is available (e.g. in Rails), every identification emits an `identify.feather_ai` event. Without ActiveSupport the instrumentation is a no-op.
+
+```ruby
+ActiveSupport::Notifications.subscribe("identify.feather_ai") do |_name, _start, _finish, _id, payload|
+  Rails.logger.info "Identified #{payload[:result].common_name} " \
+                     "with model=#{payload[:model]} in #{payload[:result].duration_ms}ms"
+end
+```
+
+Payload keys: `model`, `location`, `has_image`, `image_count`, `has_audio`, and `result` (the `FeatherAi::Result`).
+
+## Error Handling
+
+FeatherAi raises specific error classes, all inheriting from `FeatherAi::Error`:
+
+- `FeatherAi::ConfigurationError` — invalid or missing configuration (e.g. no image or audio provided)
+- `FeatherAi::IdentificationError` — failure during the LLM identification call
+
+```ruby
+begin
+  FeatherAi.identify("path/to/bird.jpg")
+rescue FeatherAi::ConfigurationError => e
+  # handle bad config
+rescue FeatherAi::IdentificationError => e
+  # handle LLM failure
+end
+```
+
 ## Development
 
 ```bash
@@ -182,6 +290,12 @@ bin/console         # Interactive console with gem loaded
 
 Tests use VCR + WebMock to record and replay LLM responses — no API keys are required to run the test suite.
 
+Use `FeatherAi.reset!` to clear configuration between test examples:
+
+```ruby
+after { FeatherAi.reset! }
+```
+
 ## Thread Safety
 
 `FeatherAi.configuration` is a process-level singleton initialised lazily with `||=`. Under MRI Ruby, the Global VM Lock (GVL) makes this safe in practice. If you use JRuby or Ractors, initialise configuration eagerly at boot time before spawning threads:

data/lib/feather_ai/configuration.rb

@@ -3,20 +3,22 @@
 module FeatherAi
   # Configuration object for FeatherAi gem settings.
   class Configuration
-    attr_accessor :provider, :model, :location, :consensus_models, :tips_model, :media_resolution
+    attr_accessor :provider, :model, :location, :consensus_models, :tips_model, :media_resolution, :tools
 
     def initialize
       @provider = :anthropic
-      @model = "claude-sonnet-4"
+      @model = "claude-sonnet-4-5"
       @location = nil
-      @consensus_models = %w[claude-sonnet-4 claude-haiku-4]
-      @tips_model = "claude-haiku-4"
+      @consensus_models = %w[claude-sonnet-4-5 claude-haiku-4-5]
+      @tips_model = "claude-haiku-4-5"
       @media_resolution = :high
+      @tools = []
     end
 
     def initialize_copy(source)
       super
       @consensus_models = source.consensus_models.dup
+      @tools = source.tools.dup
     end
   end
 end

data/lib/feather_ai/consensus.rb

@@ -2,17 +2,18 @@
 
 module FeatherAi
   # Multi-model consensus identification to improve accuracy.
+  # rubocop:disable Metrics/ClassLength
   class Consensus
     def initialize(config: FeatherAi.configuration)
       @config = config
       @models = config.consensus_models
     end
 
-    def identify(image = nil, audio = nil, location: nil)
+    def identify(image = nil, audio = nil, location: nil, tools: nil)
       payload = { models: @models, location: location || @config.location }
 
       Instrumentation.instrument("consensus.feather_ai", payload) do
-        results = fetch_results_from_models(image, audio, location)
+        results = fetch_results_from_models(image, audio, location, tools)
         shared_attrs = aggregate_metrics(results)
         result = build_consensus_result(results, shared_attrs)
 
@@ -24,10 +25,12 @@ module FeatherAi
 
     private
 
-    def fetch_results_from_models(image, audio, location)
+    def fetch_results_from_models(image, audio, location, tools)
       @models.map do |model|
         config_for_model = config_with_model(model)
-        Thread.new { Identifier.new(config: config_for_model).identify(image, audio, location: location) }
+        Thread.new do
+          Identifier.new(config: config_for_model).identify(image, audio, location: location, tools: tools)
+        end
       end.map(&:value)
     end
 
@@ -66,6 +69,7 @@ module FeatherAi
         confidence: :high,
         region_native: primary.region_native?,
         model_id: primary.model_id,
+        candidates: primary.candidates,
         photography_tips_loader: tips_loader_for(primary)
       }
     end
@@ -78,7 +82,24 @@ module FeatherAi
         confidence: :low,
         region_native: false,
         model_id: nil,
-        candidates: results
+        candidates: ranked_candidates(results)
+      }
+    end
+
+    # Rank disagreeing identifications by vote share across the consensus models.
+    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] }
+    end
+
+    def vote_candidate(group, total)
+      primary = group.first
+      {
+        common_name: primary.common_name,
+        species: primary.species,
+        score: group.size.to_f / total
       }
     end
 
@@ -112,4 +133,5 @@ module FeatherAi
       dup_config
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/feather_ai/identifier.rb

@@ -13,6 +13,15 @@ module FeatherAi
       string :family, description: "Bird family name"
       string :confidence, description: "Identification confidence: high, medium, or low"
       boolean :region_native, description: "Whether this species is native to the given region"
+      array :candidates, min_items: 1, max_items: 3,
+                         description: "Candidate species ranked most to least likely; " \
+                                      "the first entry must match your identification" do
+        object do
+          string :common_name, description: "Common name of the candidate"
+          string :species, description: "Scientific species name (Genus species)"
+          number :score, minimum: 0, maximum: 1, description: "Relative likelihood of this candidate"
+        end
+      end
     end
 
     # Approximate mid-2025 rates (USD per 1M tokens).
@@ -27,10 +36,11 @@ module FeatherAi
 
     # @param image [String, Array<String>, nil] path(s) to image file(s)
     # @param audio [String, nil] path to audio file
-    def identify(image = nil, audio = nil, location: nil)
+    # @param tools [Array, nil] RubyLLM tools (classes or instances) the model may call for grounding
+    def identify(image = nil, audio = nil, location: nil, tools: nil)
       images = normalize_images(image)
       validate_inputs!(images, audio)
-      run_identification(images, audio, location || @config.location)
+      run_identification(images, audio, location || @config.location, Array(tools || @config.tools))
     end
 
     private
@@ -44,12 +54,12 @@ module FeatherAi
       end
     end
 
-    def run_identification(images, audio, effective_location)
+    def run_identification(images, audio, effective_location, tools)
       source = derive_source(images, audio)
       payload = instrumentation_payload(effective_location, images, audio)
 
       Instrumentation.instrument("identify.feather_ai", payload) do
-        response, duration_ms = perform_identification(images, audio, effective_location)
+        response, duration_ms = perform_identification(images, audio, effective_location, tools)
         result = build_result(response, duration_ms, source)
         payload[:result] = result
         result
@@ -72,8 +82,8 @@ module FeatherAi
       }
     end
 
-    def perform_identification(images, audio, location)
-      chat = configure_chat(location)
+    def perform_identification(images, audio, location, tools)
+      chat = configure_chat(location, tools)
       prompt = build_text_prompt(images, audio)
       attachments = images.any? ? images : nil
 
@@ -84,10 +94,11 @@ module FeatherAi
       [response, duration_ms]
     end
 
-    def configure_chat(location)
+    def configure_chat(location, tools)
       chat = RubyLLM.chat(model: @config.model)
-      chat.with_instructions(system_prompt(location))
+      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?
       chat
     end
@@ -117,10 +128,21 @@ module FeatherAi
         family: parsed["family"],
         confidence: parsed["confidence"],
         region_native: parsed["region_native"],
+        candidates: normalize_candidates(parsed["candidates"]),
         photography_tips_loader: tips_loader(parsed)
       }
     end
 
+    def normalize_candidates(candidates)
+      Array(candidates).map do |candidate|
+        {
+          common_name: candidate["common_name"],
+          species: candidate["species"],
+          score: candidate["score"]
+        }
+      end
+    end
+
     def response_observability_attrs(response, duration_ms, source)
       {
         model_id: response.model_id,
@@ -163,12 +185,17 @@ module FeatherAi
       ((input_tokens * rates[:input]) + (output_tokens * rates[:output])) / 1_000_000.0
     end
 
-    def system_prompt(location)
-      base = base_system_prompt
-      return base unless location
-
-      "#{base} The observer is located in #{location} — " \
-        "prioritise species native to that region and consider regional plumage variations."
+    def system_prompt(location, tools = [])
+      prompt = base_system_prompt
+      if location
+        prompt += " The observer is located in #{location} — " \
+                  "prioritise species native to that region and consider regional plumage variations."
+      end
+      if tools.any?
+        prompt += " Use the provided lookup tools to verify species occurrence " \
+                  "for the observer's region before committing."
+      end
+      prompt
     end
 
     def base_system_prompt

data/lib/feather_ai/rails/acts_as_sighting.rb

@@ -33,13 +33,15 @@ module FeatherAi
         private
 
         def update_from_result!(result)
-          update!(
+          attrs = {
             common_name: result.common_name,
             species: result.species,
             family: result.family,
             confidence: result.confidence.to_s,
             region_native: result.region_native?
-          )
+          }
+          attrs[:candidates] = result.candidates if has_attribute?("candidates")
+          update!(attrs)
         end
 
         def close_photo_file(photo_file)

data/lib/feather_ai/version.rb

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

data/lib/feather_ai.rb

@@ -33,11 +33,12 @@ module FeatherAi
     # Identify a bird from image(s) and/or audio.
     # @param image [String, Array<String>, nil] path(s) to image file(s)
     # @param audio [String, nil] path to audio file
-    def identify(image = nil, audio = nil, location: nil, consensus: false)
+    # @param tools [Array, nil] RubyLLM tools (classes or instances) the model may call for grounding
+    def identify(image = nil, audio = nil, location: nil, consensus: false, tools: nil)
       if consensus
-        Consensus.new.identify(image, audio, location: location)
+        Consensus.new.identify(image, audio, location: location, tools: tools)
       else
-        Identifier.new.identify(image, audio, location: location)
+        Identifier.new.identify(image, audio, location: location, tools: tools)
       end
     end
   end

data/lib/generators/feather_ai/templates/migration.rb.tt

@@ -5,5 +5,6 @@ class AddFeatherAiFieldsTo<%= model_name.camelize.pluralize %> < ActiveRecord::M
     add_column :<%= model_name.underscore.pluralize %>, :family, :string
     add_column :<%= model_name.underscore.pluralize %>, :confidence, :string
     add_column :<%= model_name.underscore.pluralize %>, :region_native, :boolean
+    add_column :<%= model_name.underscore.pluralize %>, :candidates, :jsonb
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: feather-ai
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Brandyn Britton
@@ -40,6 +40,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- CHANGELOG.md
 - CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
@@ -83,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Identify birds from photos and audio using LLMs
 test_files: []