build.md

Hotel Search App — Builder Work Summary

Plan Review

The Architect's plan (plan.md) specifies a Gradio-based hotel search app deployed on Hugging Face Spaces, using SerpApi's google_hotels engine, with natural language input parsing. The plan was implemented as designed with no deviations.

Technologies used (as specified in plan)

Component	Package / Tool	Version
Web UI	Gradio	>= 4.0
Hotel search API	google-search-results (SerpApi)	>= 2.4.2
Date parsing	python-dateutil	>= 2.8.2
Language	Python	3.10+
Deployment	Hugging Face Spaces	Gradio SDK

Implementation Details

File structure

Hotel App/
├── app.py              # Complete application (single file per plan)
├── requirements.txt    # Python dependencies
├── plan.md             # Architect deliverable
├── build.md            # This file (Builder deliverable)
├── qa.md               # QA deliverable
├── ver.md              # Synthesizer deliverable
└── README.md           # Hugging Face Space metadata + user guide

Modules implemented in app.py

Function	Purpose
parse_user_input(text)	Extracts location, dates, price range, adults, required/desired/avoid features from free-form text using regex and dateutil
get_hotel_link(hotel)	Resolves the best non-travel-agency URL for a hotel result. Falls back to a Google search link if no direct URL is available
format_hotel_results(properties)	Renders a list of hotel dicts as styled HTML cards with images, ratings, amenities, and booking links
parsed_summary_html(parsed, total)	Generates a summary banner showing the extracted search parameters
search_hotels(user_input, api_key)	Orchestrates parsing → SerpApi call → filtering → rendering. Entry point for Gradio

Input parsing capabilities

• Dates: Handles MM/DD/YYYY, YYYY-MM-DD, Month Day, Year, Month Day-Day, Year ranges. Defaults to tomorrow + 1 night when no dates are given. Rejects past dates.
• Prices: Recognizes $X to $Y, under $X, budget of $X, above $X, and similar variations.
• Adults: Detects N adults/guests/people/travelers. Defaults to 2.
• Location: Extracts proper-noun phrases following "in", "near", "around", "at", "close to".
• Features: Classifies into required (must have / need), desired (would like / prefer), and avoid (no / don't want / avoid).

Search pipeline

1. Parse free-form text → structured dict
2. Build SerpApi google_hotels request params
3. Call SerpApi and receive JSON response
4. Filter out properties linking to travel-agency domains (configurable blocklist of 20+ agencies)
5. Resolve each hotel's best direct link via get_hotel_link
6. Render top 15 results as HTML cards
7. Prepend a parsed-parameters summary banner

Security measures

• API key is never hard-coded. Accepted via a password-masked Gradio field or SERPAPI_KEY environment variable.
• All external links open with rel='noopener noreferrer' to prevent reverse tabnapping.
• User input is only used within regex matching and as a SerpApi query string; no shell execution or eval.
• Exception handling wraps the entire search pipeline so stack traces are never exposed to the user.

Suggestions for QA

1. Date parsing edge cases: Try formats like "next Friday", "this weekend", single dates, past dates, and nonsensical dates.
2. Price parsing edge cases: Overlapping price keywords, no dollar sign, negative numbers.
3. Empty / gibberish input: Ensure friendly error messages.
4. Missing API key: Verify the prompt appears.
5. Invalid API key: Verify SerpApi error is surfaced clearly.
6. Travel-agency filtering: Confirm no Expedia/Booking.com links appear.
7. Link validity: Spot-check that "Visit Hotel Website" buttons lead to real hotel sites.
8. Responsive layout: Test on narrow viewports.
9. Location extraction: Try multi-word cities ("San Francisco"), cities with state ("Austin, TX"), landmarks ("near Times Square").
10. Feature extraction: Verify required vs. desired vs. avoid classification.