# Adopter Matcher Phase 3: Species Filter — Implementation Report

Date: 2026-04-20

## Changes Made

### 1. types.ts — Added preferredSpecies to AdopterPreferences interface
- Added `preferredSpecies: string` field (line 92)

### 2. attributeParser.ts — Zod schema + LLM prompt
- Added `preferredSpecies` to `AdopterPreferencesSchema`: `z.enum(['dog', 'cat', 'small', 'any']).nullable().transform(v => v ?? 'any')`
- Added bullet to `ADOPTER_EXTRACTION_PROMPT`:
  `- preferredSpecies: One of "dog", "cat", "small", or "any". Use "small" for rabbit, guinea pig, hamster, gerbil, ferret, chinchilla, rat, mouse, bird, or reptile. Use "any" if the adopter has no species preference. Extract even if buried in phrases like "I'd love a rabbit" or "we want a kitten."`

### 3. Database — ALTER TABLE
- `ALTER TABLE adopter_preferences ADD COLUMN preferred_species TEXT`
- Existing rows get NULL, read as 'any' via `|| 'any'` fallback

### 4. localDatabase.ts — DB read/write
- `saveAdopterPreferences()`: INSERT now includes `preferred_species` (13 columns, 13 params)
- `getAdopterPreferences()`: reads `row.preferred_species` with `|| 'any'` fallback
- `getRecentAdopterPreferences()`: same read pattern

### 5. matchingEngine.ts — Species pre-filter
- Added `SMALL_SPECIES` constant matching Web Matcher's list
- Pre-filter before scoring loop: 'dog'→dogs only, 'cat'→cats only, 'small'→small species only, 'any'/missing→all animals

SMALL_SPECIES list (verbatim from Web Matcher):
['rabbit', 'guinea pig', 'hamster', 'gerbil', 'ferret', 'chinchilla', 'rat', 'mouse', 'bird', 'reptile', 'small']

## Smoke Test Results

| Test | preferredSpecies | Top 5 Species Returned | Pass? |
|---|---|---|---|
| Cat | "cat" | Cat, Cat, Cat, Cat, Cat | ✅ |
| Dog | "dog" | Dog, Dog, Dog, Dog, Dog | ✅ |
| Small | "small" | Rabbit, Rabbit, Rabbit, Rabbit, Rabbit | ✅ |
| Any | "any" | Cat, Dog, Cat, Dog, Cat | ✅ (mixed) |

## Files Modified

- /home/shelter/shelter-apps/server/src/types.ts
- /home/shelter/shelter-apps/server/src/attributeParser.ts
- /home/shelter/shelter-apps/server/src/localDatabase.ts
- /home/shelter/shelter-apps/server/src/matchingEngine.ts
- /home/shelter/shelter-apps/data/shelter.db (ALTER TABLE)

## Not Touched

- staging-staff, staff-pwa (no front-end changes)
- sw.js (no SW bump)
- Caddy config
- Web Matcher (already has its own species filtering)

REPORT COMPLETE