Add SafarX AI Travel Companion backend with Docker support

.dockerignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.env
+.venv
+env.bak
+venv.bak
+.git/
+.gitignore
+.vscode/

.env.example

@@ -0,0 +1,33 @@
+# Copy this file to .env and fill in your own values
+# NEVER commit the actual .env file to version control
+
+# ── Google Gemini ─────────────────────────────────────────────
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# ── Tavily Search ─────────────────────────────────────────────
+TAVILY_API_KEY=your_tavily_api_key_here
+
+# ── TBO (TekTravels) API ──────────────────────────────────────
+TBO_CLIENT_ID=ApiIntegrationNew
+TBO_USERNAME=your_tbo_username
+TBO_PASSWORD=your_tbo_password
+TBO_END_USER_IP=
+
+# TBO Endpoint URLs (leave as-is unless using a different environment)
+TBO_AUTH_URL=http://Sharedapi.tektravels.com/SharedData.svc/rest/Authenticate
+TBO_LOGOUT_URL=http://Sharedapi.tektravels.com/SharedData.svc/rest/Logout
+TBO_SEARCH_URL=http://api.tektravels.com/BookingEngineService_Air/AirService.svc/rest/Search
+TBO_BOOK_URL=http://api.tektravels.com/BookingEngineService_Air/AirService.svc/rest/Book
+TBO_TICKET_URL=http://api.tektravels.com/BookingEngineService_Air/AirService.svc/rest/Ticket
+
+
+# ── RapidAPI / TripAdvisor Hotel Credentials ─────────────
+RAPIDAPI_KEY=your_rapidapi_key_here
+RAPIDAPI_HOST=tripadvisor16.p.rapidapi.com
+
+# ── Server ────────────────────────────────────────────────────
+HOST=0.0.0.0
+PORT=8000
+
+# ── Frontend URL (for CORS) ───────────────────────────────────
+FRONTEND_URL=http://localhost:5173

Dockerfile

@@ -0,0 +1,18 @@
+# Use the official Python string image
+FROM python:3.10-slim
+
+# Set the working directory
+WORKDIR /app
+
+# Install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the application code
+COPY . .
+
+# Expose port (Hugging Face Spaces uses 7860 by default for Docker spaces)
+EXPOSE 7860
+
+# Command to run the FastApi application
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,29 @@
 ---
 title: SafarX
-emoji: 📉
+emoji: ✈️
 colorFrom: blue
-colorTo: indigo
+colorTo: purple
 sdk: docker
 pinned: false
+license: mit
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# SafarX - AI Travel Companion Backend
+
+FastAPI backend for the SafarX AI Travel Companion, powered by Google Gemini.
+
+## Features
+- AI-powered travel chat agent
+- Web search via Tavily
+- Flight booking (TBO/TekTravels API)
+- Hotel search (TripAdvisor via RapidAPI)
+- Itinerary generation
+- Destination recommendations
+
+## Environment Variables
+Set the following secrets in your Hugging Face Space settings:
+- `GEMINI_API_KEY`
+- `TAVILY_API_KEY`
+- `TBO_CLIENT_ID`, `TBO_USERNAME`, `TBO_PASSWORD`
+- `RAPIDAPI_KEY`

agent.py

@@ -0,0 +1,224 @@
+"""
+Gemini-powered Travel AI Agent with tool calling capabilities.
+"""
+
+import os
+import json
+from typing import Optional
+import google.generativeai as genai
+from dotenv import load_dotenv
+
+from prompts import SYSTEM_PROMPT, ITINERARY_PROMPT, RECOMMENDATION_PROMPT
+from tools import (
+    search_web,
+    generate_itinerary,
+    recommend_destinations,
+    TOOL_DEFINITIONS
+)
+
+
+load_dotenv()
+
+# Configure Gemini
+genai.configure(api_key=os.getenv("GEMINI_API_KEY"))
+
+
+class TravelAgent:
+    """
+    Immersive Traveler Companion AI Agent powered by Gemini.
+    Handles travel queries with tool calling for VR, search, and recommendations.
+    """
+    
+    def __init__(self):
+        self.model = genai.GenerativeModel(
+            model_name="gemini-3-flash-preview",
+            system_instruction=SYSTEM_PROMPT,
+            tools=self._get_tools()
+        )
+        self.chat_sessions = {}  # Store chat history per session
+    
+    def _get_tools(self):
+        """Define tools for Gemini function calling."""
+        return [
+            genai.protos.Tool(
+                function_declarations=[
+                    genai.protos.FunctionDeclaration(
+                        name="search_web",
+                        description="Search the web for travel information, booking websites, flight prices, hotel deals. Use when users ask about booking or need real-time info.",
+                        parameters=genai.protos.Schema(
+                            type=genai.protos.Type.OBJECT,
+                            properties={
+                                "query": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Search query for travel information"
+                                )
+                            },
+                            required=["query"]
+                        )
+                    ),
+
+                    genai.protos.FunctionDeclaration(
+                        name="generate_itinerary",
+                        description="Generate a detailed day-by-day travel itinerary. Use when users want to plan a trip.",
+                        parameters=genai.protos.Schema(
+                            type=genai.protos.Type.OBJECT,
+                            properties={
+                                "destination": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Travel destination"
+                                ),
+                                "days": genai.protos.Schema(
+                                    type=genai.protos.Type.INTEGER,
+                                    description="Number of days"
+                                ),
+                                "preferences": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Travel preferences"
+                                )
+                            },
+                            required=["destination", "days"]
+                        )
+                    ),
+                    genai.protos.FunctionDeclaration(
+                        name="recommend_destinations",
+                        description="Recommend destinations based on preferences. Use when users describe their ideal trip.",
+                        parameters=genai.protos.Schema(
+                            type=genai.protos.Type.OBJECT,
+                            properties={
+                                "budget": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Budget: 'budget', 'moderate', 'luxury'"
+                                ),
+                                "style": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Style: 'adventure', 'relaxation', 'cultural'"
+                                ),
+                                "interests": genai.protos.Schema(
+                                    type=genai.protos.Type.STRING,
+                                    description="Interests like beaches, mountains, food"
+                                )
+                            },
+                            required=[]
+                        )
+                    )
+                ]
+            )
+        ]
+    
+    def get_or_create_session(self, session_id: str):
+        """Get existing chat session or create new one."""
+        if session_id not in self.chat_sessions:
+            self.chat_sessions[session_id] = self.model.start_chat(history=[])
+        return self.chat_sessions[session_id]
+    
+    async def _execute_tool(self, tool_name: str, tool_args: dict) -> dict:
+        """Execute a tool and return results."""
+        if tool_name == "search_web":
+            return await search_web(tool_args.get("query", ""))
+
+        elif tool_name == "generate_itinerary":
+            return generate_itinerary(
+                tool_args.get("destination", ""),
+                tool_args.get("days", 3),
+                tool_args.get("preferences")
+            )
+        elif tool_name == "recommend_destinations":
+            return recommend_destinations(
+                budget=tool_args.get("budget"),
+                style=tool_args.get("style"),
+                interests=tool_args.get("interests", "").split(",") if tool_args.get("interests") else None
+            )
+        return {"error": f"Unknown tool: {tool_name}"}
+    
+    async def chat(self, message: str, session_id: str = "default") -> dict:
+        """
+        Process a chat message and return agent response.
+        
+        Args:
+            message: User message
+            session_id: Session ID for chat history
+            
+        Returns:
+            Dictionary with response text, tool calls, and metadata
+        """
+        chat = self.get_or_create_session(session_id)
+        
+        try:
+            # Send message to Gemini
+            response = chat.send_message(message)
+            
+            result = {
+                "response": "",
+                "tool_calls": [],
+                "search_results": None,
+                "itinerary": None,
+                "recommendations": None
+
+            }
+            
+            # Process response parts
+            for part in response.parts:
+                if hasattr(part, 'text') and part.text:
+                    result["response"] += part.text
+                
+                if hasattr(part, 'function_call') and part.function_call:
+                    fc = part.function_call
+                    tool_name = fc.name
+                    tool_args = dict(fc.args)
+                    
+                    # Execute tool
+                    tool_result = await self._execute_tool(tool_name, tool_args)
+                    
+                    result["tool_calls"].append({
+                        "name": tool_name,
+                        "args": tool_args,
+                        "result": tool_result
+                    })
+                    
+                    # Categorize results
+                    if tool_name == "search_web":
+                        result["search_results"] = tool_result
+                    elif tool_name == "generate_itinerary":
+                        result["itinerary"] = tool_result
+                    elif tool_name == "recommend_destinations":
+                        result["recommendations"] = tool_result
+                    
+                    # Send tool result back to model for final response
+
+                    function_response = genai.protos.Part(
+                        function_response=genai.protos.FunctionResponse(
+                            name=tool_name,
+                            response={"result": json.dumps(tool_result)}
+                        )
+                    )
+                    
+                    follow_up = chat.send_message(function_response)
+                    for fp in follow_up.parts:
+                        if hasattr(fp, 'text') and fp.text:
+                            result["response"] += "\n\n" + fp.text
+            
+            return result
+            
+        except Exception as e:
+            return {
+                "response": f"I apologize, but I encountered an error: {str(e)}. Please try again.",
+                "tool_calls": [],
+                "error": str(e)
+            }
+    
+    def clear_session(self, session_id: str):
+        """Clear chat history for a session."""
+        if session_id in self.chat_sessions:
+            del self.chat_sessions[session_id]
+
+
+# Global agent instance
+_agent = None
+
+
+def get_agent() -> TravelAgent:
+    """Get or create agent singleton."""
+    global _agent
+    if _agent is None:
+        _agent = TravelAgent()
+    return _agent

config.py

@@ -0,0 +1,46 @@
+# backend/config.py
+
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+
+
+class Settings(BaseSettings):
+    # ── TBO Credentials ──────────────────────────────────────────
+    tbo_client_id:   str = "ApiIntegrationNew"
+    tbo_username:    str = ""
+    tbo_password:    str = ""
+    tbo_end_user_ip: str = ""
+
+    # ── TBO URLs ─────────────────────────────────────────────────
+    tbo_auth_url:   str = "http://Sharedapi.tektravels.com/SharedData.svc/rest/Authenticate"
+    tbo_logout_url: str = "http://Sharedapi.tektravels.com/SharedData.svc/rest/Logout"
+    tbo_search_url: str = "http://api.tektravels.com/BookingEngineService_Air/AirService.svc/rest/Search"
+    tbo_book_url:   str = "http://api.tektravels.com/BookingEngineService_Air/AirService.svc/rest/Book"
+    tbo_ticket_url: str = "http://api.tektravels.com/BookingEngineService_Air/AirService.svc/rest/Ticket"
+
+    # ── RapidAPI / TripAdvisor Hotel Credentials ─────────────────
+    rapidapi_key:  str = ""
+    rapidapi_host: str = "tripadvisor16.p.rapidapi.com"
+
+    # ── Gemini AI ─────────────────────────────────────────────────
+    gemini_api_key: str = ""
+
+    # ── Tavily Search ─────────────────────────────────────────────
+    tavily_api_key: str = ""
+
+    # ── Server ────────────────────────────────────────────────────
+    host: str = "0.0.0.0"
+    port: int = 8000
+
+    # ── App ───────────────────────────────────────────────────────
+    frontend_url: str = "http://localhost:5173"
+
+    model_config = {
+        "env_file": ".env",
+        "extra": "ignore",       # ← silently ignore any unknown .env keys
+    }
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    return Settings()

main.py

@@ -0,0 +1,209 @@
+"""
+FastAPI Backend for Immersive Traveler Companion AI
+Main application with all API endpoints.
+"""
+
+import os
+from typing import Optional, List
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from dotenv import load_dotenv
+
+from agent import get_agent
+from tavily_client import get_tavily_client
+from tools import recommend_destinations, generate_itinerary
+
+# Add this to your existing main FastAPI file
+from routers.hotel_routes import router as hotel_router
+
+
+# ── NEW: Import flight router ─────────────────────────────────
+from routers.flights import router as flights_router
+# ─────────────────────────────────────────────────────────────
+
+load_dotenv()
+
+# Initialize FastAPI app
+app = FastAPI(
+    title="Immersive Traveler Companion AI",
+    description="AI-powered travel assistant with VR previews, web search, and personalized recommendations",
+    version="1.0.0"
+)
+
+# CORS middleware for frontend
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # In production, specify your frontend URL
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ── NEW: Mount flight booking routes ──────────────────────────
+# All flight routes will be prefixed with /flights
+# e.g. POST /flights/search, POST /flights/book
+app.include_router(flights_router)
+# ─────────────────────────────────────────────────────────────
+app.include_router(hotel_router)
+
+# ============== Pydantic Models ==============
+# (all your existing models stay completely unchanged)
+
+class ChatRequest(BaseModel):
+    message: str
+    session_id: Optional[str] = "default"
+
+
+class ChatResponse(BaseModel):
+    response: str
+    tool_calls: list = []
+    search_results: Optional[dict] = None
+    itinerary: Optional[dict] = None
+    recommendations: Optional[dict] = None
+    error: Optional[str] = None
+
+
+class SearchRequest(BaseModel):
+    query: str
+    max_results: Optional[int] = 5
+
+
+class SearchResponse(BaseModel):
+    query: str
+    results: list
+    answer: Optional[str] = None
+    error: Optional[str] = None
+
+
+class ItineraryRequest(BaseModel):
+    destination: str
+    days: int
+    preferences: Optional[str] = None
+
+
+class ItineraryResponse(BaseModel):
+    destination: str
+    days: int
+    itinerary: str
+
+
+class RecommendRequest(BaseModel):
+    budget: Optional[str] = None
+    style: Optional[str] = None
+    interests: Optional[List[str]] = None
+    duration: Optional[str] = None
+    season: Optional[str] = None
+
+
+class RecommendResponse(BaseModel):
+    recommendations: str
+    preferences: dict
+
+
+# ============== API Endpoints ==============
+# (all your existing endpoints stay completely unchanged)
+
+@app.get("/")
+async def root():
+    """Health check endpoint."""
+    return {
+        "status": "online",
+        "service": "Immersive Traveler Companion AI",
+        "version": "1.0.0"
+    }
+
+
+@app.post("/agent", response_model=ChatResponse)
+async def agent_chat(request: ChatRequest):
+    """Main chat endpoint for the AI travel agent."""
+    try:
+        agent = get_agent()
+        result = await agent.chat(request.message, request.session_id)
+        return ChatResponse(**result)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/search", response_model=SearchResponse)
+async def web_search(request: SearchRequest):
+    """Direct web search endpoint using Tavily."""
+    try:
+        client = get_tavily_client()
+        result = await client.search(request.query, request.max_results)
+        return SearchResponse(**result)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/itinerary", response_model=ItineraryResponse)
+async def create_itinerary(request: ItineraryRequest):
+    """Generate a detailed travel itinerary."""
+    try:
+        agent = get_agent()
+        prompt = f"Generate a detailed {request.days}-day itinerary for {request.destination}"
+        if request.preferences:
+            prompt += f" with focus on: {request.preferences}"
+        result = await agent.chat(prompt, session_id=f"itinerary_{request.destination}")
+        return ItineraryResponse(
+            destination=request.destination,
+            days=request.days,
+            itinerary=result["response"]
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/recommend", response_model=RecommendResponse)
+async def get_recommendations(request: RecommendRequest):
+    """Get personalized destination recommendations."""
+    try:
+        agent = get_agent()
+        preferences = []
+        if request.budget:
+            preferences.append(f"budget: {request.budget}")
+        if request.style:
+            preferences.append(f"style: {request.style}")
+        if request.interests:
+            preferences.append(f"interests: {', '.join(request.interests)}")
+        if request.duration:
+            preferences.append(f"duration: {request.duration}")
+        if request.season:
+            preferences.append(f"season: {request.season}")
+
+        pref_str = ", ".join(preferences) if preferences else "no specific preferences"
+        prompt = f"Recommend travel destinations based on: {pref_str}"
+        result = await agent.chat(prompt, session_id="recommendations")
+
+        return RecommendResponse(
+            recommendations=result["response"],
+            preferences={
+                "budget": request.budget,
+                "style": request.style,
+                "interests": request.interests,
+                "duration": request.duration,
+                "season": request.season
+            }
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.delete("/session/{session_id}")
+async def clear_session(session_id: str):
+    """Clear chat history for a session."""
+    try:
+        agent = get_agent()
+        agent.clear_session(session_id)
+        return {"status": "cleared", "session_id": session_id}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ============== Run Server ==============
+
+if __name__ == "__main__":
+    import uvicorn
+    host = os.getenv("HOST", "0.0.0.0")
+    port = int(os.getenv("PORT", 8000))
+    uvicorn.run("main:app", host=host, port=port, reload=True)

models/flight_models.py

@@ -0,0 +1,98 @@
+from pydantic import BaseModel
+from typing import Optional, List
+from datetime import datetime
+
+
+# ─── Auth Models ─────────────────────────────────────────────
+
+class TokenCache(BaseModel):
+    """
+    Stores the token in memory so we don't
+    call authenticate on every search request.
+    Token is valid from 00:00 AM to 11:59 PM same day.
+    """
+    token_id: str
+    member_id: int
+    agency_id: int
+    generated_date: str  # store as YYYY-MM-DD
+
+
+# ─── Search Request Models ────────────────────────────────────
+
+class FlightSegment(BaseModel):
+    """One segment of the journey (origin → destination)"""
+    origin: str                  # e.g. "DEL"
+    destination: str             # e.g. "BOM"
+    departure_date: str          # e.g. "2024-08-10"
+    cabin_class: int = 2         # 1=All 2=Economy 3=PremiumEconomy 4=Business 5=PremiumBusiness 6=First
+
+
+class FlightSearchRequest(BaseModel):
+    """
+    What the frontend sends to our backend
+    (simplified, human-friendly format)
+    """
+    origin: str                              # e.g. "DEL"
+    destination: str                         # e.g. "DXB"
+    departure_date: str                      # e.g. "2024-08-10"
+    return_date: Optional[str] = None        # only for round trips
+    adult_count: int = 1
+    child_count: int = 0
+    infant_count: int = 0
+    cabin_class: int = 2                     # Economy default
+    trip_type: str = "one-way"               # "one-way" | "round"
+    direct_flight: bool = False
+
+
+# ─── Booking Request Models ───────────────────────────────────
+
+class PassengerFare(BaseModel):
+    base_fare: float
+    tax: float
+    transaction_fee: float = 0
+    yq_tax: float = 0
+    additional_txn_fee_ofrd: float = 0
+    additional_txn_fee_pub: float = 0
+    air_trans_fee: float = 0
+
+
+class PassengerDetail(BaseModel):
+    title: str                    # "Mr", "Mrs", "Miss", "Mstr"
+    first_name: str
+    last_name: str
+    pax_type: int                 # 1=Adult, 2=Child, 3=Infant
+    gender: int                   # 1=Male, 2=Female
+    date_of_birth: Optional[str] = None
+    passport_no: Optional[str] = None
+    passport_expiry: Optional[str] = None
+    address_line1: str
+    city: str
+    country_code: str
+    country_name: str
+    contact_no: str
+    email: str
+    is_lead_pax: bool = False
+    nationality: str = "IN"
+    fare: PassengerFare
+
+
+class FlightBookRequest(BaseModel):
+    """What the frontend sends to book a flight"""
+    result_index: str            # from search results
+    trace_id: str                # from search response (valid 15 mins)
+    passengers: List[PassengerDetail]
+
+
+class FlightTicketRequest(BaseModel):
+    """What the frontend sends to ticket (for LCC)"""
+    result_index: str
+    trace_id: str
+    passengers: List[PassengerDetail]
+
+
+class NonLCCTicketRequest(BaseModel):
+    """For Non-LCC (already booked via Book endpoint)"""
+    trace_id: str
+    pnr: str
+    booking_id: int
+    is_price_change_accepted: bool = False

models/hotel_models.py

@@ -0,0 +1,37 @@
+from pydantic import BaseModel
+from typing import Optional, List
+
+class SearchLocationRequest(BaseModel):
+    query: str
+
+class SearchHotelsRequest(BaseModel):
+    geoId: str
+    checkIn: str
+    checkOut: str
+    pageNumber: Optional[int] = 1
+    sort: Optional[str] = None
+    adults: Optional[int] = 0
+    rooms: Optional[int] = 0
+    currencyCode: Optional[str] = "USD"
+    rating: Optional[int] = 0
+    priceMin: Optional[int] = 0
+    priceMax: Optional[int] = 0
+
+class SearchHotelsByLocationRequest(BaseModel):
+    latitude: str
+    longitude: str
+    checkIn: str
+    checkOut: str
+    pageNumber: Optional[int] = 1
+    sort: Optional[str] = None
+    adults: Optional[int] = 0
+    rooms: Optional[int] = 0
+    currencyCode: Optional[str] = "USD"
+
+class HotelDetailsRequest(BaseModel):
+    id: str
+    checkIn: str
+    checkOut: str
+    adults: Optional[int] = 0
+    rooms: Optional[int] = 0
+    currency: Optional[str] = "USD"

prompts.py

@@ -0,0 +1,75 @@
+"""
+System prompts for the Immersive Traveler Companion AI Agent.
+"""
+
+SYSTEM_PROMPT = """You are an Immersive Traveler Companion AI — a sophisticated, friendly, and knowledgeable travel assistant.
+
+## Your Capabilities:
+1. **Destination Discovery**: Help users explore and discover travel destinations based on their preferences, budget, travel style, and interests.
+2. **Itinerary Generation**: Create detailed, day-by-day travel itineraries with activities, timings, and local tips.
+3. **Web Search**: Use Tavily to search for real-time information about booking websites, flights, hotels, and travel deals.
+4. **Personalized Recommendations**: Offer tailored suggestions based on user preferences.
+
+
+## Your Personality:
+- Friendly and enthusiastic about travel
+- Concise but informative
+- Confident in your recommendations
+- Culturally aware and respectful
+- Proactive in offering helpful suggestions
+
+## Response Guidelines:
+1. Keep responses concise and scannable
+2. Use bullet points and structured formatting
+3. Always offer actionable next steps
+4. When mentioning destinations, offer helpful details
+
+5. When users ask about bookings, use web search to find current options
+6. Be proactive about suggesting itineraries for mentioned destinations
+
+## Tool Usage:
+- Use `search_web` when users ask about booking, prices, current deals, or need real-time information
+
+- Use `generate_itinerary` when users want a trip plan
+- Use `recommend_destinations` when users describe their travel preferences
+
+## Example Interactions:
+User: "Plan a 3-day Goa trip"
+→ Generate itinerary + Ask about booking needs
+
+User: "Where should I book tickets?"
+→ Use Tavily to search for best booking platforms
+
+User: "I want a peaceful beach destination under $1000"
+→ Recommend destinations
+
+Remember: You're here to make travel planning exciting, effortless, and immersive!
+"""
+
+ITINERARY_PROMPT = """Generate a detailed {days}-day travel itinerary for {destination}.
+
+Include for each day:
+- Morning, afternoon, and evening activities
+- Recommended restaurants and local cuisine
+- Travel tips and estimated costs
+- Must-see attractions
+- Hidden gems and local experiences
+
+Format the response as a structured itinerary with clear day-by-day breakdown.
+Make it practical, exciting, and culturally immersive.
+"""
+
+RECOMMENDATION_PROMPT = """Based on the following travel preferences, recommend the top 3-5 destinations:
+
+Preferences: {preferences}
+
+For each destination, provide:
+- Destination name and country
+- Why it matches their preferences
+- Best time to visit
+- Estimated budget range
+- 2-3 highlight experiences
+
+
+Be creative and consider both popular and off-the-beaten-path options.
+"""

requirements.txt

@@ -0,0 +1,10 @@
+fastapi==0.109.0
+uvicorn[standard]==0.27.0
+python-dotenv==1.0.0
+google-generativeai==0.8.3
+httpx==0.27.0
+pydantic==2.5.3
+tavily-python==0.5.0
+
+pydantic-settings==2.1.0
+python-multipart==0.0.6

routers/flights.py

@@ -0,0 +1,236 @@
+# backend/routers/flights.py
+
+"""
+Flight booking API routes.
+These get mounted into the existing FastAPI app in main.py.
+"""
+
+from fastapi import APIRouter, HTTPException, status
+from pydantic import BaseModel, Field
+from typing import Optional, List
+from services import tbo_service
+import logging
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(
+    prefix="/flights",
+    tags=["Flight Booking"],
+)
+
+
+# ─── Request / Response Models ────────────────────────────────
+
+class FlightSearchRequest(BaseModel):
+    origin: str = Field(..., min_length=2, max_length=3, example="DEL")
+    destination: str = Field(..., min_length=2, max_length=3, example="DXB")
+    departure_date: str = Field(..., example="2024-08-10")
+    return_date: Optional[str] = Field(None, example="2024-08-17")
+    adult_count: int = Field(1, ge=1, le=9)
+    child_count: int = Field(0, ge=0, le=9)
+    infant_count: int = Field(0, ge=0, le=9)
+    cabin_class: int = Field(2, ge=1, le=6)
+    trip_type: str = Field("one-way", example="one-way")
+    direct_flight: bool = False
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "origin": "DEL",
+                "destination": "BOM",
+                "departure_date": "2024-08-10",
+                "adult_count": 1,
+                "child_count": 0,
+                "infant_count": 0,
+                "cabin_class": 2,
+                "trip_type": "one-way",
+                "direct_flight": False
+            }
+        }
+
+
+class PassengerFareModel(BaseModel):
+    base_fare: float = 0
+    tax: float = 0
+    transaction_fee: float = 0
+    yq_tax: float = 0
+
+
+class PassengerModel(BaseModel):
+    title: str = "Mr"
+    first_name: str
+    last_name: str
+    pax_type: int = 1           # 1=Adult, 2=Child, 3=Infant
+    gender: int = 1             # 1=Male, 2=Female
+    date_of_birth: Optional[str] = None
+    passport_no: Optional[str] = None
+    passport_expiry: Optional[str] = None
+    address_line1: str = ""
+    city: str = ""
+    country_code: str = "IN"
+    country_name: str = "India"
+    contact_no: str = ""
+    email: str = ""
+    is_lead_pax: bool = False
+    nationality: str = "IN"
+    fare: PassengerFareModel = PassengerFareModel()
+
+
+class FlightBookRequest(BaseModel):
+    result_index: str
+    trace_id: str
+    passengers: List[PassengerModel]
+
+
+class FlightTicketLCCRequest(BaseModel):
+    result_index: str
+    trace_id: str
+    passengers: List[PassengerModel]
+    is_price_change_accepted: bool = False
+
+
+class FlightTicketNonLCCRequest(BaseModel):
+    trace_id: str
+    pnr: str
+    booking_id: int
+    is_price_change_accepted: bool = False
+
+
+# ─── Routes ──────────────────────────────────────────────────
+
+@router.post("/search")
+async def search_flights(request: FlightSearchRequest):
+    """
+    Search available flights via TBO API.
+    
+    - Returns list of flights sorted cheapest first
+    - Save the `trace_id` from response for booking
+    - trace_id expires in 15 minutes!
+    - Cabin class: 2=Economy, 4=Business, 6=First
+    """
+    try:
+        results = await tbo_service.search_flights(
+            origin=request.origin,
+            destination=request.destination,
+            departure_date=request.departure_date,
+            adult_count=request.adult_count,
+            child_count=request.child_count,
+            infant_count=request.infant_count,
+            cabin_class=request.cabin_class,
+            trip_type=request.trip_type,
+            return_date=request.return_date,
+            direct_flight=request.direct_flight,
+        )
+        return {"success": True, "data": results}
+
+    except Exception as e:
+        logger.error(f"Flight search failed: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+
+@router.post("/book")
+async def book_flight(request: FlightBookRequest):
+    """
+    Book a Non-LCC flight (creates PNR / hold).
+    
+    - Only for Non-LCC flights (check IsLCC field in search results)
+    - For LCC flights use /flights/ticket/lcc instead
+    - If IsPriceChanged=true → show user new price → re-call with updated fare
+    - trace_id must be used within 15 minutes of search!
+    """
+    try:
+        # Convert Pydantic models to dicts for tbo_service
+        passengers_data = [p.model_dump() for p in request.passengers]
+
+        result = await tbo_service.book_flight(
+            result_index=request.result_index,
+            trace_id=request.trace_id,
+            passengers=passengers_data,
+        )
+        return {"success": True, "data": result}
+
+    except Exception as e:
+        logger.error(f"Flight booking failed: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+
+@router.post("/ticket/lcc")
+async def ticket_lcc(request: FlightTicketLCCRequest):
+    """
+    Directly issue ticket for LCC flights (no prior Book needed).
+    
+    LCC airlines: SpiceJet, IndiGo, GoAir, AirAsia, FlyDubai, etc.
+    Check IsLCC=true in search results to identify LCC flights.
+    """
+    try:
+        passengers_data = [p.model_dump() for p in request.passengers]
+
+        result = await tbo_service.ticket_flight_lcc(
+            result_index=request.result_index,
+            trace_id=request.trace_id,
+            passengers=passengers_data,
+            is_price_change_accepted=request.is_price_change_accepted,
+        )
+        return {"success": True, "data": result}
+
+    except Exception as e:
+        logger.error(f"LCC ticket failed: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+
+@router.post("/ticket/non-lcc")
+async def ticket_non_lcc(request: FlightTicketNonLCCRequest):
+    """
+    Issue ticket for Non-LCC flight (after /book call).
+    
+    Requires PNR and BookingId from the /book response.
+    """
+    try:
+        result = await tbo_service.ticket_flight_non_lcc(
+            trace_id=request.trace_id,
+            pnr=request.pnr,
+            booking_id=request.booking_id,
+            is_price_change_accepted=request.is_price_change_accepted,
+        )
+        return {"success": True, "data": result}
+
+    except Exception as e:
+        logger.error(f"Non-LCC ticket failed: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+
+@router.get("/auth-status")
+async def check_auth_status():
+    """
+    Check if TBO authentication token is valid.
+    Useful for debugging — confirms credentials are working.
+    """
+    try:
+        auth = await tbo_service.authenticate()
+        ip = await tbo_service.get_end_user_ip()
+        return {
+            "success": True,
+            "authenticated": True,
+            "member_id": auth["member_id"],
+            "agency_id": auth["agency_id"],
+            "server_ip": ip,
+            "token_preview": auth["token_id"][:8] + "..."
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "authenticated": False,
+            "error": str(e)
+        }

routers/hotel_routes.py

@@ -0,0 +1,136 @@
+from fastapi import APIRouter, HTTPException, Query
+from typing import Optional
+from services.hotel_service import (
+    search_location,
+    get_hotels_filter,
+    search_hotels,
+    search_hotels_by_location,
+    get_hotel_details
+)
+
+router = APIRouter(prefix="/api/hotels", tags=["hotels"])
+
+
+@router.get("/search-location")
+async def api_search_location(query: str = Query(..., description="Location name")):
+    if not query or len(query.strip()) < 3:
+        raise HTTPException(status_code=400, detail="Query must be at least 3 characters")
+    
+    result = search_location(query.strip())
+    
+    if not result["success"]:
+        error_msg = result.get("error", "Search failed")
+        
+        # propagate rate limit correctly
+        if "429" in error_msg or "Too Many Requests" in error_msg:
+            raise HTTPException(status_code=429, detail="Rate limit reached. Please type slower.")
+        
+        raise HTTPException(status_code=500, detail=error_msg)
+    
+    return result
+
+
+@router.get("/filters")
+async def api_get_filters(
+    geoId: str = Query(...),
+    checkIn: str = Query(...),
+    checkOut: str = Query(...)
+):
+    """Get hotel filters for a location."""
+    result = get_hotels_filter(geoId, checkIn, checkOut)
+    
+    if not result["success"]:
+        raise HTTPException(status_code=500, detail=result.get("error", "Failed to get filters"))
+    
+    return result
+
+
+@router.get("/search")
+async def api_search_hotels(
+    geoId: str = Query(...),
+    checkIn: str = Query(...),
+    checkOut: str = Query(...),
+    pageNumber: int = Query(default=1),
+    sort: Optional[str] = Query(default=None),
+    adults: int = Query(default=0),
+    rooms: int = Query(default=0),
+    currencyCode: str = Query(default="USD"),
+    rating: int = Query(default=0),
+    priceMin: int = Query(default=0),
+    priceMax: int = Query(default=0)
+):
+    """Search hotels by location ID."""
+    result = search_hotels(
+        geoId=geoId,
+        checkIn=checkIn,
+        checkOut=checkOut,
+        pageNumber=pageNumber,
+        sort=sort,
+        adults=adults,
+        rooms=rooms,
+        currencyCode=currencyCode,
+        rating=rating,
+        priceMin=priceMin,
+        priceMax=priceMax
+    )
+    
+    if not result["success"]:
+        raise HTTPException(status_code=500, detail=result.get("error", "Search failed"))
+    
+    return result
+
+
+@router.get("/search-by-location")
+async def api_search_by_location(
+    latitude: str = Query(...),
+    longitude: str = Query(...),
+    checkIn: str = Query(...),
+    checkOut: str = Query(...),
+    pageNumber: int = Query(default=1),
+    sort: Optional[str] = Query(default=None),
+    adults: int = Query(default=0),
+    rooms: int = Query(default=0),
+    currencyCode: str = Query(default="USD")
+):
+    """Search hotels by coordinates."""
+    result = search_hotels_by_location(
+        latitude=latitude,
+        longitude=longitude,
+        checkIn=checkIn,
+        checkOut=checkOut,
+        pageNumber=pageNumber,
+        sort=sort,
+        adults=adults,
+        rooms=rooms,
+        currencyCode=currencyCode
+    )
+    
+    if not result["success"]:
+        raise HTTPException(status_code=500, detail=result.get("error", "Search failed"))
+    
+    return result
+
+
+@router.get("/details")
+async def api_get_hotel_details(
+    id: str = Query(...),
+    checkIn: str = Query(...),
+    checkOut: str = Query(...),
+    adults: int = Query(default=0),
+    rooms: int = Query(default=0),
+    currency: str = Query(default="USD")
+):
+    """Get details for a specific hotel."""
+    result = get_hotel_details(
+        hotel_id=id,
+        checkIn=checkIn,
+        checkOut=checkOut,
+        adults=adults,
+        rooms=rooms,
+        currency=currency
+    )
+    
+    if not result["success"]:
+        raise HTTPException(status_code=500, detail=result.get("error", "Failed to get details"))
+    
+    return result

services/hotel_service.py

@@ -0,0 +1,376 @@
+# backend/services/hotel_service.py
+
+import requests
+import logging
+import re
+from typing import Optional, Dict, Any
+from functools import lru_cache
+from config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+def _get_hotel_headers() -> dict:
+    """Build RapidAPI headers fresh from settings each call."""
+    settings = get_settings()
+    return {
+        "x-rapidapi-key":  settings.rapidapi_key,
+        "x-rapidapi-host": settings.rapidapi_host,
+    }
+
+
+def _get_base_url() -> str:
+    settings = get_settings()
+    return f"https://{settings.rapidapi_host}/api/v1/hotels"
+
+
+def _extract_geo_id(raw_geo_id: str) -> str:
+    """
+    Extract the clean numeric geoId from whatever format TripAdvisor returns.
+
+    Examples:
+      "loc;317100;g317100"  →  "317100"
+      "g317100"             →  "317100"
+      "317100"              →  "317100"
+      "295424"              →  "295424"
+    """
+    if not raw_geo_id:
+        return raw_geo_id
+
+    # If it contains semicolons e.g. "loc;317100;g317100"
+    # grab the first pure numeric segment
+    if ";" in raw_geo_id:
+        parts = raw_geo_id.split(";")
+        for part in parts:
+            # strip leading letters like "g" then check if numeric
+            cleaned = re.sub(r'^[a-zA-Z]+', '', part)
+            if cleaned.isdigit():
+                return cleaned
+
+    # If it starts with letters followed by digits e.g. "g317100"
+    match = re.match(r'^[a-zA-Z]+(\d+)$', raw_geo_id)
+    if match:
+        return match.group(1)
+
+    # Already a plain number
+    if raw_geo_id.isdigit():
+        return raw_geo_id
+
+    # Fallback — return as-is
+    return raw_geo_id
+
+
+# ── Public service functions ──────────────────────────────────────────────────
+def _normalize_query(q: str) -> str:
+    return q.strip().lower()
+
+
+@lru_cache(maxsize=200)
+def _search_location_cached(norm_query: str) -> Dict[str, Any]:
+    """Cached internal location search."""
+    try:
+        url = f"{_get_base_url()}/searchLocation"
+        params = {"query": norm_query}
+
+        response = requests.get(
+            url,
+            headers=_get_hotel_headers(),
+            params=params,
+            timeout=15,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+
+        if data.get("status"):
+            items = data.get("data", [])
+            for item in items:
+                if "title" in item:
+                    item["title"] = (
+                        item["title"]
+                        .replace("<b>", "")
+                        .replace("</b>", "")
+                    )
+                if "documentId" in item:
+                    item["geoId"] = _extract_geo_id(item["documentId"])
+
+            return {"success": True, "data": items}
+
+        return {"success": False, "error": data.get("message", "Unknown error"), "data": []}
+
+    except requests.exceptions.Timeout:
+        logger.error("Timeout searching location: %s", norm_query)
+        return {"success": False, "error": "Request timed out", "data": []}
+    except requests.exceptions.RequestException as e:
+        logger.error("Error searching location: %s", str(e))
+        return {"success": False, "error": str(e), "data": []}
+
+
+def search_location(query: str) -> Dict[str, Any]:
+    norm = _normalize_query(query)
+
+    if len(norm) < 3:
+        return {"success": True, "data": []}
+
+    return _search_location_cached(norm)
+
+
+def get_hotels_filter(
+    geoId: str,
+    checkIn: str,
+    checkOut: str,
+) -> Dict[str, Any]:
+    """Get available hotel filters for a location."""
+    try:
+        url    = f"{_get_base_url()}/getHotelsFilter"
+        params = {
+            "geoId":    _extract_geo_id(geoId),
+            "checkIn":  checkIn,
+            "checkOut": checkOut,
+        }
+
+        response = requests.get(
+            url,
+            headers=_get_hotel_headers(),
+            params=params,
+            timeout=15,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+
+        if data.get("status"):
+            return {"success": True, "data": data.get("data", {})}
+
+        return {
+            "success": False,
+            "error":   data.get("message", "Unknown error"),
+            "data":    {},
+        }
+
+    except requests.exceptions.RequestException as e:
+        logger.error("Error getting hotel filters: %s", str(e))
+        return {"success": False, "error": str(e), "data": {}}
+
+
+def search_hotels(
+    geoId: str,
+    checkIn: str,
+    checkOut: str,
+    pageNumber:   int = 1,
+    sort:         Optional[str] = None,
+    adults:       int = 0,
+    rooms:        int = 0,
+    currencyCode: str = "USD",
+    rating:       int = 0,
+    priceMin:     int = 0,
+    priceMax:     int = 0,
+) -> Dict[str, Any]:
+    """Search hotels by geoId."""
+    try:
+        # Always extract clean numeric geoId before calling RapidAPI
+        clean_geo_id = _extract_geo_id(geoId)
+        logger.info("Searching hotels — raw geoId: %s → clean: %s", geoId, clean_geo_id)
+
+        url    = f"{_get_base_url()}/searchHotels"
+        params = {
+            "geoId":        clean_geo_id,
+            "checkIn":      checkIn,
+            "checkOut":     checkOut,
+            "pageNumber":   str(pageNumber),
+            "currencyCode": currencyCode,
+        }
+
+        if sort:         params["sort"]     = sort
+        if adults > 0:   params["adults"]   = str(adults)
+        if rooms > 0:    params["rooms"]    = str(rooms)
+        if rating > 0:   params["rating"]   = str(rating)
+        if priceMin > 0: params["priceMin"] = str(priceMin)
+        if priceMax > 0: params["priceMax"] = str(priceMax)
+
+        response = requests.get(
+            url,
+            headers=_get_hotel_headers(),
+            params=params,
+            timeout=20,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+
+        if data.get("status"):
+            hotels    = data.get("data", {}).get("data", [])
+            processed = _process_hotel_list(hotels)
+            return {
+                "success":        True,
+                "data":           processed,
+                "sortDisclaimer": data.get("data", {}).get("sortDisclaimer", ""),
+            }
+
+        # RapidAPI returned status: false
+        logger.error(
+            "RapidAPI hotel search failed — geoId: %s message: %s",
+            clean_geo_id,
+            data.get("message"),
+        )
+        return {
+            "success": False,
+            "error":   data.get("message", "No hotels found for this location"),
+            "data":    [],
+        }
+
+    except requests.exceptions.Timeout:
+        logger.error("Timeout searching hotels for geoId: %s", geoId)
+        return {"success": False, "error": "Request timed out", "data": []}
+    except requests.exceptions.RequestException as e:
+        logger.error("Error searching hotels: %s", str(e))
+        return {"success": False, "error": str(e), "data": []}
+
+
+def search_hotels_by_location(
+    latitude:     str,
+    longitude:    str,
+    checkIn:      str,
+    checkOut:     str,
+    pageNumber:   int = 1,
+    sort:         Optional[str] = None,
+    adults:       int = 0,
+    rooms:        int = 0,
+    currencyCode: str = "USD",
+) -> Dict[str, Any]:
+    """Search hotels by geographic coordinates."""
+    try:
+        url    = f"{_get_base_url()}/searchHotelsByLocation"
+        params = {
+            "latitude":     latitude,
+            "longitude":    longitude,
+            "checkIn":      checkIn,
+            "checkOut":     checkOut,
+            "pageNumber":   str(pageNumber),
+            "currencyCode": currencyCode,
+        }
+
+        if sort:        params["sort"]   = sort
+        if adults > 0:  params["adults"] = str(adults)
+        if rooms > 0:   params["rooms"]  = str(rooms)
+
+        response = requests.get(
+            url,
+            headers=_get_hotel_headers(),
+            params=params,
+            timeout=20,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+
+        if data.get("status"):
+            hotels    = data.get("data", {}).get("data", [])
+            processed = _process_hotel_list(hotels)
+            return {
+                "success":        True,
+                "data":           processed,
+                "sortDisclaimer": data.get("data", {}).get("sortDisclaimer", ""),
+            }
+
+        return {
+            "success": False,
+            "error":   data.get("message", "Unknown error"),
+            "data":    [],
+        }
+
+    except requests.exceptions.RequestException as e:
+        logger.error("Error searching hotels by location: %s", str(e))
+        return {"success": False, "error": str(e), "data": []}
+
+
+def get_hotel_details(
+    hotel_id: str,
+    checkIn:  str,
+    checkOut: str,
+    adults:   int = 0,
+    rooms:    int = 0,
+    currency: str = "USD",
+) -> Dict[str, Any]:
+    """Get detailed information for a specific hotel."""
+    try:
+        url    = f"{_get_base_url()}/getHotelDetails"
+        params = {
+            "id":       hotel_id,
+            "checkIn":  checkIn,
+            "checkOut": checkOut,
+            "currency": currency,
+        }
+
+        if adults > 0:  params["adults"] = str(adults)
+        if rooms > 0:   params["rooms"]  = str(rooms)
+
+        response = requests.get(
+            url,
+            headers=_get_hotel_headers(),
+            params=params,
+            timeout=20,
+        )
+        response.raise_for_status()
+
+        data = response.json()
+
+        if data.get("status"):
+            return {"success": True, "data": data.get("data", {})}
+
+        return {
+            "success": False,
+            "error":   data.get("message", "Unknown error"),
+            "data":    {},
+        }
+
+    except requests.exceptions.Timeout:
+        logger.error("Timeout getting hotel details for id: %s", hotel_id)
+        return {"success": False, "error": "Request timed out", "data": {}}
+    except requests.exceptions.RequestException as e:
+        logger.error("Error getting hotel details: %s", str(e))
+        return {"success": False, "error": str(e), "data": {}}
+
+
+# ── Private helper ────────────────────────────────────────────────────────────
+
+def _process_hotel_list(hotels: list) -> list:
+    """Clean and normalise hotel list data."""
+    processed = []
+
+    for hotel in hotels:
+        thumbnail = None
+        photos    = hotel.get("cardPhotos", [])
+
+        if photos:
+            template = photos[0].get("sizes", {}).get("urlTemplate", "")
+            if template:
+                thumbnail = (
+                    template
+                    .replace("{width}",  "400")
+                    .replace("{height}", "300")
+                )
+
+        processed.append({
+            "id":              hotel.get("id"),
+            "title":           hotel.get("title", "").lstrip("0123456789. "),
+            "primaryInfo":     hotel.get("primaryInfo"),
+            "secondaryInfo":   hotel.get("secondaryInfo"),
+            "rating":          hotel.get("bubbleRating", {}).get("rating", 0),
+            "reviewCount":     hotel.get("bubbleRating", {}).get("count", "0"),
+            "provider":        hotel.get("provider"),
+            "priceForDisplay": hotel.get("priceForDisplay"),
+            "isSponsored":     hotel.get("isSponsored", False),
+            "badge":           hotel.get("badge", {}),
+            "thumbnail":       thumbnail,
+            "photos": [
+                p.get("sizes", {})
+                 .get("urlTemplate", "")
+                 .replace("{width}",  "800")
+                 .replace("{height}", "600")
+                for p in photos[:4]
+                if p.get("sizes", {}).get("urlTemplate")
+            ],
+        })
+
+    return processed

services/tbo_service.py

@@ -0,0 +1,745 @@
+# backend/services/tbo_service.py
+
+"""
+TBO Flight API Service
+Handles all communication with TBO's flight booking API.
+
+Key Points from TBO Docs:
+- Generate token ONCE per day (valid 00:00 AM to 11:59 PM)
+- NEVER generate a new token on every search request
+- TraceId from search is valid for only 15 minutes
+- For LCC flights: go directly to Ticket endpoint
+- For Non-LCC flights: Book first, then Ticket
+"""
+
+import httpx
+import logging
+from datetime import datetime
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# ─── Load environment variables directly ─────────────────────
+import os
+from dotenv import load_dotenv
+load_dotenv()
+
+TBO_CLIENT_ID = os.getenv("TBO_CLIENT_ID", "ApiIntegrationNew")
+TBO_USERNAME = os.getenv("TBO_USERNAME", "")
+TBO_PASSWORD = os.getenv("TBO_PASSWORD", "")
+TBO_END_USER_IP_ENV = os.getenv("TBO_END_USER_IP", "")
+
+TBO_AUTH_URL = os.getenv(
+    "TBO_AUTH_URL",
+    "http://Sharedapi.tektravels.com/SharedData.svc/rest/Authenticate"
+)
+TBO_LOGOUT_URL = os.getenv(
+    "TBO_LOGOUT_URL",
+    "http://Sharedapi.tektravels.com/SharedData.svc/rest/Logout"
+)
+TBO_SEARCH_URL = os.getenv(
+    "TBO_SEARCH_URL",
+    "http://api.tektravels.com/BookingEngineService_Air/AirService.svc/rest/Search"
+)
+TBO_BOOK_URL = os.getenv(
+    "TBO_BOOK_URL",
+    "http://api.tektravels.com/BookingEngineService_Air/AirService.svc/rest/Book"
+)
+TBO_TICKET_URL = os.getenv(
+    "TBO_TICKET_URL",
+    "http://api.tektravels.com/BookingEngineService_Air/AirService.svc/rest/Ticket"
+)
+
+
+# ─── In-Memory Token Cache ────────────────────────────────────
+# IMPORTANT: Per TBO docs — generate only ONE token per day
+# Token is valid from 00:00 AM to 11:59 PM of the same day
+_token_cache = {
+    "token_id": None,
+    "member_id": None,
+    "agency_id": None,
+    "date": None,         # date this token was generated (YYYY-MM-DD)
+}
+
+# Cache for public IP so we don't fetch it on every request
+_public_ip_cache = {
+    "ip": None
+}
+
+
+# ─── Helper: Get Public IP ────────────────────────────────────
+
+async def get_end_user_ip() -> str:
+    """
+    Get the server's public IP address.
+    
+    TBO requires EndUserIp in every request.
+    We auto-detect if not set in .env
+    
+    Priority:
+    1. Value from .env file (TBO_END_USER_IP)
+    2. Auto-detected from ipify.org (cached after first call)
+    3. Fallback to localhost (not ideal but won't crash)
+    """
+    # Priority 1: Use manually set IP from .env
+    if TBO_END_USER_IP_ENV and TBO_END_USER_IP_ENV.strip():
+        return TBO_END_USER_IP_ENV.strip()
+
+    # Priority 2: Use cached IP
+    if _public_ip_cache["ip"]:
+        return _public_ip_cache["ip"]
+
+    # Priority 3: Auto-detect public IP
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            response = await client.get("https://api.ipify.org")
+            ip = response.text.strip()
+            _public_ip_cache["ip"] = ip
+            logger.info(f"Auto-detected public IP: {ip}")
+            return ip
+    except Exception as e:
+        logger.warning(f"Could not detect public IP: {e}. Using fallback.")
+        return "127.0.0.1"  # fallback
+
+
+# ─── Helper: Check Token Validity ────────────────────────────
+
+def _is_token_valid() -> bool:
+    """
+    Check if the cached TBO token is still valid for today.
+    TBO tokens expire at midnight (00:00) each day.
+    """
+    if not _token_cache["token_id"]:
+        return False
+    
+    today = datetime.now().strftime("%Y-%m-%d")
+    
+    if _token_cache["date"] != today:
+        logger.info("TBO token expired (new calendar day). Will re-authenticate.")
+        return False
+    
+    return True
+
+
+# ─── Helper: Map cabin class ─────────────────────────────────
+
+def _map_cabin_class(class_name: str) -> int:
+    """
+    Map human-readable class name to TBO FlightCabinClass enum.
+    1=All, 2=Economy, 3=PremiumEconomy, 4=Business,
+    5=PremiumBusiness, 6=First
+    """
+    class_map = {
+        "all": 1,
+        "economy": 2,
+        "premiumeconomy": 3,
+        "business": 4,
+        "premiumbusiness": 5,
+        "first": 6,
+    }
+    return class_map.get(class_name.lower().replace(" ", ""), 2)
+
+
+# ─── Helper: Map trip type ───────────────────────────────────
+
+def _map_trip_type(trip_type: str) -> int:
+    """
+    Map trip type string to TBO JourneyType enum.
+    1=OneWay, 2=Return, 3=MultiStop,
+    4=AdvanceSearch, 5=SpecialReturn
+    """
+    trip_map = {
+        "one-way": 1,
+        "oneway": 1,
+        "round": 2,
+        "return": 2,
+        "multistop": 3,
+    }
+    return trip_map.get(trip_type.lower(), 1)
+
+
+# ─── Helper: Format date for TBO ─────────────────────────────
+
+def _format_date_for_tbo(date_str: str) -> str:
+    """
+    Convert 'YYYY-MM-DD' to TBO format 'YYYY-MM-DDT00:00:00'
+    """
+    return f"{date_str}T00:00:00"
+
+
+# ─── Core: Authenticate ──────────────────────────────────────
+
+async def authenticate() -> dict:
+    """
+    Authenticate with TBO API and get/return token.
+    
+    Uses in-memory cache — only makes actual API call
+    when token is missing or expired (past midnight).
+    
+    Returns:
+        dict with token_id, member_id, agency_id
+    
+    Raises:
+        Exception if authentication fails
+    """
+    # Return cached token if still valid for today
+    if _is_token_valid():
+        return {
+            "token_id": _token_cache["token_id"],
+            "member_id": _token_cache["member_id"],
+            "agency_id": _token_cache["agency_id"],
+        }
+
+    logger.info("Calling TBO Authenticate API...")
+
+    end_user_ip = await get_end_user_ip()
+
+    payload = {
+        "ClientId": TBO_CLIENT_ID,
+        "UserName": TBO_USERNAME,
+        "Password": TBO_PASSWORD,
+        "EndUserIp": end_user_ip,
+    }
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        response = await client.post(
+            TBO_AUTH_URL,
+            json=payload,
+            headers={"Content-Type": "application/json"}
+        )
+        response.raise_for_status()
+
+    data = response.json()
+
+    # TBO Status codes:
+    # 0=NotSet, 1=Successful, 2=Failed,
+    # 3=IncorrectUsername, 4=IncorrectPassword, 5=PasswordExpired
+    status = data.get("Status")
+    
+    status_messages = {
+        0: "Authentication status not set",
+        2: "Authentication failed",
+        3: "Incorrect TBO username",
+        4: "Incorrect TBO password",
+        5: "TBO password expired — contact TBO support",
+    }
+
+    if status != 1:
+        error_msg = data.get("Error", {}).get("ErrorMessage", "Unknown error")
+        friendly_msg = status_messages.get(status, error_msg)
+        logger.error(f"TBO Auth failed with status {status}: {friendly_msg}")
+        raise Exception(f"TBO Authentication Error: {friendly_msg}")
+
+    # Store in cache for the rest of the day
+    _token_cache["token_id"] = data["TokenId"]
+    _token_cache["member_id"] = data["Member"]["MemberId"]
+    _token_cache["agency_id"] = data["Member"]["AgencyId"]
+    _token_cache["date"] = datetime.now().strftime("%Y-%m-%d")
+
+    logger.info(
+        f"TBO Auth successful | "
+        f"MemberId: {_token_cache['member_id']} | "
+        f"AgencyId: {_token_cache['agency_id']} | "
+        f"Token: {data['TokenId'][:8]}..."
+    )
+
+    return {
+        "token_id": _token_cache["token_id"],
+        "member_id": _token_cache["member_id"],
+        "agency_id": _token_cache["agency_id"],
+    }
+
+
+# ─── Core: Search Flights ────────────────────────────────────
+
+async def search_flights(
+    origin: str,
+    destination: str,
+    departure_date: str,
+    adult_count: int = 1,
+    child_count: int = 0,
+    infant_count: int = 0,
+    cabin_class: int = 2,
+    trip_type: str = "one-way",
+    return_date: Optional[str] = None,
+    direct_flight: bool = False,
+) -> dict:
+    """
+    Search for available flights via TBO Search API.
+    
+    Flow:
+    1. Get token (cached or fresh)
+    2. Get public IP
+    3. Build TBO request payload
+    4. Call TBO Search endpoint
+    5. Clean and return response
+    
+    IMPORTANT: Save the trace_id from response!
+    It's needed for Book/Ticket calls and
+    expires in only 15 minutes.
+    
+    Args:
+        origin: IATA code e.g. "DEL"
+        destination: IATA code e.g. "BOM"
+        departure_date: "YYYY-MM-DD"
+        adult_count: number of adults (max 9 total)
+        child_count: number of children
+        infant_count: number of infants
+        cabin_class: 2=Economy, 4=Business, 6=First
+        trip_type: "one-way" or "round"
+        return_date: "YYYY-MM-DD" (required for round trips)
+        direct_flight: filter for direct flights only
+    
+    Returns:
+        dict with trace_id and list of flight results
+    """
+    auth = await authenticate()
+    end_user_ip = await get_end_user_ip()
+
+    # Build segments (journey legs)
+    segments = [
+        {
+            "Origin": origin.upper().strip(),
+            "Destination": destination.upper().strip(),
+            "FlightCabinClass": cabin_class,
+            "PreferredDepartureTime": _format_date_for_tbo(departure_date),
+            "PreferredArrivalTime": _format_date_for_tbo(departure_date),
+        }
+    ]
+
+    # Add return segment for round trips
+    if trip_type in ("round", "return") and return_date:
+        segments.append({
+            "Origin": destination.upper().strip(),
+            "Destination": origin.upper().strip(),
+            "FlightCabinClass": cabin_class,
+            "PreferredDepartureTime": _format_date_for_tbo(return_date),
+            "PreferredArrivalTime": _format_date_for_tbo(return_date),
+        })
+
+    journey_type = _map_trip_type(trip_type)
+
+    payload = {
+        "EndUserIp": end_user_ip,
+        "TokenId": auth["token_id"],
+        "AdultCount": str(adult_count),
+        "ChildCount": str(child_count),
+        "InfantCount": str(infant_count),
+        "DirectFlight": "true" if direct_flight else "false",
+        "OneStopFlight": "false",
+        "JourneyType": str(journey_type),
+        "PreferredAirlines": None,
+        "Segments": segments,
+        "Sources": None,
+    }
+
+    logger.info(
+        f"TBO Search | {origin} → {destination} | "
+        f"{departure_date} | Adults: {adult_count} | "
+        f"Class: {cabin_class} | Type: {trip_type}"
+    )
+
+    async with httpx.AsyncClient(timeout=60.0) as client:
+        response = await client.post(
+            TBO_SEARCH_URL,
+            json=payload,
+            headers={"Content-Type": "application/json"}
+        )
+        response.raise_for_status()
+
+    data = response.json()
+
+    # TBO wraps response in "Response" key
+    tbo_response = data.get("Response", data)
+
+    # Check for API-level errors
+    error = tbo_response.get("Error", {})
+    if error.get("ErrorCode", 0) != 0:
+        error_msg = error.get("ErrorMessage", "Unknown search error")
+        logger.error(f"TBO Search Error: {error_msg}")
+        raise Exception(f"Flight search failed: {error_msg}")
+
+    return _format_search_response(tbo_response)
+
+
+def _format_search_response(tbo_response: dict) -> dict:
+    """
+    Transform TBO's raw search response into a
+    clean format that our frontend can easily consume.
+    """
+    trace_id = tbo_response.get("TraceId", "")
+    raw_results = tbo_response.get("Results", [])
+
+    if not raw_results:
+        return {
+            "trace_id": trace_id,
+            "origin": tbo_response.get("Origin", ""),
+            "destination": tbo_response.get("Destination", ""),
+            "total_results": 0,
+            "flights": [],
+        }
+
+    # TBO sometimes returns Results as array of arrays
+    # e.g. [[flight1, flight2], [flight3]] for round trips
+    # We flatten for one-way, keep structure for round trip
+    if raw_results and isinstance(raw_results[0], list):
+        flat_results = []
+        for group in raw_results:
+            flat_results.extend(group)
+        raw_results = flat_results
+
+    formatted_flights = []
+    for flight in raw_results:
+        try:
+            formatted = _format_single_flight(flight)
+            formatted_flights.append(formatted)
+        except Exception as e:
+            logger.warning(f"Skipping malformed flight result: {e}")
+            continue
+
+    # Sort cheapest first
+    formatted_flights.sort(
+        key=lambda x: x.get("fare", {}).get("offered_fare", float("inf"))
+    )
+
+    return {
+        "trace_id": trace_id,
+        "origin": tbo_response.get("Origin", ""),
+        "destination": tbo_response.get("Destination", ""),
+        "total_results": len(formatted_flights),
+        "flights": formatted_flights,
+    }
+
+
+def _format_single_flight(flight: dict) -> dict:
+    """
+    Extract and clean a single flight result from TBO response.
+    Only picks fields the frontend actually needs.
+    """
+    fare = flight.get("Fare", {})
+    segments = flight.get("Segments", [[]])
+
+    # Segments come as [[seg1, seg2], [seg3]] nested structure
+    segment_list = (
+        segments[0]
+        if segments and isinstance(segments[0], list)
+        else segments
+    )
+
+    first_seg = segment_list[0] if segment_list else {}
+    last_seg = segment_list[-1] if segment_list else {}
+
+    airline = first_seg.get("Airline", {})
+    origin_airport = first_seg.get("Origin", {}).get("Airport", {})
+    dest_airport = last_seg.get("Destination", {}).get("Airport", {})
+
+    return {
+        "result_index": flight.get("ResultIndex", ""),
+        "source": flight.get("Source", ""),
+        "is_lcc": flight.get("IsLCC", False),
+        "is_refundable": flight.get("IsRefundable", False),
+        "airline_remarks": flight.get("AirlineRemarks", ""),
+        "airline": {
+            "code": airline.get("AirlineCode", ""),
+            "name": airline.get("AirlineName", ""),
+            "flight_number": airline.get("FlightNumber", ""),
+            "fare_class": airline.get("FareClass", ""),
+            "operating_carrier": airline.get("OperatingCarrier", ""),
+        },
+        "origin": {
+            "airport_code": origin_airport.get("AirportCode", ""),
+            "airport_name": origin_airport.get("AirportName", ""),
+            "city_name": origin_airport.get("CityName", ""),
+            "city_code": origin_airport.get("CityCode", ""),
+            "country_name": origin_airport.get("CountryName", ""),
+            "terminal": origin_airport.get("Terminal", ""),
+            "departure_time": first_seg.get("DepTime", ""),
+        },
+        "destination": {
+            "airport_code": dest_airport.get("AirportCode", ""),
+            "airport_name": dest_airport.get("AirportName", ""),
+            "city_name": dest_airport.get("CityName", ""),
+            "city_code": dest_airport.get("CityCode", ""),
+            "country_name": dest_airport.get("CountryName", ""),
+            "terminal": dest_airport.get("Terminal", ""),
+            "arrival_time": last_seg.get("ArrTime", ""),
+        },
+        "duration": first_seg.get("Duration", 0),
+        "accumulated_duration": first_seg.get("AccumulatedDuration", 0),
+        "stop_count": max(0, len(segment_list) - 1),
+        "fare": {
+            "currency": fare.get("Currency", "INR"),
+            "base_fare": fare.get("BaseFare", 0),
+            "tax": fare.get("Tax", 0),
+            "yq_tax": fare.get("YQTax", 0),
+            "offered_fare": fare.get("OfferedFare", 0),
+            "published_fare": fare.get("PublishedFare", 0),
+            "other_charges": fare.get("OtherCharges", 0),
+            "commission_earned": fare.get("CommissionEarned", 0),
+        },
+        "fare_breakdown": flight.get("FareBreakdown", []),
+        "segments": segment_list,
+        "last_ticket_date": flight.get("LastTicketDate", ""),
+    }
+
+
+# ─── Core: Book Flight (Non-LCC only) ────────────────────────
+
+async def book_flight(
+    result_index: str,
+    trace_id: str,
+    passengers: list,
+) -> dict:
+    """
+    Book a Non-LCC flight to get a PNR (hold booking).
+    
+    IMPORTANT:
+    - Only for Non-LCC flights (IsLCC = False in search results)
+    - For LCC flights, call ticket_flight_lcc() directly
+    - If IsPriceChanged=True in response, re-send with updated fare
+    - trace_id must be used within 15 minutes of search
+    
+    Args:
+        result_index: from search response
+        trace_id: from search response (15 min expiry!)
+        passengers: list of passenger dicts
+    
+    Returns:
+        dict with booking_id, pnr, and fare details
+    """
+    auth = await authenticate()
+    end_user_ip = await get_end_user_ip()
+
+    # Format passengers for TBO
+    tbo_passengers = _format_passengers_for_tbo(passengers)
+
+    payload = {
+        "EndUserIp": end_user_ip,
+        "TokenId": auth["token_id"],
+        "TraceId": trace_id,
+        "ResultIndex": result_index,
+        "Passengers": tbo_passengers,
+    }
+
+    logger.info(
+        f"TBO Book | ResultIndex: {result_index} | "
+        f"Passengers: {len(tbo_passengers)}"
+    )
+
+    async with httpx.AsyncClient(timeout=60.0) as client:
+        response = await client.post(
+            TBO_BOOK_URL,
+            json=payload,
+            headers={"Content-Type": "application/json"}
+        )
+        response.raise_for_status()
+
+    data = response.json()
+    tbo_response = data.get("Response", data)
+
+    is_price_changed = tbo_response.get("IsPriceChanged", False)
+    is_time_changed = tbo_response.get("IsTimeChanged", False)
+
+    if is_price_changed:
+        logger.warning("TBO Book: Price has changed! Frontend must confirm new price.")
+    if is_time_changed:
+        logger.warning("TBO Book: Flight time has changed! Frontend must inform user.")
+
+    itinerary = tbo_response.get("FlightItinerary", {})
+
+    return {
+        "success": True,
+        "is_price_changed": is_price_changed,
+        "is_time_changed": is_time_changed,
+        "booking_id": itinerary.get("BookingId"),
+        "pnr": itinerary.get("PNR"),
+        "is_lcc": itinerary.get("IsLCC", False),
+        "status": tbo_response.get("Status"),
+        "fare": itinerary.get("Fare", {}),
+        "passengers": itinerary.get("Passenger", []),
+        "segments": itinerary.get("Segments", []),
+        "ssr_denied": tbo_response.get("SSRDenied", ""),
+        "ssr_message": tbo_response.get("SSRMessage", ""),
+    }
+
+
+# ─── Core: Ticket LCC Flights ────────────────────────────────
+
+async def ticket_flight_lcc(
+    result_index: str,
+    trace_id: str,
+    passengers: list,
+    is_price_change_accepted: bool = False,
+) -> dict:
+    """
+    Issue ticket for LCC (Low Cost Carrier) flights directly.
+    No prior Book call needed for LCC.
+    
+    LCC examples: SpiceJet, IndiGo, GoAir, AirAsia, etc.
+    Non-LCC examples: Air India, Jet Airways (via GDS)
+    
+    Args:
+        result_index: from search response
+        trace_id: from search response (15 min expiry!)
+        passengers: list of passenger dicts with fare
+        is_price_change_accepted: set True if user confirmed price change
+    
+    Returns:
+        dict with pnr, booking_id, ticket_status
+    """
+    auth = await authenticate()
+    end_user_ip = await get_end_user_ip()
+
+    tbo_passengers = _format_passengers_for_tbo(passengers)
+
+    payload = {
+        "EndUserIp": end_user_ip,
+        "TokenId": auth["token_id"],
+        "TraceId": trace_id,
+        "ResultIndex": result_index,
+        "Passengers": tbo_passengers,
+        "IsPriceChangeAccepted": is_price_change_accepted,
+    }
+
+    logger.info(f"TBO Ticket LCC | ResultIndex: {result_index}")
+
+    async with httpx.AsyncClient(timeout=60.0) as client:
+        response = await client.post(
+            TBO_TICKET_URL,
+            json=payload,
+            headers={"Content-Type": "application/json"}
+        )
+        response.raise_for_status()
+
+    data = response.json()
+    tbo_response = data.get("Response", data)
+
+    # TicketStatus: 0=Failed, 1=Successful, 2=NotSaved,
+    # 3=NotCreated, 5=InProgress, 8=PriceChanged, 9=OtherError
+    ticket_status = tbo_response.get("TicketStatus")
+
+    if ticket_status == 8:
+        logger.warning("LCC Ticket: Price changed — user must reconfirm")
+    elif ticket_status not in (1, 5):
+        logger.error(f"LCC Ticket failed with status: {ticket_status}")
+
+    return {
+        "success": ticket_status in (1, 5),
+        "pnr": tbo_response.get("PNR"),
+        "booking_id": tbo_response.get("BookingId"),
+        "is_price_changed": tbo_response.get("IsPriceChanged", False),
+        "is_time_changed": tbo_response.get("IsTimeChanged", False),
+        "ticket_status": ticket_status,
+        "message": tbo_response.get("Message", ""),
+        "flight_itinerary": tbo_response.get("FlightItinerary", {}),
+    }
+
+
+# ─── Core: Ticket Non-LCC Flights ────────────────────────────
+
+async def ticket_flight_non_lcc(
+    trace_id: str,
+    pnr: str,
+    booking_id: int,
+    is_price_change_accepted: bool = False,
+) -> dict:
+    """
+    Issue ticket for Non-LCC flights (after Book call).
+    
+    Must be called AFTER book_flight() for Non-LCC airlines.
+    Uses PNR and BookingId from book_flight() response.
+    
+    Args:
+        trace_id: from original search response
+        pnr: from book_flight() response
+        booking_id: from book_flight() response
+        is_price_change_accepted: True if user confirmed price change
+    
+    Returns:
+        dict with ticket details
+    """
+    auth = await authenticate()
+    end_user_ip = await get_end_user_ip()
+
+    payload = {
+        "EndUserIp": end_user_ip,
+        "TokenId": auth["token_id"],
+        "TraceId": trace_id,
+        "PNR": pnr,
+        "BookingId": booking_id,
+        "IsPriceChangeAccepted": is_price_change_accepted,
+    }
+
+    logger.info(f"TBO Ticket Non-LCC | PNR: {pnr} | BookingId: {booking_id}")
+
+    async with httpx.AsyncClient(timeout=60.0) as client:
+        response = await client.post(
+            TBO_TICKET_URL,
+            json=payload,
+            headers={"Content-Type": "application/json"}
+        )
+        response.raise_for_status()
+
+    data = response.json()
+    tbo_response = data.get("Response", data)
+
+    ticket_status = tbo_response.get("TicketStatus")
+
+    return {
+        "success": ticket_status in (1, 5),
+        "pnr": tbo_response.get("PNR"),
+        "booking_id": tbo_response.get("BookingId"),
+        "is_price_changed": tbo_response.get("IsPriceChanged", False),
+        "ticket_status": ticket_status,
+        "message": tbo_response.get("Message", ""),
+        "flight_itinerary": tbo_response.get("FlightItinerary", {}),
+    }
+
+
+# ─── Helper: Format Passengers ───────────────────────────────
+
+def _format_passengers_for_tbo(passengers: list) -> list:
+    """
+    Convert passenger data from our API format to TBO format.
+    Handles all required and optional fields.
+    """
+    tbo_passengers = []
+
+    for pax in passengers:
+        tbo_pax = {
+            "Title": pax.get("title", "Mr"),
+            "FirstName": pax.get("first_name", ""),
+            "LastName": pax.get("last_name", ""),
+            "PaxType": str(pax.get("pax_type", 1)),  # 1=Adult, 2=Child, 3=Infant
+            "DateOfBirth": pax.get("date_of_birth", ""),
+            "Gender": str(pax.get("gender", 1)),     # 1=Male, 2=Female
+            "PassportNo": pax.get("passport_no", ""),
+            "PassportExpiry": pax.get("passport_expiry", ""),
+            "AddressLine1": pax.get("address_line1", ""),
+            "AddressLine2": pax.get("address_line2", ""),
+            "City": pax.get("city", ""),
+            "CountryCode": pax.get("country_code", "IN"),
+            "CountryName": pax.get("country_name", "India"),
+            "ContactNo": pax.get("contact_no", ""),
+            "Email": pax.get("email", ""),
+            "IsLeadPax": pax.get("is_lead_pax", False),
+            "Nationality": pax.get("nationality", "IN"),
+            # GST fields (mandatory in API but blank for B2C customers)
+            "GSTCompanyAddress": pax.get("gst_company_address", ""),
+            "GSTCompanyContactNumber": pax.get("gst_company_contact", ""),
+            "GSTCompanyName": pax.get("gst_company_name", ""),
+            "GSTNumber": pax.get("gst_number", ""),
+            "GSTCompanyEmail": pax.get("gst_company_email", ""),
+            "Fare": {
+                "BaseFare": pax.get("fare", {}).get("base_fare", 0),
+                "Tax": pax.get("fare", {}).get("tax", 0),
+                "TransactionFee": pax.get("fare", {}).get("transaction_fee", 0),
+                "YQTax": pax.get("fare", {}).get("yq_tax", 0),
+                "AdditionalTxnFeeOfrd": 0,
+                "AdditionalTxnFeePub": 0,
+                "AirTransFee": 0,
+            },
+        }
+        tbo_passengers.append(tbo_pax)
+
+    return tbo_passengers

tavily_client.py

@@ -0,0 +1,96 @@
+"""
+Tavily API Client for web search functionality.
+Used for finding booking websites, travel deals, and real-time travel information.
+"""
+
+import os
+from tavily import TavilyClient
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+class TavilySearchClient:
+    """Client for Tavily web search API."""
+    
+    def __init__(self):
+        api_key = os.getenv("TAVILY_API_KEY")
+        if not api_key:
+            raise ValueError("TAVILY_API_KEY environment variable is not set")
+        self.client = TavilyClient(api_key=api_key)
+    
+    async def search(self, query: str, max_results: int = 5) -> dict:
+        """
+        Perform a web search using Tavily API.
+        
+        Args:
+            query: Search query string
+            max_results: Maximum number of results to return
+            
+        Returns:
+            Dictionary containing search results with URLs and summaries
+        """
+        try:
+            # Add travel context to improve results
+            enhanced_query = f"travel booking {query}"
+            
+            response = self.client.search(
+                query=enhanced_query,
+                search_depth="advanced",
+                max_results=max_results,
+                include_domains=[
+                    "booking.com", "expedia.com", "skyscanner.com",
+                    "kayak.com", "makemytrip.com", "goibibo.com",
+                    "tripadvisor.com", "airbnb.com", "hotels.com",
+                    "agoda.com", "cleartrip.com", "yatra.com"
+                ]
+            )
+            
+            results = []
+            for result in response.get("results", []):
+                results.append({
+                    "title": result.get("title", ""),
+                    "url": result.get("url", ""),
+                    "content": result.get("content", "")[:300],
+                    "score": result.get("score", 0)
+                })
+            
+            return {
+                "query": query,
+                "results": results,
+                "answer": response.get("answer", "")
+            }
+            
+        except Exception as e:
+            return {
+                "query": query,
+                "results": [],
+                "error": str(e)
+            }
+    
+    async def search_flights(self, origin: str, destination: str) -> dict:
+        """Search for flight booking options."""
+        query = f"best flight tickets from {origin} to {destination} cheap deals"
+        return await self.search(query)
+    
+    async def search_hotels(self, destination: str, budget: str = "") -> dict:
+        """Search for hotel booking options."""
+        query = f"best hotels in {destination} {budget} booking"
+        return await self.search(query)
+    
+    async def search_activities(self, destination: str) -> dict:
+        """Search for activities and experiences."""
+        query = f"best things to do activities experiences in {destination}"
+        return await self.search(query)
+
+
+# Singleton instance
+_client = None
+
+
+def get_tavily_client() -> TavilySearchClient:
+    """Get or create Tavily client singleton."""
+    global _client
+    if _client is None:
+        _client = TavilySearchClient()
+    return _client

tools.py

@@ -0,0 +1,158 @@
+"""
+Tool implementations for the Travel AI Agent.
+These tools are called by the Gemini agent to perform specific actions.
+"""
+
+import urllib.parse
+from typing import Optional
+from tavily_client import get_tavily_client
+
+
+
+
+
+
+
+
+async def search_web(query: str) -> dict:
+    """
+    Search the web using Tavily for travel-related information.
+    
+    Args:
+        query: Search query
+        
+    Returns:
+        Search results with URLs and summaries
+    """
+    client = get_tavily_client()
+    results = await client.search(query)
+    return results
+
+
+def generate_itinerary(destination: str, days: int, preferences: Optional[str] = None) -> dict:
+    """
+    Generate a base itinerary structure (actual content generated by Gemini).
+    
+    Args:
+        destination: Travel destination
+        days: Number of days
+        preferences: Optional travel preferences
+        
+    Returns:
+        Itinerary metadata and prompt for generation
+    """
+    return {
+        "destination": destination,
+        "days": days,
+        "preferences": preferences or "balanced mix of culture, food, and relaxation",
+        "generate_prompt": True,
+        "message": f"📅 Generating a {days}-day itinerary for {destination}..."
+    }
+
+
+def recommend_destinations(
+    budget: Optional[str] = None,
+    style: Optional[str] = None,
+    interests: Optional[list] = None,
+    duration: Optional[str] = None,
+    season: Optional[str] = None
+) -> dict:
+    """
+    Structure preferences for destination recommendations.
+    
+    Args:
+        budget: Budget range (e.g., "low", "medium", "luxury")
+        style: Travel style (e.g., "adventure", "relaxation", "cultural")
+        interests: List of interests
+        duration: Trip duration
+        season: Preferred travel season
+        
+    Returns:
+        Structured preferences for recommendation generation
+    """
+    preferences = {
+        "budget": budget or "flexible",
+        "style": style or "balanced",
+        "interests": interests or ["sightseeing", "local cuisine", "culture"],
+        "duration": duration or "flexible",
+        "season": season or "any"
+    }
+    
+    return {
+        "preferences": preferences,
+        "generate_prompt": True,
+        "message": "🗺️ Finding perfect destinations based on your preferences..."
+    }
+
+
+# Tool definitions for Gemini function calling
+TOOL_DEFINITIONS = [
+    {
+        "name": "search_web",
+        "description": "Search the web for travel information, booking websites, flight prices, hotel deals, and current travel news. Use this when users ask about booking, prices, or need real-time information.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "The search query for travel-related information"
+                }
+            },
+            "required": ["query"]
+        }
+    },
+
+    {
+        "name": "generate_itinerary",
+        "description": "Generate a detailed day-by-day travel itinerary for a destination. Use this when users want to plan a trip or ask for itinerary suggestions.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "destination": {
+                    "type": "string",
+                    "description": "The travel destination"
+                },
+                "days": {
+                    "type": "integer",
+                    "description": "Number of days for the trip"
+                },
+                "preferences": {
+                    "type": "string",
+                    "description": "Optional travel preferences or interests"
+                }
+            },
+            "required": ["destination", "days"]
+        }
+    },
+    {
+        "name": "recommend_destinations",
+        "description": "Recommend travel destinations based on user preferences. Use this when users describe what kind of trip they want.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "budget": {
+                    "type": "string",
+                    "description": "Budget range: 'budget', 'moderate', 'luxury'"
+                },
+                "style": {
+                    "type": "string",
+                    "description": "Travel style: 'adventure', 'relaxation', 'cultural', 'romantic', 'family'"
+                },
+                "interests": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "List of interests like 'beaches', 'mountains', 'history', 'food'"
+                },
+                "duration": {
+                    "type": "string",
+                    "description": "Trip duration like '3 days', '1 week'"
+                },
+                "season": {
+                    "type": "string",
+                    "description": "Preferred travel season"
+                }
+            },
+            "required": []
+        }
+    }
+]