feather-ai 0.2.0

data/lib/feather_ai/consensus.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module FeatherAi
+  # Multi-model consensus identification to improve accuracy.
+  class Consensus
+    def initialize(config: FeatherAi.configuration)
+      @config = config
+      @models = config.consensus_models
+    end
+
+    def identify(image = nil, audio = nil, location: nil)
+      payload = { models: @models, location: location || @config.location }
+
+      Instrumentation.instrument("consensus.feather_ai", payload) do
+        results = fetch_results_from_models(image, audio, location)
+        shared_attrs = aggregate_metrics(results)
+        result = build_consensus_result(results, shared_attrs)
+
+        payload[:agreed] = result.confident?
+        payload[:result] = result
+        result
+      end
+    end
+
+    private
+
+    def fetch_results_from_models(image, audio, location)
+      @models.map do |model|
+        config_for_model = config_with_model(model)
+        Thread.new { Identifier.new(config: config_for_model).identify(image, audio, location: location) }
+      end.map(&:value)
+    end
+
+    def aggregate_metrics(results)
+      {
+        consensus_models: @models,
+        input_tokens: sum_field(results, :input_tokens),
+        output_tokens: sum_field(results, :output_tokens),
+        duration_ms: sum_field(results, :duration_ms),
+        cost: sum_field(results, :cost),
+        source: results.first&.source
+      }
+    end
+
+    def build_consensus_result(results, shared_attrs)
+      if agree?(results)
+        build_agreed_result(results.first, shared_attrs)
+      else
+        build_disagreed_result(results, shared_attrs)
+      end
+    end
+
+    def build_agreed_result(primary, shared_attrs)
+      Result.new(**shared_attrs, **agreed_result_attrs(primary))
+    end
+
+    def build_disagreed_result(results, shared_attrs)
+      Result.new(**shared_attrs, **disagreed_result_attrs(results))
+    end
+
+    def agreed_result_attrs(primary)
+      {
+        common_name: primary.common_name,
+        species: primary.species,
+        family: primary.family,
+        confidence: :high,
+        region_native: primary.region_native?,
+        model_id: primary.model_id,
+        photography_tips_loader: tips_loader_for(primary)
+      }
+    end
+
+    def disagreed_result_attrs(results)
+      {
+        common_name: nil,
+        species: nil,
+        family: calculate_agreed_family(results),
+        confidence: :low,
+        region_native: false,
+        model_id: nil,
+        candidates: results
+      }
+    end
+
+    def tips_loader_for(primary)
+      config = @config
+      lambda {
+        PhotographyTips.new(
+          species: primary.species,
+          common_name: primary.common_name,
+          config: config
+        ).fetch
+      }
+    end
+
+    def calculate_agreed_family(results)
+      results.map(&:family).uniq.length == 1 ? results.first.family : nil
+    end
+
+    def sum_field(results, field)
+      values = results.map(&field)
+      values.any?(&:nil?) ? nil : values.sum
+    end
+
+    def agree?(results)
+      results.map { |r| r.species&.strip&.downcase }.uniq.length == 1
+    end
+
+    def config_with_model(model)
+      dup_config = @config.dup
+      dup_config.model = model
+      dup_config
+    end
+  end
+end

data/lib/feather_ai/identifier.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module FeatherAi
+  # Core bird identification using LLM vision and audio transcription.
+  # rubocop:disable Metrics/ClassLength
+  class Identifier
+    SCHEMA = RubyLLM::Schema.create do
+      string :common_name, description: "Common name of the bird"
+      string :species, description: "Scientific species name (Genus species)"
+      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"
+    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
+
+    def identify(image = nil, audio = nil, location: nil)
+      validate_inputs!(image, audio)
+
+      effective_location = location || @config.location
+      source = derive_source(image, audio)
+      payload = instrumentation_payload(effective_location, image, audio)
+
+      Instrumentation.instrument("identify.feather_ai", payload) do
+        response, duration_ms = perform_identification(image, audio, effective_location)
+        result = build_result(response, duration_ms, source)
+        payload[:result] = result
+        result
+      end
+    end
+
+    private
+
+    def validate_inputs!(image, audio)
+      return unless image.nil? && audio.nil?
+
+      raise FeatherAi::ConfigurationError, "At least one of image or audio must be provided"
+    end
+
+    def instrumentation_payload(location, image, audio)
+      {
+        model: @config.model,
+        location: location,
+        has_image: !image.nil?,
+        has_audio: !audio.nil?
+      }
+    end
+
+    def perform_identification(image, audio, location)
+      chat = configure_chat(location)
+      message = build_message(image, audio)
+
+      start_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+      response = chat.ask(message)
+      duration_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - start_ms
+
+      [response, duration_ms]
+    end
+
+    def configure_chat(location)
+      chat = RubyLLM.chat(model: @config.model)
+      chat.with_instructions(system_prompt(location))
+      chat.with_schema(SCHEMA)
+      chat
+    end
+
+    def build_result(response, duration_ms, source)
+      parsed = response.content
+      Result.new(
+        **parsed_identification_attrs(parsed),
+        **response_observability_attrs(response, duration_ms, source)
+      )
+    end
+
+    def parsed_identification_attrs(parsed)
+      {
+        common_name: parsed["common_name"],
+        species: parsed["species"],
+        family: parsed["family"],
+        confidence: parsed["confidence"],
+        region_native: parsed["region_native"],
+        photography_tips_loader: tips_loader(parsed)
+      }
+    end
+
+    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),
+        duration_ms: duration_ms,
+        source: source
+      }
+    end
+
+    def tips_loader(parsed)
+      lambda {
+        PhotographyTips.new(
+          species: parsed["species"],
+          common_name: parsed["common_name"],
+          config: @config
+        ).fetch
+      }
+    end
+
+    def derive_source(image, audio)
+      if image && audio
+        :multimodal
+      elsif image
+        :vision
+      else
+        :audio
+      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)
+      base = "You are an expert ornithologist. Identify the bird from the provided image and/or audio. " \
+             "Return structured identification data."
+      return base unless location
+
+      "#{base} The observer is located in #{location} — prioritize species native to that region."
+    end
+
+    def build_message(image, audio)
+      parts = []
+
+      parts << { type: :image, content: image } if image
+
+      if audio
+        transcript = RubyLLM.transcribe(audio)
+        parts << { type: :text, content: "Bird call/song transcript: #{transcript}" }
+      end
+
+      parts << { type: :text, content: "Identify the bird shown and/or heard above." }
+
+      parts
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/feather_ai/instrumentation.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module FeatherAi
+  # Instrumentation hooks for ActiveSupport::Notifications.
+  module Instrumentation
+    def self.instrument(event_name, payload = {}, &)
+      if defined?(ActiveSupport::Notifications)
+        ActiveSupport::Notifications.instrument(event_name, payload, &)
+      else
+        yield
+      end
+    end
+  end
+end

data/lib/feather_ai/photography_tips.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module FeatherAi
+  # Generates photography tips for identified bird species.
+  class PhotographyTips
+    SCHEMA = RubyLLM::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)"
+      string :habitat, description: "Where to find this species for photography"
+    end
+
+    def initialize(species:, common_name:, config: FeatherAi.configuration)
+      @species = species
+      @common_name = common_name
+      @config = config
+    end
+
+    def fetch
+      Instrumentation.instrument("photography_tips.feather_ai", instrumentation_payload) do
+        parsed = fetch_from_llm
+        build_tips_hash(parsed)
+      end
+    end
+
+    private
+
+    def instrumentation_payload
+      { species: @species, common_name: @common_name }
+    end
+
+    def fetch_from_llm
+      chat = RubyLLM.chat(model: @config.tips_model)
+      chat.with_schema(SCHEMA)
+      chat.ask(prompt).content
+    end
+
+    def build_tips_hash(parsed)
+      {
+        time_of_day: parsed["time_of_day"],
+        approach: parsed["approach"],
+        settings: parsed["settings"],
+        habitat: parsed["habitat"]
+      }
+    end
+
+    def prompt
+      "Provide concise bird photography tips for #{@common_name} (#{@species}). " \
+        "Include best time of day, how to approach, recommended camera settings, and ideal habitat for photography."
+    end
+  end
+end

data/lib/feather_ai/rails/acts_as_sighting.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module FeatherAi
+  module Rails
+    module ActsAsSighting
+      CORRECTABLE_FIELDS = %i[common_name species family confidence region_native].freeze
+
+      # Class methods for ActiveRecord models.
+      module ClassMethods
+        def acts_as_sighting
+          include InstanceMethods
+        end
+      end
+
+      # Instance methods for bird sighting records.
+      module InstanceMethods
+        def identify!
+          photo_file = photo.download
+          result = FeatherAi.identify(photo_file, location: location)
+          update_from_result!(result)
+          result
+        ensure
+          close_photo_file(photo_file)
+        end
+
+        def correct!(attrs)
+          return if attrs.empty?
+
+          validate_correctable_fields!(attrs.keys)
+          update!(prefix_and_timestamp_attrs(attrs))
+        end
+
+        private
+
+        def update_from_result!(result)
+          update!(
+            common_name: result.common_name,
+            species: result.species,
+            family: result.family,
+            confidence: result.confidence.to_s,
+            region_native: result.region_native?
+          )
+        end
+
+        def close_photo_file(photo_file)
+          photo_file&.close! if photo_file.respond_to?(:close!)
+        end
+
+        def validate_correctable_fields!(keys)
+          invalid_keys = keys.map(&:to_sym) - CORRECTABLE_FIELDS
+          return if invalid_keys.empty?
+
+          raise ArgumentError,
+                "Unknown correctable field(s): #{invalid_keys.join(", ")}. " \
+                "Allowed fields: #{CORRECTABLE_FIELDS.join(", ")}"
+        end
+
+        def prefix_and_timestamp_attrs(attrs)
+          corrected_attrs = attrs.each_with_object({}) do |(field, value), hash|
+            hash[:"corrected_#{field}"] = value
+          end
+          corrected_attrs.merge(corrected_at: Time.current)
+        end
+
+        public
+
+        def corrected?
+          !corrected_at.nil?
+        end
+
+        def correction_delta
+          return {} unless corrected?
+
+          CORRECTABLE_FIELDS.each_with_object({}) do |field, delta|
+            corrected_value = public_send(:"corrected_#{field}")
+            next if corrected_value.nil?
+
+            # NOTE: `public_send(field)` reads the original AI column, not the
+            # corrected column, so :from always reflects the AI identification
+            # regardless of how many times correct! has been called.
+            delta[field] = { from: public_send(field), to: corrected_value }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/feather_ai/rails/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module FeatherAi
+  module Rails
+    # Rails integration via Railtie.
+    class Railtie < ::Rails::Railtie
+      initializer "feather_ai.acts_as_sighting" do
+        ActiveSupport.on_load(:active_record) do
+          extend FeatherAi::Rails::ActsAsSighting::ClassMethods
+        end
+      end
+    end
+  end
+end

data/lib/feather_ai/rails.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "rails/acts_as_sighting"
+require_relative "rails/railtie"

data/lib/feather_ai/result.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module FeatherAi
+  # Immutable value object wrapping all identification output.
+  class Result
+    attr_reader :common_name, :species, :family, :confidence, :region_native, :candidates,
+                :input_tokens, :output_tokens, :cost, :model_id, :duration_ms, :source,
+                :consensus_models
+
+    def initialize(attrs = {})
+      assign_identification_attrs(attrs)
+      assign_photography_attrs(attrs)
+      assign_observability_attrs(attrs)
+    end
+
+    def confident?
+      @confidence == :high
+    end
+
+    def region_native?
+      @region_native == true
+    end
+
+    def photography_tips
+      return @photography_tips_data if defined?(@photography_tips_loaded)
+
+      @photography_tips_loaded = true
+      @photography_tips_data = @photography_tips_loader&.call
+    end
+
+    def to_h
+      identification_hash
+        .merge(observability_hash)
+        .merge(photography_hash)
+    end
+
+    private
+
+    def assign_identification_attrs(attrs)
+      @common_name = attrs[:common_name]
+      @species = attrs[:species]
+      @family = attrs[:family]
+      @confidence = attrs[:confidence]&.to_sym
+      @region_native = attrs[:region_native]
+      @candidates = attrs[:candidates] || []
+    end
+
+    def assign_photography_attrs(attrs)
+      @photography_tips_loader = attrs[:photography_tips_loader]
+      @photography_tips_data = attrs[:photography_tips]
+      @photography_tips_loaded = true if attrs.key?(:photography_tips)
+    end
+
+    def assign_observability_attrs(attrs)
+      @input_tokens = attrs[:input_tokens]
+      @output_tokens = attrs[:output_tokens]
+      @cost = attrs[:cost]
+      @model_id = attrs[:model_id]
+      @duration_ms = attrs[:duration_ms]
+      @source = attrs[:source]
+      @consensus_models = attrs[:consensus_models]
+    end
+
+    def identification_hash
+      {
+        common_name: @common_name,
+        species: @species,
+        family: @family,
+        confidence: @confidence,
+        confident: confident?,
+        region_native: region_native?,
+        candidates: @candidates
+      }
+    end
+
+    def observability_hash
+      {
+        model_id: @model_id,
+        input_tokens: @input_tokens,
+        output_tokens: @output_tokens,
+        cost: @cost,
+        duration_ms: @duration_ms,
+        source: @source,
+        consensus_models: @consensus_models
+      }
+    end
+
+    def photography_hash
+      { photography_tips: photography_tips }
+    end
+  end
+end

data/lib/feather_ai/version.rb

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

data/lib/feather_ai.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "ruby_llm/schema"
+
+require_relative "feather_ai/version"
+require_relative "feather_ai/configuration"
+require_relative "feather_ai/instrumentation"
+require_relative "feather_ai/result"
+require_relative "feather_ai/photography_tips"
+require_relative "feather_ai/identifier"
+require_relative "feather_ai/consensus"
+
+# Top-level module for bird identification using LLMs.
+module FeatherAi
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class IdentificationError < Error; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset!
+      @configuration = nil
+    end
+
+    def identify(image = nil, audio = nil, location: nil, consensus: false)
+      if consensus
+        Consensus.new.identify(image, audio, location: location)
+      else
+        Identifier.new.identify(image, audio, location: location)
+      end
+    end
+  end
+end

data/lib/generators/feather_ai/add_corrections_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module FeatherAi
+  module Generators
+    # Rails generator for adding user correction fields.
+    class AddCorrectionsGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a migration to add user correction fields to your sighting model"
+
+      argument :model_name, type: :string, default: "sighting",
+                            desc: "Name of the model to add correction fields to"
+
+      def self.next_migration_number(path)
+        next_migration_number = current_migration_number(path) + 1
+        ::ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def create_migration
+        migration_template(
+          "correction_migration.rb.tt",
+          "db/migrate/add_feather_ai_correction_fields_to_#{model_name.underscore.pluralize}.rb"
+        )
+      end
+    end
+  end
+end

data/lib/generators/feather_ai/install_generator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module FeatherAi
+  module Generators
+    # Rails generator for installing FeatherAi bird identification fields.
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a migration to add bird identification fields to your sighting model"
+
+      argument :model_name, type: :string, default: "sighting",
+                            desc: "Name of the model to add sighting fields to"
+
+      def self.next_migration_number(path)
+        next_migration_number = current_migration_number(path) + 1
+        ::ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def create_migration
+        migration_template(
+          "migration.rb.tt",
+          "db/migrate/add_feather_ai_fields_to_#{model_name.underscore.pluralize}.rb"
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+class AddFeatherAiCorrectionFieldsTo<%= model_name.camelize.pluralize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :<%= model_name.underscore.pluralize %>, :corrected_common_name, :string
+    add_column :<%= model_name.underscore.pluralize %>, :corrected_species, :string
+    add_column :<%= model_name.underscore.pluralize %>, :corrected_family, :string
+    add_column :<%= model_name.underscore.pluralize %>, :corrected_confidence, :string
+    add_column :<%= model_name.underscore.pluralize %>, :corrected_region_native, :boolean
+    add_column :<%= model_name.underscore.pluralize %>, :corrected_at, :datetime
+  end
+end

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

@@ -0,0 +1,9 @@
+class AddFeatherAiFieldsTo<%= model_name.camelize.pluralize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :<%= model_name.underscore.pluralize %>, :common_name, :string
+    add_column :<%= model_name.underscore.pluralize %>, :species, :string
+    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
+  end
+end