# Hotel Search App — User Guide

## What This App Does

The Hotel Search App lets you find hotels by describing what you want in plain, everyday English. Instead of filling out forms with checkboxes and dropdowns, you simply type a sentence or paragraph about your ideal hotel. The app uses AI to understand your request, searches the web for matching hotels, and presents ranked results with direct links to each hotel's own website.

**What makes this app different from Expedia, Booking.com, or Google Travel?**

1. **Free-form input** — You write in natural language, not forms.
2. **Direct hotel links only** — Every link goes to the hotel's own website, never a travel agency.
3. **Smart ranking** — The app distinguishes between what you *must have* and what you'd *like to have*, and ranks hotels accordingly.

---

## How to Use the App

### Step 1: Describe Your Ideal Hotel

Type into the text box. Include as many of these details as you can:

- **Location** — Where do you want to stay? (city, neighborhood, near a landmark)
- **Dates** — When are you checking in and out?
- **Budget** — What's your maximum price per night?
- **Required features** — What does the hotel absolutely *must* have?
- **Preferred features** — What would be *nice to have* but isn't a deal-breaker?

### Step 2: Click "Search Hotels"

Or press Enter. The app will:
1. Parse your text using AI.
2. Search the web for matching hotels.
3. Score and rank the results.
4. Display them as cards with match scores.

### Step 3: Review Results

Each hotel card shows:
- **Match Score** (0–100) — How well the hotel matches your request.
- **Price** (when available).
- **Rating** (when available).
- **Which of your required features matched.**
- **Which required features are missing.**
- **Which preferred features matched.**
- **A direct link to the hotel's website.**

At the bottom, you'll see a "How I Interpreted Your Request" section showing exactly how the AI understood your input.

---

## Good Examples (Do This)

### Example 1: Specific Location + Budget + Clear Requirements
> "I'm looking for a beachfront hotel in Miami, Florida for March 15-18, 2026. I need free parking and it must be under $200 per night. A pool and spa would be nice but aren't required."

**Why this works well:**
- Clear location (Miami, Florida)
- Specific dates (March 15-18, 2026)
- Explicit budget ($200/night)
- Clear distinction: "I need" (required) vs "would be nice" (preferred)

### Example 2: Clear Priorities with "Must" and "Ideally"
> "Find me a pet-friendly hotel in downtown Austin, Texas for next weekend. Must have free breakfast. Ideally has a rooftop bar and is walkable to live music venues. Budget around $150/night."

**Why this works well:**
- Uses "must have" for the one non-negotiable amenity
- Uses "ideally" for nice-to-have features
- Includes budget and location

### Example 3: Luxury with Specific Needs
> "I need a luxury hotel in Manhattan, New York for 2 guests, April 5-8, 2026. Must have a fitness center and concierge service. Would prefer a room with a city view and a hotel restaurant."

**Why this works well:**
- Specifies guest count
- "Must have" vs "Would prefer" makes ranking accurate
- Specific dates help narrow results

---

## Bad Examples (Avoid This)

### Bad Example 1: Too Vague
> "I need a hotel."

**Why this fails:**
- No location — the app doesn't know where to search.
- No dates, budget, or features — nothing to rank against.
- **Fix:** At minimum, include a city: "I need a hotel in Chicago."

### Bad Example 2: Requiring Features Rarely Listed in Descriptions
> "Must have Wi-Fi, must have a TV in the room, must have running water."

**Why this fails:**
- Wi-Fi, TVs, and running water are *universal* in modern hotels but are almost never mentioned in hotel descriptions or search results.
- Since the app matches features against hotel descriptions, requiring these will lower match scores for every hotel.
- **Fix:** Don't require features that are standard everywhere. Focus on differentiating amenities like "pool," "spa," "free parking," or "beachfront."

### Bad Example 3: No Distinction Between Must-Have and Nice-to-Have
> "I want a hotel in San Francisco with a pool, gym, restaurant, bar, spa, room service, concierge, valet parking, ocean view, and rooftop terrace."

**Why this fails:**
- Everything is treated as required (since there are no qualifiers like "ideally" or "would be nice").
- Very few hotels will match ALL of these features, resulting in low match scores across the board.
- **Fix:** Separate your must-haves from nice-to-haves:
  > "Hotel in San Francisco. Must have a pool and gym. Would be nice to have a spa, ocean view, and rooftop terrace."

### Bad Example 4: Including Travel Agency Preferences
> "Find me a hotel on Expedia under $100."

**Why this fails:**
- This app specifically avoids travel agencies. It finds hotel websites directly.
- Mentioning "Expedia" confuses the search.
- **Fix:** Just state your budget and location directly.

---

## Understanding Match Scores

| Score Range | Meaning |
|-------------|---------|
| 80–100 | Excellent match — most or all requirements met |
| 60–79 | Good match — some requirements met, most preferences met |
| 40–59 | Fair match — base score, few specific features confirmed |
| 0–39 | Poor match — multiple required features missing |

**How scoring works:**
- Each hotel starts at 50 points (base score).
- **+10 points** for each matched required feature.
- **+3 points** for each matched preferred feature.
- **-5 points** for each missing required feature.
- **+5 points** if price is within budget.
- **-10 points** if price exceeds budget.

---

## Tips for Best Results

1. **Be specific about location.** "Downtown Chicago near Millennium Park" beats "somewhere in Illinois."
2. **Include dates** when you have them — it helps narrow results.
3. **Set a clear budget** — say "under $150/night" or "budget-friendly."
4. **Use signal words:**
   - For requirements: "must have," "need," "require," "essential"
   - For preferences: "would be nice," "prefer," "ideally," "bonus if"
5. **Limit required features to 2–4.** Too many requirements = fewer results.
6. **Don't require universal features.** Skip Wi-Fi, AC, towels — they're everywhere but rarely listed.

---

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|
| "No hotels found" | Too many required features or very niche request | Relax requirements; move some to preferences |
| Low match scores | Features not mentioned in hotel descriptions | Use broader terms (e.g., "pool" not "Olympic-size heated saltwater pool") |
| No prices shown | Price not available in search results | Check the hotel's website directly via the link |
| "API key not configured" | Missing environment variables | Set `OPENAI_API_KEY` and `SERPAPI_API_KEY` as environment variables or HF Space secrets |
| Results seem off | AI misinterpreted the request | Check the "How I Interpreted Your Request" section and rephrase |

---

## Privacy & Data

- Your search text is sent to OpenAI's API for parsing (not stored by this app).
- Hotel searches are performed via SerpAPI (Google Search).
- No personal data is collected or stored by this application.