✅ Multi-Platform Search - Aggregates from Petfinder and RescueGroups
✅ Natural Language - Describe your ideal cat in plain English
✅ Semantic Matching - AI understands personality, not just keywords
✅ Color/Breed Matching - 3-tier system handles typos ("tuxado" → "tuxedo", "main coon" → "Maine Coon")
✅ Deduplication - Multi-modal (name + description + image) duplicate detection
✅ Hybrid Search - Combines vector similarity with structured filters
✅ Image Recognition - Uses CLIP to match cats visually
✅ Email Notifications - Get alerts for new matches
✅ Serverless Backend - Optionally deploy to Modal for cloud-based search and alerts

Technical Stack: OpenAI GPT-4 • ChromaDB • CLIP • Gradio • Modal

🏗️ Architecture Modes

Tuxedo Link supports two deployment modes:

Local Mode (Development)

All components run locally
Uses local database and vector store
Fast iteration and development
No Modal required

Production Mode (Cloud)

UI runs locally, backend runs on Modal
Database and vector store on Modal volumes
Scheduled email alerts active
Scalable and serverless

Switch between modes in config.yaml by setting deployment.mode to local or production.

🚀 Quick Start

Prerequisites

Python 3.11+
uv package manager
API keys (OpenAI, Petfinder, Mailgun)

Installation

Navigate to project directory

cd week8/community_contributions/dkisselev-zz/tuxedo_link

Set up virtual environment

uv venv
source .venv/bin/activate 
uv pip install -e ".[dev]"

Configure environment variables

# Copy template and add your API keys
cp env.example .env
# Edit .env with your keys

Configure application settings

# Copy configuration template
cp config.example.yaml config.yaml
# Edit config.yaml for email provider and deployment mode

Initialize databases

python setup_vectordb.py

Run the application

./run.sh

Visit http://localhost:7860 in your browser!

🔑 API Setup

Required API Keys

Add these to your .env file:

# OpenAI (for profile extraction)
# Get key from: https://platform.openai.com/api-keys
OPENAI_API_KEY=sk-...

# Petfinder (for cat listings)
# Get key from: https://www.petfinder.com/developers/
PETFINDER_API_KEY=your_key
PETFINDER_SECRET=your_secret

# Mailgun (for email alerts)
# Get key from: https://app.mailgun.com/
MAILGUN_API_KEY=your_mailgun_key

Optional API Keys

# RescueGroups (additional cat listings)
# Get key from: https://userguide.rescuegroups.org/
RESCUEGROUPS_API_KEY=your_key

# SendGrid (alternative email provider)
SENDGRID_API_KEY=SG...

# Modal (for cloud deployment)
MODAL_TOKEN_ID=...
MODAL_TOKEN_SECRET=...

Application Configuration

Edit config.yaml to configure:

# Email provider (mailgun or sendgrid)
email:
  provider: mailgun
  from_name: "Tuxedo Link"
  from_email: "noreply@yourdomain.com"

# Mailgun domain
mailgun:
  domain: "your-domain.mailgun.org"

# Deployment mode (local or production)
deployment:
  mode: local  # Use 'local' for development

Note: API keys go in .env (git-ignored), application settings go in config.yaml (also git-ignored).

💻 Usage

Search Tab

Describe your ideal cat in natural language
Click "Search" or press Enter
Browse results with match scores
Click "View Details" to see adoption page

Example queries:

"I want a friendly family cat in NYC good with children"
"Looking for a playful young kitten"
"Show me calm adult cats that like to cuddle"
"Find me a tuxedo maine coon in Boston" (natural color/breed terms work!)
"Orange tabby that's good with other cats"

Alerts Tab

Perform a search in the Search tab first
Go to Alerts tab
Enter your email address
Choose notification frequency (Immediately, Daily, Weekly)
Click "Save Alert"

You'll receive email notifications when new matches are found!

About Tab

Learn about Kyra and the technology behind the app

Development Mode

For faster development and testing, use local mode in config.yaml:

deployment:
  mode: local  # Uses local database and cached data

📚 Documentation

Complete Technical Reference

For detailed documentation on the architecture, agents, and every function in the codebase, see:

📖 TECHNICAL_REFERENCE.md - Complete technical documentation including:

Configuration system
Agentic architecture
Data flow pipeline
Deduplication strategy
Email provider system
Alert management
All functions with examples
User journey walkthroughs

📊 ARCHITECTURE_DIAGRAM.md - Visual diagrams:

System architecture
Agent interaction
Data flow
Database schema

🚀 MODAL_DEPLOYMENT.md - Cloud deployment guide:

Production mode architecture
Automated deployment with deploy.sh
Modal API and scheduled jobs
UI-to-Modal communication
Monitoring and troubleshooting

🧪 tests/README.md - Testing guide:

Running unit tests
Running integration tests
Manual test scripts
Coverage reports

🤝 Contributing

This project was built as part of the Andela LLM Engineering bootcamp. Contributions and improvements are welcome!

📄 License

See LICENSE file for details.

Made with ❤️ in memory of Kyra

May every cat find their perfect home 🐾

Technical Reference • Architecture • Deployment • Tests