feather-ai 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31f571486891a197ef789e511c429a5433290f5755330eb8c87e9ebd5d2a1f25
-  data.tar.gz: ea99ec7efd75ccab6ce2321cd56bf3e712b0d3a79bef4139b4828eb3e23efa1b
+  metadata.gz: 9f2195b84828584d6764f60823b99fbbbe9961c1c0ebee3d26679b6450a0dd53
+  data.tar.gz: '008c505376ab82635e2a8fdae0475a3adab609c5b9bef588f6a48573c238036c'
 SHA512:
-  metadata.gz: 83000667059ba7fc6090b49029051675e54f6b56ccf5a99e39f5156cd36387467fb0ef01136d2fac5aba9de1be52941c312c721dcb8db760fe5a8fb125731ce1
-  data.tar.gz: 0b378a24104f4463d487bc7a4523ff479c8e7cda4ef251fe61b88e75ff2936fde4ee9aec77cfb5677e3246a770a987961192199e2284e7f1dedf1e903ed824c2
+  metadata.gz: be14496f9c58080371192aa146f521178f563433e9bb28e4ecd720c3f802e4264e3a5efef7281813e6a1f18d2e03998eb69e4279dee5c156052879cb2510ed2b
+  data.tar.gz: 14f4968e7363d889e2d0590b675141ec4868385cd58138fbb4de4910acabe61385a14b079136ec0c10d93ba709b2a656de76e2e39bc50016b9faa98672134627

data/README.md

@@ -1,5 +1,7 @@
 # FeatherAi
 
+[![Gem Version](https://badge.fury.io/rb/feather-ai.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/feather-ai)
+
 A Ruby gem for identifying birds from photos and audio using [RubyLLM](https://github.com/coelacanth/ruby_llm). FeatherAi adds multi-modal identification, location-aware results, multi-model consensus, and a Rails integration on top of RubyLLM.
 
 ## Installation

data/lib/feather_ai/configuration.rb

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

data/lib/feather_ai/identifier.rb

@@ -5,6 +5,9 @@ module FeatherAi
   # rubocop:disable Metrics/ClassLength
   class Identifier
     SCHEMA = RubyLLM::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"
       string :common_name, description: "Common name of the bird"
       string :species, description: "Scientific species name (Genus species)"
       string :family, description: "Bird family name"
@@ -22,44 +25,60 @@ module FeatherAi
       @config = config
     end
 
+    # @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)
-      validate_inputs!(image, audio)
+      images = normalize_images(image)
+      validate_inputs!(images, audio)
+      run_identification(images, audio, location || @config.location)
+    end
+
+    private
+
+    def normalize_images(image)
+      case image
+      when nil    then []
+      when String then [image]
+      when Array  then image
+      else raise ArgumentError, "image must be a String or Array<String>, got #{image.class}"
+      end
+    end
 
-      effective_location = location || @config.location
-      source = derive_source(image, audio)
-      payload = instrumentation_payload(effective_location, image, audio)
+    def run_identification(images, audio, effective_location)
+      source = derive_source(images, audio)
+      payload = instrumentation_payload(effective_location, images, audio)
 
       Instrumentation.instrument("identify.feather_ai", payload) do
-        response, duration_ms = perform_identification(image, audio, effective_location)
+        response, duration_ms = perform_identification(images, 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?
+    def validate_inputs!(images, audio)
+      return unless images.empty? && audio.nil?
 
       raise FeatherAi::ConfigurationError, "At least one of image or audio must be provided"
     end
 
-    def instrumentation_payload(location, image, audio)
+    def instrumentation_payload(location, images, audio)
       {
         model: @config.model,
         location: location,
-        has_image: !image.nil?,
+        has_image: images.any?,
+        image_count: images.size,
         has_audio: !audio.nil?
       }
     end
 
-    def perform_identification(image, audio, location)
+    def perform_identification(images, audio, location)
       chat = configure_chat(location)
-      message = build_message(image, audio)
+      prompt = build_text_prompt(images, audio)
+      attachments = images.any? ? images : nil
 
       start_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
-      response = chat.ask(message)
+      response = chat.ask(prompt, with: attachments)
       duration_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - start_ms
 
       [response, duration_ms]
@@ -69,9 +88,19 @@ module FeatherAi
       chat = RubyLLM.chat(model: @config.model)
       chat.with_instructions(system_prompt(location))
       chat.with_schema(SCHEMA)
+      chat.with_params(**generation_params) if generation_params.any?
       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
+    end
+
     def build_result(response, duration_ms, source)
       parsed = response.content
       Result.new(
@@ -82,6 +111,7 @@ module FeatherAi
 
     def parsed_identification_attrs(parsed)
       {
+        reasoning: parsed["reasoning"],
         common_name: parsed["common_name"],
         species: parsed["species"],
         family: parsed["family"],
@@ -112,10 +142,10 @@ module FeatherAi
       }
     end
 
-    def derive_source(image, audio)
-      if image && audio
+    def derive_source(images, audio)
+      if images.any? && audio
         :multimodal
-      elsif image
+      elsif images.any?
         :vision
       else
         :audio
@@ -134,26 +164,44 @@ module FeatherAi
     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."
+      base = base_system_prompt
       return base unless location
 
-      "#{base} The observer is located in #{location} — prioritize species native to that region."
+      "#{base} The observer is located in #{location} — " \
+        "prioritise species native to that region and consider regional plumage variations."
     end
 
-    def build_message(image, audio)
-      parts = []
-
-      parts << { type: :image, content: image } if image
+    def base_system_prompt
+      <<~PROMPT.gsub(/\s+/, " ").strip
+        You are an expert ornithologist specialising in field identification.
+        Before identifying the bird, carefully analyse key visual features:
+        body size and shape, bill shape and size, plumage colour and pattern,
+        eye colour, leg colour, tail shape, and any distinctive markings.
+        Consider common look-alikes and explain why this is not one of them.
+        Only then commit to your identification with structured data.
+        If the image is unclear or shows multiple species, identify the most
+        prominent bird and set confidence to low or medium accordingly.
+      PROMPT
+    end
 
+    def build_text_prompt(images, audio)
+      parts = []
       if audio
         transcript = RubyLLM.transcribe(audio)
-        parts << { type: :text, content: "Bird call/song transcript: #{transcript}" }
+        parts << "Bird call/song transcript: #{transcript}"
       end
+      parts << identification_prompt(images.size, has_audio: !audio.nil?)
+      parts.join("\n")
+    end
 
-      parts << { type: :text, content: "Identify the bird shown and/or heard above." }
-
-      parts
+    def identification_prompt(image_count, has_audio:)
+      if image_count > 1 && has_audio
+        "Identify the bird shown in the provided images and heard in the audio. Use all inputs together."
+      elsif image_count > 1
+        "Identify the bird shown in the provided images. Use all images together to make your identification."
+      else
+        "Identify the bird shown and/or heard above."
+      end
     end
   end
   # rubocop:enable Metrics/ClassLength

data/lib/feather_ai/result.rb

@@ -3,7 +3,7 @@
 module FeatherAi
   # Immutable value object wrapping all identification output.
   class Result
-    attr_reader :common_name, :species, :family, :confidence, :region_native, :candidates,
+    attr_reader :common_name, :species, :family, :confidence, :region_native, :reasoning, :candidates,
                 :input_tokens, :output_tokens, :cost, :model_id, :duration_ms, :source,
                 :consensus_models
 
@@ -42,6 +42,7 @@ module FeatherAi
       @family = attrs[:family]
       @confidence = attrs[:confidence]&.to_sym
       @region_native = attrs[:region_native]
+      @reasoning = attrs[:reasoning]
       @candidates = attrs[:candidates] || []
     end
 
@@ -63,6 +64,7 @@ module FeatherAi
 
     def identification_hash
       {
+        reasoning: @reasoning,
         common_name: @common_name,
         species: @species,
         family: @family,

data/lib/feather_ai/version.rb

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

data/lib/feather_ai.rb

@@ -30,6 +30,9 @@ module FeatherAi
       @configuration = nil
     end
 
+    # 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)
       if consensus
         Consensus.new.identify(image, audio, location: location)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: feather-ai
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Brandyn Britton
 bindir: exe
 cert_chain: []
-date: 2026-03-18 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -83,7 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.8
 specification_version: 4
 summary: Identify birds from photos and audio using LLMs
 test_files: []