qa_report.md

QA Report — Hotel Search App

Plan-vs-Build Compliance Matrix

#	Requirement	Plan	Build	Status
R1	Free-form text input	gr.Textbox	gr.Textbox, 5 lines, placeholder	✅ Pass
R2	Distinguish required vs preferred features	LLM parsing with keyword rules	PARSE_SYSTEM_PROMPT classifies by qualifier words	✅ Pass
R3	Extract dates, location, price, amenities	LLM → JSON schema	parse_request() → structured dict	✅ Pass
R4	Search for matching hotels	SerpAPI Google Search	search_hotels() via SerpAPI	✅ Pass
R5	Rank by required first, preferred as tie-breaker	+10 req, +3 pref, -5 missing	rank_results() implements exact scoring	✅ Pass
R6	Return name, description, price, score, direct link	Markdown cards	format_output() produces cards	✅ Pass
R7	Never show travel-agency links	Block list in utils.py	BLOCKED_DOMAINS set (40+ domains)	✅ Pass
R8	Clear message when no results	Warning with suggestions	format_output() handles empty list	✅ Pass
R9	Example queries in UI	Pre-filled examples	5 examples in EXAMPLES list	✅ Pass
R10	Deploy on HF Spaces via Gradio	Gradio Blocks	gr.Blocks + HF README metadata	✅ Pass

Architecture Compliance

Component	Plan	Build	Match
app.py	Gradio Blocks, Textbox, Markdown output, Examples	Implemented exactly	✅
search.py	4-stage pipeline (parse → search → rank → format)	All 4 stages present	✅
utils.py	Domain filtering, URL validation, price extraction	All implemented	✅
requirements.txt	gradio, openai, serpapi	All listed with versions	✅

Issues Found and Resolved

Issue 1: Travel Agency Filter Gap (FIXED)

• Severity: Medium
• Description: Hotels from SerpAPI's hotels_results block were not filtered through is_travel_agency(), only organic results were filtered.
• Fix: Added is_travel_agency(link) check to the hotels_results loop in search_hotels().

Issue 2: Plan-Build Discrepancy on Default Feature Classification (FIXED)

• Severity: Low
• Description: Plan Section 7 said unqualified amenities default to "preferred," but the LLM prompt (correctly) treats them as "required." The assignment description supports the "required" default.
• Fix: Updated plan.md to match the build behavior.

Code Quality Assessment

Aspect	Rating	Notes
Error handling	Good	API key checks, try/except blocks, graceful fallbacks
Input validation	Good	Empty input check, JSON parse fallback
Separation of concerns	Excellent	Clean split across app.py / search.py / utils.py
User experience	Good	Tips panel, example queries, interpretation display
Security	Good	API keys via env vars, not hardcoded
Code readability	Excellent	Clear docstrings, logical section dividers

Edge Cases Considered

• ✅ Empty input → friendly prompt message
• ✅ Missing API keys → clear error with setup instructions
• ✅ LLM returns invalid JSON → fallback to raw text as location
• ✅ SerpAPI error → error message displayed
• ✅ No matching hotels → suggestions for broadening search
• ✅ Duplicate hotel names → deduplicated

Recommendations

1. Future versions could add caching for repeated searches (mentioned in plan but not yet implemented).
2. Consider adding a loading indicator/progress bar for long searches.
3. The keyword-matching heuristic in _feature_present() could be enhanced with semantic similarity.

QA Verdict: ✅ PASS

The build faithfully implements the architecture plan. All 10 requirements are met. Two minor issues were found and fixed during QA review.