🏡 Find Your Hood - AI-Powered Neighborhood Discovery

Discover your perfect neighborhood in Los Angeles through natural language - because finding home should feel like a conversation, not a spreadsheet.

🎯 Inspiration

Moving to a new city is overwhelming. Traditional neighborhood searches force you to manually filter through dozens of criteria - crime rates, transit scores, school ratings, cost of living - making the process feel more like data analysis than finding a home.

We asked ourselves: What if finding your perfect neighborhood was as simple as describing your ideal lifestyle?

"I'm a young professional who loves nightlife and needs good public transit" should be enough. No checkboxes, no sliders, no spreadsheets - just a conversation with an AI that truly understands what you're looking for.

We built Find Your Hood to make neighborhood discovery human again.

✨ What It Does

Find Your Hood is an intelligent neighborhood recommendation system that uses natural language processing to match people with their perfect Los Angeles neighborhood based on their lifestyle description.

Key Features:

🧠 Natural Language Understanding

Describe your ideal lifestyle in your own words (English, Spanish, or Catalan)
AI extracts your preferences for safety, nature, transit, nightlife, community, and more
Conversational refinement - chat with the system to improve recommendations

🎵 Personalized Soundtrack

Each neighborhood gets a unique song from a curated Spotify playlist
Songs are matched to neighborhood vibes and your preferences
Instant preview with embedded Spotify player

📍 Interactive Maps

Beautiful 3D Mapbox visualization
Neighborhood boundaries with GeoJSON data
Explore centroids and geographic details

🖼️ Contextual Imagery

AI-generated search queries for each neighborhood
Google Places API integration for authentic photos
4 unique images showcasing parks, restaurants, culture, and more

🏘️ Relevant Places

ChatGPT curates 4 must-visit locations per neighborhood
Personalized to your interests and needs
Includes accessibility information

📧 Email Summaries

Beautiful HTML emails with your top recommendation
Professional design with neighborhood details
Powered by Resend API

🗣️ Multilingual Support

Natural language processing in English, Spanish, and Catalan
Spanish email summaries
Context-aware conversation history

🛠️ How We Built It

Architecture

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
│   React/TS      │ ◄─────► │   Flask API      │ ◄─────► │   OpenAI GPT    │
│   Frontend      │         │   Backend        │         │   NLP Engine    │
└────────┬────────┘         └────────┬─────────┘         └─────────────────┘
         │                           │
         │                           ├─────► Spotify API
         │                           ├─────► Google Places API
         │                           ├─────► Supabase (Context)
         │                           ├─────► Mapbox (Maps)
         │                           └─────► Resend (Emails)
         │
    ┌────▼─────────────────────────┐
    │   Beautiful UI with:         │
    │   • Shadcn/ui components     │
    │   • Tailwind CSS             │
    │   • Mapbox GL JS             │
    │   • Framer Motion            │
    └──────────────────────────────┘

Tech Stack

Backend (`/api`)

Python 3.13 - Core language
Flask - Web framework with async support
Pydantic AI - LLM integration framework
OpenAI GPT-4o - Natural language understanding
Pandas & NumPy - Data processing and analysis
GeoPandas & Shapely - Geospatial data handling
Spotipy - Spotify API integration
Resend - Email delivery
Supabase - User context and conversation history
Flask-CORS - Cross-origin resource sharing

Frontend (`/front-end`)

React 18.3 - UI framework
TypeScript 5.6 - Type safety
Vite - Build tool and dev server
Tailwind CSS - Utility-first styling
Shadcn/ui - Beautiful component library
Mapbox GL JS - Interactive maps
Embla Carousel - Image galleries

AI & Data

OpenAI GPT-4o - Preference extraction from natural language
LA Times Neighborhood GeoJSON - Boundary data
Census Data - Population, income, demographics
Crime Data - Safety statistics
POI Data - Points of interest (restaurants, parks, etc.)

Data Processing Pipeline

Data Collection (recommender.py)
- 114 Los Angeles neighborhoods
- 39+ features per neighborhood (crime rates, transit, parks, income, etc.)
- GeoJSON boundaries from LA Times dataset
NLP Pipeline (nlp_agent.py)
- User input → Pydantic AI Agent
- GPT-4o extracts 8 preference dimensions (1-10 scale)
- Intelligent reasoning: "works from home" → high quiet preference
- Context-aware: maintains conversation history via Supabase
Matching Algorithm (recommender.py)
- Weighted scoring based on user preferences
- Directional preferences (want high/low values)
- Normalization and feature engineering
- Top-K recommendations with match scores
Enrichment (demo_spotify.py)
- Spotify song matching per neighborhood
- Google Places image search with AI-generated queries
- ChatGPT curates relevant places
- Centroid calculation for maps

🚧 Challenges We Ran Into

1. Multilingual NLP Accuracy

Problem: GPT doesn't always correctly interpret lifestyle implications.

Solution: We engineered a 500+ line system prompt with detailed inference patterns:

"works from home" → quiet: 10, transit: 8
"startup founder" → community: 9, affordability: 8
"three dogs" → nature: 9

2. Spotify Track Matching Without Audio Features

Problem: Client credentials don't provide audio feature access.

Solution: Created a keyword-based matching algorithm using:

Track names and artists
Popularity scores
Position in playlist (curator preferences)
Preference-to-keyword mapping

3. Neighborhood Name Fuzzy Matching

Problem: GeoJSON has "Silver Lake" but dataset has "Silverlake".

Solution: Implemented intelligent normalization:

Remove punctuation and special characters
Substring matching with confidence thresholds
Common word filtering to avoid false positives

4. Ensuring Minimum 3 Results

Problem: Users with niche preferences got 0-1 recommendations.

Solution: Adaptive threshold system:

if len(results) < 3:
    # Retry with min_score=0 and higher top_k
    results = get_recommendations(min_score=0.0, top_k=10)

5. CORS Issues with ngrok

Problem: Preflight requests failing from different domains.

Solution: Comprehensive CORS setup:

Flask-CORS with wildcard origins
Manual headers on all responses
Support for all HTTP methods and headers

6. Context Persistence Across Conversations

Problem: Each query was independent - no refinement possible.

Solution: Supabase integration for message history:

Store user conversations with timestamps
Load context before each query
Append new messages after response

🏆 Accomplishments That We're Proud Of

🎨 Beautiful, Polished UI

We didn't just build a functional app - we crafted a delightful experience with:

Apple-inspired design language
Smooth animations and transitions
Responsive layouts that work on any device
3D map views and interactive elements

🧠 Advanced NLP Understanding

Our AI doesn't just parse keywords - it truly understands context:

"I'm a data scientist working 100% from home" 
→ Correctly identifies: high quiet, good transit for accessibility

🎵 Unique Spotify Integration

Each neighborhood gets its own song based on vibe + user preferences. Not random - intelligently matched!

📧 Professional Email Templates

We built gorgeous HTML emails from scratch with:

Responsive design
Gradient headers
Neighborhood details
Call-to-action buttons

🗺️ Complex Geospatial Data Handling

Successfully integrated:

GeoJSON polygon rendering
Centroid calculations
Fuzzy name matching
3D map visualizations

🔄 Conversational Refinement

Users can chat with the system to improve results - maintaining context across multiple interactions.

📚 What We Learned

Technical Skills

Advanced Prompt Engineering: Crafting detailed system prompts is an art. We learned how to guide LLMs with examples, constraints, and reasoning patterns.
Geospatial Data Processing: Working with GeoJSON, calculating centroids, and fuzzy matching geographic names.
API Orchestration: Coordinating 6+ external APIs (OpenAI, Spotify, Google Places, Supabase, Resend, Mapbox) in a single flow.
TypeScript Generics: Building flexible, type-safe interfaces for complex API responses.

Design Patterns

Separation of Concerns: Clean architecture with distinct layers (API, business logic, UI components)
Error Handling: Graceful degradation when external services fail
Responsive Design: Mobile-first approach with Tailwind utilities

Product Thinking

User Experience > Features: A simple, beautiful interface beats a complex, feature-rich one
Progressive Enhancement: Core functionality works, extras (Spotify, images) enhance
Conversation > Forms: Natural language is more intuitive than traditional filters

Team Collaboration

Git Workflow: Effective branching and merging strategies
Documentation: Clear README and inline comments save time
Iterative Development: MVP → polish → features

🚀 What's Next for Find Your Hood

Short Term (Next Sprint)

[ ] User Accounts: Save favorite neighborhoods and search history
[ ] Comparison View: Side-by-side comparison of 2-3 neighborhoods
[ ] Mobile App: React Native version for iOS/Android
[ ] More Cities: Expand beyond LA to NYC, SF, Austin, etc.

Medium Term (3-6 Months)

[ ] Virtual Tours: Integrate Google Street View 360° imagery
[ ] Commute Calculator: "I work at [address], show me 30min commute neighborhoods"
[ ] Social Features: Share recommendations with friends/family
[ ] Price Alerts: Notify when rental prices drop in saved neighborhoods
[ ] Transit Integration: Real-time bus/train schedules

Long Term (Vision)

[ ] Relocation Platform: Full moving service (realtors, movers, utilities)
[ ] Community Integration: Connect users moving to same neighborhood
[ ] Business Model: Partner with landlords and real estate agents
[ ] AR Exploration: Walk around neighborhoods in augmented reality
[ ] Predictive Analytics: "This neighborhood is gentrifying - act now"

🚀 Getting Started

Prerequisites

# Backend
Python 3.13+
pip or pip3

# Frontend  
Node.js 18+
npm or bun

# APIs (Get your keys)
- OpenAI API key
- Spotify Client ID & Secret
- Google Places API key
- Mapbox token
- Supabase project
- Resend API key

Installation

Backend Setup

cd api

# Install dependencies
pip3 install -r requirements.txt

# Configure API keys (create config.py)
cat > config.py << EOF
OPENAI_API_KEY = "sk-..."
SPOTIFY_CLIENT_ID = "your-id"
SPOTIFY_CLIENT_SECRET = "your-secret"
SUPABASE_URL = "https://your-project.supabase.co"
SUPABASE_KEY = "your-key"
EOF

# Run the server
python3 api.py

Backend runs on: http://localhost:3001

Frontend Setup

cd front-end

# Install dependencies
npm install
# or
bun install

# Configure environment (.env)
cat > .env << EOF
VITE_MAPBOX=your-mapbox-token
EOF

# Run development server
npm run dev
# or
bun run dev

Frontend runs on: http://localhost:8081

API Endpoints

`POST /get_response`

Full neighborhood recommendations with Spotify, images, and maps.

Request:

{
  "user_id": "unique-user-id",
  "message": "I'm a young professional who loves nightlife"
}

Response:

{
  "recommendations": [
    {
      "neighbourhood": "Silver Lake",
      "match_score": 87.5,
      "song": { "name": "Track Name", "uri": "spotify:..." },
      "images": ["url1", "url2", ...],
      "places": [{"nombre": "...", "tipo": "...", ...}],
      "geometry": {...},
      "centroid": {"latitude": 34.08, "longitude": -118.27}
    }
  ]
}

`POST /get_best_recommendation_summary`

Quick summary of best match + email notification.