major changes

COPILOT_MASTER_PROMPT.md

@@ -0,0 +1,1568 @@
+# 🤖 GITHUB COPILOT MASTER PROMPT
+# Hotel Booking AI — Universal Smart Booking System
+# Paste this ENTIRE file into Copilot Chat before starting any task.
+# Then use the TASK PROMPTS below for specific coding work.
+
+---
+
+## ═══════════════════════════════════════════════
+## SECTION 1 — SYSTEM CONTEXT (READ BEFORE ANY TASK)
+## ═══════════════════════════════════════════════
+
+```
+You are a senior full-stack AI engineer working on a production Hotel Booking AI
+Chatbot delivered exclusively through Facebook Messenger. The system is ALREADY
+PARTIALLY BUILT. Module 1 (Language Detection + Greeting) is COMPLETE and working.
+
+Your job is to CONTINUE building from the existing codebase — never rewrite what
+already works, only extend and upgrade it.
+
+ARCHITECTURE RULE (NON-NEGOTIABLE):
+- ONE HuggingFace Space hosts: ALL Python backend logic + ALL AI inference +
+  ALL database calls (Supabase + Redis + Qdrant + Elasticsearch)
+- Render hosts: ONLY the Rasa webhook receiver + messenger channel connector
+  (Render has limited RAM — keep it a thin relay, nothing more)
+- Facebook Messenger is the ONLY user interface
+- No local development environment — all code runs on HF Space or Render
+
+EXISTING COMPLETED FILES (DO NOT REWRITE):
+  ✅ services/language_service/detector.py        — langdetect + XLM-RoBERTa
+  ✅ services/language_service/translator.py      — Helsinki-NLP translation
+  ✅ services/language_service/main.py            — FastAPI /detect endpoint
+  ✅ actions/actions_brain.py::ActionGreetUser    — multilingual greeting action
+  ✅ data/nlu/nlu_en.yml (intent: greet)          — 25 training examples
+  ✅ db/supabase_client.py                        — connection pool setup
+  ✅ db/redis_client.py                           — async + sync clients
+  ✅ channels/messenger_connector.py              — FB webhook verified
+  ✅ config.yml                                   — Rasa pipeline configured
+  ✅ credentials.yml                              — Messenger credentials
+  ✅ endpoints.yml                                — Redis tracker store
+  ✅ domain.yml (partial)                         — base slots + greet response
+
+WHEN I SAY "continue from existing files" I mean:
+  1. Import from the completed files above — never duplicate their logic
+  2. Check existing slot names in domain.yml before adding new ones
+  3. Append to actions files — never replace existing action classes
+  4. Append to nlu_en.yml — never replace existing intents
+  5. Check Redis key patterns in SKILL.md before creating new keys
+```
+
+---
+
+## ═══════════════════════════════════════════════
+## SECTION 2 — UX INTERACTION RULES (CRITICAL)
+## ═══════════════════════════════════════════════
+
+```
+INTERACTION DESIGN LAW:
+  > 50% of all user interactions MUST be button clicks (Messenger quick replies
+    or generic template buttons) — not free text typing.
+
+BUTTON-FIRST PRINCIPLE:
+  Every bot message that presents choices MUST show buttons. Never ask the user
+  to type something they could click.
+
+WHEN TO USE QUICK REPLIES (max 13, text max 20 chars):
+  - Yes/No confirmations
+  - Language selection
+  - Trip purpose selection
+  - Star rating filter
+  - Meal plan selection
+  - Add-on accept/decline
+  - Review star rating (1-5 stars as emoji buttons)
+  - "Show more" / "Next" / "Back" navigation
+  - Post-booking options (Directions / Weather / Share)
+
+WHEN TO USE GENERIC TEMPLATE CARDS (carousel, max 10 cards):
+  - Hotel search results (1 card per hotel)
+  - Room type options (1 card per room)
+  - Add-on catalogue items
+  - Booking summary before payment
+  Each card MUST have:
+    - image_url (hotel/room thumbnail from Supabase Storage)
+    - title (hotel/room name, max 80 chars)
+    - subtitle (key details: stars, price, key feature)
+    - buttons: max 3 per card [View Details | Select This | Save for Later]
+
+WHEN TO USE LIST TEMPLATE:
+  - Booking modification options
+  - Loyalty tier benefits
+  - FAQ category selection
+  - Post-booking service menu
+
+WHEN TO ACCEPT FREE TEXT (and ONLY then):
+  - Guest name input
+  - Email address input
+  - Phone number input
+  - Special requests / dietary notes
+  - Review free-text comment
+  - Any FAQ question (open search)
+
+VOICE INTERACTION RULE:
+  - Voice input is ALWAYS transcribed to text first (STT on HF Space)
+  - After transcription, the same button-first response logic applies
+  - Bot voice responses (TTS) are offered as an audio attachment option
+  - Voice is activated by user tapping a 🎙️ button in Messenger Webview
+
+PROGRESSIVE DISCLOSURE RULE:
+  - Never show all options at once �� show top 3 with a "Show more →" button
+  - Never ask more than ONE question per message
+  - Never combine a question and a statement in the same bubble — split into 2 messages
+  - Use typing indicators (sender_action: typing_on) before every substantive reply
+
+SMART AUTO-DETECTION RULE (Universal System):
+  - Auto-detect: language, timezone (from FB profile locale), currency (from country)
+  - Never ask for what can be inferred — only confirm if confidence < 0.85
+  - Pre-fill: returning user's last search city, last guest details (with "Use saved?" button)
+  - Show prices in user's local currency (convert via open exchange rates)
+  - Date format matches user's locale (MM/DD vs DD/MM vs YYYY/MM/DD)
+```
+
+---
+
+## ═══════════════════════════════════════════════
+## SECTION 3 — HUGGINGFACE SPACE ARCHITECTURE
+## ═══════════════════════════════════════════════
+
+```
+ONE SPACE RULES — hf_space/app.py is the SINGLE entry point for everything.
+
+HuggingFace Space structure:
+  hf_space/
+  ├── app.py                  ← FastAPI app, mounts ALL routers, starts ALL services
+  ├── routers/
+  │   ├── language.py         ← /api/language/* endpoints
+  │   ├── search.py           ← /api/search/*
+  │   ├── rag.py              ← /api/rag/*
+  │   ├── booking.py          ← /api/booking/*
+  │   ├── payment.py          ← /api/payment/*
+  │   ├── voice.py            ← /api/voice/* + WebSocket
+  │   ├── loyalty.py          ← /api/loyalty/*
+  │   ├── notification.py     ← /api/notify/*
+  │   └── analytics.py        ← /api/analytics/*
+  ├── models/
+  │   ├── labse_model.py      ← LaBSE loaded ONCE at startup (module-level singleton)
+  │   ├── whisper_model.py    ← Faster-Whisper loaded ONCE at startup
+  │   └── llm_client.py       ← Groq API client (free tier) for Llama 3 — NOT local model
+  ├── db/
+  │   ├── supabase.py         ← Supabase client singleton
+  │   └── redis.py            ← Redis client singleton (Upstash Redis — HTTP-based, HF compatible)
+  └── requirements.txt
+
+CRITICAL: Use Groq API (free tier) for LLM — NOT a local Llama model.
+  Groq gives Llama 3 70B for free with fast inference.
+  This avoids GPU memory issues on HF Space.
+  GROQ_API_KEY from environment — model: "llama3-70b-8192"
+
+CRITICAL: Use Upstash Redis (HTTP REST API) — NOT a TCP Redis connection.
+  HF Spaces blocks outbound TCP on non-standard ports.
+  Upstash Redis works over HTTPS — fully compatible.
+  from upstash_redis import Redis
+  redis = Redis(url=os.environ["UPSTASH_REDIS_URL"], token=os.environ["UPSTASH_REDIS_TOKEN"])
+
+CRITICAL: All AI models load at HF Space STARTUP — not per-request.
+  Use @asynccontextmanager lifespan in FastAPI app.py
+  Store models as module-level globals: labse_model = None, whisper_model = None
+  This prevents cold-start timeouts on first user message.
+
+HF Space startup sequence (app.py lifespan):
+  1. Connect Supabase (verify with SELECT 1)
+  2. Connect Upstash Redis (verify with PING)
+  3. Load LaBSE model → verify with test embed
+  4. Load Faster-Whisper model → keep in memory
+  5. Test Groq API → verify connection
+  6. Connect Qdrant Cloud → verify collection exists
+  7. Connect Elasticsearch → verify index exists
+  8. Log "✅ All systems ready" to HF Space logs
+  9. FastAPI begins accepting requests
+
+RENDER (THIN WEBHOOK ONLY):
+  render_webhook/
+  ├── main.py       ← FastAPI, receives Messenger webhook, forwards to HF Space
+  ├── rasa_relay.py ← Rasa action server that calls HF Space endpoints
+  └── requirements.txt  ← ONLY: fastapi, uvicorn, rasa, httpx (nothing heavy)
+
+  Render main.py logic:
+    POST /webhooks/messenger/webhook
+      → verify FB signature
+      → extract sender_psid + message text/postback
+      → POST to HF_SPACE_URL/api/process_message
+      → receive response (text + buttons + cards)
+      → format for Messenger Graph API
+      → POST reply to graph.facebook.com/v18.0/me/messages
+      → return 200 OK immediately (< 200ms, before FB 5s timeout)
+```
+
+---
+
+## ═══════════════════════════════════════════════
+## SECTION 4 — UNIVERSAL SYSTEM RULES
+## ═══════════════════════════════════════════════
+
+```
+This system serves ANYONE from ANYWHERE automatically. These rules are mandatory:
+
+1. AUTO-LOCALE DETECTION
+   On first message from new user:
+   - Call GET https://graph.facebook.com/v18.0/{psid}?fields=locale,timezone,name
+   - Parse locale: "en_US" → language="en", country="US", currency="USD"
+   - Parse locale: "ar_SA" → language="ar", country="SA", currency="SAR", rtl=True
+   - Never ask "what language?" unless confidence < 0.75
+   - Store in Upstash Redis: user:{psid}:profile for 30 days
+
+2. AUTO-CURRENCY
+   - All prices stored in USD in Supabase
+   - Display converted to user's local currency using Open Exchange Rates (free API)
+   - Cache rates in Redis: fx:{currency} EX 3600 (refresh hourly)
+   - Show: "¥28,000 / night (~$187 USD)" for transparency
+
+3. AUTO-TIMEZONE
+   - All Supabase datetimes stored as UTC
+   - Display times converted to user's Facebook timezone
+   - Date pickers show in user's local date format
+
+4. RETURNING USER INTELLIGENCE
+   On every message, before responding:
+   - Check Redis user:{psid}:profile for existing profile
+   - If returning: load last_search_city, last_booking, preferred_language, tier
+   - If booking in progress: resume from last state (show "Continue booking?" button)
+   - Pre-fill forms with saved data, show "Use saved details?" button
+
+5. GLOBAL PAYMENT SUPPORT
+   Stripe supports 135+ currencies — always charge in user's local currency if supported
+   Fallback: charge in USD with conversion shown
+   Show accepted payment methods icons as quick-reply buttons:
+   💳 Card | 🍎 Apple Pay | 🤖 Google Pay | 🏦 Bank Transfer
+
+6. ACCESSIBILITY (non-negotiable)
+   - RTL languages (ar, he, fa, ur): all text labels marked with dir="rtl" in templates
+   - All button labels max 20 chars (Messenger limit, also aids screen readers)
+   - All image attachments include accessible_title field
+   - Audio responses always offered alongside text (never audio-only)
+   - Simple language mode: user can say "speak simply" → bot uses shorter sentences
+
+7. GRACEFUL DEGRADATION
+   If HF Space is cold-starting (first request after idle):
+   - Render webhook immediately replies: "One moment, connecting you to our AI... 🔄"
+   - Polls HF Space health endpoint every 2s for up to 30s
+   - Once ready, sends the actual response
+   - If HF Space fails after 30s: send fallback menu with pre-built button options
+
+8. SESSION CONTINUITY
+   User can switch devices, come back days later:
+   - All state in Upstash Redis keyed by Facebook PSID (not session UUID)
+   - Incomplete bookings preserved 48 hours with "Resume booking?" offer
+   - Completed bookings accessible anytime via "My Bookings" menu button
+```
+
+---
+
+## ═══════════════════════════════════════════════
+## SECTION 5 — MESSENGER RESPONSE BUILDER
+## ═══════════════════════════════════════════════
+
+```
+ALWAYS use this builder pattern — never construct raw Messenger JSON manually.
+
+File: render_webhook/messenger_builder.py
+This file must be created and used by ALL response-sending code.
+
+class MessengerResponse:
+    def __init__(self, recipient_psid: str):
+        self.psid = recipient_psid
+
+    def typing(self) -> dict:
+        """Send before every substantive message"""
+        return {"recipient": {"id": self.psid}, "sender_action": "typing_on"}
+
+    def text(self, message: str) -> dict:
+        """Plain text — auto-split if > 2000 chars"""
+        # Split at sentence boundaries if > 2000 chars
+        # Never truncate mid-word
+        return {"recipient": {"id": self.psid}, "message": {"text": message[:2000]}}
+
+    def quick_replies(self, text: str, options: list[dict]) -> dict:
+        """
+        options = [
+          {"title": "Paris 🗼", "payload": "CITY_PARIS"},
+          {"title": "Tokyo 🗾", "payload": "CITY_TOKYO"},
+        ]
+        Max 13 options. Title max 20 chars.
+        Auto-truncate titles to 20 chars with ellipsis.
+        """
+        qr = [
+            {
+                "content_type": "text",
+                "title": opt["title"][:20],
+                "payload": opt["payload"]
+            }
+            for opt in options[:13]
+        ]
+        return {
+            "recipient": {"id": self.psid},
+            "message": {"text": text, "quick_replies": qr}
+        }
+
+    def hotel_cards(self, hotels: list[dict]) -> dict:
+        """
+        hotels = [{
+            "name": "Grand Tokyo Hotel",
+            "stars": 5,
+            "price_from": 28000,
+            "currency": "JPY",
+            "price_usd": 187,
+            "thumbnail_url": "https://...",
+            "hotel_id": "h_123",
+            "distance_km": 1.2,
+            "top_feature": "Free breakfast"
+        }]
+        Max 10 hotels. Always show top 3 first with "Show 4 more →" button.
+        """
+        elements = []
+        for h in hotels[:10]:
+            stars_emoji = "⭐" * h["stars"]
+            elements.append({
+                "title": f"{h['name']} {stars_emoji}"[:80],
+                "subtitle": f"From {h['currency']} {h['price_from']:,}/night · {h['top_feature']}"[:80],
+                "image_url": h["thumbnail_url"],
+                "buttons": [
+                    {"type": "postback", "title": "📋 View Details", "payload": f"HOTEL_DETAILS_{h['hotel_id']}"},
+                    {"type": "postback", "title": "✅ Select Hotel", "payload": f"HOTEL_SELECT_{h['hotel_id']}"},
+                    {"type": "postback", "title": "🔖 Save for Later", "payload": f"HOTEL_SAVE_{h['hotel_id']}"},
+                ]
+            })
+        return {
+            "recipient": {"id": self.psid},
+            "message": {
+                "attachment": {
+                    "type": "template",
+                    "payload": {"template_type": "generic", "elements": elements}
+                }
+            }
+        }
+
+    def room_cards(self, rooms: list[dict]) -> dict:
+        """Same pattern as hotel_cards but for room types"""
+        # buttons: View Photos | Select Room | Compare
+        ...
+
+    def booking_summary_card(self, booking: dict) -> dict:
+        """
+        Single card with full booking summary before payment.
+        Button: Confirm & Pay | Modify | Cancel
+        """
+        ...
+
+    def list_template(self, title: str, items: list[dict], cta_button: dict = None) -> dict:
+        """
+        items = [{"title": "...", "subtitle": "...", "payload": "..."}]
+        Max 4 items. Optional global CTA button at bottom.
+        Used for: modification options, loyalty info, FAQ categories
+        """
+        ...
+
+    def image(self, url: str, caption: str = None) -> dict:
+        """Send hotel photo, QR code, or map screenshot"""
+        payload = {"url": url, "is_reusable": True}
+        msg = {"attachment": {"type": "image", "payload": payload}}
+        if caption:
+            # Send caption as separate text message after image
+            pass
+        return {"recipient": {"id": self.psid}, "message": msg}
+
+    def file(self, url: str, filename: str) -> dict:
+        """Send PDF booking voucher"""
+        return {
+            "recipient": {"id": self.psid},
+            "message": {
+                "attachment": {
+                    "type": "file",
+                    "payload": {"url": url, "is_reusable": False}
+                }
+            }
+        }
+
+    def send_sequence(self, messages: list[dict], delay_ms: int = 600) -> list[dict]:
+        """
+        Send multiple messages in sequence with typing indicators.
+        Always: typing → message → typing → message
+        delay_ms between messages prevents Messenger from reordering them.
+        Returns ordered list to be sent one by one.
+        """
+        sequence = []
+        for msg in messages:
+            sequence.append(self.typing())
+            sequence.append(msg)
+        return sequence
+
+# USAGE EXAMPLE in render_webhook/main.py:
+async def send_to_messenger(messages: list[dict], access_token: str):
+    async with httpx.AsyncClient() as client:
+        for msg in messages:
+            await client.post(
+                f"https://graph.facebook.com/v18.0/me/messages?access_token={access_token}",
+                json=msg
+            )
+            if msg.get("sender_action") != "typing_on":
+                await asyncio.sleep(0.6)   # 600ms between messages
+```
+
+---
+
+## ═══════════════════════════════════════════════
+## SECTION 6 — COMPLETE TASK PROMPTS
+## ═══════════════════════════════════════════════
+
+### COPY ONE PROMPT AT A TIME INTO COPILOT CHAT
+
+---
+
+### 🔵 TASK PROMPT 1 — HF SPACE UNIFIED APP SETUP
+
+```
+TASK: Create the unified HuggingFace Space entry point.
+
+Context: Module 1 is done. I need the single hf_space/app.py that:
+1. Loads ALL AI models at startup (LaBSE, Faster-Whisper, Groq client)
+2. Connects to ALL databases (Supabase, Upstash Redis, Qdrant, Elasticsearch)
+3. Mounts ALL routers (language, search, rag, booking, payment, voice, loyalty)
+4. Exposes GET /health that returns {"status": "ready", "models": [...], "dbs": [...]}
+5. Exposes POST /api/process_message — the MAIN endpoint called by Render webhook
+
+The /api/process_message endpoint:
+  Input: {
+    "psid": "facebook_page_scoped_id",
+    "message_type": "text" | "postback" | "audio",
+    "text": "user message or postback payload",
+    "audio_url": "messenger audio url (if voice message)",
+    "fb_locale": "en_US",          # from FB profile
+    "fb_timezone": -5,             # from FB profile
+    "timestamp": 1234567890
+  }
+  
+  Processing flow:
+    1. Get/create user profile from Upstash Redis (user:{psid}:profile)
+    2. If audio_url: call whisper_model.transcribe(audio_url) first
+    3. If first message: auto-detect language from fb_locale, fetch FB profile
+    4. Route message to correct handler based on user's current_state in Redis
+    5. Return: {
+         "messages": [array of Messenger-formatted message objects],
+         "new_state": "searching" | "selecting_room" | "filling_form" | "paying" | etc.
+       }
+
+Use existing: db/supabase_client.py and db/redis_client.py (import them)
+UPSTASH_REDIS_URL and UPSTASH_REDIS_TOKEN replace standard Redis env vars.
+Use fastapi lifespan for model loading, NOT @app.on_event (deprecated).
+```
+
+---
+
+### 🔵 TASK PROMPT 2 — MODULE 2: HOTEL SEARCH WITH BUTTON-FIRST UX
+
+```
+TASK: Build Module 2 — Hotel Search & Discovery with full button-first UX.
+
+Continuing from existing: ActionGreetUser is done, language is detected.
+Build: hf_space/routers/search.py + render_webhook state handler for search.
+
+CONVERSATION FLOW (button-first design):
+  
+  STEP 1 — Destination (after greeting)
+  Bot sends TWO messages:
+    Message 1: "Where would you like to stay? 🌍"
+    Message 2: Quick replies showing:
+      [🗼 Paris] [🗾 Tokyo] [🏙️ Dubai] [🌴 Bali] [🎭 London] [🗽 New York] [✏️ Type city...]
+    If user clicks "Type city..." → bot asks for free text
+    If user types directly → accept free text too
+
+  STEP 2 — Dates
+  Bot sends:
+    Message 1: "When are you checking in? 📅"
+    Message 2: Quick replies:
+      [Tonight] [Tomorrow] [This weekend] [Next week] [Next month] [📅 Pick date]
+    "Pick date" opens Messenger Webview with a mini date-picker
+    After check-in: same pattern for check-out
+
+  STEP 3 — Guests
+  Bot sends:
+    Message 1: "How many guests? 👥"  
+    Message 2: Quick replies: [1 Guest] [2 Guests] [3 Guests] [4 Guests] [4+ Guests]
+    If "4+ Guests": ask for number (free text)
+
+  STEP 4 — Optional filters (show as collapsible)
+  Bot sends:
+    Message 1: "Any preferences? (optional)"
+    Message 2: Quick replies:
+      [⭐ 3 Stars] [⭐⭐ 4 Stars] [⭐⭐⭐ 5 Stars] [🍳 Breakfast incl.] 
+      [🏊 Pool] [💼 Business] [Skip filters →]
+
+  STEP 5 — Results (hotel cards carousel)
+  Show top 3 hotel cards first.
+  After cards, send quick replies:
+    [Show 4 more →] [Change filters 🔧] [New search 🔄] [Sort by price ↕]
+
+SEARCH BACKEND (hf_space/routers/search.py):
+  POST /api/search/hotels
+    Input: {psid, city, check_in, check_out, num_guests, filters{stars, max_price, amenities}}
+    
+    1. Auto-detect currency from user profile → convert prices for display
+    2. Auto-detect timezone → validate dates are in the future for user's timezone
+    3. Call Elasticsearch with bool query + geo-distance + availability filter
+    4. Call ranker.py: score = 0.4*ES + 0.3*rating + 0.2*availability + 0.1*personalization
+    5. For returning users: fetch preference vector from Qdrant, boost personalization
+    6. Return top 10 hotels formatted for hotel_cards() builder
+    
+  GET /api/search/suggest?query={partial_city}&lang={lang}
+    Returns city autocomplete suggestions (from pre-loaded city list in Redis)
+    Used by Webview mini search input
+
+  SMART FEATURES:
+    - If city not found in ES: suggest closest alternative ("Did you mean Dubai? 🤔")
+    - If no availability for dates: show "sold out" message + suggest ±3 days alternatives
+    - If < 3 results: automatically expand star rating filter by ±1 and notify user
+    - Cache search results in Redis: search:{city}:{check_in}:{check_out} EX 300 (5 min)
+
+State after search: set Redis user:{psid}:state = "viewing_hotels"
+                   set Redis user:{psid}:last_search = {city, dates, guests}
+```
+
+---
+
+### 🔵 TASK PROMPT 3 — MODULE 3: ROOM SELECTION WITH SMART CARDS
+
+```
+TASK: Build Module 3 — Room Selection.
+
+Triggered when user clicks "✅ Select Hotel" button from hotel card (postback: HOTEL_SELECT_{id})
+
+CONVERSATION FLOW:
+
+  TRIGGER: postback payload = "HOTEL_SELECT_{hotel_id}"
+  
+  Bot immediately sends sequence:
+    Message 1: typing...
+    Message 2: "Great choice! Let me check available rooms at {hotel_name} 🏨"
+    Message 3: typing...
+    Message 4: Room cards carousel (top 3 rooms)
+    Message 5: Quick replies: [Show all rooms] [Back to hotels ←]
+
+  ROOM CARD FORMAT (per card):
+    Image: room thumbnail from Supabase Storage
+    Title: "Deluxe King Room • 42m²"
+    Subtitle: "🛏 King bed • 🛁 Bathtub • 🌆 City view • from ¥28,000/night"
+    Buttons:
+      [📸 See Photos]    → postback: ROOM_PHOTOS_{room_id}
+      [✅ Choose Room]   → postback: ROOM_SELECT_{room_id}
+      [ℹ️ Full Details]  → postback: ROOM_DETAILS_{room_id}
+
+  ON "See Photos" (postback: ROOM_PHOTOS_{room_id}):
+    Send up to 5 room images one by one
+    After last image: quick replies [✅ Choose This Room] [← Other Rooms]
+
+  ON "Full Details" (postback: ROOM_DETAILS_{room_id}):
+    Send list template with:
+      - Size, bed type, max guests
+      - Amenities (wifi, minibar, AC, safe, etc.)
+      - Cancellation policy for this room
+    Then quick replies: [✅ Choose Room] [← Back to Rooms]
+
+  ON "Choose Room" (postback: ROOM_SELECT_{room_id}):
+    STEP 1 — Rate plan selection
+    Message: "Which rate plan suits you? 🍽️"
+    Quick replies:
+      [🛏 Room Only  ¥28,000]
+      [☕ With Breakfast  ¥32,000]
+      [🌮 Half Board  ¥38,000]
+      [🍽 Full Board  ¥45,000]
+    
+    STEP 2 — After rate selected: ACQUIRE SOFT LOCK immediately
+      Call hf_space POST /api/rooms/soft_lock
+      If lock fails (race condition): "Room just got reserved by someone else!
+        Let me find the next best option..." → show next available room
+
+    STEP 3 — Show price summary before proceeding
+    Message: "📋 Your selection:"
+    List template:
+      Hotel: Grand Tokyo Hotel ⭐⭐⭐⭐⭐
+      Room: Deluxe King Room • City View
+      Plan: Breakfast Included
+      Check-in: Fri, 15 Mar 2026
+      Check-out: Sun, 17 Mar 2026
+      Total: ¥64,000 (~$427 USD)
+    Quick replies: [✅ Looks Good!] [✏️ Change Room] [❌ Start Over]
+
+BACKEND (hf_space/routers/rooms.py):
+  GET /api/rooms/{hotel_id}?check_in=&check_out=&guests=
+    Returns available rooms with real-time availability from Supabase
+    
+  POST /api/rooms/soft_lock
+    Input: {room_type_id, date_range, psid, lock_minutes=15}
+    Upstash Redis SET with NX flag (atomic)
+    Lua script for multi-date atomic lock
+    Returns: {locked: bool, expires_at, lock_id}
+    
+  POST /api/rooms/refresh_lock
+    Called every 5 min during payment to extend lock
+    Input: {lock_id, psid}
+
+State: user:{psid}:state = "rate_selected"
+       user:{psid}:booking_draft = {hotel_id, room_type_id, rate_plan, check_in, check_out, total}
+```
+
+---
+
+### 🔵 TASK PROMPT 4 — MODULE 4: GUEST FORM (CONVERSATIONAL, BUTTON-ASSISTED)
+
+```
+TASK: Build Module 4 — Guest Information Collection, conversational with max button use.
+
+NEVER show a web form. Collect everything through chat conversation.
+One question per message. Validate immediately. Show friendly error, re-ask once.
+
+CONVERSATION FLOW:
+
+  Triggered after rate_selected state confirmed.
+
+  Q1 — Name
+  "What's your name? 👤"
+  [Free text — no buttons here]
+  Validation: min 2 chars each part, no numbers, strip whitespace
+  
+  Q2 — Email  
+  "What email should I send your booking confirmation to? 📧"
+  [Free text]
+  Validation: RFC-5322 regex, detect common typos (gmail.con → gmail.com)
+  On typo: "Did you mean {corrected}? 🤔"
+  Quick replies: [Yes, use {corrected}] [No, let me retype]
+  
+  Q3 — Phone
+  "Your phone number? (with country code) 📱"
+  [Free text]
+  Auto-detect country code from user's FB locale if possible
+  Show hint: "e.g. +1 555 123 4567 (US) or +44 7700 900123 (UK)"
+  Validation: phonenumbers library → E.164 format
+  
+  Q4 — Trip Purpose (ALL BUTTONS)
+  "What brings you to {city}? ✈️"
+  Quick replies:
+    [🏖 Leisure] [💍 Honeymoon] [👨‍👩‍👧 Family Trip]
+    [💼 Business] [🎓 Study/Conference] [🏥 Medical]
+  
+  Q5 — Dietary needs (ALL BUTTONS)
+  "Any dietary requirements? 🍽️"
+  Quick replies:
+    [🚫 None] [🥗 Vegetarian] [🌱 Vegan] [🕌 Halal]
+    [✡️ Kosher] [🚫🥜 Nut Allergy] [✏️ Other...]
+  
+  Q6 — Accessibility (ALL BUTTONS)
+  "Any accessibility needs? ♿"
+  Quick replies:
+    [None needed ✅] [Wheelchair access ♿] [Ground floor room 🔑]
+    [Visual assistance 👁️] [Hearing assistance 👂] [✏️ Specify...]
+
+  RETURNING USER SHORTCUT:
+  If user has booked before, show at start:
+    Message: "Use your saved details? 💾"
+    List template showing saved: Name, Email, Phone
+    Quick replies: [✅ Yes, use saved] [✏️ Update details]
+    
+  PASSPORT OCR SHORTCUT (optional):
+    After name collected:
+    "Would you like to scan your passport for faster check-in? 📷"
+    Quick replies: [📷 Scan Passport] [Skip for now →]
+    If scan: open Messenger camera / image picker
+    Process OCR in hf_space, pre-fill remaining fields
+
+BACKEND (hf_space/routers/guest.py):
+  POST /api/guest/validate
+    Input: {field: "email", value: "test@gmail.con", context: {}}
+    Returns: {valid: bool, normalized: "test@gmail.com", suggestion: "gmail.com", error: null}
+    
+  POST /api/guest/ocr_passport
+    Input: {image_url: "messenger CDN URL", psid}
+    Fetch image from Messenger CDN → pre-process → Tesseract MRZ
+    Returns extracted fields with confidence scores
+    
+  POST /api/guest/save_profile
+    Input: all validated guest fields + psid
+    Upsert Supabase guests table WHERE messenger_psid = psid
+    Update Redis user:{psid}:profile with name, email, phone
+
+State: user:{psid}:state = "guest_complete"
+       user:{psid}:guest_data = {validated guest fields JSON}
+```
+
+---
+
+### 🔵 TASK PROMPT 5 — MODULE 5: ADD-ONS WITH SMART RECOMMENDATIONS
+
+```
+TASK: Build Module 5 — Add-Ons & Upsell, personalised and button-driven.
+
+Triggered after guest_complete state.
+
+CONVERSATION FLOW:
+
+  SMART OPENER (personalised by trip_purpose):
+  
+  IF honeymoon:
+    Message 1: "Since it's a special occasion 💍, I've picked these for you:"
+    Message 2: Generic cards (3 items):
+      Card 1: 🥂 Champagne Welcome — $45
+              "Chilled champagne + chocolates waiting in your room"
+              [Add to Booking ✅] [Tell me more ���]
+      Card 2: 🛁 Rose Petal Turndown — $35
+              "Romantic rose petal room setup at evening turndown"
+              [Add to Booking ✅] [Tell me more 💬]
+      Card 3: 💆 Couples Spa 60min — $120
+              "Private couples treatment at the hotel spa"
+              [Add to Booking ✅] [Tell me more 💬]
+    After cards:
+    Quick replies: [See all add-ons 📋] [Skip add-ons →] [Add all 3! 🎁]
+    
+  IF family:
+    Show: Extra bed, Kids club, Airport family transfer, Babysitting
+    
+  IF business:
+    Show: Late checkout (2pm), Meeting room (2h), Airport sedan transfer, Laundry
+
+  ON "Tell me more":
+    Send 2-3 line description from addons table
+    Quick replies: [Add this ✅] [No thanks ❌]
+    
+  ON "See all add-ons":
+    Show categories as list template:
+      🧖 Spa & Wellness
+      🍽️ Dining & Drinks  
+      🚗 Transport
+      🎯 Activities
+      🛏️ Room Extras
+    User taps category → carousel of items in that category
+
+  CART SUMMARY (after each add):
+    Message: "✅ Added! Your extras so far:"
+    List template showing cart items with prices
+    Quick replies: [Continue adding 🛍️] [Proceed to payment →]
+
+BACKEND (hf_space/routers/addons.py):
+  GET /api/addons/recommend
+    Input: {hotel_id, trip_purpose, num_children, psid}
+    Query Supabase addons by hotel + trip_purpose_tags match
+    Return top 3 with score multiplier applied
+    
+  POST /api/addons/cart/add
+    Input: {psid, addon_id}
+    Append to Redis user:{psid}:addon_cart (JSON list)
+    
+  POST /api/addons/cart/remove
+    Input: {psid, addon_id}
+    Remove from Redis list
+    
+  GET /api/addons/cart/{psid}
+    Returns full cart with live prices and subtotal
+
+State: user:{psid}:state = "addons_complete"
+       user:{psid}:addon_cart = [{addon_id, name, price, currency}]
+```
+
+---
+
+### 🔵 TASK PROMPT 6 — MODULE 6: PAYMENT FLOW (SECURE, BUTTON-DRIVEN)
+
+```
+TASK: Build Module 6 — Payment, fully secure with Stripe, button-driven UX.
+
+CRITICAL SECURITY: Card data NEVER touches Render or HF Space.
+Stripe.js tokenizes on client side inside a Messenger Webview popup.
+
+CONVERSATION FLOW:
+
+  STEP 1 — Full booking summary BEFORE payment
+  Bot sends sequence:
+    Message 1: "📋 Let's review your booking before payment:"
+    Message 2: Generic template (1 card — booking summary card):
+      Image: hotel main photo
+      Title: "Grand Tokyo Hotel ⭐⭐⭐⭐⭐"
+      Subtitle: "Deluxe King · 15-17 Mar · 2 guests · Breakfast"
+      Button: [📋 View Full Details]   → postback BOOKING_SUMMARY_FULL
+    Message 3: Text: "💰 Total: ¥64,000 (~$427 USD) for 2 nights"
+    Message 4: Quick replies:
+      [💳 Pay Now] [✏️ Change something] [❌ Cancel]
+      
+  IF "Change something":
+    Quick replies:
+      [📅 Change Dates] [🛏 Change Room] [👤 Edit Guest Info] [🛍 Edit Add-ons]
+    Route to appropriate state based on selection
+
+  STEP 2 — Payment method selection
+  After "Pay Now":
+    Message: "Choose payment method 💳"
+    Quick replies:
+      [💳 Credit / Debit Card]
+      [🍎 Apple Pay]
+      [🤖 Google Pay]
+      
+  STEP 3 — Stripe Webview (for card payment)
+  Send Messenger button template:
+    Message: "Tap below to enter your card securely 🔒"
+    Button: [Open Secure Payment →] (web_url type, opens Webview)
+    URL: https://{hf_space_url}/pay_webview?booking_draft_id={id}&psid={psid}
+    
+  hf_space/static/pay_webview.html:
+    - Loads Stripe.js
+    - Shows hotel name + amount (from booking_draft in Redis)
+    - Stripe Elements card input (tokenizes client-side)
+    - On submit: POST stripe_token to HF Space /api/payment/process
+    - On success: closes Webview, sends postback PAYMENT_SUCCESS to Render webhook
+    - On fail: shows error in Webview, allows retry (max 3 attempts)
+    
+  STEP 4 — Fraud check + charge (server-side in HF Space)
+  POST /api/payment/process:
+    1. fraud_check.py: calculate risk score
+    2. If risk >= 71: block, message user "Payment flagged. Contact support."
+    3. If risk 31-70: require Stripe 3DS (return client_secret to Webview)
+    4. If risk < 31: charge immediately
+    5. On Stripe success: 
+       - Save to Supabase payments table
+       - Generate booking_reference: HTL-{YEAR}-{6-char random uppercase}
+       - Update bookings table status='confirmed'
+       - Publish Kafka 'payment.completed' event
+    6. Return {success: true, booking_reference: "HTL-2026-XYZABC"}
+
+  STEP 5 — Post-payment (after PAYMENT_SUCCESS postback received by Render)
+  Bot sends sequence (all within 30 seconds):
+    Message 1: "🎉 Booking confirmed! Reference: HTL-2026-XYZABC"
+    Message 2: QR code image (generated in HF Space, stored in Supabase Storage)
+    Message 3: "📄 Your booking voucher is ready:"
+    Message 4: File attachment — PDF voucher from Supabase Storage
+    Message 5: Quick replies:
+      [📅 Add to Calendar] [🗺 Get Directions] [🌤 Weather Forecast]
+      [🏨 Hotel Contact] [📤 Share Booking] [🏠 Back to Menu]
+    
+  CONFIRMATION EMAIL: trigger async via hf_space/routers/notification.py
+
+BACKEND (hf_space/routers/payment.py):
+  POST /api/payment/process
+    Full fraud check + Stripe charge as described above
+    
+  POST /api/payment/webhook (Stripe webhooks)
+    Verify HMAC signature FIRST — reject if invalid
+    Handle: payment_intent.succeeded, payment_intent.payment_failed
+    
+  GET /api/payment/pay_webview
+    Render static HTML page with Stripe Elements
+    Loads booking draft from Redis by booking_draft_id
+    Shows amount in user's currency
+```
+
+---
+
+### 🔵 TASK PROMPT 7 — MODULES 8 & 9: MODIFY + CANCEL WITH SMART POLICY
+
+```
+TASK: Build Modules 8 & 9 — Booking Modification and Cancellation.
+
+Triggered from "My Bookings" menu or user saying "change/cancel my booking".
+
+MY BOOKINGS FLOW:
+  User taps "📋 My Bookings" from Persistent Menu
+  
+  If no bookings: "You don't have any bookings yet. Start searching? 🔍"
+                  Quick replies: [🔍 Search Hotels] [🏠 Main Menu]
+  
+  If 1 booking: Show it directly as a card
+  
+  If multiple: Show list template with up to 4 recent bookings
+    Each item: "Grand Tokyo · 15 Mar - 17 Mar · HTL-2026-XYZ"
+    Button: [View & Manage]
+
+  BOOKING DETAIL VIEW (single booking card):
+    Card buttons:
+      [✏️ Modify Booking] → postback BOOKING_MODIFY_{booking_id}
+      [❌ Cancel Booking] → postback BOOKING_CANCEL_{booking_id}
+      [📞 Contact Hotel]  → postback BOOKING_CONTACT_{hotel_id}
+
+MODIFICATION FLOW:
+
+  ON postback BOOKING_MODIFY_{booking_id}:
+    1. Fetch booking from Supabase
+    2. Call policy_engine.py → get allowed changes
+    3. Message: "What would you like to change? ✏️"
+    4. Quick replies (show only allowed options based on policy):
+       [📅 Change Dates] [🛏 Change Room Type] [👥 Change Guest Count]
+       [🍽 Change Meal Plan] [🛍 Edit Add-ons] [← Back]
+
+    ON "Change Dates":
+      Show current dates, ask for new check-in (same button flow as Module 2 Step 2)
+      After new dates: call rebooking.py
+      If price_diff > 0: "New dates cost ¥12,000 more. Proceed?"
+                         Quick replies: [✅ Pay Difference ¥12,000] [❌ Keep Original Dates]
+      If price_diff < 0: "New dates are ¥8,000 cheaper! You'll get a refund."
+                         Quick replies: [✅ Confirm Change] [❌ Keep Original]
+      If not available: "Sorry, {room_type} is sold out for new dates."
+                         Quick replies: [🔄 Try Other Dates] [🛏 Try Different Room]
+
+    ON fee applicable:
+      ALWAYS show: "⚠️ A modification fee of ${fee} applies for changes within {days} days."
+      Quick replies: [✅ Accept Fee & Continue] [❌ Keep Booking As Is]
+
+CANCELLATION FLOW:
+
+  ON postback BOOKING_CANCEL_{booking_id}:
+    1. Call refund_engine.py → calculate refund FIRST
+    2. Bot ALWAYS shows refund amount BEFORE asking to confirm:
+    
+    Full refund case:
+      "Your booking qualifies for a full refund ✅
+       💰 Refund: ¥64,000 → back to your card in 5-10 days
+       Reference: HTL-2026-XYZ"
+      Quick replies: [✅ Confirm Cancellation] [❌ Keep Booking]
+      
+    Partial refund case:
+      "⚠️ Cancellation within {days} days:
+       💰 Refund: ¥32,000 (50%) — ¥32,000 is non-refundable"
+      Quick replies: [✅ Confirm & Get ¥32,000 Back] [❌ Keep Booking]
+      
+    No refund case:
+      "⚠️ Non-refundable booking:
+       💰 Refund: ¥0 (0%) — rate plan is non-refundable"
+      Quick replies: [✅ Cancel Anyway (No Refund)] [❌ Keep Booking]
+    
+    ON confirm: ask reason (for analytics)
+      Quick replies: [🗓 Date changed] [✈️ Flight issue] [💸 Price concern]
+                     [😷 Health/Emergency] [🔄 Found better hotel] [❌ Skip]
+
+BACKEND (hf_space/routers/modification.py + cancellation.py):
+  Already defined in SKILL.md — implement policy_engine, rebooking, refund_engine, stripe_refund.
+  All policy rules fetch from Supabase hotels.cancellation_policy JSONB column.
+```
+
+---
+
+### 🔵 TASK PROMPT 8 — MODULE 11: FAQ RAG WITH SMART ROUTING
+
+```
+TASK: Build Module 11 — FAQ & RAG pipeline with smart question routing.
+
+Triggered when: user asks a question about a specific hotel (any language).
+Context needed: user must have a hotel_id in their current session.
+
+CONVERSATION FLOW:
+
+  FAQ CATEGORY SHORTCUT (proactive, after hotel selection):
+  After user selects a hotel (before room selection):
+    Bot sends: "Got any questions about {hotel_name}? I can help! 💬"
+    List template with FAQ categories:
+      🏊 Facilities (pool, gym, spa)
+      🍽️ Dining (restaurants, breakfast, room service)
+      🚗 Transport (airport transfer, parking)
+      🛎️ Services (check-in, concierge, late checkout)
+      💳 Policies (cancellation, pets, children)
+    Global button: [No questions, continue booking →]
+    
+  ON category tap OR free text question:
+    1. Embed question via LaBSE (HF Space model — already loaded)
+    2. Search Qdrant hotel_faqs with hotel_id filter, top_k=3
+    3. If Qdrant score > 0.85: return direct answer (no LLM needed, fast)
+    4. If 0.6 < score < 0.85: send to Groq Llama 3 with context
+    5. If score < 0.6: "I don't have that info, but here's the hotel's contact:"
+                       + contact buttons
+    6. Translate answer to user's detected language via translator.py
+    
+  ANSWER FORMAT:
+    Message 1: Answer text (in user's language)
+    Message 2: Quick replies:
+      [🙋 Another question] [✅ Continue booking] [📞 Ask hotel directly]
+    
+  VOICE QUESTION SUPPORT:
+    If user sends voice message while browsing hotel:
+      1. Transcribe via Whisper (already loaded in HF Space)
+      2. Show transcription: "You asked: '{transcript}'"
+      3. Process through RAG as normal
+      4. Offer TTS response: quick reply [🔊 Hear answer]
+
+BACKEND (hf_space/routers/rag.py):
+  POST /api/rag/ask
+    Input: {question, hotel_id, psid, language}
+    1. embed question: labse_model.encode([question])
+    2. qdrant_client.search(collection="hotel_faqs", vector=embedding, 
+                             filter={"hotel_id": hotel_id}, limit=3)
+    3. If best_score > 0.85: return top result payload.answer directly
+    4. Else: groq_client.chat.completions.create(
+               model="llama3-70b-8192",
+               messages=[{"role": "system", "content": concierge_prompt},
+                          {"role": "user", "content": f"Context: {chunks}\n\nQuestion: {question}"}]
+             )
+    5. translator.translate(answer, target_lang=language) if language != "en"
+    6. Return {answer, source: "direct"|"rag"|"fallback", confidence}
+    
+  POST /api/rag/onboard_hotel
+    Input: {hotel_id, faqs: [{question, answer, category}]}
+    Batch embed all FAQs with LaBSE
+    Upsert to Qdrant hotel_faqs collection with hotel_id filter
+    Called by hotel_onboarding.py script
+```
+
+---
+
+### 🔵 TASK PROMPT 9 — MODULE 10: LOYALTY WITH GAMIFICATION BUTTONS
+
+```
+TASK: Build Module 10 — Loyalty & Gamification, fully surfaced through Messenger buttons.
+
+LOYALTY CHECK FLOW (triggered by "My Rewards" menu or asking about points):
+
+  Bot sends sequence:
+    Message 1: "🏆 Your Loyalty Status"
+    Message 2: Generic template card:
+      Image: tier badge image from Supabase Storage (bronze/silver/gold/platinum/black)
+      Title: "Ahmed Al-Rashidi • Gold Member"
+      Subtitle: "⭐ 14,392 points · {points_needed} to Platinum"
+      Buttons:
+        [🎁 Redeem Points] → postback LOYALTY_REDEEM
+        [📊 Points History] → postback LOYALTY_HISTORY
+        [🎖 My Badges]    → postback LOYALTY_BADGES
+    Message 3: Progress bar text:
+      "Gold ████████░░ Platinum — 3,608 pts to go!"
+    Message 4: Quick replies:
+      [🎁 Redeem Points] [👥 Refer a Friend] [📜 Tier Benefits] [🏠 Main Menu]
+
+  ON "Tier Benefits":
+    List template with benefits for current + next tier
+    Global button: [How to earn more points →]
+    
+  ON "My Badges" (postback LOYALTY_BADGES):
+    Carousel showing earned badges as cards
+    Each card: badge image, name, how it was earned, date
+    Unearned badges shown as "locked" with earn conditions
+    Quick replies: [🏠 Main Menu] [🔍 Search Hotels]
+
+  ON "Refer a Friend":
+    Message: "Share this link and earn 200 points when they book! 🎉"
+    Send referral link + quick reply: [📋 Copy Link] [📤 Share]
+
+  PROACTIVE LOYALTY (after booking confirmed):
+  Automatically send:
+    "🎉 You earned 842 points for this booking!
+     New balance: 14,392 points (Gold tier)
+     You're 3,608 points from Platinum — 2 more bookings could get you there! 🚀"
+    Quick replies: [🏆 View Rewards] [🏠 Main Menu]
+
+  TIER UPGRADE NOTIFICATION:
+  On Kafka 'loyalty.tier_upgraded' event:
+    Send proactive message to user:
+    "🌟 CONGRATULATIONS! You've reached {new_tier} status!
+     {tier_specific_welcome_message}"
+    Send tier badge image
+    Quick replies: [🎁 See New Benefits] [🏠 Main Menu]
+
+BACKEND (hf_space/routers/loyalty.py):
+  POST /api/loyalty/award
+    Input: {psid, booking_id, booking_total, currency}
+    Calculate points via points_engine.py
+    Update Supabase loyalty_accounts + loyalty_transactions
+    Check tier upgrade via tier_engine.py
+    Award badges via gamification.py
+    Return {points_earned, new_balance, tier_changed, badges_awarded}
+    
+  GET /api/loyalty/profile/{psid}
+    Returns full loyalty profile for display
+    
+  POST /api/loyalty/redeem
+    Input: {psid, points_to_redeem, booking_id}
+    Validate points balance
+    Apply discount to booking
+    Update loyalty_accounts
+```
+
+---
+
+### 🔵 TASK PROMPT 10 — MODULE 13: HUMAN HANDOFF + MODULE 12: REVIEWS
+
+```
+TASK: Build Module 13 (Human Handoff via Chatwoot) and Module 12 (Post-Stay Reviews).
+
+HANDOFF FLOW:
+
+  TRIGGERS (any of these):
+  - User types: "talk to human", "real agent", "help me please" (intent: intent_human_handoff)
+  - FallbackClassifier fires 2 consecutive times
+  - User sends angry sentiment detected by sentiment.py (score < 0.2)
+  - User asks same question 3 times without booking progressing
+
+  Bot sends:
+    Message 1: "I'll connect you with a live agent right away! 🙋"
+    Message 2: "Estimated wait: ~{wait_time} minutes"
+    Message 3: Quick replies: 
+      [📞 Connect Now] [💬 Keep trying with AI] [📩 Email instead]
+    
+  ON "Connect Now":
+    1. Call /api/handoff/create with full conversation history
+    2. Create Chatwoot conversation with language-matched agent queue
+    3. Post all Messenger messages as initial Chatwoot note
+    4. Set Redis user:{psid}:state = "handoff_active"
+    5. Set Redis user:{psid}:handoff_active = "true"
+    6. Message: "✅ Connected! Reference: CHAT-{id}
+                 Agent {name} will be with you shortly.
+                 I'll be quiet until they're done helping you."
+    
+  WHILE handoff_active:
+    All incoming Messenger messages relay to Chatwoot conversation via API
+    All Chatwoot agent messages relay back to Messenger
+    Bot does NOT process any NLU during handoff
+    
+  ON Chatwoot resolved webhook:
+    1. Clear Redis user:{psid}:handoff_active
+    2. Set user:{psid}:state = "post_handoff"
+    3. Message: "Welcome back! Your issue has been resolved. 😊"
+    4. Quick replies: [🔍 Search Hotels] [📋 My Bookings] [🏠 Main Menu]
+
+REVIEW FLOW (automated, 24h after checkout):
+
+  Celery beat task triggers:
+    1. Query Supabase: bookings where check_out + 24h <= now AND review_requested = false
+    2. For each: call /api/review/send_request
+    
+  Review Request Message:
+    Message 1: "How was your stay at {hotel_name}? We'd love your feedback! 🌟"
+    Message 2: "Rate your overall experience:"
+    Quick replies (star ratings):
+      [⭐ Poor] [⭐⭐ Fair] [⭐⭐⭐ Good] [⭐⭐⭐⭐ Great] [⭐⭐⭐⭐⭐ Excellent!]
+    [Skip review →]
+    
+  AFTER STAR RATING (e.g., user clicks ⭐⭐⭐⭐ Great):
+    Message: "Thanks! Rate specific aspects:"
+    Multiple quick reply sequences (one per aspect):
+      "🛏️ Room quality?"  → [⭐ Poor] [⭐⭐⭐ OK] [⭐⭐⭐⭐⭐ Great]
+      "🍽️ Dining?"        → [⭐ Poor] [⭐⭐⭐ OK] [⭐⭐⭐⭐⭐ Great] [N/A]
+      "🤝 Staff service?" → [⭐ Poor] [⭐⭐⭐ OK] [⭐⭐⭐⭐⭐ Great]
+      "📍 Location?"      → [⭐ Poor] [⭐⭐⭐ OK] [⭐⭐⭐⭐⭐ Great]
+    
+    Then: "Any comments? (optional)"
+    Quick replies: [Skip ✓] OR user types free text
+    
+  AFTER REVIEW SUBMITTED:
+    1. Run sentiment.py on review text (if provided)
+    2. If negative (score < 0.3): Kafka 'review.negative_alert' → hotel partner
+    3. Award 50 loyalty points: "🎉 +50 loyalty points for your review!"
+    4. Message: "Thanks {name}! Your feedback helps millions of travelers. 🙏"
+    Quick replies: [🔍 Search Hotels] [🏆 My Rewards] [🏠 Main Menu]
+
+BACKEND (hf_space/routers/reviews.py + handoff.py):
+  POST /api/review/submit
+    Input: {psid, booking_id, overall_score, aspect_scores, review_text}
+    Insert into Supabase reviews table
+    Run sentiment.py
+    Award points via loyalty service
+    
+  POST /api/handoff/create
+    Create Chatwoot conversation
+    Post history
+    Return {conversation_id, agent_name, wait_time}
+    
+  POST /api/handoff/relay_message
+    Input: {chatwoot_conversation_id, message_text, from_agent: bool}
+    If from_agent: forward to Messenger via Graph API
+    If from_user: forward to Chatwoot via API
+```
+
+---
+
+### 🔵 TASK PROMPT 11 — VOICE INTERACTION COMPLETE SETUP
+
+```
+TASK: Add full voice interaction support within the single HuggingFace Space.
+
+Voice is delivered via Messenger's native audio message support + a Webview for recording.
+
+HOW MESSENGER VOICE WORKS:
+  Option A — User sends voice note in Messenger:
+    Messenger delivers audio as: {"message": {"attachments": [{"type": "audio", "payload": {"url": "..."}}]}}
+    Render webhook detects audio attachment → sends audio_url to HF Space /api/process_message
+    HF Space fetches audio from Messenger CDN → feeds to Faster-Whisper → processes as text
+    
+  Option B — User taps 🎙️ button to open voice Webview:
+    Opens hf_space/static/voice_webview.html
+    MediaRecorder API captures audio in browser
+    Sends audio blob to HF Space /api/voice/transcribe in real-time
+    Returns transcript → shown in webview → auto-submitted to main flow
+
+VOICE INPUT (hf_space/routers/voice.py):
+  POST /api/voice/transcribe
+    Input: audio file (multipart) OR {audio_url: "messenger CDN URL"}
+    
+    If audio_url: 
+      async download with httpx (Messenger CDN requires no auth)
+      Convert to 16kHz mono WAV using pydub in-memory (NO ffmpeg subprocess — use pydub.AudioSegment)
+      
+    transcribe with faster_whisper model (loaded at startup)
+    segments, info = whisper_model.transcribe(wav_bytes, beam_size=5, language=None)
+    
+    If info.language_probability < 0.6:
+      Return {success: false, message: "Could not understand audio. Please try again."}
+    
+    Store detected language in Upstash Redis (override if different from profile lang)
+    Return {transcript, language, confidence}
+
+VOICE OUTPUT (TTS via Groq/external):
+  DO NOT load local TTS model (too heavy for HF Space).
+  Use: Edge-TTS (Microsoft Azure free tier, no API key needed)
+    import edge_tts
+    voice map by language:
+      en → en-US-JennyNeural (female) or en-US-GuyNeural (male)
+      ar → ar-SA-ZariyahNeural
+      fr → fr-FR-DeniseNeural
+      es → es-ES-ElviraNeural
+      zh → zh-CN-XiaoxiaoNeural
+      ja → ja-JP-NanamiNeural
+      hi → hi-IN-SwaraNeural
+      (add all 15 Tier 1 languages)
+    
+    async def text_to_speech(text: str, language: str, gender: str = "female") -> bytes:
+      voice = VOICE_MAP.get(f"{language}_{gender}", "en-US-JennyNeural")
+      communicate = edge_tts.Communicate(text, voice)
+      audio_bytes = b""
+      async for chunk in communicate.stream():
+          if chunk["type"] == "audio":
+              audio_bytes += chunk["data"]
+      return audio_bytes  # MP3 bytes
+      
+  Cache TTS in Upstash Redis:
+    key: tts:{lang}:{gender}:{sha256(text)[:16]} 
+    Store base64-encoded MP3, EX 86400
+    Check cache before generating
+
+VOICE UX RULE:
+  - Never send ONLY audio — always include text first
+  - After text response, add [🔊 Hear this] quick reply
+  - When user clicks: generate TTS → upload to Supabase Storage → send as Messenger audio attachment
+  - Voice input always shows transcript back to user: "I heard: '{transcript}'"
+
+POST /api/voice/speak
+  Input: {text, language, gender, psid}
+  Check TTS cache
+  Generate via edge_tts if cache miss
+  Upload MP3 to Supabase Storage bucket "tts-audio" with 1-hour expiry
+  Return {audio_url} to Render webhook which sends as Messenger audio attachment
+```
+
+---
+
+### 🔵 TASK PROMPT 12 — RENDER WEBHOOK (THIN RELAY ONLY)
+
+```
+TASK: Build the Render webhook — a thin relay with NO heavy processing.
+
+Render has limited RAM. This service does EXACTLY 3 things:
+  1. Receive Facebook Messenger webhook events
+  2. Forward to HF Space for processing
+  3. Send HF Space response back to Messenger
+
+File: render_webhook/main.py
+
+from fastapi import FastAPI, Request, HTTPException, BackgroundTasks
+import httpx, hmac, hashlib, asyncio, os
+
+app = FastAPI()
+HF_SPACE_URL = os.environ["HF_SPACE_URL"]  # full HF Space URL
+PAGE_ACCESS_TOKEN = os.environ["FACEBOOK_PAGE_ACCESS_TOKEN"]
+APP_SECRET = os.environ["FACEBOOK_APP_SECRET"]
+VERIFY_TOKEN = os.environ["FACEBOOK_VERIFY_TOKEN"]
+GRAPH_API = "https://graph.facebook.com/v18.0/me/messages"
+
+@app.get("/webhooks/messenger/webhook")
+async def verify_webhook(request: Request):
+    """Facebook webhook verification — one-time setup"""
+    params = dict(request.query_params)
+    if params.get("hub.mode") == "subscribe" and params.get("hub.verify_token") == VERIFY_TOKEN:
+        return int(params["hub.challenge"])
+    raise HTTPException(status_code=403)
+
+@app.post("/webhooks/messenger/webhook")  
+async def receive_message(request: Request, background_tasks: BackgroundTasks):
+    """
+    Receive Messenger events.
+    MUST return 200 OK within 200ms (before FB's 5-second timeout).
+    All processing happens in background task.
+    """
+    # Verify Facebook signature
+    signature = request.headers.get("X-Hub-Signature-256", "")
+    body = await request.body()
+    expected = "sha256=" + hmac.new(APP_SECRET.encode(), body, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(signature, expected):
+        raise HTTPException(status_code=403, detail="Invalid signature")
+    
+    data = await request.json()
+    background_tasks.add_task(process_webhook_event, data)
+    return {"status": "ok"}  # Return immediately
+
+async def process_webhook_event(data: dict):
+    """Run in background — no time pressure"""
+    for entry in data.get("entry", []):
+        for messaging in entry.get("messaging", []):
+            psid = messaging["sender"]["id"]
+            
+            # Build HF Space request payload
+            hf_payload = {
+                "psid": psid,
+                "message_type": "text",
+                "timestamp": messaging.get("timestamp", 0)
+            }
+            
+            if "message" in messaging:
+                msg = messaging["message"]
+                if msg.get("text"):
+                    hf_payload["message_type"] = "text"
+                    hf_payload["text"] = msg["text"]
+                elif msg.get("attachments"):
+                    att = msg["attachments"][0]
+                    if att["type"] == "audio":
+                        hf_payload["message_type"] = "audio"
+                        hf_payload["audio_url"] = att["payload"]["url"]
+                    elif att["type"] == "image":
+                        hf_payload["message_type"] = "image"
+                        hf_payload["image_url"] = att["payload"]["url"]
+                        
+            elif "postback" in messaging:
+                hf_payload["message_type"] = "postback"
+                hf_payload["text"] = messaging["postback"]["payload"]
+            else:
+                return  # Skip delivery receipts, read receipts
+            
+            # Send typing indicator immediately (shows user bot is working)
+            await send_to_messenger([{
+                "recipient": {"id": psid},
+                "sender_action": "typing_on"
+            }])
+            
+            # Call HF Space
+            try:
+                async with httpx.AsyncClient(timeout=55.0) as client:
+                    resp = await client.post(f"{HF_SPACE_URL}/api/process_message", json=hf_payload)
+                    result = resp.json()
+                    messages = result.get("messages", [])
+            except httpx.TimeoutException:
+                messages = [{
+                    "recipient": {"id": psid},
+                    "message": {"text": "Sorry, I'm experiencing a delay. Please try again in a moment. 🔄"}
+                }]
+            
+            # Send all messages to Messenger in sequence
+            await send_to_messenger(messages)
+
+async def send_to_messenger(messages: list):
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        for msg in messages:
+            try:
+                await client.post(
+                    f"{GRAPH_API}?access_token={PAGE_ACCESS_TOKEN}",
+                    json=msg
+                )
+                if msg.get("sender_action") != "typing_on":
+                    await asyncio.sleep(0.6)
+            except Exception as e:
+                print(f"Messenger send error: {e}")
+
+# Health check endpoint
+@app.get("/health")
+async def health():
+    return {"status": "ok", "service": "messenger_relay"}
+
+# requirements.txt for Render (MINIMAL — low RAM):
+# fastapi==0.111.0
+# uvicorn==0.29.0
+# httpx==0.27.0
+# python-multipart==0.0.9
+# (nothing else — no ML libraries, no database drivers)
+```
+
+---
+
+### 🔵 TASK PROMPT 13 — CICD + ENVIRONMENT SETUP
+
+```
+TASK: Create complete CI/CD pipeline and environment configuration.
+
+File: .github/workflows/deploy.yml
+Triggers:
+  - Push to main → deploy HF Space + Render webhook
+  - Push to develop → run tests only, no deploy
+  - PR to main → run tests + lint, block merge if fail
+
+Jobs:
+  1. lint:
+     - ruff check . (Python linting)
+     - ruff format --check .
+     
+  2. test:
+     - pytest tests/ --cov=hf_space --cov-report=xml --cov-fail-under=70
+     - Test against real Supabase test project (SUPABASE_URL_TEST secret)
+     - Test against Stripe test mode (STRIPE_SECRET_KEY_TEST secret)
+     
+  3. deploy_hf_space (on main only, after test passes):
+     - Uses HuggingFace CLI to push to Space
+     - huggingface-cli upload {HF_USERNAME}/hotel-booking-ai ./hf_space .
+     - Wait for Space build to succeed (poll /health endpoint)
+     
+  4. deploy_render (on main only, after hf_space deploy):
+     - Trigger Render deploy hook (POST to Render deploy URL)
+     - Wait for health check at Render webhook /health
+     - Run smoke test: send test Messenger message, verify response
+
+File: .env.example (ALL variables documented):
+  # HuggingFace Space
+  HF_SPACE_URL=https://{username}-hotel-booking-ai.hf.space
+  HF_TOKEN=hf_xxxxxxxxxxxx
+  
+  # Upstash Redis (HTTPS-based, HF Space compatible)
+  UPSTASH_REDIS_URL=https://xxxx.upstash.io
+  UPSTASH_REDIS_TOKEN=xxxxxxxxxxxx
+  
+  # Supabase
+  SUPABASE_URL=https://xxxx.supabase.co
+  SUPABASE_ANON_KEY=eyJ...
+  SUPABASE_SERVICE_ROLE_KEY=eyJ...   # Server-side only
+  SUPABASE_DATABASE_URL=postgresql://...
+  
+  # Facebook / Messenger
+  FACEBOOK_PAGE_ACCESS_TOKEN=EAAxxxx
+  FACEBOOK_APP_SECRET=xxxx
+  FACEBOOK_VERIFY_TOKEN=your_chosen_string
+  WHATSAPP_PHONE_NUMBER_ID=xxxx
+  
+  # Groq (free LLM API)
+  GROQ_API_KEY=gsk_xxxx
+  
+  # Stripe
+  STRIPE_SECRET_KEY=sk_live_xxxx         # sk_test_ for development
+  STRIPE_PUBLISHABLE_KEY=pk_live_xxxx
+  STRIPE_WEBHOOK_SECRET=whsec_xxxx
+  
+  # Qdrant Cloud
+  QDRANT_URL=https://xxxx.qdrant.io
+  QDRANT_API_KEY=xxxx
+  
+  # Elasticsearch (Bonsai.io free tier)
+  ELASTICSEARCH_URL=https://xxxx.bonsai.io
+  ELASTICSEARCH_USER=xxxx
+  ELASTICSEARCH_PASS=xxxx
+  
+  # Notifications
+  SENDGRID_API_KEY=SG.xxxx
+  
+  # Chatwoot
+  CHATWOOT_API_URL=https://your-chatwoot.onrender.com
+  CHATWOOT_API_TOKEN=xxxx
+  CHATWOOT_ACCOUNT_ID=1
+  
+  # Kafka (Confluent Cloud free tier)
+  KAFKA_BOOTSTRAP_SERVERS=pkc-xxxx.confluent.cloud:9092
+  KAFKA_API_KEY=xxxx
+  KAFKA_API_SECRET=xxxx
+  
+  # ClickHouse Cloud
+  CLICKHOUSE_URL=https://xxxx.clickhouse.cloud:8443
+  CLICKHOUSE_USER=default
+  CLICKHOUSE_PASSWORD=xxxx
+  
+  # Open Exchange Rates (free tier)
+  OPEN_EXCHANGE_RATES_APP_ID=xxxx
+  
+  # HF Space URL (used by Render)
+  HF_SPACE_URL=https://{hf_username}-hotel-booking-ai.hf.space
+```
+
+---
+
+## ═══════════════════════════════════════════════
+## SECTION 7 — CODE QUALITY RULES (ALWAYS APPLY)
+## ═══════════════════════════════════════════════
+
+```
+When Copilot generates ANY code for this project, enforce these rules:
+
+1. ASYNC EVERYWHERE
+   All FastAPI endpoints and database calls MUST be async.
+   Use httpx.AsyncClient (never requests).
+   Use asyncpg or supabase-py async client.
+   Never use time.sleep() — use asyncio.sleep().
+
+2. TYPE HINTS ALWAYS
+   Every function signature must have complete type hints.
+   Return types must be specified.
+   Use Pydantic models for all FastAPI request/response bodies.
+
+3. ERROR HANDLING PATTERN
+   Every service call must have try/except with:
+     - Specific exception type (not bare Exception)
+     - Structured error response: {"error": "...", "code": "...", "fallback": "..."}
+     - Fallback behavior (never let an error crash the conversation)
+   
+4. LOGGING STANDARD
+   import structlog
+   log = structlog.get_logger()
+   Every endpoint logs: psid (hashed), intent, response_time_ms, success/fail
+   Never log: full card numbers, passwords, passport numbers, raw personal data
+
+5. ENVIRONMENT VARIABLES
+   Never hardcode ANY value that could differ between environments.
+   Never hardcode model names — always from os.environ with defaults.
+   Use pydantic-settings for config management.
+
+6. MESSENGER RESPONSE VALIDATION
+   Before returning ANY messages list:
+   - Verify no text > 2000 chars
+   - Verify no carousel > 10 cards  
+   - Verify no quick replies > 13
+   - Verify all button titles <= 20 chars
+   Use: from render_webhook.messenger_builder import validate_messages
+
+7. IDEMPOTENCY
+   All payment operations: idempotency_key = f"booking-{booking_id}"
+   All notification sends: check Redis "sent:{type}:{booking_id}" before sending
+   All Celery tasks: check idempotency key in Upstash Redis before executing
+
+8. STATE MACHINE
+   User conversation state MUST always be one of:
+   new | greeting | searching | viewing_hotels | selecting_room |
+   choosing_rate | filling_guest_form | selecting_addons | reviewing_booking |
+   paying | booking_confirmed | modifying | cancelling | faq_browsing |
+   handoff_active | post_stay_review | loyalty_browsing
+   
+   Every state transition must update: Upstash Redis user:{psid}:state
+   Invalid state transitions must log warning and reset to appropriate state.
+```
+
+---
+
+## ═══════════════════════════════════════════════
+## HOW TO USE THIS FILE WITH GITHUB COPILOT
+## ═══════════════════════════════════════════════
+
+```
+STEP 1 — Attach context before every session:
+  Open this file in VS Code.
+  In Copilot Chat, type:
+  "@workspace Using COPILOT_MASTER_PROMPT.md as full context, [paste task prompt]"
+
+STEP 2 — For new module work, paste ONE task prompt at a time:
+  Copy the exact text from "TASK PROMPT X" section above.
+  Paste into Copilot Chat.
+  Review generated code against SKILL.md rules before accepting.
+
+STEP 3 — For debugging / upgrading existing code:
+  "Using COPILOT_MASTER_PROMPT.md context, review [filename] and:
+   1. Check it follows all Code Quality Rules from Section 7
+   2. Ensure all Messenger responses use MessengerResponse builder
+   3. Verify button-first UX law (>50% interactions via buttons)
+   4. Confirm state transitions update Upstash Redis correctly"
+
+STEP 4 — For adding a feature not in this file:
+  "Using COPILOT_MASTER_PROMPT.md context, add [feature].
+   Constraints:
+   - Must run in HF Space (not Render)
+   - Must use Upstash Redis for state (not local Redis)
+   - Must return Messenger-formatted message objects
+   - Must follow button-first UX law
+   - Must handle users from any country/language automatically"
+```

hf_spaces/embeddings/app.py

@@ -0,0 +1,91 @@
+"""
+hf_spaces/embeddings/app.py
+------------------------------
+HuggingFace Space: LaBSE sentence embedding service.
+POST /embed  {"texts": ["..."]}  → {"embeddings": [[float, ...]]}
+POST /embed_one {"text": "..."}  → {"embedding": [float, ...]}
+"""
+
+import os
+import logging
+from typing import List
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+log = logging.getLogger(__name__)
+app = FastAPI(title="Embeddings Space")
+
+_model = None
+
+
+def _get_model():
+    global _model
+    if _model is None:
+        try:
+            from sentence_transformers import SentenceTransformer
+            _model = SentenceTransformer("sentence-transformers/LaBSE")
+            log.info("LaBSE model loaded")
+        except Exception as exc:
+            log.error("Could not load LaBSE: %s", exc)
+    return _model
+
+
+class EmbedRequest(BaseModel):
+    texts: List[str]
+
+
+class EmbedOneRequest(BaseModel):
+    text: str
+
+
+@app.on_event("startup")
+async def startup():
+    import threading
+    threading.Thread(target=_get_model, daemon=True).start()
+
+
+@app.post("/embed")
+def embed(req: EmbedRequest):
+    model = _get_model()
+    if model is None:
+        return {"embeddings": [], "error": "model_loading"}
+    embeddings = model.encode(req.texts, normalize_embeddings=True).tolist()
+    return {"embeddings": embeddings}
+
+
+@app.post("/embed_one")
+def embed_one(req: EmbedOneRequest):
+    model = _get_model()
+    if model is None:
+        return {"embedding": [], "error": "model_loading"}
+    vec = model.encode([req.text], normalize_embeddings=True)[0].tolist()
+    return {"embedding": vec}
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "model": "LaBSE", "loaded": _model is not None}
+
+
+# Gradio interface (for HF Space UI)
+import gradio as gr
+
+def gradio_embed(texts_str: str) -> str:
+    texts = [t.strip() for t in texts_str.split("\n") if t.strip()]
+    model = _get_model()
+    if not model:
+        return "Model loading..."
+    vecs = model.encode(texts, normalize_embeddings=True)
+    return str(vecs.tolist())
+
+demo = gr.Interface(
+    fn=gradio_embed,
+    inputs=gr.Textbox(lines=5, label="Enter texts (one per line)"),
+    outputs=gr.Textbox(label="Embeddings (JSON)"),
+    title="LaBSE Embeddings",
+)
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)

hf_spaces/llm/app.py

@@ -0,0 +1,136 @@
+"""
+hf_spaces/llm/app.py
+-----------------------
+HuggingFace Space: LLM inference for RAG (Llama 3 via transformers).
+Falls back to Groq API if local model OOMs.
+
+POST /generate {"prompt": "...", "max_tokens": 256}
+             → {"text": "...", "source": "local|groq"}
+"""
+
+import os
+import logging
+import threading
+from typing import Optional
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+log = logging.getLogger(__name__)
+app = FastAPI(title="LLM Space")
+
+MODEL_ID   = os.environ.get("LLM_MODEL_ID",    "meta-llama/Meta-Llama-3-8B-Instruct")
+GROQ_KEY   = os.environ.get("GROQ_API_KEY",    "")
+HF_TOKEN   = os.environ.get("HF_TOKEN",         "")
+_pipeline  = None
+_loading   = False
+
+
+def _load_model():
+    global _pipeline, _loading
+    _loading = True
+    try:
+        import torch
+        from transformers import pipeline as hf_pipeline, AutoTokenizer
+        tok    = AutoTokenizer.from_pretrained(MODEL_ID, token=HF_TOKEN)
+        _pipeline = hf_pipeline(
+            "text-generation",
+            model=MODEL_ID,
+            tokenizer=tok,
+            torch_dtype=torch.float16,
+            device_map="auto",
+            token=HF_TOKEN,
+        )
+        log.info("LLM %s loaded", MODEL_ID)
+    except Exception as exc:
+        log.warning("Local LLM unavailable: %s (Groq fallback will be used)", exc)
+    finally:
+        _loading = False
+
+
+@app.on_event("startup")
+async def startup():
+    threading.Thread(target=_load_model, daemon=True).start()
+
+
+class GenerateRequest(BaseModel):
+    prompt:     str
+    max_tokens: Optional[int] = 256
+    temperature: Optional[float] = 0.7
+
+
+def _groq_generate(prompt: str, max_tokens: int, temperature: float) -> str:
+    import json, urllib.request
+    payload = json.dumps({
+        "model":       "llama3-8b-8192",
+        "messages":    [{"role": "user", "content": prompt}],
+        "max_tokens":  max_tokens,
+        "temperature": temperature,
+    }).encode()
+    req = urllib.request.Request(
+        "https://api.groq.com/openai/v1/chat/completions",
+        data=payload,
+        headers={"Authorization": f"Bearer {GROQ_KEY}", "Content-Type": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        data = json.loads(resp.read())
+    return data["choices"][0]["message"]["content"]
+
+
+@app.post("/generate")
+def generate(req: GenerateRequest):
+    if _loading:
+        return {"text": "Model is warming up, please retry shortly.", "source": "loading"}
+
+    if _pipeline is not None:
+        try:
+            outputs = _pipeline(
+                req.prompt,
+                max_new_tokens=req.max_tokens,
+                temperature=req.temperature,
+                do_sample=True,
+                pad_token_id=_pipeline.tokenizer.eos_token_id,
+            )
+            text = outputs[0]["generated_text"][len(req.prompt):].strip()
+            return {"text": text, "source": "local"}
+        except Exception as exc:
+            log.warning("Local generation failed: %s", exc)
+
+    if GROQ_KEY:
+        try:
+            text = _groq_generate(req.prompt, req.max_tokens, req.temperature)
+            return {"text": text, "source": "groq"}
+        except Exception as exc:
+            log.error("Groq fallback failed: %s", exc)
+
+    return {"text": "I apologize, the AI service is temporarily unavailable.", "source": "fallback"}
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "loaded": _pipeline is not None, "loading": _loading,
+            "groq_available": bool(GROQ_KEY)}
+
+
+# Gradio UI
+import gradio as gr
+
+def gradio_generate(prompt_text, max_tokens, temperature):
+    result = generate(GenerateRequest(prompt=prompt_text, max_tokens=int(max_tokens), temperature=float(temperature)))
+    return result.get("text", "")
+
+demo = gr.Interface(
+    fn=gradio_generate,
+    inputs=[
+        gr.Textbox(lines=6, label="Prompt"),
+        gr.Slider(64, 1024, value=256, step=64, label="Max Tokens"),
+        gr.Slider(0.1, 1.5, value=0.7, step=0.1, label="Temperature"),
+    ],
+    outputs=gr.Textbox(label="Response"),
+    title="Llama 3 RAG Generator",
+)
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)

hf_spaces/stt/app.py

@@ -0,0 +1,101 @@
+"""
+hf_spaces/stt/app.py
+-----------------------
+HuggingFace Space: Whisper Speech-to-Text service.
+POST /transcribe  {"audio_b64": "...", "language": "en"}
+               → {"text": "...", "language": "en", "confidence": 0.99}
+"""
+
+import os
+import io
+import base64
+import logging
+import threading
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+from typing import Optional
+
+log = logging.getLogger(__name__)
+app = FastAPI(title="STT Space")
+
+WHISPER_SIZE = os.environ.get("WHISPER_MODEL_SIZE", "small")
+_model       = None
+
+
+def _load_model():
+    global _model
+    try:
+        from faster_whisper import WhisperModel
+        _model = WhisperModel(WHISPER_SIZE, device="cpu", compute_type="int8")
+        log.info("Whisper %s loaded", WHISPER_SIZE)
+    except Exception as exc:
+        log.error("Whisper load failed: %s", exc)
+
+
+@app.on_event("startup")
+async def startup():
+    threading.Thread(target=_load_model, daemon=True).start()
+
+
+class TranscribeRequest(BaseModel):
+    audio_b64: str
+    language:  Optional[str] = None
+
+
+@app.post("/transcribe")
+def transcribe(req: TranscribeRequest):
+    if _model is None:
+        return {"text": "", "language": "en", "confidence": 0.0, "status": "warming_up"}
+
+    try:
+        import numpy as np
+        import scipy.io.wavfile as wav_io
+
+        audio_bytes = base64.b64decode(req.audio_b64)
+        sr, data    = wav_io.read(io.BytesIO(audio_bytes))
+        audio_np    = data.astype(np.float32) / 32768.0
+
+        segs, info = _model.transcribe(
+            audio_np,
+            beam_size=5,
+            language=req.language,
+            vad_filter=True,
+        )
+        text = " ".join(s.text for s in segs).strip()
+        return {
+            "text":       text,
+            "language":   info.language,
+            "confidence": round(info.language_probability, 3),
+        }
+    except Exception as exc:
+        log.error("Transcription error: %s", exc)
+        return {"text": "", "language": "en", "confidence": 0.0, "error": str(exc)}
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "model": f"whisper-{WHISPER_SIZE}", "loaded": _model is not None}
+
+
+# Gradio UI
+import gradio as gr
+
+def gradio_transcribe(audio_path, language):
+    if _model is None:
+        return "Model loading, please wait..."
+    with open(audio_path, "rb") as f:
+        audio_b64 = base64.b64encode(f.read()).decode()
+    result = transcribe(TranscribeRequest(audio_b64=audio_b64, language=language or None))
+    return result.get("text", "")
+
+demo = gr.Interface(
+    fn=gradio_transcribe,
+    inputs=[gr.Audio(type="filepath", label="Upload Audio"), gr.Textbox(label="Language (optional)")],
+    outputs=gr.Textbox(label="Transcription"),
+    title=f"Whisper STT ({WHISPER_SIZE})",
+)
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)

rasa/actions/__init__.py

@@ -0,0 +1,2 @@
+# rasa/actions/__init__.py
+# Rasa custom actions package

rasa/actions/actions_brain.py

@@ -0,0 +1,243 @@
+"""
+rasa/actions/actions_brain.py
+------------------------------
+Custom Rasa actions — BRAIN module.
+
+Module 1: Language Detection + Multilingual Greeting (COMPLETE)
+  ActionGreetUser — detects user language, responds in that language,
+                    sets the `language` slot, sends quick-reply buttons.
+
+Do NOT modify existing action classes. Append new actions below.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import Any, Text, Dict, List
+
+from rasa_sdk import Action, Tracker
+from rasa_sdk.executor import CollectingDispatcher
+from rasa_sdk.events import SlotSet
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Path bootstrap — allows importing from services/ when actions run as a
+# standalone server (rasa run actions).  The actions server starts from the
+# rasa/ directory, so we walk two levels up to the repo root.
+# ---------------------------------------------------------------------------
+_REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+if _REPO_ROOT not in sys.path:
+    sys.path.insert(0, _REPO_ROOT)
+
+
+# ---------------------------------------------------------------------------
+# Multilingual greeting strings (mirrors services/language_service/main.py).
+# Kept here as a local copy so ActionGreetUser never needs an HTTP call at
+# greet time — zero latency, zero external dependency on the language service.
+# ---------------------------------------------------------------------------
+_GREETINGS: Dict[str, str] = {
+    "en": "Hello! Welcome to BookBot. 👋 How can I help you today?",
+    "ar": "مرحباً! أهلاً بك في BookBot. 👋 كيف يمكنني مساعدتك اليوم؟",
+    "fr": "Bonjour! Bienvenue sur BookBot. 👋 Comment puis-je vous aider?",
+    "es": "¡Hola! Bienvenido a BookBot. 👋 ¿Cómo puedo ayudarte hoy?",
+    "de": "Hallo! Willkommen bei BookBot. 👋 Wie kann ich Ihnen heute helfen?",
+    "hi": "नमस्ते! BookBot में आपका स्वागत है। 👋 आज मैं आपकी कैसे मदद कर सकता हूँ?",
+    "zh": "您好！欢迎来到 BookBot。👋 今天我能帮您什么？",
+    "ja": "こんにちは！BookBot へようこそ。👋 本日はどのようなご用件でしょうか？",
+    "ko": "안녕하세요! BookBot 에 오신 것을 환영합니다. 👋 오늘 어떻게 도와드릴까요?",
+    "pt": "Olá! Bem-vindo ao BookBot. 👋 Como posso ajudá-lo hoje?",
+    "ru": "Здравствуйте! Добро пожаловать в BookBot. 👋 Чем могу помочь?",
+    "id": "Halo! Selamat datang di BookBot. 👋 Bagaimana saya bisa membantu Anda?",
+    "tr": "Merhaba! BookBot'a hoş geldiniz. 👋 Bugün size nasıl yardımcı olabilirim?",
+    "th": "สวัสดี! ยินดีต้อนรับสู่ BookBot! 👋 วันนี้ฉันจะช่วยคุณได้อย่างไร?",
+    "vi": "Xin chào! Chào mừng đến với BookBot. 👋 Tôi có thể giúp gì cho bạn hôm nay?",
+    "te": "హలో! BookBot కి స్వాగతం. 👋 నేను మీకు ఎలా సహాయపడగలను?",
+    "ta": "வணக்கம்! BookBot-க்கு வரவேற்கிறோம். 👋 இன்று நான் உங்களுக்கு எவ்வாறு உதவலாம்?",
+}
+
+# Quick-reply button definitions sent with every greeting.
+# Payload prefix LANG_ is stripped by main.py before forwarding to the processor.
+_LANG_BUTTONS: List[Dict[str, str]] = [
+    {"content_type": "text", "title": "🇬🇧 English",  "payload": "LANG_en"},
+    {"content_type": "text", "title": "🇸🇦 عربي",     "payload": "LANG_ar"},
+    {"content_type": "text", "title": "🇫🇷 Français", "payload": "LANG_fr"},
+    {"content_type": "text", "title": "🇪🇸 Español",  "payload": "LANG_es"},
+    {"content_type": "text", "title": "🇩🇪 Deutsch",  "payload": "LANG_de"},
+    {"content_type": "text", "title": "🇮🇳 हिन्दी",   "payload": "LANG_hi"},
+    {"content_type": "text", "title": "🇨🇳 中文",      "payload": "LANG_zh"},
+    {"content_type": "text", "title": "🇯🇵 日本語",    "payload": "LANG_ja"},
+    {"content_type": "text", "title": "🇧🇷 Português", "payload": "LANG_pt"},
+    {"content_type": "text", "title": "🇷🇺 Русский",  "payload": "LANG_ru"},
+]
+
+# Languages that are written right-to-left.
+_RTL_LANGS = {"ar", "he", "fa", "ur", "yi"}
+
+
+def _detect_lang(text: str) -> tuple[str, float]:
+    """
+    Detect the language of *text* using the project's language detector.
+
+    Returns (language_code, confidence).  Falls back to ("en", 0.0) on any
+    error so the greeting always succeeds.
+    """
+    if not text or not text.strip():
+        return "en", 0.0
+    try:
+        from services.language_service.detector import detect
+        result = detect(text)
+        return result.get("language_code", "en"), result.get("confidence", 0.0)
+    except Exception as exc:
+        logger.warning("Language detection failed: %s — defaulting to 'en'", exc)
+        return "en", 0.0
+
+
+def _translate_greeting(text: str, target_lang: str) -> str:
+    """
+    Translate the English greeting to *target_lang* via the translator service.
+    Returns the original English greeting on any error.
+    """
+    try:
+        from services.language_service.translator import translate
+        return translate(text, src="en", tgt=target_lang)
+    except Exception as exc:
+        logger.warning("Translation failed for lang=%s: %s", target_lang, exc)
+        return text
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# MODULE 1 — ACTION: ActionGreetUser
+# ═══════════════════════════════════════════════════════════════════════════
+
+class ActionGreetUser(Action):
+    """
+    Multilingual greeting action — Module 1, fully complete.
+
+    Flow:
+      1. Check if `language` slot already set (returning user / language button tap).
+      2. If not set: detect from the user's opening message text.
+      3. If confidence < 0.75 (short greetings like "hi"): keep detected language
+         but show language-selection quick replies so the user can confirm.
+      4. Return greeting in the user's language.
+      5. Set `language` slot so all subsequent actions know the preferred language.
+    """
+
+    def name(self) -> Text:
+        return "action_greet_user"
+
+    def run(
+        self,
+        dispatcher: CollectingDispatcher,
+        tracker: Tracker,
+        domain: Dict[Text, Any],
+    ) -> List[Dict[Text, Any]]:
+
+        # ── 1. Resolve language ──────────────────────────────────────────────
+        lang = tracker.get_slot("language")
+        confidence = 1.0
+
+        if not lang:
+            user_text = tracker.latest_message.get("text", "") or ""
+            lang, confidence = _detect_lang(user_text)
+
+        # Sanitise: strip region suffix (e.g. "zh-cn" → "zh")
+        lang = lang.lower().split("-")[0].split("_")[0]
+
+        # ── 2. Build greeting ────────────────────────────────────────────────
+        if lang in _GREETINGS:
+            greeting = _GREETINGS[lang]
+        else:
+            # Language known but no pre-written greeting → translate English one
+            english = _GREETINGS["en"]
+            greeting = _translate_greeting(english, lang)
+
+        # ── 3. Build follow-up prompt ────────────────────────────────────────
+        # Low confidence + Latin-script message could mean we misidentified.
+        # Show language buttons so user can pick if needed; also offer "Book now".
+        show_lang_buttons = confidence < 0.85
+
+        if show_lang_buttons:
+            dispatcher.utter_message(text=greeting, quick_replies=_LANG_BUTTONS)
+        else:
+            # High-confidence detection — show action buttons directly.
+            action_buttons = [
+                {"content_type": "text", "title": "🏨 Book a Hotel",  "payload": "ACTION_BOOK"},
+                {"content_type": "text", "title": "📋 My Bookings",   "payload": "MY_BOOKINGS"},
+                {"content_type": "text", "title": "🌐 Change Language", "payload": "ACTION_CHANGE_LANG"},
+            ]
+            dispatcher.utter_message(text=greeting, quick_replies=action_buttons)
+
+        # ── 4. Persist language slot ─────────────────────────────────────────
+        return [SlotSet("language", lang)]
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# MODULE 1 — ACTION: ActionChangeLanguage
+# ═══════════════════════════════════════════════════════════════════════════
+
+class ActionChangeLanguage(Action):
+    """
+    Handles ACTION_CHANGE_LANG postback and `change_language` intent.
+
+    Sends the full language-selection quick-reply menu and clears the
+    current language slot so the user can pick a new one.
+    """
+
+    def name(self) -> Text:
+        return "action_change_language"
+
+    def run(
+        self,
+        dispatcher: CollectingDispatcher,
+        tracker: Tracker,
+        domain: Dict[Text, Any],
+    ) -> List[Dict[Text, Any]]:
+
+        dispatcher.utter_message(
+            text="Which language would you prefer? 🌐",
+            quick_replies=_LANG_BUTTONS,
+        )
+        return [SlotSet("language", None)]
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# MODULE 1 — ACTION: ActionSessionStart
+# ═══════════════════════════════════════════════════════════════════════════
+
+class ActionSessionStart(Action):
+    """
+    Fires on every new conversation session (maps to action_session_start).
+
+    Restores the `language` slot from the previous session if it was saved
+    in Redis, so returning users are greeted in their chosen language.
+    """
+
+    def name(self) -> Text:
+        return "action_session_start"
+
+    def run(
+        self,
+        dispatcher: CollectingDispatcher,
+        tracker: Tracker,
+        domain: Dict[Text, Any],
+    ) -> List[Dict[Text, Any]]:
+
+        sender = tracker.sender_id
+        saved_lang: str | None = None
+
+        try:
+            from db.redis_client import sync_redis
+            r = sync_redis()
+            saved_lang = r.get(f"user:{sender}:lang")
+        except Exception as exc:
+            logger.debug("Could not load language from Redis: %s", exc)
+
+        events: List[Dict[Text, Any]] = []
+        if saved_lang:
+            events.append(SlotSet("language", saved_lang))
+            logger.info("Restored language=%s for sender=%s", saved_lang, sender)
+
+        return events

rasa/config.yml

@@ -0,0 +1,38 @@
+# rasa/config.yml
+# ------------------------------------------------
+# Rasa NLU + Core pipeline configuration
+# ------------------------------------------------
+
+recipe: default.v1
+
+language: en
+
+pipeline:
+  - name: WhitespaceTokenizer
+  - name: RegexFeaturizer
+  - name: LexicalSyntacticFeaturizer
+  - name: CountVectorsFeaturizer
+  - name: CountVectorsFeaturizer
+    analyzer: char_wb
+    min_ngram: 1
+    max_ngram: 4
+  - name: DIETClassifier
+    epochs: 100
+    constrain_similarities: true
+  - name: EntitySynonymMapper
+  - name: ResponseSelector
+    epochs: 100
+  - name: FallbackClassifier
+    threshold: 0.3
+    ambiguity_threshold: 0.1
+
+policies:
+  - name: MemoizationPolicy
+  - name: TEDPolicy
+    max_history: 10
+    epochs: 100
+    constrain_similarities: true
+  - name: RulePolicy
+    core_fallback_threshold: 0.4
+    core_fallback_action_name: action_default_fallback
+    enable_fallback_prediction: true

rasa/credentials.yml

@@ -0,0 +1,12 @@
+# rasa/credentials.yml
+# ------------------------------------------------
+# Channel credentials for Rasa server
+# ------------------------------------------------
+
+facebook:
+  verify: "${VERIFY_TOKEN}"
+  secret: "${FB_APP_SECRET}"
+  page-access-token: "${PAGE_ACCESS_TOKEN}"
+
+rest:
+  # REST channel for testing / internal API calls

rasa/data/nlu/nlu_en.yml

@@ -0,0 +1,207 @@
+# rasa/data/nlu/nlu_en.yml
+# ----------------------------------------
+# English NLU training data
+# ----------------------------------------
+
+version: "3.1"
+
+nlu:
+
+- intent: greet
+  examples: |
+    - hi
+    - hello
+    - hey
+    - good morning
+    - good evening
+    - howdy
+    - what's up
+    - hiya
+    - hi there
+    - greetings
+    - sup
+    - yo
+    - good afternoon
+    - good day
+    - heya
+    - hey there
+    - hello there
+    - hola
+    - ahoy
+    - bonjour
+    - salaam
+    - namaste
+    - salam
+    - start
+    - begin
+
+- intent: goodbye
+  examples: |
+    - bye
+    - goodbye
+    - see you later
+    - good night
+    - take care
+    - ciao
+    - see ya
+
+- intent: affirm
+  examples: |
+    - yes
+    - yep
+    - yeah
+    - confirm
+    - correct
+    - that's right
+    - ok
+    - okay
+    - sure
+    - absolutely
+    - go ahead
+
+- intent: deny
+  examples: |
+    - no
+    - nope
+    - not really
+    - cancel
+    - stop
+    - negative
+    - I don't want that
+    - no thanks
+
+- intent: book_hotel
+  examples: |
+    - I want to book a hotel
+    - book a room
+    - I need a hotel
+    - find me a hotel
+    - hotel reservation please
+    - make a booking
+    - I'd like to stay at a hotel
+    - can you book a hotel room for me
+    - hotel booking
+    - reserve a hotel
+    - I want to travel to [Paris](city) and stay somewhere nice
+
+- intent: provide_city
+  examples: |
+    - [Paris](city)
+    - I want to go to [London](city)
+    - [New York](city) please
+    - staying in [Tokyo](city)
+    - [Dubai](city)
+    - [Mumbai](city)
+    - [Bangkok](city)
+    - [Singapore](city)
+    - [Istanbul](city)
+
+- intent: provide_checkin
+  examples: |
+    - [2025-06-15](date)
+    - June 15th
+    - next Monday
+    - this Friday
+    - tomorrow
+    - [2025-07-01](date)
+    - checking in on [2025-08-10](date)
+
+- intent: provide_guests
+  examples: |
+    - [2](number) guests
+    - just [1](number)
+    - [3](number) people
+    - [4](number) adults
+    - a family of [5](number)
+    - only me
+    - for [2](number)
+
+- intent: provide_name
+  examples: |
+    - my name is John Smith
+    - it's Maria Garcia
+    - Ravi Kumar
+    - Ahmed Hassan
+    - for Priya Mehta
+
+- intent: provide_email
+  examples: |
+    - [john@example.com](email)
+    - my email is [user@gmail.com](email)
+    - [someone@company.org](email)
+
+- intent: provide_phone
+  examples: |
+    - [+1-555-0100](phone_number)
+    - my number is [+44-207-946-0958](phone_number)
+    - [+91-9876543210](phone_number)
+
+- intent: confirm_booking
+  examples: |
+    - confirm
+    - yes please confirm
+    - book it
+    - proceed
+    - finalize
+    - yes I confirm
+
+- intent: cancel_booking
+  examples: |
+    - cancel my booking
+    - I want to cancel
+    - please cancel reservation [BK12345](booking_ref)
+    - cancel booking [BK99999](booking_ref)
+    - I need to cancel
+
+- intent: view_bookings
+  examples: |
+    - show my bookings
+    - my reservations
+    - what bookings do I have
+    - view my trips
+    - list my bookings
+    - upcoming stays
+
+- intent: modify_booking
+  examples: |
+    - I want to change my booking
+    - modify reservation
+    - change dates
+    - update my booking
+    - I need to change the room
+
+- intent: ask_faq
+  examples: |
+    - what is the check-in time
+    - do you have free wifi
+    - is breakfast included
+    - what's the cancellation policy
+    - is parking available
+    - are pets allowed
+    - what amenities are available
+
+- intent: change_language
+  examples: |
+    - change language
+    - speak to me in [Hindi](language)
+    - switch to [French](language)
+    - [Telugu](language) please
+    - I want [Arabic](language)
+    - use [Spanish](language)
+
+- intent: human_handoff
+  examples: |
+    - talk to an agent
+    - real person please
+    - human support
+    - live agent
+    - I want to speak to someone
+    - connect me to staff
+
+- intent: out_of_scope
+  examples: |
+    - what is the weather
+    - tell me a joke
+    - who won the match
+    - what's 2 + 2
+    - call a taxi

rasa/domain.yml

@@ -0,0 +1,177 @@
+# rasa/domain.yml
+# ------------------------------------------------
+# Rasa domain: intents, entities, slots, responses, actions
+# ------------------------------------------------
+
+version: "3.1"
+
+intents:
+  - greet
+  - goodbye
+  - affirm
+  - deny
+  - book_hotel
+  - provide_city
+  - provide_checkin
+  - provide_checkout
+  - provide_guests
+  - provide_hotel_choice
+  - provide_room_choice
+  - provide_meal_plan
+  - provide_name
+  - provide_email
+  - provide_phone
+  - confirm_booking
+  - cancel_booking
+  - view_bookings
+  - modify_booking
+  - ask_faq
+  - change_language
+  - human_handoff
+  - out_of_scope
+  - nlu_fallback
+
+entities:
+  - city
+  - date
+  - number
+  - email
+  - phone_number
+  - hotel_name
+  - room_type
+  - meal_plan
+  - language
+  - booking_ref
+
+slots:
+  city:
+    type: text
+    mappings:
+      - type: from_entity
+        entity: city
+  check_in:
+    type: text
+    mappings:
+      - type: from_entity
+        entity: date
+  check_out:
+    type: text
+    mappings:
+      - type: custom
+  guests:
+    type: float
+    mappings:
+      - type: from_entity
+        entity: number
+  hotel_id:
+    type: text
+    mappings:
+      - type: custom
+  room_type_id:
+    type: text
+    mappings:
+      - type: custom
+  meal_plan:
+    type: text
+    mappings:
+      - type: from_entity
+        entity: meal_plan
+  guest_name:
+    type: text
+    mappings:
+      - type: custom
+  guest_email:
+    type: text
+    mappings:
+      - type: from_entity
+        entity: email
+  guest_phone:
+    type: text
+    mappings:
+      - type: from_entity
+        entity: phone_number
+  language:
+    type: text
+    mappings:
+      - type: custom
+  booking_ref:
+    type: text
+    mappings:
+      - type: from_entity
+        entity: booking_ref
+  booking_step:
+    type: text
+    mappings:
+      - type: custom
+
+responses:
+  # ── Module 1 responses ──────────────────────────────────────────────────
+  # utter_greet is a static fallback only; ActionGreetUser handles the real
+  # multilingual greeting dynamically via action_greet_user.
+  utter_greet:
+    - text: "Hello! I'm your hotel booking assistant. How can I help you today?"
+  utter_ask_language_choice:
+    - text: "Which language would you prefer? 🌐"
+  utter_goodbye:
+    - text: "Thank you for using our service. Have a great day! 👋"
+  utter_affirm:
+    - text: "Great!"
+  utter_ask_city:
+    - text: "Which city would you like to stay in?"
+  utter_ask_checkin:
+    - text: "What's your check-in date? (e.g. 2025-06-15)"
+  utter_ask_checkout:
+    - text: "And what's your check-out date?"
+  utter_ask_guests:
+    - text: "How many guests will be staying?"
+  utter_ask_name:
+    - text: "Please provide the full name for the booking."
+  utter_ask_email:
+    - text: "What's the email address for the confirmation?"
+  utter_ask_phone:
+    - text: "And your phone number with country code? (e.g. +1-555-0100)"
+  utter_fallback:
+    - text: "I didn't quite understand that. Could you rephrase? Or type MENU for options."
+  utter_handoff:
+    - text: "Connecting you to a live agent now, please hold on..."
+  utter_out_of_scope:
+    - text: "I can only help with hotel bookings. Type MENU to see what I can do."
+
+actions:
+  # ── Module 1: Language + Greeting (COMPLETE) ────────────────────────────
+  - action_greet_user
+  - action_change_language
+  - action_session_start
+  # ── Module 2+: Booking flow ──────────────────────────────────────────────
+  - action_search_hotels
+  - action_show_hotels
+  - action_select_hotel
+  - action_show_rooms
+  - action_select_room
+  - action_collect_guest_details
+  - action_create_booking
+  - action_show_my_bookings
+  - action_modify_booking
+  - action_cancel_booking
+  - action_answer_faq
+  - action_human_handoff
+  - action_default_fallback
+  - validate_booking_form
+
+forms:
+  booking_form:
+    required_slots:
+      - city
+      - check_in
+      - check_out
+      - guests
+      - hotel_id
+      - room_type_id
+      - meal_plan
+      - guest_name
+      - guest_email
+      - guest_phone
+
+session_config:
+  session_expiration_time: 60   # minutes
+  carry_over_slots_to_new_session: false

rasa/endpoints.yml

@@ -0,0 +1,24 @@
+# rasa/endpoints.yml
+# ------------------------------------------------
+# External service endpoints for Rasa
+# ------------------------------------------------
+
+action_endpoint:
+  url: "${RASA_ACTIONS_URL}/webhook"
+
+tracker_store:
+  type: redis
+  url: "${REDIS_HOST}"
+  port: ${REDIS_PORT:-6379}
+  password: "${REDIS_PASSWORD}"
+  db: 0
+  key_prefix: "rasa:"
+
+event_broker:
+  type: kafka
+  url: "${KAFKA_BOOTSTRAP_SERVERS}"
+  topic: rasa.events
+  security_protocol: SASL_SSL
+  sasl_mechanism: PLAIN
+  sasl_plain_username: "${KAFKA_API_KEY}"
+  sasl_plain_password: "${KAFKA_API_SECRET}"

scripts/hotel_onboarding.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""
+scripts/hotel_onboarding.py
+-----------------------------
+Onboards a new hotel partner:
+  1. Inserts hotel record into Supabase
+  2. Indexes hotel into Elasticsearch
+  3. Embeds and upserts FAQ entries into Qdrant
+
+Usage:
+    python scripts/hotel_onboarding.py --file data/hotel_sample.json
+"""
+
+import argparse
+import json
+import os
+import sys
+
+SUPABASE_URL = os.environ.get("SUPABASE_URL", "")
+SUPABASE_KEY = os.environ.get("SUPABASE_SERVICE_ROLE_KEY", "")
+
+
+def _sb_headers():
+    return {
+        "apikey":        SUPABASE_KEY,
+        "Authorization": f"Bearer {SUPABASE_KEY}",
+        "Content-Type":  "application/json",
+        "Prefer":        "return=representation",
+    }
+
+
+def insert_supabase(hotel: dict) -> dict:
+    import urllib.request
+    url  = f"{SUPABASE_URL}/rest/v1/hotels"
+    data = json.dumps(hotel).encode()
+    req  = urllib.request.Request(url, data=data, headers=_sb_headers(), method="POST")
+    with urllib.request.urlopen(req) as resp:
+        result = json.loads(resp.read())
+    return result[0] if isinstance(result, list) else result
+
+
+def index_elasticsearch(hotel: dict) -> None:
+    sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+    from services.search_service.elasticsearch_client import index_hotel
+    index_hotel(hotel)
+    print(f"  ✓ Elasticsearch indexed hotel '{hotel.get('name')}'")
+
+
+def embed_faqs(hotel_id: str, faqs: list[dict]) -> None:
+    sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+    from services.rag_service.qdrant_client import upsert_faqs
+    upsert_faqs(hotel_id, faqs)
+    print(f"  ✓ Qdrant upserted {len(faqs)} FAQ entries for hotel {hotel_id}")
+
+
+def onboard(hotel_data: dict) -> None:
+    print(f"\nOnboarding hotel: {hotel_data.get('name', '?')}")
+
+    # 1. Supabase
+    record = insert_supabase({k: v for k, v in hotel_data.items() if k != "faqs"})
+    hotel_id = record.get("id")
+    print(f"  ✓ Supabase inserted hotel id={hotel_id}")
+
+    # 2. Elasticsearch
+    index_elasticsearch({**hotel_data, "id": hotel_id})
+
+    # 3. Qdrant FAQs
+    faqs = hotel_data.get("faqs", [])
+    if faqs:
+        embed_faqs(hotel_id, faqs)
+    else:
+        print("  ℹ️  No FAQs provided; skipping Qdrant upsert")
+
+    print(f"\n✅ Hotel '{hotel_data.get('name')}' onboarded successfully (id={hotel_id})\n")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--file", required=True, help="Path to hotel JSON file")
+    args   = parser.parse_args()
+
+    with open(args.file, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    if isinstance(data, list):
+        for hotel in data:
+            onboard(hotel)
+    else:
+        onboard(data)

scripts/setup_elasticsearch_index.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""
+scripts/setup_elasticsearch_index.py
+--------------------------------------
+Creates (or re-creates) the Elasticsearch hotel index with
+the correct mappings and settings.
+
+Usage:
+    ES_URL=https://... python scripts/setup_elasticsearch_index.py
+"""
+
+import os
+import json
+import urllib.request
+
+ES_URL   = os.environ.get("ELASTICSEARCH_URL", "http://localhost:9200")
+ES_USER  = os.environ.get("ELASTICSEARCH_USERNAME", "elastic")
+ES_PASS  = os.environ.get("ELASTICSEARCH_PASSWORD", "")
+INDEX    = "hotels"
+
+MAPPING = {
+    "settings": {
+        "number_of_shards":   1,
+        "number_of_replicas": 1,
+        "analysis": {
+            "analyzer": {
+                "hotel_analyzer": {
+                    "type":      "custom",
+                    "tokenizer": "standard",
+                    "filter":    ["lowercase", "asciifolding", "stop"],
+                }
+            }
+        },
+    },
+    "mappings": {
+        "properties": {
+            "id":          {"type": "keyword"},
+            "name":        {"type": "text",    "analyzer": "hotel_analyzer"},
+            "city":        {"type": "text",    "analyzer": "hotel_analyzer",
+                            "fields": {"keyword": {"type": "keyword"}}},
+            "country":     {"type": "keyword"},
+            "description": {"type": "text",   "analyzer": "hotel_analyzer"},
+            "stars":       {"type": "integer"},
+            "rating":      {"type": "float"},
+            "price_per_night": {"type": "float"},
+            "amenities":   {"type": "keyword"},
+            "location": {
+                "type":       "geo_point",
+            },
+            "is_active":   {"type": "boolean"},
+            "images":      {"type": "keyword", "index": False},
+            "updated_at":  {"type": "date"},
+        }
+    },
+}
+
+
+def _request(method: str, path: str, body: dict = None):
+    url  = f"{ES_URL}{path}"
+    data = json.dumps(body).encode() if body else None
+    import base64
+    creds   = base64.b64encode(f"{ES_USER}:{ES_PASS}".encode()).decode()
+    headers = {
+        "Content-Type":  "application/json",
+        "Authorization": f"Basic {creds}",
+    }
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read())
+
+
+def setup():
+    # Delete existing index if present
+    try:
+        _request("DELETE", f"/{INDEX}")
+        print(f"Deleted existing index '{INDEX}'")
+    except Exception:
+        pass
+
+    result = _request("PUT", f"/{INDEX}", MAPPING)
+    print(f"Index '{INDEX}' created:", result)
+
+
+if __name__ == "__main__":
+    setup()

scripts/setup_messenger_menu.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""
+scripts/setup_messenger_menu.py
+---------------------------------
+Sets up the Facebook Messenger Persistent Menu for the bot page.
+Run once per page or whenever menu items change.
+
+Usage:
+    python scripts/setup_messenger_menu.py
+"""
+
+import os
+import json
+import urllib.request
+
+PAGE_ACCESS_TOKEN = os.environ["PAGE_ACCESS_TOKEN"]
+META_GRAPH_URL    = "https://graph.facebook.com/v18.0/me/messenger_profile"
+
+MENU = {
+    "persistent_menu": [
+        {
+            "locale":                 "default",
+            "composer_input_disabled": False,
+            "call_to_actions": [
+                {"type": "postback", "title": "🏨 Book a Hotel",        "payload": "BOOK_HOTEL"},
+                {"type": "postback", "title": "📋 My Bookings",          "payload": "MY_BOOKINGS"},
+                {
+                    "type":  "nested",
+                    "title": "⚙️ Manage Booking",
+                    "call_to_actions": [
+                        {"type": "postback", "title": "✏️ Modify Booking",    "payload": "MODIFY_BOOKING"},
+                        {"type": "postback", "title": "❌ Cancel Booking",     "payload": "CANCEL_BOOKING"},
+                        {"type": "postback", "title": "📧 Resend Confirmation","payload": "RESEND_CONFIRM"},
+                    ],
+                },
+                {"type": "postback", "title": "🌐 Change Language",    "payload": "CHANGE_LANGUAGE"},
+                {"type": "postback", "title": "🤝 Talk to Agent",       "payload": "HUMAN_HANDOFF"},
+            ],
+        }
+    ],
+    "get_started": {"payload": "GET_STARTED"},
+    "greeting": [
+        {"locale": "default", "text": "Hello {{user_first_name}}! I'm your hotel booking assistant. How can I help you today?"},
+        {"locale": "hi_IN",   "text": "नमस्ते {{user_first_name}}! मैं आपका होटल बुकिंग सहायक हूं।"},
+    ],
+}
+
+
+def setup():
+    data    = json.dumps(MENU).encode()
+    headers = {
+        "Content-Type":  "application/json",
+    }
+    url = f"{META_GRAPH_URL}?access_token={PAGE_ACCESS_TOKEN}"
+    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+    with urllib.request.urlopen(req) as resp:
+        result = json.loads(resp.read())
+    print("Messenger menu set:", result)
+
+
+if __name__ == "__main__":
+    setup()

scripts/setup_qdrant_collection.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""
+scripts/setup_qdrant_collection.py
+------------------------------------
+Creates the Qdrant collection for hotel FAQ embeddings (LaBSE 768-dim).
+
+Usage:
+    QDRANT_URL=https://... QDRANT_API_KEY=xxx python scripts/setup_qdrant_collection.py
+"""
+
+import os
+
+QDRANT_URL     = os.environ.get("QDRANT_URL",     "http://localhost:6333")
+QDRANT_API_KEY = os.environ.get("QDRANT_API_KEY", "")
+COLLECTION     = "hotel_faqs"
+VECTOR_SIZE    = 768   # LaBSE
+
+
+def setup():
+    try:
+        from qdrant_client import QdrantClient
+        from qdrant_client.models import Distance, VectorParams, HnswConfigDiff
+    except ImportError:
+        raise SystemExit("qdrant-client is required: pip install qdrant-client")
+
+    client = QdrantClient(url=QDRANT_URL, api_key=QDRANT_API_KEY or None)
+
+    # Delete if exists
+    collections = [c.name for c in client.get_collections().collections]
+    if COLLECTION in collections:
+        client.delete_collection(COLLECTION)
+        print(f"Deleted existing collection '{COLLECTION}'")
+
+    client.create_collection(
+        collection_name=COLLECTION,
+        vectors_config=VectorParams(size=VECTOR_SIZE, distance=Distance.COSINE),
+        hnsw_config=HnswConfigDiff(m=16, ef_construct=100),
+    )
+    print(f"Collection '{COLLECTION}' created (size={VECTOR_SIZE}, metric=COSINE)")
+
+
+if __name__ == "__main__":
+    setup()

services/analytics_service/clickhouse_schema.sql

@@ -0,0 +1,55 @@
+-- ============================================================
+-- ClickHouse schema for BookHotel analytics
+-- ============================================================
+
+CREATE DATABASE IF NOT EXISTS bookhotel;
+
+-- ---------------------------------------------------------------
+-- Booking Events
+-- ---------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS bookhotel.booking_events
+(
+    event_type  LowCardinality(String),  -- created | succeeded | cancelled | modified
+    booking_id  String,
+    hotel_id    String,
+    guest_id    String,
+    amount_usd  Float64,
+    check_in    String,
+    check_out   String,
+    created_at  DateTime
+)
+ENGINE = MergeTree()
+PARTITION BY toYYYYMM(created_at)
+ORDER BY (event_type, created_at);
+
+-- ---------------------------------------------------------------
+-- NLU Logs
+-- ---------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS bookhotel.nlu_logs
+(
+    sender_id   String,
+    intent      LowCardinality(String),
+    confidence  Float32,
+    language    LowCardinality(String),
+    created_at  DateTime
+)
+ENGINE = MergeTree()
+PARTITION BY toYYYYMM(created_at)
+ORDER BY (intent, created_at);
+
+-- ---------------------------------------------------------------
+-- Revenue Summary (materialized view refreshed hourly)
+-- ---------------------------------------------------------------
+CREATE MATERIALIZED VIEW IF NOT EXISTS bookhotel.revenue_daily
+ENGINE = SummingMergeTree()
+PARTITION BY toYYYYMM(day)
+ORDER BY (hotel_id, day)
+AS
+SELECT
+    hotel_id,
+    toDate(created_at) AS day,
+    count()            AS bookings,
+    sum(amount_usd)    AS revenue_usd
+FROM bookhotel.booking_events
+WHERE event_type = 'succeeded'
+GROUP BY hotel_id, day;

services/analytics_service/kafka_consumer.py

@@ -0,0 +1,116 @@
+"""
+services/analytics_service/kafka_consumer.py
+----------------------------------------------
+Consumes booking events from Kafka and inserts them into ClickHouse.
+
+Topics consumed:
+  booking.created
+  booking.payment.succeeded
+  booking.cancelled
+  booking.modified
+  nlu.intent.logged
+
+Runs as a standalone worker process (not a FastAPI route).
+"""
+
+import os
+import json
+import logging
+from datetime import datetime, timezone
+
+log = logging.getLogger(__name__)
+
+KAFKA_BOOTSTRAP  = os.environ.get("KAFKA_BOOTSTRAP_SERVERS", "localhost:9092")
+KAFKA_GROUP_ID   = os.environ.get("KAFKA_CONSUMER_GROUP",    "analytics-consumer")
+KAFKA_TOPICS     = ["booking.created", "booking.payment.succeeded",
+                    "booking.cancelled", "booking.modified", "nlu.intent.logged"]
+
+CLICKHOUSE_HOST  = os.environ.get("CLICKHOUSE_HOST",     "localhost")
+CLICKHOUSE_PORT  = int(os.environ.get("CLICKHOUSE_PORT", "9000"))
+CLICKHOUSE_DB    = os.environ.get("CLICKHOUSE_DB",       "bookhotel")
+CLICKHOUSE_USER  = os.environ.get("CLICKHOUSE_USER",     "default")
+CLICKHOUSE_PASS  = os.environ.get("CLICKHOUSE_PASSWORD", "")
+
+
+def _get_ch_client():
+    try:
+        from clickhouse_driver import Client
+        return Client(
+            host=CLICKHOUSE_HOST,
+            port=CLICKHOUSE_PORT,
+            database=CLICKHOUSE_DB,
+            user=CLICKHOUSE_USER,
+            password=CLICKHOUSE_PASS,
+        )
+    except ImportError:
+        raise RuntimeError("clickhouse-driver is required: pip install clickhouse-driver")
+
+
+def _insert_booking_event(ch, event: dict) -> None:
+    ch.execute(
+        "INSERT INTO booking_events (event_type, booking_id, hotel_id, guest_id, "
+        "amount_usd, check_in, check_out, created_at) VALUES",
+        [{
+            "event_type": event.get("type", "unknown"),
+            "booking_id": event.get("booking_id", ""),
+            "hotel_id":   event.get("hotel_id", ""),
+            "guest_id":   event.get("guest_id", ""),
+            "amount_usd": float(event.get("amount_usd", 0)),
+            "check_in":   event.get("check_in", ""),
+            "check_out":  event.get("check_out", ""),
+            "created_at": datetime.now(timezone.utc),
+        }],
+    )
+
+
+def _insert_nlu_event(ch, event: dict) -> None:
+    ch.execute(
+        "INSERT INTO nlu_logs (sender_id, intent, confidence, language, created_at) VALUES",
+        [{
+            "sender_id":  event.get("sender_id", ""),
+            "intent":     event.get("intent", ""),
+            "confidence": float(event.get("confidence", 0)),
+            "language":   event.get("language", "en"),
+            "created_at": datetime.now(timezone.utc),
+        }],
+    )
+
+
+def run() -> None:
+    """
+    Blocking Kafka consumer loop.
+    Call from a Celery worker or a dedicated Render background worker.
+    """
+    try:
+        from kafka import KafkaConsumer
+    except ImportError:
+        raise RuntimeError("kafka-python is required: pip install kafka-python")
+
+    consumer = KafkaConsumer(
+        *KAFKA_TOPICS,
+        bootstrap_servers=KAFKA_BOOTSTRAP.split(","),
+        group_id=KAFKA_GROUP_ID,
+        auto_offset_reset="earliest",
+        enable_auto_commit=True,
+        value_deserializer=lambda m: json.loads(m.decode("utf-8")),
+    )
+    ch = _get_ch_client()
+    log.info("Kafka consumer started; topics=%s", KAFKA_TOPICS)
+
+    for message in consumer:
+        try:
+            event = message.value
+            topic = message.topic
+
+            if topic == "nlu.intent.logged":
+                _insert_nlu_event(ch, event)
+            else:
+                event["type"] = topic.split(".")[-1]
+                _insert_booking_event(ch, event)
+        except Exception as exc:
+            log.error("Error processing Kafka message: %s", exc)
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    run()

services/auth_service/main.py

@@ -0,0 +1,135 @@
+"""
+services/auth_service/main.py
+--------------------------------
+Lightweight JWT-based auth microservice for hotel staff dashboard.
+Issues short-lived access tokens + long-lived refresh tokens.
+Passwords are hashed with bcrypt.  Never stores plain text.
+"""
+
+import os
+import json
+import logging
+from datetime import datetime, timezone, timedelta
+
+from fastapi import FastAPI, HTTPException, Depends
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from pydantic import BaseModel, EmailStr
+from typing import Optional
+
+log = logging.getLogger(__name__)
+app = FastAPI(title="Auth Service")
+
+JWT_SECRET     = os.environ.get("JWT_SECRET", "CHANGE_ME_IN_PRODUCTION")
+ACCESS_EXPIRE  = int(os.environ.get("JWT_ACCESS_EXPIRE_MINUTES",   "60"))
+REFRESH_EXPIRE = int(os.environ.get("JWT_REFRESH_EXPIRE_DAYS",     "30"))
+
+bearer_scheme = HTTPBearer()
+
+
+def _encode(payload: dict) -> str:
+    try:
+        import jwt
+        return jwt.encode(payload, JWT_SECRET, algorithm="HS256")
+    except ImportError:
+        raise RuntimeError("PyJWT is required: pip install PyJWT")
+
+
+def _decode(token: str) -> dict:
+    try:
+        import jwt
+        return jwt.decode(token, JWT_SECRET, algorithms=["HS256"])
+    except Exception as exc:
+        raise HTTPException(status_code=401, detail="Invalid or expired token")
+
+
+def _hash_password(password: str) -> str:
+    try:
+        import bcrypt
+        return bcrypt.hashpw(password.encode(), bcrypt.gensalt()).decode()
+    except ImportError:
+        raise RuntimeError("bcrypt is required: pip install bcrypt")
+
+
+def _verify_password(plain: str, hashed: str) -> bool:
+    try:
+        import bcrypt
+        return bcrypt.checkpw(plain.encode(), hashed.encode())
+    except ImportError:
+        raise RuntimeError("bcrypt is required")
+
+
+class LoginRequest(BaseModel):
+    email:    str
+    password: str
+
+
+class RefreshRequest(BaseModel):
+    refresh_token: str
+
+
+def _get_staff_from_db(email: str) -> Optional[dict]:
+    """Fetch staff record from Supabase."""
+    SUPA = os.environ.get("SUPABASE_URL", "")
+    KEY  = os.environ.get("SUPABASE_SERVICE_ROLE_KEY", "")
+    import urllib.request
+    url  = f"{SUPA}/rest/v1/staff_users?email=eq.{email}&select=*&limit=1"
+    req  = urllib.request.Request(url, headers={
+        "apikey": KEY, "Authorization": f"Bearer {KEY}"
+    })
+    with urllib.request.urlopen(req) as resp:
+        rows = json.loads(resp.read())
+    return rows[0] if rows else None
+
+
+@app.post("/login")
+def login(req: LoginRequest):
+    staff = _get_staff_from_db(req.email)
+    if not staff or not _verify_password(req.password, staff["password_hash"]):
+        raise HTTPException(status_code=401, detail="Invalid credentials")
+
+    now = datetime.now(timezone.utc)
+    access_payload = {
+        "sub":   staff["id"],
+        "email": staff["email"],
+        "role":  staff.get("role", "staff"),
+        "exp":   now + timedelta(minutes=ACCESS_EXPIRE),
+        "iat":   now,
+    }
+    refresh_payload = {
+        "sub":  staff["id"],
+        "type": "refresh",
+        "exp":  now + timedelta(days=REFRESH_EXPIRE),
+        "iat":  now,
+    }
+    return {
+        "access_token":  _encode(access_payload),
+        "refresh_token": _encode(refresh_payload),
+        "token_type":    "bearer",
+        "expires_in":    ACCESS_EXPIRE * 60,
+    }
+
+
+@app.post("/refresh")
+def refresh(req: RefreshRequest):
+    payload = _decode(req.refresh_token)
+    if payload.get("type") != "refresh":
+        raise HTTPException(status_code=401, detail="Not a refresh token")
+
+    now = datetime.now(timezone.utc)
+    new_access = {
+        "sub": payload["sub"],
+        "exp": now + timedelta(minutes=ACCESS_EXPIRE),
+        "iat": now,
+    }
+    return {"access_token": _encode(new_access), "token_type": "bearer"}
+
+
+@app.get("/me")
+def me(creds: HTTPAuthorizationCredentials = Depends(bearer_scheme)):
+    payload = _decode(creds.credentials)
+    return {"sub": payload.get("sub"), "email": payload.get("email"), "role": payload.get("role")}
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "service": "auth_service"}

services/corporate_service/approval_engine.py

@@ -0,0 +1,96 @@
+"""
+services/corporate_service/approval_engine.py
+-----------------------------------------------
+Routes high-value corporate bookings through an approval workflow.
+
+Rules:
+  amount < APPROVAL_THRESHOLD  → auto-approve
+  amount >= APPROVAL_THRESHOLD → create pending approval request,
+                                  email approver, return approval_id
+"""
+
+import os
+import json
+import logging
+from datetime import datetime, timezone
+import urllib.request
+
+log = logging.getLogger(__name__)
+
+SUPABASE_URL        = os.environ.get("SUPABASE_URL", "")
+SUPABASE_KEY        = os.environ.get("SUPABASE_SERVICE_ROLE_KEY", "")
+APPROVAL_THRESHOLD  = float(os.environ.get("CORPORATE_APPROVAL_THRESHOLD_USD", "1000"))
+NOTIFY_URL          = os.environ.get("NOTIFICATION_SERVICE_URL", "http://localhost:8007")
+
+
+def _headers():
+    return {
+        "apikey":        SUPABASE_KEY,
+        "Authorization": f"Bearer {SUPABASE_KEY}",
+        "Content-Type":  "application/json",
+        "Prefer":        "return=representation",
+    }
+
+
+def _post(table: str, payload: dict) -> dict:
+    url  = f"{SUPABASE_URL}/rest/v1/{table}"
+    data = json.dumps(payload).encode()
+    req  = urllib.request.Request(url, data=data, headers=_headers(), method="POST")
+    with urllib.request.urlopen(req) as resp:
+        result = json.loads(resp.read())
+    return result[0] if isinstance(result, list) else result
+
+
+def evaluate(
+    corporate_account_id: str,
+    booking_id:           str,
+    amount_usd:           float,
+    approver_email:       str,
+) -> dict:
+    """
+    Returns {status, approval_id, message}.
+    status: "approved" | "pending_approval"
+    """
+    if amount_usd < APPROVAL_THRESHOLD:
+        return {"status": "approved", "approval_id": None,
+                "message": "Auto-approved (below threshold)"}
+
+    record = _post("approval_requests", {
+        "corporate_account_id": corporate_account_id,
+        "booking_id":           booking_id,
+        "amount_usd":           amount_usd,
+        "approver_email":       approver_email,
+        "status":               "pending",
+        "requested_at":         datetime.now(timezone.utc).isoformat(),
+    })
+    approval_id = record.get("id")
+
+    # Notify approver via notification service
+    try:
+        payload = json.dumps({
+            "channel":        "email",
+            "to_email":       approver_email,
+            "email_subject":  f"Approval Required: Corporate Booking ${amount_usd:.0f}",
+            "email_template": "approval_request.html",
+            "template_ctx": {
+                "booking_id":   booking_id,
+                "amount_usd":   amount_usd,
+                "approval_id":  approval_id,
+                "approve_url":  f"https://bookhotel.ai/approve/{approval_id}",
+            },
+        }).encode()
+        notify_req = urllib.request.Request(
+            f"{NOTIFY_URL}/notify",
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        urllib.request.urlopen(notify_req)
+    except Exception as exc:
+        log.warning("Could not send approval email: %s", exc)
+
+    return {
+        "status":      "pending_approval",
+        "approval_id": approval_id,
+        "message":     f"Approval required (≥${APPROVAL_THRESHOLD:.0f}). Email sent to {approver_email}.",
+    }

services/corporate_service/main.py

@@ -0,0 +1,69 @@
+"""
+services/corporate_service/main.py
+------------------------------------
+FastAPI corporate booking microservice.
+"""
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from typing import Optional
+
+from .rate_lookup     import get_corporate_rate
+from .approval_engine import evaluate as check_approval
+
+app = FastAPI(title="Corporate Service")
+
+
+class RateRequest(BaseModel):
+    corporate_account_id: str
+    hotel_id:             str
+    room_type_id:         str
+    check_in:             str  # YYYY-MM-DD
+
+
+class ApprovalRequest(BaseModel):
+    corporate_account_id: str
+    booking_id:           str
+    amount_usd:           float
+    approver_email:       str
+
+
+@app.post("/rate")
+def corporate_rate(req: RateRequest):
+    return get_corporate_rate(
+        corporate_account_id=req.corporate_account_id,
+        hotel_id=req.hotel_id,
+        room_type_id=req.room_type_id,
+        check_in=req.check_in,
+    )
+
+
+@app.post("/approval")
+def approval(req: ApprovalRequest):
+    return check_approval(
+        corporate_account_id=req.corporate_account_id,
+        booking_id=req.booking_id,
+        amount_usd=req.amount_usd,
+        approver_email=req.approver_email,
+    )
+
+
+@app.get("/approval/{approval_id}")
+def get_approval(approval_id: str):
+    import os, json, urllib.request
+    SUPA = os.environ.get("SUPABASE_URL", "")
+    KEY  = os.environ.get("SUPABASE_SERVICE_ROLE_KEY", "")
+    url  = f"{SUPA}/rest/v1/approval_requests?id=eq.{approval_id}"
+    req  = urllib.request.Request(url, headers={
+        "apikey": KEY, "Authorization": f"Bearer {KEY}"
+    })
+    with urllib.request.urlopen(req) as resp:
+        rows = json.loads(resp.read())
+    if not rows:
+        raise HTTPException(status_code=404, detail="Approval not found")
+    return rows[0]
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "service": "corporate_service"}

services/corporate_service/rate_lookup.py

@@ -0,0 +1,83 @@
+"""
+services/corporate_service/rate_lookup.py
+--------------------------------------------
+Retrieves negotiated corporate rates from Supabase.
+Falls back to the standard best-available rate if no contract exists.
+"""
+
+import os
+import json
+import logging
+import urllib.request
+from datetime import datetime
+
+log = logging.getLogger(__name__)
+
+SUPABASE_URL = os.environ.get("SUPABASE_URL", "")
+SUPABASE_KEY = os.environ.get("SUPABASE_SERVICE_ROLE_KEY", "")
+
+
+def _headers():
+    return {
+        "apikey":        SUPABASE_KEY,
+        "Authorization": f"Bearer {SUPABASE_KEY}",
+        "Content-Type":  "application/json",
+    }
+
+
+def get_corporate_rate(
+    corporate_account_id: str,
+    hotel_id:             str,
+    room_type_id:         str,
+    check_in:             str,
+) -> dict:
+    """
+    Returns:
+        rate_per_night   float
+        currency         str
+        contract_id      str | None
+        is_negotiated    bool
+    """
+    url = (
+        f"{SUPABASE_URL}/rest/v1/corporate_rates"
+        f"?corporate_account_id=eq.{corporate_account_id}"
+        f"&hotel_id=eq.{hotel_id}"
+        f"&room_type_id=eq.{room_type_id}"
+        f"&valid_from=lte.{check_in}"
+        f"&valid_to=gte.{check_in}"
+        f"&is_active=eq.true"
+        f"&select=*&limit=1"
+    )
+    req = urllib.request.Request(url, headers=_headers())
+    with urllib.request.urlopen(req) as resp:
+        rows = json.loads(resp.read())
+
+    if rows:
+        r = rows[0]
+        return {
+            "rate_per_night": float(r["rate_per_night"]),
+            "currency":       r.get("currency", "USD"),
+            "contract_id":    r["id"],
+            "is_negotiated":  True,
+            "discount_label": f"Corporate rate – contract {r['id'][:8]}",
+        }
+
+    # Fallback: fetch standard room rate
+    url2 = (
+        f"{SUPABASE_URL}/rest/v1/room_rates"
+        f"?room_type_id=eq.{room_type_id}"
+        f"&rate_type=eq.standard"
+        f"&select=rate_per_night,currency&limit=1"
+    )
+    req2 = urllib.request.Request(url2, headers=_headers())
+    with urllib.request.urlopen(req2) as resp:
+        rows2 = json.loads(resp.read())
+
+    std_rate = float(rows2[0]["rate_per_night"]) if rows2 else 100.0
+    return {
+        "rate_per_night": std_rate,
+        "currency":       "USD",
+        "contract_id":    None,
+        "is_negotiated":  False,
+        "discount_label": "Best available rate",
+    }

services/force_majeure_service/main.py

@@ -0,0 +1,54 @@
+"""
+services/force_majeure_service/main.py
+----------------------------------------
+FastAPI force-majeure detection & relocation microservice.
+"""
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+from typing import Optional
+
+from .news_monitor import assess
+from .relocation   import find_alternatives, build_relocation_message
+
+app = FastAPI(title="Force Majeure Service")
+
+
+class AssessRequest(BaseModel):
+    city:         str
+    country:      str
+    country_iso2: Optional[str] = ""
+
+
+class RelocationRequest(BaseModel):
+    original_city:  str
+    original_ref:   str
+    check_in:       str
+    check_out:      str
+    guests:         Optional[int]   = 1
+    budget:         Optional[float] = 500.0
+    stars:          Optional[int]   = 3
+
+
+@app.post("/assess")
+def assess_risk(req: AssessRequest):
+    return assess(req.city, req.country, req.country_iso2)
+
+
+@app.post("/relocate")
+def relocate(req: RelocationRequest):
+    alternatives = find_alternatives(
+        original_city=req.original_city,
+        check_in=req.check_in,
+        check_out=req.check_out,
+        guests=req.guests,
+        budget=req.budget,
+        stars=req.stars,
+    )
+    message = build_relocation_message(alternatives, req.original_ref)
+    return {"alternatives": alternatives, "message": message}
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "service": "force_majeure_service"}

services/force_majeure_service/news_monitor.py

@@ -0,0 +1,100 @@
+"""
+services/force_majeure_service/news_monitor.py
+------------------------------------------------
+Monitors news feeds for force-majeure events (severe weather, natural disasters,
+political unrest, pandemics) near hotel locations.
+
+Sources:
+  1. GNews API  (free tier, configurable)
+  2. ReliefWeb API (UN OCHA humanitarian events, free / no key)
+
+Returns a severity level: "none" | "watch" | "warning" | "critical"
+"""
+
+import os
+import json
+import logging
+import urllib.request
+import urllib.parse
+from typing import Optional
+
+log = logging.getLogger(__name__)
+
+GNEWS_KEY = os.environ.get("GNEWS_API_KEY", "")
+FM_KEYWORDS = [
+    "earthquake", "hurricane", "typhoon", "cyclone", "tsunami", "volcano",
+    "flood", "wildfire", "war", "conflict", "martial law", "airport closed",
+    "travel ban", "pandemic", "lockdown", "curfew",
+]
+
+
+def _gnews_search(city: str, country: str) -> list[dict]:
+    if not GNEWS_KEY:
+        return []
+    query = urllib.parse.quote(f"{city} {country} disaster OR emergency OR warning")
+    url   = (
+        f"https://gnews.io/api/v4/search?q={query}"
+        f"&lang=en&max=5&apikey={GNEWS_KEY}"
+    )
+    try:
+        with urllib.request.urlopen(url, timeout=5) as resp:
+            return json.loads(resp.read()).get("articles", [])
+    except Exception as exc:
+        log.debug("GNews unavailable: %s", exc)
+        return []
+
+
+def _reliefweb_search(country_iso2: str) -> list[dict]:
+    url = (
+        "https://api.reliefweb.int/v1/disasters?appname=bookhotel"
+        f"&filter[field]=country.iso3&filter[value]={country_iso2}"
+        "&filter[field]=status&filter[value]=current&limit=5"
+    )
+    try:
+        with urllib.request.urlopen(url, timeout=5) as resp:
+            data = json.loads(resp.read())
+            return data.get("data", [])
+    except Exception as exc:
+        log.debug("ReliefWeb unavailable: %s", exc)
+        return []
+
+
+def assess(
+    city:          str,
+    country:       str,
+    country_iso2:  Optional[str] = "",
+) -> dict:
+    """
+    Returns {severity, events, message}.
+    severity: "none" | "watch" | "warning" | "critical"
+    """
+    articles    = _gnews_search(city, country)
+    rw_events   = _reliefweb_search(country_iso2 or country)
+
+    triggered = []
+    for art in articles:
+        title = (art.get("title") or "").lower()
+        desc  = (art.get("description") or "").lower()
+        for kw in FM_KEYWORDS:
+            if kw in title or kw in desc:
+                triggered.append({"source": "gnews", "keyword": kw, "title": art["title"]})
+                break
+
+    for evt in rw_events:
+        fields = evt.get("fields", {})
+        triggered.append({"source": "reliefweb", "name": fields.get("name"), "type": fields.get("type")})
+
+    if not triggered:
+        severity = "none"
+        message  = "No active force-majeure events detected."
+    elif len(triggered) >= 3:
+        severity = "critical"
+        message  = f"Multiple force-majeure events near {city}. Full waiver recommended."
+    elif len(triggered) >= 1:
+        severity = "watch"
+        message  = f"Potential disruption near {city}. Monitor situation."
+    else:
+        severity = "none"
+        message  = "No active force-majeure events."
+
+    return {"severity": severity, "events": triggered, "message": message}

services/force_majeure_service/relocation.py

@@ -0,0 +1,76 @@
+"""
+services/force_majeure_service/relocation.py
+----------------------------------------------
+Finds alternative hotels when a force-majeure event affects the original hotel.
+Calls the search service to find available hotels in nearby cities.
+"""
+
+import os
+import json
+import logging
+import urllib.request
+
+log = logging.getLogger(__name__)
+
+SEARCH_SERVICE_URL = os.environ.get("SEARCH_SERVICE_URL", "http://localhost:8002")
+
+
+def find_alternatives(
+    original_city: str,
+    check_in:      str,
+    check_out:     str,
+    guests:        int = 1,
+    budget:        float = 500.0,
+    stars:         int  = 3,
+    radius_km:     int  = 50,
+) -> list[dict]:
+    """
+    Calls the search service for nearby hotels and returns relocation options.
+    """
+    payload = json.dumps({
+        "city":       original_city,
+        "check_in":   check_in,
+        "check_out":  check_out,
+        "guests":     guests,
+        "max_price":  budget,
+        "stars":      stars,
+        "radius_km":  radius_km,
+        "limit":      5,
+    }).encode()
+
+    try:
+        req = urllib.request.Request(
+            f"{SEARCH_SERVICE_URL}/search",
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            data = json.loads(resp.read())
+            return data.get("hotels", [])
+    except Exception as exc:
+        log.error("Search service unavailable for relocation: %s", exc)
+        return []
+
+
+def build_relocation_message(
+    alternatives: list[dict],
+    original_ref: str,
+) -> str:
+    """Returns a human-readable relocation offer message."""
+    if not alternatives:
+        return (
+            f"We're sorry, no suitable alternatives are available right now. "
+            f"Your booking {original_ref} has been marked for full refund."
+        )
+    lines = [
+        f"Due to a force-majeure event, we're offering you a free move for booking {original_ref}.\n"
+        "Available alternatives:\n"
+    ]
+    for i, h in enumerate(alternatives[:3], 1):
+        name  = h.get("name", "Hotel")
+        price = h.get("price_per_night", "—")
+        stars = "★" * int(h.get("stars", 3))
+        lines.append(f"{i}. {name} {stars} — ${price}/night")
+    lines.append("\nReply with the number to confirm or type REFUND for a full refund.")
+    return "\n".join(lines)

services/group_service/deposit_scheduler.py

@@ -0,0 +1,56 @@
+"""
+services/group_service/deposit_scheduler.py
+---------------------------------------------
+Schedules deposit reminders for group bookings via Celery.
+30% deposit at block creation → 70% balance due 30 days before event.
+"""
+
+import logging
+from datetime import datetime, timezone, timedelta
+
+log = logging.getLogger(__name__)
+
+
+def schedule_deposits(
+    block_id:       str,
+    total_amount:   float,
+    date_from:      str,
+    organiser_email: str,
+) -> dict:
+    """
+    Schedules Celery tasks to send deposit reminder emails.
+    Returns the schedule as a dict for logging/testing.
+    """
+    try:
+        from tasks.celery_app import celery_app
+    except ImportError:
+        log.warning("Celery not available; deposit schedule logged only")
+        celery_app = None
+
+    deposit_30 = round(total_amount * 0.30, 2)
+    balance_70 = round(total_amount * 0.70, 2)
+    event_date = datetime.strptime(date_from, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+    balance_due = event_date - timedelta(days=30)
+    now         = datetime.now(timezone.utc)
+
+    schedule = {
+        "deposit_30_usd":         deposit_30,
+        "deposit_30_due":         "immediately",
+        "balance_70_usd":         balance_70,
+        "balance_70_due":         balance_due.strftime("%Y-%m-%d"),
+    }
+
+    if celery_app:
+        eta_balance = balance_due if balance_due > now else now + timedelta(minutes=1)
+        celery_app.send_task(
+            "group_service.send_balance_reminder",
+            kwargs={
+                "block_id":       block_id,
+                "amount":         balance_70,
+                "organiser_email": organiser_email,
+            },
+            eta=eta_balance,
+        )
+
+    log.info("Deposit schedule for block %s: %s", block_id, schedule)
+    return schedule

services/group_service/main.py

@@ -0,0 +1,76 @@
+"""
+services/group_service/main.py
+--------------------------------
+FastAPI group booking microservice.
+"""
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from typing import Optional
+
+from .room_block         import create_block, pickup_room, get_block
+from .deposit_scheduler  import schedule_deposits
+
+app = FastAPI(title="Group Service")
+
+
+class BlockRequest(BaseModel):
+    hotel_id:        str
+    room_type_id:    str
+    rooms_reserved:  int
+    date_from:       str  # YYYY-MM-DD
+    date_to:         str  # YYYY-MM-DD
+    group_name:      str
+    pickup_deadline: str  # YYYY-MM-DD
+    rate_per_night:  float
+    organiser_email: str
+
+
+class PickupRequest(BaseModel):
+    block_id:   str
+    booking_id: str
+
+
+@app.post("/block")
+def create(req: BlockRequest):
+    if req.rooms_reserved < 1:
+        raise HTTPException(status_code=422, detail="rooms_reserved must be >= 1")
+
+    block    = create_block(**req.dict())
+    total    = req.rooms_reserved * req.rate_per_night * _nights(req.date_from, req.date_to)
+    schedule = schedule_deposits(
+        block_id=block["id"],
+        total_amount=total,
+        date_from=req.date_from,
+        organiser_email=req.organiser_email,
+    )
+    return {"block": block, "deposit_schedule": schedule}
+
+
+@app.post("/pickup")
+def pickup(req: PickupRequest):
+    try:
+        result = pickup_room(req.block_id, req.booking_id)
+    except ValueError as e:
+        raise HTTPException(status_code=409, detail=str(e))
+    return result
+
+
+@app.get("/block/{block_id}")
+def fetch_block(block_id: str):
+    try:
+        return get_block(block_id)
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "service": "group_service"}
+
+
+def _nights(date_from: str, date_to: str) -> int:
+    from datetime import datetime
+    d1 = datetime.strptime(date_from, "%Y-%m-%d")
+    d2 = datetime.strptime(date_to,   "%Y-%m-%d")
+    return max((d2 - d1).days, 1)

services/group_service/room_block.py

@@ -0,0 +1,99 @@
+"""
+services/group_service/room_block.py
+--------------------------------------
+Manages group / rooming-list room blocks.
+A room block reserves N rooms of a type from date_from to date_to,
+with a pickup deadline and optional deposit schedule.
+"""
+
+import os
+import json
+import logging
+from datetime import datetime, timezone
+import urllib.request
+
+log = logging.getLogger(__name__)
+
+SUPABASE_URL = os.environ.get("SUPABASE_URL", "")
+SUPABASE_KEY = os.environ.get("SUPABASE_SERVICE_ROLE_KEY", "")
+
+
+def _headers():
+    return {
+        "apikey":        SUPABASE_KEY,
+        "Authorization": f"Bearer {SUPABASE_KEY}",
+        "Content-Type":  "application/json",
+        "Prefer":        "return=representation",
+    }
+
+
+def _post(table: str, payload: dict) -> dict:
+    url  = f"{SUPABASE_URL}/rest/v1/{table}"
+    data = json.dumps(payload).encode()
+    req  = urllib.request.Request(url, data=data, headers=_headers(), method="POST")
+    with urllib.request.urlopen(req) as resp:
+        result = json.loads(resp.read())
+    return result[0] if isinstance(result, list) else result
+
+
+def _get(path: str) -> list:
+    url = f"{SUPABASE_URL}/rest/v1/{path}"
+    req = urllib.request.Request(url, headers=_headers())
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read())
+
+
+def create_block(
+    hotel_id:       str,
+    room_type_id:   str,
+    rooms_reserved: int,
+    date_from:      str,
+    date_to:        str,
+    group_name:     str,
+    pickup_deadline: str,
+    rate_per_night:  float,
+    organiser_email: str,
+) -> dict:
+    block = _post("room_blocks", {
+        "hotel_id":        hotel_id,
+        "room_type_id":    room_type_id,
+        "rooms_reserved":  rooms_reserved,
+        "rooms_picked_up": 0,
+        "date_from":       date_from,
+        "date_to":         date_to,
+        "group_name":      group_name,
+        "pickup_deadline": pickup_deadline,
+        "rate_per_night":  rate_per_night,
+        "organiser_email": organiser_email,
+        "status":          "active",
+        "created_at":      datetime.now(timezone.utc).isoformat(),
+    })
+    log.info("Room block created: %s (%d rooms)", group_name, rooms_reserved)
+    return block
+
+
+def pickup_room(block_id: str, booking_id: str) -> dict:
+    """Marks one room from the block as picked up."""
+    blocks = _get(f"room_blocks?id=eq.{block_id}")
+    if not blocks:
+        raise ValueError(f"Block {block_id} not found")
+    block = blocks[0]
+    if block["rooms_picked_up"] >= block["rooms_reserved"]:
+        raise ValueError("All rooms already picked up")
+
+    url  = f"{SUPABASE_URL}/rest/v1/room_blocks?id=eq.{block_id}"
+    data = json.dumps({
+        "rooms_picked_up": block["rooms_picked_up"] + 1,
+        "updated_at":       datetime.now(timezone.utc).isoformat(),
+    }).encode()
+    req = urllib.request.Request(url, data=data, headers=_headers(), method="PATCH")
+    with urllib.request.urlopen(req) as resp:
+        result = json.loads(resp.read())
+    return result[0] if isinstance(result, list) else result
+
+
+def get_block(block_id: str) -> dict:
+    rows = _get(f"room_blocks?id=eq.{block_id}")
+    if not rows:
+        raise ValueError(f"Block {block_id} not found")
+    return rows[0]

services/loyalty_service/gamification.py

@@ -0,0 +1,71 @@
+"""
+services/loyalty_service/gamification.py
+------------------------------------------
+Leaderboard and challenge badges using Redis sorted sets.
+
+Leaderboard key  : loyalty:leaderboard
+Challenge keys   : loyalty:challenge:{name}:{guest_id}
+"""
+
+import os
+import redis
+import logging
+from typing import Optional
+
+log = logging.getLogger(__name__)
+
+_r = redis.from_url(os.environ.get("REDIS_URL", "redis://localhost:6379"), decode_responses=True)
+
+LB_KEY = "loyalty:leaderboard"
+
+BADGES = {
+    "first_booking":  {"label": "First Booking",  "points_bonus": 200},
+    "five_stays":     {"label": "5 Stays",         "points_bonus": 500},
+    "ten_stays":      {"label": "10 Stays",         "points_bonus": 1000},
+    "globe_trotter":  {"label": "Globe Trotter",   "points_bonus": 1500},   # 3+ cities
+    "loyalty_fan":    {"label": "Loyalty Fan",     "points_bonus": 300},    # app review submitted
+    "speed_booker":   {"label": "Speed Booker",    "points_bonus": 100},    # books within 5 min
+}
+
+
+def update_leaderboard(guest_id: str, total_points: int) -> None:
+    """Adds/updates the guest's score in the global leaderboard."""
+    _r.zadd(LB_KEY, {guest_id: total_points})
+
+
+def top_guests(n: int = 10) -> list[dict]:
+    """Returns the top-N guests with their scores."""
+    entries = _r.zrevrange(LB_KEY, 0, n - 1, withscores=True)
+    return [{"guest_id": gid, "points": int(score)} for gid, score in entries]
+
+
+def get_rank(guest_id: str) -> Optional[int]:
+    """Returns 1-based rank of the guest (None if not in leaderboard)."""
+    rank = _r.zrevrank(LB_KEY, guest_id)
+    return None if rank is None else rank + 1
+
+
+def award_badge(guest_id: str, badge_name: str) -> dict:
+    """
+    Marks a badge as earned for the guest.
+    Returns {badge, points_bonus, already_earned}.
+    """
+    key = f"loyalty:badge:{badge_name}:{guest_id}"
+    already = _r.exists(key)
+    if already:
+        return {"badge": badge_name, "points_bonus": 0, "already_earned": True}
+
+    _r.set(key, "1")
+    bonus = BADGES.get(badge_name, {}).get("points_bonus", 0)
+    log.info("Badge '%s' awarded to guest %s (+%d pts)", badge_name, guest_id, bonus)
+    return {"badge": badge_name, "points_bonus": bonus, "already_earned": False}
+
+
+def list_badges(guest_id: str) -> list[str]:
+    """Returns list of badge names earned by the guest."""
+    earned = []
+    for badge_name in BADGES:
+        key = f"loyalty:badge:{badge_name}:{guest_id}"
+        if _r.exists(key):
+            earned.append(badge_name)
+    return earned

services/loyalty_service/main.py

@@ -0,0 +1,81 @@
+"""
+services/loyalty_service/main.py
+----------------------------------
+FastAPI loyalty microservice.
+"""
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from typing import Optional
+
+from .points_engine  import award, redeem, get_balance
+from .tier_engine    import evaluate as evaluate_tier, get_perks, next_tier_info
+from .gamification   import update_leaderboard, top_guests, get_rank, award_badge, list_badges
+
+app = FastAPI(title="Loyalty Service")
+
+
+class AwardRequest(BaseModel):
+    guest_id:   str
+    amount_usd: float
+    booking_id: str
+
+
+class RedeemRequest(BaseModel):
+    guest_id:          str
+    points_to_redeem:  int
+    booking_id:        str
+
+
+class BadgeRequest(BaseModel):
+    guest_id:    str
+    badge_name:  str
+
+
+@app.post("/award")
+def award_points(req: AwardRequest):
+    result = award(req.guest_id, req.amount_usd, req.booking_id)
+    balance = get_balance(req.guest_id)
+    tier    = evaluate_tier(balance["points_balance"])
+    update_leaderboard(req.guest_id, balance["points_balance"])
+    return {**result, "balance": balance, "tier": tier}
+
+
+@app.post("/redeem")
+def redeem_points(req: RedeemRequest):
+    try:
+        result = redeem(req.guest_id, req.points_to_redeem, req.booking_id)
+    except ValueError as e:
+        raise HTTPException(status_code=409, detail=str(e))
+    update_leaderboard(req.guest_id, result["remaining_balance"])
+    return result
+
+
+@app.get("/balance/{guest_id}")
+def balance(guest_id: str):
+    bal     = get_balance(guest_id)
+    tier    = evaluate_tier(bal["points_balance"])
+    next_t  = next_tier_info(bal["points_balance"])
+    badges  = list_badges(guest_id)
+    rank    = get_rank(guest_id)
+    return {**bal, "tier": tier, "next_tier_info": next_t, "badges": badges, "leaderboard_rank": rank}
+
+
+@app.get("/perks/{tier}")
+def perks(tier: str):
+    return get_perks(tier)
+
+
+@app.post("/badge")
+def badge(req: BadgeRequest):
+    return award_badge(req.guest_id, req.badge_name)
+
+
+@app.get("/leaderboard")
+def leaderboard(n: int = 10):
+    return {"leaderboard": top_guests(n)}
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "service": "loyalty_service"}

services/loyalty_service/points_engine.py

@@ -0,0 +1,138 @@
+"""
+services/loyalty_service/points_engine.py
+-------------------------------------------
+Awards and redeems loyalty points.
+
+Earning rule  : 10 points per USD spent
+Redemption    : 100 points = $1 discount
+Expiry        : Points expire after 365 days (handled by scheduled task)
+"""
+
+import os
+import json
+import logging
+from datetime import datetime, timezone, timedelta
+
+import urllib.request
+
+log = logging.getLogger(__name__)
+
+SUPABASE_URL = os.environ.get("SUPABASE_URL", "")
+SUPABASE_KEY = os.environ.get("SUPABASE_SERVICE_ROLE_KEY", "")
+
+POINTS_PER_USD    = 10
+POINTS_PER_DOLLAR = 100   # redemption rate
+
+
+def _headers():
+    return {
+        "apikey":        SUPABASE_KEY,
+        "Authorization": f"Bearer {SUPABASE_KEY}",
+        "Content-Type":  "application/json",
+        "Prefer":        "return=representation",
+    }
+
+
+def _rpc(fn: str, args: dict) -> dict:
+    url  = f"{SUPABASE_URL}/rest/v1/rpc/{fn}"
+    data = json.dumps(args).encode()
+    req  = urllib.request.Request(url, data=data, headers=_headers(), method="POST")
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read())
+
+
+def _get(path: str) -> list:
+    url = f"{SUPABASE_URL}/rest/v1/{path}"
+    req = urllib.request.Request(url, headers=_headers())
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read())
+
+
+def _patch(path: str, payload: dict) -> list:
+    url  = f"{SUPABASE_URL}/rest/v1/{path}"
+    data = json.dumps(payload).encode()
+    req  = urllib.request.Request(url, data=data, headers=_headers(), method="PATCH")
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read())
+
+
+def _insert(table: str, payload: dict) -> dict:
+    url  = f"{SUPABASE_URL}/rest/v1/{table}"
+    data = json.dumps(payload).encode()
+    req  = urllib.request.Request(url, data=data, headers=_headers(), method="POST")
+    with urllib.request.urlopen(req) as resp:
+        result = json.loads(resp.read())
+    return result[0] if isinstance(result, list) else result
+
+
+def award(guest_id: str, amount_usd: float, booking_id: str) -> dict:
+    """Awards points for a completed booking."""
+    points_earned = int(amount_usd * POINTS_PER_USD)
+    if points_earned <= 0:
+        return {"awarded": 0}
+
+    # Upsert loyalty_accounts
+    rows = _get(f"loyalty_accounts?guest_id=eq.{guest_id}")
+    expires = (datetime.now(timezone.utc) + timedelta(days=365)).isoformat()
+
+    if rows:
+        acc    = rows[0]
+        new_pts = acc["points_balance"] + points_earned
+        _patch(f"loyalty_accounts?guest_id=eq.{guest_id}", {"points_balance": new_pts})
+    else:
+        _insert("loyalty_accounts", {
+            "guest_id":       guest_id,
+            "points_balance": points_earned,
+            "tier":           "bronze",
+        })
+
+    # Record transaction
+    _insert("loyalty_transactions", {
+        "guest_id":    guest_id,
+        "booking_id":  booking_id,
+        "points":      points_earned,
+        "type":        "earn",
+        "expires_at":  expires,
+        "created_at":  datetime.now(timezone.utc).isoformat(),
+    })
+
+    log.info("Awarded %d points to guest %s for booking %s", points_earned, guest_id, booking_id)
+    return {"awarded": points_earned}
+
+
+def redeem(guest_id: str, points_to_redeem: int, booking_id: str) -> dict:
+    """
+    Redeems points for a discount.  Returns {discount_usd, remaining_balance}.
+    Raises ValueError if insufficient balance.
+    """
+    rows = _get(f"loyalty_accounts?guest_id=eq.{guest_id}")
+    if not rows or rows[0]["points_balance"] < points_to_redeem:
+        raise ValueError("Insufficient loyalty points")
+
+    acc     = rows[0]
+    new_pts = acc["points_balance"] - points_to_redeem
+    discount_usd = round(points_to_redeem / POINTS_PER_DOLLAR, 2)
+
+    _patch(f"loyalty_accounts?guest_id=eq.{guest_id}", {"points_balance": new_pts})
+
+    _insert("loyalty_transactions", {
+        "guest_id":    guest_id,
+        "booking_id":  booking_id,
+        "points":      -points_to_redeem,
+        "type":        "redeem",
+        "created_at":  datetime.now(timezone.utc).isoformat(),
+    })
+
+    return {"discount_usd": discount_usd, "remaining_balance": new_pts}
+
+
+def get_balance(guest_id: str) -> dict:
+    rows = _get(f"loyalty_accounts?guest_id=eq.{guest_id}")
+    if not rows:
+        return {"points_balance": 0, "tier": "bronze"}
+    acc = rows[0]
+    return {
+        "points_balance": acc.get("points_balance", 0),
+        "tier":           acc.get("tier", "bronze"),
+        "discount_usd":   round(acc.get("points_balance", 0) / POINTS_PER_DOLLAR, 2),
+    }

services/loyalty_service/tier_engine.py

@@ -0,0 +1,54 @@
+"""
+services/loyalty_service/tier_engine.py
+-----------------------------------------
+Upgrades / downgrades loyalty tier based on lifetime points.
+
+Tiers:
+  Bronze  :     0 – 4 999 points
+  Silver  :  5 000 – 19 999 points
+  Gold    : 20 000 – 49 999 points
+  Platinum: 50 000+ points
+"""
+
+TIER_THRESHOLDS = [
+    ("platinum", 50_000),
+    ("gold",     20_000),
+    ("silver",    5_000),
+    ("bronze",        0),
+]
+
+TIER_PERKS = {
+    "bronze":   {"late_checkout": False, "lounge_access": False, "discount_pct": 0},
+    "silver":   {"late_checkout": False, "lounge_access": False, "discount_pct": 5},
+    "gold":     {"late_checkout": True,  "lounge_access": False, "discount_pct": 10},
+    "platinum": {"late_checkout": True,  "lounge_access": True,  "discount_pct": 15},
+}
+
+
+def evaluate(lifetime_points: int) -> str:
+    """Returns the tier name for the given lifetime points total."""
+    for tier_name, threshold in TIER_THRESHOLDS:
+        if lifetime_points >= threshold:
+            return tier_name
+    return "bronze"
+
+
+def get_perks(tier: str) -> dict:
+    return TIER_PERKS.get(tier, TIER_PERKS["bronze"])
+
+
+def next_tier_info(lifetime_points: int) -> dict:
+    """Returns how many points away the guest is from the next tier."""
+    current = evaluate(lifetime_points)
+    tiers   = [t for t, _ in TIER_THRESHOLDS]
+    idx     = tiers.index(current)
+
+    if idx == 0:
+        return {"next_tier": None, "points_needed": 0, "current_tier": current}
+
+    next_tier_name, next_threshold = TIER_THRESHOLDS[idx - 1]
+    return {
+        "current_tier": current,
+        "next_tier":    next_tier_name,
+        "points_needed": next_threshold - lifetime_points,
+    }

services/maps_service/nominatim.py

@@ -0,0 +1,97 @@
+"""
+services/maps_service/nominatim.py
+------------------------------------
+Geocoding + reverse geocoding via OpenStreetMap Nominatim.
+No API key required.  Rate limited to 1 req/s per OSM policy.
+"""
+
+import json
+import logging
+import time
+import urllib.request
+import urllib.parse
+from typing import Optional
+
+log = logging.getLogger(__name__)
+
+NOMINATIM_BASE   = "https://nominatim.openstreetmap.org"
+USER_AGENT       = "BookHotelBot/1.0 (contact@bookhotel.ai)"
+_last_call       = 0.0   # timestamp of last request (rate limit)
+
+
+def _request(url: str) -> dict:
+    global _last_call
+    elapsed = time.time() - _last_call
+    if elapsed < 1.1:
+        time.sleep(1.1 - elapsed)
+
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    with urllib.request.urlopen(req, timeout=10) as resp:
+        _last_call = time.time()
+        return json.loads(resp.read())
+
+
+def geocode(query: str) -> Optional[dict]:
+    """
+    Forward geocoding.
+    Returns {lat, lon, display_name, country_code} or None.
+    """
+    params = urllib.parse.urlencode({
+        "q":      query,
+        "format": "json",
+        "limit":  1,
+        "addressdetails": 1,
+    })
+    url    = f"{NOMINATIM_BASE}/search?{params}"
+    try:
+        results = _request(url)
+        if results:
+            r = results[0]
+            addr = r.get("address", {})
+            return {
+                "lat":          float(r["lat"]),
+                "lon":          float(r["lon"]),
+                "display_name": r["display_name"],
+                "country_code": addr.get("country_code", "").upper(),
+                "city":         addr.get("city") or addr.get("town") or addr.get("village", ""),
+                "country":      addr.get("country", ""),
+            }
+    except Exception as exc:
+        log.error("Nominatim geocode error: %s", exc)
+    return None
+
+
+def reverse_geocode(lat: float, lon: float) -> Optional[dict]:
+    """
+    Reverse geocoding.
+    Returns {display_name, city, country, country_code} or None.
+    """
+    params = urllib.parse.urlencode({
+        "lat":    lat,
+        "lon":    lon,
+        "format": "json",
+        "addressdetails": 1,
+    })
+    url = f"{NOMINATIM_BASE}/reverse?{params}"
+    try:
+        r    = _request(url)
+        addr = r.get("address", {})
+        return {
+            "display_name": r.get("display_name", ""),
+            "city":         addr.get("city") or addr.get("town") or addr.get("village", ""),
+            "country":      addr.get("country", ""),
+            "country_code": addr.get("country_code", "").upper(),
+        }
+    except Exception as exc:
+        log.error("Nominatim reverse geocode error: %s", exc)
+    return None
+
+
+def distance_km(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    """Haversine distance in km between two coordinates."""
+    from math import radians, sin, cos, sqrt, atan2
+    R    = 6371.0
+    dlat = radians(lat2 - lat1)
+    dlon = radians(lon2 - lon1)
+    a    = sin(dlat / 2) ** 2 + cos(radians(lat1)) * cos(radians(lat2)) * sin(dlon / 2) ** 2
+    return R * 2 * atan2(sqrt(a), sqrt(1 - a))

services/notification_service/main.py

@@ -0,0 +1,84 @@
+"""
+services/notification_service/main.py
+---------------------------------------
+FastAPI unified notification microservice.
+Routes to email / WhatsApp / push depending on the channel field.
+"""
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+from typing import Optional, List
+
+from .email_sender    import send as send_email
+from .whatsapp_sender import send_template as send_wa_template, send_text as send_wa_text
+from .push_sender     import send as send_push
+
+app = FastAPI(title="Notification Service")
+
+
+class NotifyRequest(BaseModel):
+    channel:       str           # "email" | "whatsapp" | "push" | "all"
+    booking_ref:   Optional[str] = None
+
+    # Email
+    to_email:      Optional[str] = None
+    to_name:       Optional[str] = None
+    email_subject: Optional[str] = None
+    email_template: Optional[str] = "booking_confirmation.html"
+    template_ctx:  Optional[dict] = None
+
+    # WhatsApp
+    wa_phone:      Optional[str] = None
+    wa_template:   Optional[str] = "booking_confirmation"
+    wa_language:   Optional[str] = "en_US"
+    wa_components: Optional[list] = None
+
+    # Push
+    push_subscription: Optional[dict] = None
+    push_title:        Optional[str]  = None
+    push_body:         Optional[str]  = None
+    push_url:          Optional[str]  = None
+
+
+@app.post("/notify")
+def notify(req: NotifyRequest):
+    results = {}
+
+    ctx = req.template_ctx or {}
+    if req.booking_ref:
+        ctx.setdefault("booking_ref", req.booking_ref)
+
+    # Email
+    if req.channel in ("email", "all") and req.to_email:
+        results["email"] = send_email(
+            to_email=req.to_email,
+            subject=req.email_subject or f"Booking Confirmation – {req.booking_ref}",
+            template=req.email_template,
+            context=ctx,
+            to_name=req.to_name,
+        )
+
+    # WhatsApp
+    if req.channel in ("whatsapp", "all") and req.wa_phone:
+        results["whatsapp"] = send_wa_template(
+            to=req.wa_phone,
+            template_name=req.wa_template,
+            language=req.wa_language,
+            components=req.wa_components,
+        )
+
+    # Push
+    if req.channel in ("push", "all") and req.push_subscription:
+        results["push"] = send_push(
+            subscription_info=req.push_subscription,
+            title=req.push_title or "Booking Update",
+            body=req.push_body  or ctx.get("message", ""),
+            url=req.push_url,
+        )
+
+    return {"results": results}
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "service": "notification_service"}

services/review_service/celery_tasks.py

@@ -0,0 +1,75 @@
+"""
+services/review_service/celery_tasks.py
+-----------------------------------------
+Celery tasks for sending post-stay review requests.
+Triggered 24 h after checkout via a Celery beat schedule.
+"""
+
+from celery import shared_task
+from datetime import datetime, timezone
+import os
+import json
+import logging
+import urllib.request
+
+log = logging.getLogger(__name__)
+
+SUPABASE_URL = os.environ.get("SUPABASE_URL", "")
+SUPABASE_KEY = os.environ.get("SUPABASE_SERVICE_ROLE_KEY", "")
+NOTIFY_URL   = os.environ.get("NOTIFICATION_SERVICE_URL", "http://localhost:8007")
+
+
+def _headers():
+    return {
+        "apikey":        SUPABASE_KEY,
+        "Authorization": f"Bearer {SUPABASE_KEY}",
+        "Content-Type":  "application/json",
+    }
+
+
+@shared_task(name="review_service.send_review_request", bind=True, max_retries=3)
+def send_review_request(self, booking_id: str):
+    """
+    Fetches booking info and sends review request email + Messenger message.
+    """
+    try:
+        url  = f"{SUPABASE_URL}/rest/v1/bookings?id=eq.{booking_id}&select=*,guests(*)"
+        req  = urllib.request.Request(url, headers=_headers())
+        with urllib.request.urlopen(req) as resp:
+            rows = json.loads(resp.read())
+
+        if not rows:
+            log.warning("Review task: booking %s not found", booking_id)
+            return
+
+        booking = rows[0]
+        guest   = (booking.get("guests") or [{}])[0]
+        ctx     = {
+            "guest_name":  guest.get("first_name", "Guest"),
+            "hotel_name":  booking.get("hotel_id"),
+            "booking_ref": booking.get("ref"),
+            "review_url":  f"https://bookhotel.ai/review/{booking.get('ref')}",
+        }
+
+        if guest.get("email"):
+            payload = json.dumps({
+                "channel":        "email",
+                "to_email":       guest["email"],
+                "to_name":        guest.get("first_name"),
+                "email_subject":  "How was your stay? Leave a review",
+                "email_template": "post_stay_review_request.html",
+                "template_ctx":   ctx,
+            }).encode()
+            notify_req = urllib.request.Request(
+                f"{NOTIFY_URL}/notify",
+                data=payload,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            urllib.request.urlopen(notify_req)
+
+        log.info("Review request sent for booking %s", booking_id)
+
+    except Exception as exc:
+        log.error("Review task failed: %s", exc)
+        raise self.retry(exc=exc, countdown=300)

services/review_service/main.py

@@ -0,0 +1,90 @@
+"""
+services/review_service/main.py
+---------------------------------
+FastAPI review microservice.
+Accepts guest reviews, runs sentiment analysis, stores in Supabase,
+and queues a task to notify the hotel.
+"""
+
+import os
+import json
+import logging
+from datetime import datetime, timezone
+import urllib.request
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from typing import Optional
+
+from .sentiment import analyse
+
+log = logging.getLogger(__name__)
+app = FastAPI(title="Review Service")
+
+SUPABASE_URL = os.environ.get("SUPABASE_URL", "")
+SUPABASE_KEY = os.environ.get("SUPABASE_SERVICE_ROLE_KEY", "")
+
+
+def _headers():
+    return {
+        "apikey":        SUPABASE_KEY,
+        "Authorization": f"Bearer {SUPABASE_KEY}",
+        "Content-Type":  "application/json",
+        "Prefer":        "return=representation",
+    }
+
+
+def _insert(table: str, payload: dict) -> dict:
+    url  = f"{SUPABASE_URL}/rest/v1/{table}"
+    data = json.dumps(payload).encode()
+    req  = urllib.request.Request(url, data=data, headers=_headers(), method="POST")
+    with urllib.request.urlopen(req) as resp:
+        result = json.loads(resp.read())
+    return result[0] if isinstance(result, list) else result
+
+
+class ReviewRequest(BaseModel):
+    booking_id:  str
+    guest_id:    str
+    hotel_id:    str
+    rating:      int   # 1-5
+    text:        str
+    language:    Optional[str] = "en"
+
+
+@app.post("/review")
+def submit_review(req: ReviewRequest):
+    if not 1 <= req.rating <= 5:
+        raise HTTPException(status_code=422, detail="Rating must be 1-5")
+
+    sentiment = analyse(req.text)
+
+    review = _insert("reviews", {
+        "booking_id":  req.booking_id,
+        "guest_id":    req.guest_id,
+        "hotel_id":    req.hotel_id,
+        "rating":      req.rating,
+        "text":        req.text,
+        "language":    req.language,
+        "sentiment":   sentiment["sentiment"],
+        "created_at":  datetime.now(timezone.utc).isoformat(),
+    })
+
+    return {"review_id": review.get("id"), "sentiment": sentiment}
+
+
+@app.get("/reviews/{hotel_id}")
+def list_reviews(hotel_id: str, limit: int = 20, offset: int = 0):
+    url = (
+        f"{SUPABASE_URL}/rest/v1/reviews"
+        f"?hotel_id=eq.{hotel_id}&order=created_at.desc"
+        f"&limit={limit}&offset={offset}"
+    )
+    req = urllib.request.Request(url, headers=_headers())
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read())
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "service": "review_service"}

services/review_service/sentiment.py

@@ -0,0 +1,78 @@
+"""
+services/review_service/sentiment.py
+--------------------------------------
+Analyses the sentiment of a review text.
+Uses a simple VADER-based approach (no GPU required) with a
+transformers fallback if the BERT model is available.
+"""
+
+import logging
+from typing import Optional
+
+log = logging.getLogger(__name__)
+
+
+def analyse(text: str) -> dict:
+    """
+    Returns:
+        sentiment   str  "positive" | "neutral" | "negative"
+        score       float  -1.0 to 1.0
+        stars       int   1-5
+    """
+    # Try transformers sentiment pipeline first
+    try:
+        from transformers import pipeline as hf_pipeline
+        _clf = hf_pipeline(
+            "sentiment-analysis",
+            model="distilbert-base-uncased-finetuned-sst-2-english",
+            truncation=True,
+        )
+        result  = _clf(text[:512])[0]
+        label   = result["label"].lower()   # "positive" | "negative"
+        conf    = result["score"]
+        score   = conf if label == "positive" else -conf
+        stars   = _score_to_stars(score)
+        sentiment = "positive" if score > 0.1 else ("negative" if score < -0.1 else "neutral")
+        return {"sentiment": sentiment, "score": round(score, 3), "stars": stars}
+    except Exception as exc:
+        log.debug("Transformers sentiment unavailable: %s – falling back to VADER", exc)
+
+    # VADER fallback
+    try:
+        from vaderSentiment.vaderSentiment import SentimentIntensityAnalyzer
+        analyser = SentimentIntensityAnalyzer()
+        vs       = analyser.polarity_scores(text)
+        score    = vs["compound"]
+        if score >= 0.05:
+            sentiment = "positive"
+        elif score <= -0.05:
+            sentiment = "negative"
+        else:
+            sentiment = "neutral"
+        return {"sentiment": sentiment, "score": round(score, 3), "stars": _score_to_stars(score)}
+    except ImportError:
+        pass
+
+    # Bare keyword fallback
+    positive_words = {"excellent", "great", "amazing", "love", "perfect", "wonderful", "fantastic"}
+    negative_words = {"terrible", "awful", "horrible", "worst", "bad", "dirty", "rude", "disappointing"}
+    tokens = set(text.lower().split())
+    pos = len(tokens & positive_words)
+    neg = len(tokens & negative_words)
+    if pos > neg:
+        return {"sentiment": "positive", "score": 0.5, "stars": 4}
+    if neg > pos:
+        return {"sentiment": "negative", "score": -0.5, "stars": 2}
+    return {"sentiment": "neutral", "score": 0.0, "stars": 3}
+
+
+def _score_to_stars(score: float) -> int:
+    if score >= 0.6:
+        return 5
+    if score >= 0.2:
+        return 4
+    if score >= -0.2:
+        return 3
+    if score >= -0.6:
+        return 2
+    return 1

services/voice_service/audio_utils.py

@@ -0,0 +1,55 @@
+"""
+services/voice_service/audio_utils.py
+----------------------------------------
+Audio pre-processing helpers shared by STT and TTS modules.
+"""
+
+import io
+import logging
+
+log = logging.getLogger(__name__)
+
+
+def convert_to_wav(audio_bytes: bytes, src_format: str = "ogg") -> bytes:
+    """
+    Converts audio to 16-bit PCM WAV at 16 000 Hz mono.
+    Uses pydub + ffmpeg.  Returns raw WAV bytes.
+    """
+    try:
+        from pydub import AudioSegment
+    except ImportError:
+        raise RuntimeError("pydub is required: pip install pydub")
+
+    buf = io.BytesIO(audio_bytes)
+    seg = AudioSegment.from_file(buf, format=src_format)
+    seg = seg.set_channels(1).set_frame_rate(16000).set_sample_width(2)
+
+    out = io.BytesIO()
+    seg.export(out, format="wav")
+    return out.getvalue()
+
+
+def denoise(audio_bytes: bytes, sample_rate: int = 16000) -> bytes:
+    """
+    Applies noisereduce to WAV bytes.
+    Returns denoised WAV bytes.
+    """
+    try:
+        import numpy as np
+        import noisereduce as nr
+        import scipy.io.wavfile as wav_io
+    except ImportError:
+        log.debug("noisereduce not installed; skipping denoising")
+        return audio_bytes
+
+    buf        = io.BytesIO(audio_bytes)
+    sr, data   = wav_io.read(buf)
+    reduced    = nr.reduce_noise(y=data.astype(float), sr=sr)
+    out        = io.BytesIO()
+    wav_io.write(out, sr, reduced.astype(np.int16))
+    return out.getvalue()
+
+
+def audio_bytes_to_base64(audio_bytes: bytes) -> str:
+    import base64
+    return base64.b64encode(audio_bytes).decode()

services/voice_service/main.py

@@ -0,0 +1,60 @@
+"""
+services/voice_service/main.py
+---------------------------------
+FastAPI voice microservice (STT + TTS).
+"""
+
+import base64
+from fastapi import FastAPI, UploadFile, File
+from fastapi.responses import Response
+from pydantic import BaseModel
+from typing import Optional
+
+from .audio_utils import convert_to_wav, denoise
+from .stt import transcribe
+from .tts import synthesize
+
+app = FastAPI(title="Voice Service")
+
+
+class TTSRequest(BaseModel):
+    text:     str
+    language: Optional[str] = "en"
+
+
+@app.post("/stt")
+async def speech_to_text(
+    file:      UploadFile = File(...),
+    language:  Optional[str] = None,
+    denoise_audio: bool = True,
+):
+    raw = await file.read()
+    fmt = (file.content_type or "audio/ogg").split("/")[-1].split(";")[0]
+
+    wav = convert_to_wav(raw, src_format=fmt)
+    if denoise_audio:
+        wav = denoise(wav)
+
+    result = transcribe(wav, language=language)
+    return result
+
+
+@app.post("/tts")
+def text_to_speech(req: TTSRequest):
+    audio = synthesize(req.text, req.language)
+    return {"audio_b64": base64.b64encode(audio).decode(), "format": "wav"}
+
+
+@app.get("/tts/stream")
+def tts_stream(text: str, language: str = "en"):
+    audio = synthesize(text, language)
+    return Response(
+        content=audio,
+        media_type="audio/wav",
+        headers={"Content-Disposition": "inline; filename=speech.wav"},
+    )
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "service": "voice_service"}

services/voice_service/stt.py

@@ -0,0 +1,74 @@
+"""
+services/voice_service/stt.py
+--------------------------------
+Speech-to-text using faster-whisper (local) with a HuggingFace Space fallback.
+"""
+
+import io
+import os
+import logging
+
+log = logging.getLogger(__name__)
+
+HF_STT_URL  = os.environ.get("HF_STT_URL", "")
+WHISPER_SIZE = os.environ.get("WHISPER_MODEL_SIZE", "small")
+
+_whisper_model = None
+
+
+def _get_model():
+    global _whisper_model
+    if _whisper_model is None:
+        try:
+            from faster_whisper import WhisperModel
+            _whisper_model = WhisperModel(WHISPER_SIZE, device="cpu", compute_type="int8")
+            log.info("Whisper %s loaded", WHISPER_SIZE)
+        except Exception as exc:
+            log.error("Could not load Whisper: %s", exc)
+    return _whisper_model
+
+
+def transcribe(audio_bytes: bytes, language: str = None) -> dict:
+    """
+    Transcribes audio bytes (WAV 16 kHz mono) and returns
+    {text, language, confidence}.
+    Falls back to HF Space if local model unavailable.
+    """
+    # Local model path
+    model = _get_model()
+    if model:
+        try:
+            import numpy as np
+            import scipy.io.wavfile as wav_io
+            sr, data = wav_io.read(io.BytesIO(audio_bytes))
+            audio_np  = data.astype(np.float32) / 32768.0
+            segs, info = model.transcribe(
+                audio_np,
+                beam_size=5,
+                language=language,
+                vad_filter=True,
+            )
+            text = " ".join(s.text for s in segs).strip()
+            return {"text": text, "language": info.language, "confidence": info.language_probability}
+        except Exception as exc:
+            log.warning("Local Whisper failed: %s", exc)
+
+    # HF Space fallback
+    if HF_STT_URL:
+        try:
+            import urllib.request
+            import json
+            import base64
+            payload = json.dumps({"audio_b64": base64.b64encode(audio_bytes).decode(), "language": language}).encode()
+            req = urllib.request.Request(
+                f"{HF_STT_URL}/transcribe",
+                data=payload,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                return json.loads(resp.read())
+        except Exception as exc:
+            log.error("HF STT fallback failed: %s", exc)
+
+    return {"text": "", "language": language or "en", "confidence": 0.0}

services/voice_service/tts.py

@@ -0,0 +1,121 @@
+"""
+services/voice_service/tts.py
+--------------------------------
+Text-to-speech using SpeechT5 (English) / MMS-TTS (multilingual) locally,
+with a HuggingFace Space fallback.
+Redis-caches audio by md5(text+lang) for 24 h.
+"""
+
+import os
+import io
+import hashlib
+import logging
+from typing import Optional
+
+import redis
+
+log = logging.getLogger(__name__)
+
+REDIS_URL  = os.environ.get("REDIS_URL",   "redis://localhost:6379")
+HF_TTS_URL = os.environ.get("HF_TTS_URL",  "")
+
+_r = redis.from_url(REDIS_URL, decode_responses=False)
+
+MMS_LANG_MIN = {
+    "en": "eng", "hi": "hin", "te": "tel", "ta": "tam",
+    "fr": "fra", "es": "spa", "ar": "ara", "de": "deu",
+    "zh": "zho", "ja": "jpn", "ko": "kor", "pt": "por",
+}
+
+
+def synthesize(text: str, language: str = "en") -> bytes:
+    """
+    Returns MP3 audio bytes.
+    Checks Redis cache first; generates and stores if not cached.
+    """
+    cache_key = "tts:" + hashlib.md5(f"{language}:{text}".encode()).hexdigest()
+    cached    = _r.get(cache_key)
+    if cached:
+        return cached
+
+    audio = _generate(text, language)
+    if audio:
+        _r.setex(cache_key, 86400, audio)
+    return audio or b""
+
+
+def _generate(text: str, language: str) -> Optional[bytes]:
+    """Tries local model first, then HF Space."""
+    # Local MMS-TTS (multilingual) -----------------------------------------
+    lang_code = MMS_LANG_MIN.get(language[:2], "eng")
+    if language[:2] == "en":
+        audio = _speecht5(text)
+        if audio:
+            return audio
+
+    audio = _mms_tts(text, lang_code)
+    if audio:
+        return audio
+
+    # HF Space fallback -------------------------------------------------------
+    if HF_TTS_URL:
+        try:
+            import urllib.request
+            import json
+            payload = json.dumps({"text": text, "language": language}).encode()
+            req = urllib.request.Request(
+                f"{HF_TTS_URL}/tts",
+                data=payload,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                return resp.read()
+        except Exception as exc:
+            log.error("HF TTS fallback failed: %s", exc)
+
+    return None
+
+
+def _speecht5(text: str) -> Optional[bytes]:
+    try:
+        import torch
+        from transformers import SpeechT5Processor, SpeechT5ForTextToSpeech, SpeechT5HifiGan
+        from datasets import load_dataset
+
+        processor = SpeechT5Processor.from_pretrained("microsoft/speecht5_tts")
+        model     = SpeechT5ForTextToSpeech.from_pretrained("microsoft/speecht5_tts")
+        vocoder   = SpeechT5HifiGan.from_pretrained("microsoft/speecht5_hifigan")
+
+        ds        = load_dataset("Matthijs/cmu-arctic-xvectors", split="validation")
+        xvec      = torch.tensor(ds[7306]["xvector"]).unsqueeze(0)
+
+        inputs    = processor(text=text, return_tensors="pt")
+        speech    = model.generate_speech(inputs["input_ids"], xvec, vocoder=vocoder)
+
+        import scipy.io.wavfile as wav_io
+        buf = io.BytesIO()
+        wav_io.write(buf, 16000, speech.numpy())
+        return buf.getvalue()
+    except Exception as exc:
+        log.debug("SpeechT5 unavailable: %s", exc)
+        return None
+
+
+def _mms_tts(text: str, lang_code: str) -> Optional[bytes]:
+    try:
+        from transformers import VitsModel, AutoTokenizer
+        import torch
+        model_id  = f"facebook/mms-tts-{lang_code}"
+        tokenizer = AutoTokenizer.from_pretrained(model_id)
+        model     = VitsModel.from_pretrained(model_id)
+        inputs    = tokenizer(text, return_tensors="pt")
+        with torch.no_grad():
+            output = model(**inputs).waveform.squeeze().numpy()
+        import scipy.io.wavfile as wav_io
+        buf = io.BytesIO()
+        wav_io.write(buf, model.config.sampling_rate, output)
+        return buf.getvalue()
+    except Exception as exc:
+        log.debug("MMS-TTS unavailable for %s: %s", lang_code, exc)
+        return None

tasks/celery_app.py

@@ -0,0 +1,50 @@
+"""
+tasks/celery_app.py
+---------------------
+Celery application factory.
+Broker  : Redis (REDIS_URL env var)
+Backend : Redis (for result storage)
+"""
+
+import os
+from celery import Celery
+from celery.schedules import crontab
+
+REDIS_URL = os.environ.get("REDIS_URL", "redis://localhost:6379/0")
+
+celery_app = Celery(
+    "bookhotel",
+    broker=REDIS_URL,
+    backend=REDIS_URL,
+    include=[
+        "tasks.scheduled_tasks",
+        "services.review_service.celery_tasks",
+    ],
+)
+
+celery_app.conf.update(
+    task_serializer="json",
+    accept_content=["json"],
+    result_serializer="json",
+    timezone="UTC",
+    enable_utc=True,
+    task_acks_late=True,
+    worker_prefetch_multiplier=1,
+    task_track_started=True,
+    result_expires=3600,
+    # Beat schedule
+    beat_schedule={
+        "send-review-requests-daily": {
+            "task":     "tasks.scheduled_tasks.trigger_review_requests",
+            "schedule": crontab(hour=10, minute=0),   # 10:00 UTC daily
+        },
+        "expire-loyalty-points-monthly": {
+            "task":     "tasks.scheduled_tasks.expire_loyalty_points",
+            "schedule": crontab(day_of_month=1, hour=0, minute=0),
+        },
+        "release-stale-soft-locks": {
+            "task":     "tasks.scheduled_tasks.release_stale_soft_locks",
+            "schedule": crontab(minute="*/15"),   # every 15 min
+        },
+    },
+)

tasks/scheduled_tasks.py

@@ -0,0 +1,100 @@
+"""
+tasks/scheduled_tasks.py
+--------------------------
+Celery beat-scheduled maintenance tasks.
+"""
+
+import os
+import json
+import logging
+from datetime import datetime, timezone, timedelta
+import urllib.request
+
+from .celery_app import celery_app
+
+log = logging.getLogger(__name__)
+
+SUPABASE_URL = os.environ.get("SUPABASE_URL", "")
+SUPABASE_KEY = os.environ.get("SUPABASE_SERVICE_ROLE_KEY", "")
+REDIS_URL    = os.environ.get("REDIS_URL", "redis://localhost:6379/0")
+
+
+def _sb_headers():
+    return {
+        "apikey":        SUPABASE_KEY,
+        "Authorization": f"Bearer {SUPABASE_KEY}",
+        "Content-Type":  "application/json",
+    }
+
+
+@celery_app.task(name="tasks.scheduled_tasks.trigger_review_requests")
+def trigger_review_requests():
+    """
+    Finds bookings that checked out yesterday and enqueues review requests.
+    """
+    yesterday = (datetime.now(timezone.utc) - timedelta(days=1)).strftime("%Y-%m-%d")
+    url = (
+        f"{SUPABASE_URL}/rest/v1/bookings"
+        f"?check_out=eq.{yesterday}&status=eq.confirmed&select=id"
+    )
+    req = urllib.request.Request(url, headers=_sb_headers())
+    with urllib.request.urlopen(req) as resp:
+        bookings = json.loads(resp.read())
+
+    queued = 0
+    for b in bookings:
+        celery_app.send_task(
+            "review_service.send_review_request",
+            kwargs={"booking_id": b["id"]},
+            countdown=3600,  # 1 h after checkout
+        )
+        queued += 1
+    log.info("Queued %d review request tasks for %s", queued, yesterday)
+    return {"queued": queued, "date": yesterday}
+
+
+@celery_app.task(name="tasks.scheduled_tasks.expire_loyalty_points")
+def expire_loyalty_points():
+    """
+    Marks loyalty_transactions expired where expires_at < now.
+    (Points deduction handled by a Supabase function / trigger in production.)
+    """
+    now = datetime.now(timezone.utc).isoformat()
+    url = (
+        f"{SUPABASE_URL}/rest/v1/loyalty_transactions"
+        f"?expires_at=lt.{now}&expired=eq.false"
+    )
+    headers = {**_sb_headers(), "Prefer": "return=representation"}
+    data    = json.dumps({"expired": True}).encode()
+    req     = urllib.request.Request(url, data=data, headers=headers, method="PATCH")
+    with urllib.request.urlopen(req) as resp:
+        updated = json.loads(resp.read())
+    log.info("Expired %d loyalty point records", len(updated))
+    return {"expired": len(updated)}
+
+
+@celery_app.task(name="tasks.scheduled_tasks.release_stale_soft_locks")
+def release_stale_soft_locks():
+    """
+    Redis soft locks expire via TTL automatically, but this task cleans up
+    any orphaned keys whose session no longer exists.
+    Iterates soft_lock:* keys older than LOCK_TTL without matching session.
+    """
+    import redis as redis_lib
+    r = redis_lib.from_url(REDIS_URL, decode_responses=True)
+    pattern  = "soft_lock:*"
+    cursor   = 0
+    released = 0
+
+    while True:
+        cursor, keys = r.scan(cursor, match=pattern, count=200)
+        for key in keys:
+            ttl = r.ttl(key)
+            if ttl == -1:   # no TTL set → stale
+                r.delete(key)
+                released += 1
+        if cursor == 0:
+            break
+
+    log.info("Released %d stale soft locks", released)
+    return {"released": released}