docs/user_guide.md

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.