Smart Stay Finder - AI Airbnb Search

An intelligent Airbnb search application powered by LangGraph agents that allows users to find properties using natural language queries.

🌟 Features

• Natural Language Search: Describe your ideal stay in plain English
• AI-Powered Query Understanding: Claude Sonnet 4.5 extracts structured filters from your description
• Intelligent Clarification: The system asks follow-up questions when needed
• LangGraph Orchestration: Multi-agent workflow for optimal results
• Beautiful UI: Organic & earthy design with Cormorant Garamond and Manrope fonts
• Alternative Suggestions: Smart recommendations when no results are found

🏗️ Architecture

Backend (Python/FastAPI)

Agents

1. QueryUnderstandingAgent (/app/backend/agents/query_agent.py)

   • Extracts structured filters from natural language
   • Identifies: location, dates, guests, price range, amenities, property type
   • Triggers clarification when information is ambiguous

2. RetrievalRankingAgent (/app/backend/agents/retrieval_agent.py)

   • Calls Apify Airbnb scraper
   • Ranks results based on relevance
   • Generates alternatives when no results found

Services

• LangGraphService (/app/backend/services/langgraph_service.py)

  • Orchestrates agent workflow using LangGraph
  • Handles conditional logic for clarification
  • Manages state transitions

• ApifyService (/app/backend/services/apify_service.py)

  • Integrates with Apify Airbnb scraper
  • Formats raw listings into standardized format

Frontend (React)

Components

• SearchHero: Main search interface with natural language input
• PropertyCard: Displays individual listing details
• LoadingState: Custom "thinking" animation
• ClarificationPrompt: Handles follow-up questions
• NoResults: Shows alternatives when no listings found

🚀 Getting Started

Prerequisites

• Python 3.11+
• Node.js 16+
• MongoDB
• Apify API token
• Emergent LLM key (for Claude Sonnet 4.5)

Environment Setup

1. Backend Configuration (/app/backend/.env):

MONGO_URL="mongodb://localhost:27017"
DB_NAME="test_database"
CORS_ORIGINS="*"
EMERGENT_LLM_KEY=sk-emergent-44cAdB123B7FcEfB0B
APIFY_API_TOKEN=your_apify_token_here

2. Frontend Configuration (/app/frontend/.env):

REACT_APP_BACKEND_URL=your_backend_url_here
WDS_SOCKET_PORT=443
ENABLE_HEALTH_CHECK=false

Installation

1. Install Backend Dependencies:

cd /app/backend
pip install -r requirements.txt

2. Install Frontend Dependencies:

cd /app/frontend
yarn install

Running the Application

The application runs on supervisor:

# Restart services
sudo supervisorctl restart backend frontend

# Check status
sudo supervisorctl status

• Backend: http://localhost:8001
• Frontend: http://localhost:3000

📡 API Endpoints

POST /api/search

Search for Airbnb listings using natural language.

Request Body:

{
  "query": "Beach house in Malibu under $200/night",
  "session_id": "optional-session-id"
}

Response:

{
  "success": true,
  "results": [
    {
      "name": "Oceanfront Beach House",
      "location": "Malibu, CA",
      "price_per_night": 180,
      "rating": 4.8,
      "url": "https://airbnb.com/...",
      "amenities": ["wifi", "pool", "parking"],
      "image_url": "https://...",
      "bedrooms": 3,
      "bathrooms": 2,
      "property_type": "Entire home"
    }
  ],
  "message": "Found 12 properties matching your criteria",
  "clarification_needed": false
}

Clarification Response:

{
  "success": false,
  "clarification_needed": true,
  "clarification_question": "Where would you like to stay? Please provide a city or location.",
  "results": null
}

🧪 Testing

Run the backend test suite:

cd /app/backend
pytest backend_test.py -v

🎨 Design System

• Primary Color: Deep Forest Green (#1A4D2E)
• Accent Color: Terracotta (#E07A5F)
• Background: Warm Off-White (#FDFCF8)
• Typography:
  • Headings: Cormorant Garamond
  • Body: Manrope

🔧 Tech Stack

Backend

• FastAPI
• LangGraph (agent orchestration)
• LangChain
• Claude Sonnet 4.5 (via Emergent integrations)
• Apify Client
• MongoDB (Motor)
• Python 3.11

Frontend

• React 19
• Tailwind CSS
• Axios
• Lucide React (icons)
• Shadcn/ui components

📝 Example Queries

• "Beach house in Malibu under $200/night"
• "Pet-friendly apartment in Paris for 2 guests"
• "Cabin with mountain views for 6 people next month"
• "Cozy place in Aspen with hot tub"
• "Cheap place in Barcelona with wifi"

🔍 How It Works

1. User Input: User describes their ideal stay in natural language
2. Query Understanding: Claude Sonnet 4.5 extracts structured filters
3. Clarification Check: System asks follow-up questions if needed
4. Retrieval: Apify scraper searches Airbnb
5. Ranking: Results are scored and ranked by relevance
6. Display: Top properties shown in beautiful cards

💰 Cost Management

The application is configured to control Apify API costs:

• Max Listings per Request: 20 listings
• Cost per Request: ~$0.12 (at $6 per 1000 items)
• Free Tier: ~41 searches with $5 credit

See COST_OPTIMIZATION.md for detailed cost management strategies.

To adjust the limit, edit /app/backend/agents/retrieval_agent.py:

params["maxListings"] = 20  # Change this value (10-50 recommended)

🐛 Known Limitations

• Apify scraper limited to configured maxListings (default: 20)
• Date parsing is best-effort (explicit dates work better)
• Free tier: ~41 searches before limit

📦 Project Structure

/app/
├── backend/
│   ├── agents/
│   │   ├── query_agent.py
│   │   └── retrieval_agent.py
│   ├── services/
│   │   ├── apify_service.py
│   │   └── langgraph_service.py
│   ├── models/
│   │   └── schemas.py
│   ├── server.py
│   ├── requirements.txt
│   └── .env
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── SearchHero.js
│   │   │   ├── PropertyCard.js
│   │   │   ├── LoadingState.js
│   │   │   ├── ClarificationPrompt.js
│   │   │   └── NoResults.js
│   │   ├── App.js
│   │   ├── App.css
│   │   └── index.css
│   ├── public/
│   │   └── index.html
│   ├── package.json
│   └── .env
├── design_guidelines.json
└── README.md

🎯 Future Enhancements

• Save favorite properties
• User accounts and search history
• Email alerts for new listings
• Price tracking and notifications
• Advanced filtering in UI
• Map view of properties
• Comparison tool for multiple listings

📄 License

This project is built as a demonstration of LangGraph-based agentic AI applications.