feather-ai 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31f571486891a197ef789e511c429a5433290f5755330eb8c87e9ebd5d2a1f25
+  data.tar.gz: ea99ec7efd75ccab6ce2321cd56bf3e712b0d3a79bef4139b4828eb3e23efa1b
+SHA512:
+  metadata.gz: 83000667059ba7fc6090b49029051675e54f6b56ccf5a99e39f5156cd36387467fb0ef01136d2fac5aba9de1be52941c312c721dcb8db760fe5a8fb125731ce1
+  data.tar.gz: 0b378a24104f4463d487bc7a4523ff479c8e7cda4ef251fe61b88e75ff2936fde4ee9aec77cfb5677e3246a770a987961192199e2284e7f1dedf1e903ed824c2

data/.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml
+# Editor-based HTTP Client requests
+/httpRequests/

data/.idea/Feather.iml

@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="RUBY_MODULE" version="4">
+  <component name="ModuleRunConfigurationManager">
+    <shared />
+  </component>
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/features" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/spec" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/test" isTestSource="true" />
+    </content>
+    <orderEntry type="jdk" jdkName="rbenv: 3.4.8" jdkType="RUBY_SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+    <orderEntry type="library" scope="PROVIDED" name="addressable (v2.8.9, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="ast (v2.4.3, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="base64 (v0.3.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="bigdecimal (v4.0.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="bundler (v2.6.9, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="crack (v1.0.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="date (v3.5.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="diff-lcs (v1.6.2, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="docile (v1.4.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="erb (v6.0.2, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="event_stream_parser (v1.0.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="faraday (v2.14.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="faraday-multipart (v1.2.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="faraday-net_http (v3.4.2, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="faraday-retry (v2.4.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="hashdiff (v1.2.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="io-console (v0.8.2, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="irb (v1.17.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="json (v2.19.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="json-schema (v6.2.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="language_server-protocol (v3.17.0.5, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="lint_roller (v1.1.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="logger (v1.7.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="marcel (v1.1.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="mcp (v0.8.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="multipart-post (v2.4.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="net-http (v0.9.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="parallel (v1.27.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="parser (v3.3.10.2, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="pp (v0.6.3, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="prettyprint (v0.2.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="prism (v1.9.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="psych (v5.3.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="public_suffix (v7.0.5, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="racc (v1.8.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rainbow (v3.1.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rake (v13.3.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rdoc (v7.2.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="regexp_parser (v2.11.3, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="reline (v0.6.3, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rexml (v3.4.4, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec (v3.13.2, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-core (v3.13.6, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-expectations (v3.13.5, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-mocks (v3.13.8, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-support (v3.13.7, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rubocop (v1.85.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rubocop-ast (v1.49.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rubocop-rspec (v3.9.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="ruby-progressbar (v1.13.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="ruby_llm (v1.14.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="ruby_llm-schema (v0.3.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="simplecov (v0.22.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="simplecov-html (v0.13.2, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="simplecov_json_formatter (v0.1.4, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="stringio (v3.2.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="tsort (v0.2.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="unicode-display_width (v3.2.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="unicode-emoji (v4.2.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="uri (v1.1.1, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="vcr (v6.4.0, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="webmock (v3.26.2, rbenv: 3.4.8) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="zeitwerk (v2.7.5, rbenv: 3.4.8) [gem]" level="application" />
+  </component>
+</module>

data/.idea/copilot.data.migration.ask2agent.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Ask2AgentMigrationStateService">
+    <option name="migrationStatus" value="COMPLETED" />
+  </component>
+</project>

data/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/Feather.iml" filepath="$PROJECT_DIR$/.idea/Feather.iml" />
+    </modules>
+  </component>
+</project>

data/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,12 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+
+plugins:
+  - rubocop-rspec
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/.ruby-version

@@ -0,0 +1 @@
+3.4.8

data/CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+FeatherAi is a Ruby gem for identifying birds from photos and audio using RubyLLM. It adds multi-modal identification, location-aware results, multi-model consensus, and a Rails integration on top of RubyLLM.
+
+## Commands
+
+```bash
+# Install dependencies
+bin/setup
+
+# Run all tests
+bundle exec rspec
+
+# Run a single test file
+bundle exec rspec spec/feather_ai/identifier_spec.rb
+
+# Run a single example by line number
+bundle exec rspec spec/feather_ai/identifier_spec.rb:15
+
+# Lint
+bundle exec rubocop
+
+# Lint with auto-fix
+bundle exec rubocop -A
+
+# Run tests + lint (default rake task, same as CI)
+bundle exec rake
+
+# Interactive console with gem loaded
+bin/console
+
+# Build and install locally
+bundle exec rake install
+
+# Release (tags, pushes, publishes to RubyGems)
+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/`.
+
+### Data Flow
+
+`FeatherAi.identify(image, audio, location:, consensus:)` is the top-level entry point defined in `lib/feather_ai.rb`. 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.
+
+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.
+
+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.
+
+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.
+
+### Configuration
+
+```ruby
+FeatherAi.configure do |c|
+  c.provider  = :anthropic
+  c.location  = "Perth, Western Australia"  # biases results to local species
+  c.model     = "claude-sonnet-4"
+end
+```
+
+Location can be set globally or per-call via `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.
+
+## Code Style
+
+- Double quotes for all strings (configured in `.rubocop.yml`)
+- `frozen_string_literal: true` in every Ruby file
+- Target Ruby version: >= 3.2 (gemspec requires it; CI tests 3.2, 3.3, 3.4)
+- RSpec with `expect` syntax only (monkey patching disabled)
+
+## 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/`
+- SimpleCov for coverage reporting
+- Dev test dependencies go in the `Gemfile`, not the gemspec

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Brandyn Britton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,205 @@
+# FeatherAi
+
+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
+
+Add to your Gemfile:
+
+```ruby
+gem "feather-ai"
+```
+
+Or install directly:
+
+```bash
+gem install feather-ai
+```
+
+## Configuration
+
+```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
+end
+```
+
+RubyLLM must be configured with your provider credentials before using FeatherAi. See the [RubyLLM docs](https://github.com/coelacanth/ruby_llm) for setup.
+
+## Usage
+
+### Basic Identification
+
+Identify a bird from an image:
+
+```ruby
+result = FeatherAi.identify("path/to/bird.jpg")
+
+result.common_name   # => "Western Magpie"
+result.species       # => "Gymnorhina tibicen"
+result.family        # => "Artamidae"
+result.confidence    # => :high
+result.confident?    # => true
+result.region_native? # => true
+```
+
+Identify from audio:
+
+```ruby
+result = FeatherAi.identify(nil, "path/to/bird_call.mp3")
+```
+
+Identify from both image and audio:
+
+```ruby
+result = FeatherAi.identify("path/to/bird.jpg", "path/to/bird_call.mp3")
+```
+
+### Location-Aware Results
+
+Pass a location to bias the model toward species native to that region:
+
+```ruby
+result = FeatherAi.identify("path/to/bird.jpg", location: "Perth, Western Australia")
+
+result.region_native? # => true/false based on species range
+```
+
+A default location can also be set globally in configuration.
+
+### Consensus Mode
+
+Run identification through two models independently. When both agree on species, you get high confidence. When they disagree, you get the candidates:
+
+```ruby
+result = FeatherAi.identify("path/to/bird.jpg", consensus: true)
+
+if result.confident?
+  puts "Both models agree: #{result.species}"
+else
+  puts "Models disagree:"
+  result.candidates.each { |c| puts "  #{c.common_name} (#{c.species})" }
+end
+```
+
+Consensus models are configurable:
+
+```ruby
+FeatherAi.configure do |c|
+  c.consensus_models = ["claude-sonnet-4", "claude-haiku-4"]
+end
+```
+
+### Photography Tips
+
+Results expose lazy-loaded photography tips for the identified species. The tips are only fetched (via a fast, cheap model) when you access them:
+
+```ruby
+tips = result.photography_tips
+
+tips[:time_of_day]  # => "Early morning or late afternoon for soft light"
+tips[:approach]     # => "Move slowly and quietly, approach from below sight line"
+tips[:settings]     # => "1/500s or faster, f/2.8-f/4, ISO 400-1600"
+tips[:habitat]      # => "Open woodlands, grasslands, and suburban parks"
+```
+
+### Result Object
+
+All identification calls return a `FeatherAi::Result`:
+
+| Method | Type | Description |
+|---|---|---|
+| `common_name` | String | Common name (e.g. "Western Magpie") |
+| `species` | String | Scientific name (e.g. "Gymnorhina tibicen") |
+| `family` | String | Bird family (e.g. "Artamidae") |
+| `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 |
+| `photography_tips` | Hash | Lazy-loaded shooting advice |
+| `to_h` | Hash | All fields as a plain hash |
+
+## Rails Integration
+
+### Setup
+
+Run the install generator to scaffold the migration:
+
+```bash
+rails generate feather_ai:install
+# or with a custom model name:
+rails generate feather_ai:install observation
+```
+
+Run the migration:
+
+```bash
+rails db:migrate
+```
+
+### Model
+
+Add `acts_as_sighting` to your ActiveRecord model. The model must have a `photo` attribute (ActiveStorage) and a `location` string column:
+
+```ruby
+class Sighting < ApplicationRecord
+  has_one_attached :photo
+  acts_as_sighting
+end
+```
+
+The generator adds these columns to the model's table: `common_name`, `species`, `family`, `confidence`, `region_native`.
+
+### Identifying Records
+
+Call `identify!` on any instance to run identification and persist the results:
+
+```ruby
+sighting = Sighting.create!(photo: params[:photo], location: "Perth, WA")
+result = sighting.identify!
+
+sighting.common_name  # => "Western Magpie"
+sighting.species      # => "Gymnorhina tibicen"
+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`.
+
+## Development
+
+```bash
+bin/setup           # Install dependencies
+bundle exec rspec   # Run tests
+bundle exec rubocop # Lint
+bundle exec rake    # Tests + lint (same as CI)
+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.
+
+## 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:
+
+```ruby
+# In an initialiser or boot file — before any threads are created
+FeatherAi.configure do |c|
+  c.provider = :anthropic
+  c.model    = "claude-sonnet-4"
+end
+```
+
+`FeatherAi.identify` is stateless per-call — each invocation constructs its own `Identifier` or `Consensus` instance and `RubyLLM::Chat` session. Concurrent calls are safe.
+
+`FeatherAi::Consensus` parallelises model calls using Ruby threads (`Thread.new`), so two LLM requests run concurrently and the total wall-clock time is roughly that of the slower model, not the sum of both.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Birdup-Australia/Feather.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/feather_ai/configuration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module FeatherAi
+  # Configuration object for FeatherAi gem settings.
+  class Configuration
+    attr_accessor :provider, :model, :location, :consensus_models, :tips_model
+
+    def initialize
+      @provider = :anthropic
+      @model = "claude-sonnet-4"
+      @location = nil
+      @consensus_models = %w[claude-sonnet-4 claude-haiku-4]
+      @tips_model = "claude-haiku-4"
+    end
+
+    def initialize_copy(source)
+      super
+      @consensus_models = source.consensus_models.dup
+    end
+  end
+end