Initial project setup: NF Hotel Data Analysis API

- Add project structure with domain-driven design organization
- Implement FastAPI endpoints for hotel booking reports
- Add data cleaning, statistics, and LLM report generation services
- Include configuration management and security utilities
- Add repository layer for bookings and metadata access
- Setup testing framework with conftest.py
- Include example files and documentation

examples/call_from_file_report.py

@@ -0,0 +1,44 @@
+"""Example: call POST /api/v1/report/from-file.
+
+This endpoint takes no request body - it always analyzes the bundled
+data/nf_hotel_bookings.csv on the server. Only the API key is required.
+
+Usage:
+    API_KEY=your-key python examples/call_from_file_report.py
+    API_KEY=your-key python examples/call_from_file_report.py --base-url http://localhost:8000
+"""
+
+import argparse
+import json
+import os
+import sys
+
+import httpx
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--base-url", default="http://localhost:8000")
+    args = parser.parse_args()
+
+    api_key = os.environ.get("API_KEY")
+    if not api_key:
+        print("Set the API_KEY environment variable first.", file=sys.stderr)
+        raise SystemExit(1)
+
+    response = httpx.post(
+        f"{args.base_url}/api/v1/report/from-file",
+        headers={"X-API-Key": api_key},
+        timeout=180.0,
+    )
+    response.raise_for_status()
+
+    report = response.json()
+    print("=== descriptive_stats ===")
+    print(json.dumps(report["descriptive_stats"], indent=2))
+    print("\n=== llm_report ===")
+    print(report["llm_report"])
+
+
+if __name__ == "__main__":
+    main()

examples/sample_booking_request.json

@@ -0,0 +1,58 @@
+{
+  "records": [
+    {
+      "booking_id": 1,
+      "hotel": "NF Hotel",
+      "is_canceled": 0,
+      "lead_time": 342,
+      "arrival_date_week_number": 27,
+      "booking_date": "2017-07-24",
+      "arrival_date": "2018-07-01",
+      "arrival_date_day_of_month": 1,
+      "stays_in_weekend_nights": 0,
+      "stays_in_week_nights": 0,
+      "adults": 2,
+      "children": 0,
+      "babies": 0,
+      "meal": "BB",
+      "country": "Portugal",
+      "market_segment": "Direct",
+      "is_repeated_guest": 0,
+      "previous_cancellations": 0,
+      "assigned_room_type": "A",
+      "booking_changes": 3,
+      "deposit_type": "No Deposit",
+      "agent": 0,
+      "customer_type": "No Contract (Single)",
+      "required_car_parking_spaces": 0,
+      "total_of_special_requests": 0
+    },
+    {
+      "booking_id": 2,
+      "hotel": "NF Hotel",
+      "is_canceled": 0,
+      "lead_time": 737,
+      "arrival_date_week_number": 27,
+      "booking_date": "2016-06-24",
+      "arrival_date": "2018-07-01",
+      "arrival_date_day_of_month": 1,
+      "stays_in_weekend_nights": 0,
+      "stays_in_week_nights": 0,
+      "adults": 2,
+      "children": 0,
+      "babies": 0,
+      "meal": "BB",
+      "country": "Portugal",
+      "market_segment": "Direct",
+      "is_repeated_guest": 0,
+      "previous_cancellations": 0,
+      "assigned_room_type": "B",
+      "booking_changes": 4,
+      "deposit_type": "No Deposit",
+      "agent": 0,
+      "customer_type": "No Contract (Single)",
+      "required_car_parking_spaces": 0,
+      "total_of_special_requests": 0
+    }
+  ]
+}