Maharashtra Smart AI Travel Itinerary Planner 🏛️✨

An Academic AI/ML Mini-Project for Intelligent Tourism Recommendation & Constraint-Based Itinerary Optimization

---

🌟 Executive Summary

Maharashtra Smart AI Travel Itinerary Planner is a full-stack, genuine Python AIML-powered travel technology application designed for academic demonstration and real-world utility.

Unlike conventional static tourism websites that present hardcoded lists, this application executes a Multi-Dimensional Content-Based Filtering Algorithm using Cosine Similarity, weighted multi-criteria heuristic scoring, and constraint-based timeline scheduling across 10 authoritative Maharashtra tourism destinations, 80 attractions, 30 activities, 33 verified routes, 30 restaurants, and 30 hotels.

---

🚀 Key Features

1. Genuine Python AIML Recommendation Engine:
   • Computes Cosine Similarity in an 11-Dimensional Feature Space (nature, adventure, history, religious, beach, wildlife, food, shopping, photography, relaxation, family).
   • Dynamically vectorizes user preferences and applies travel-group heuristic biases (Solo, Couple, Family, Friends).
2. Explainable AI (XAI) Rationales:
   • Generates transparent natural language explanations and match percentages for why each attraction is recommended.
3. Constraint-Based Chronological Itinerary Optimizer:
   • Auto-generates structured day-by-day vertical timelines adhering to user pace, opening/closing hours, transit buffers, and meal breaks.
4. 5-Category Budget Optimization Engine:
   • Calculates expenses across Stay, Dining, Entry Fees, Activities, and Local Transport, auto-suggesting budget optimizations when user budget constraints are exceeded.
5. Interactive Mapping & Geospatial Visualization:
   • Dynamic Leaflet.js route maps showing numbered attraction pins, interactive popups, and route connecting polyline segments.
6. Executive PDF & JSON Export:
   • Generates downloadable high-resolution formatted PDF reports using reportlab.
7. Administrative Dashboard & Full Entity CRUD:
   • Manage destinations, attractions, hotels, restaurants, routes, and update ML feature vector matrices with live slider controls.
8. Feedback & Recommender Tuning Loop:
   • Logs 1-to-5 star user ratings to refine feature weights.

---

📐 AIML Mathematical Formulation

1. Vector Space Representation

Each attraction ( j ) is characterized by an 11-dimensional feature vector (\vec{A}_j \in [0, 1]^{11}). The user profile is transformed into a normalized preference vector (\vec{U} \in [0, 1]^{11}) adjusted by travel companion biases:

$$\text{Cosine Similarity}(\vec{U}, \vec{A}_j) = \frac{\vec{U} \cdot \vec{A}_j}{|\vec{U}|_2 |\vec{A}_j|_2} = \frac{\sum_{i=1}^{11} u_i \cdot a_{j,i}}{\sqrt{\sum_{i=1}^{11} u_i^2} \sqrt{\sum_{i=1}^{11} a_{j,i}^2}}$$

2. Multi-Criteria Composite Score Formulation

The total attraction fitness score ( S_j ) blends content similarity with empirical signals:

$$S_j = W_{\text{sim}} \cdot \text{Sim}_j + W_{\text{rate}} \cdot \text{Rating}_j + W_{\text{pop}} \cdot \text{Pop}_j + W_{\text{bud}} \cdot \text{Budget}_j + W_{\text{time}} \cdot \text{Pace}_j + W_{\text{route}} \cdot \text{Prox}_j$$

Factor	Weight ($W$)	Description
Interest Similarity	35% (0.35)	Cosine similarity on 11-D preference vector
Attraction Rating	20% (0.20)	Normalized visitor review rating ($[0.0, 1.0]$)
Budget Fitness	15% (0.15)	Entry fee compatibility with daily per-person budget
Popularity Fit	10% (0.10)	High (1.0), Medium (0.70), Low (0.40) weight
Duration Fit	10% (0.10)	Compatibility with travel pace (Relaxed, Moderate, Fast-paced)
Route Proximity	10% (0.10)	Regional cluster corridor proximity score

---

🏗️ System Architecture

                                +-----------------------------+
                                |      Web Client (Browser)    |
                                |  (Tailwind UI, Leaflet, JS) |
                                +--------------+--------------+
                                               | HTTP / REST
                                               v
                                +-----------------------------+
                                |      Flask Application      |
                                |   (App Factory & Blueprints)|
                                +---+-------+-------+-----+---+
                                    |       |       |     |
         +--------------------------+       |       |     +--------------------------+
         |                                  |       |                                |
         v                                  v       v                                v
+------------------+             +----------------------+                 +--------------------+
|  Public & Auth   |             |  AIML Recommender    |                 | Itinerary Engine   |
|  - Login / Reg   |             |  - 11-D Vectorizer   |                 | - Chrono Scheduler |
|  - Explore / Det |             |  - Cosine Similarity |                 | - Route Calculator |
|  - Admin CRUD    |             |  - XAI Rationale Gen |                 | - Budget Optimizer |
+--------+---------+             +----------+-----------+                 +---------+----------+
         |                                  |                                       |
         +----------------------------------+---------------------------------------+
                                            |
                                            v
                                +-----------------------+
                                |   SQLAlchemy Engine   |
                                | (SQLite / MySQL DB)   |
                                +-----------+-----------+
                                            |
                                            v
                                +-----------------------+
                                | Authoritative Dataset |
                                | (JSON Tourism Matrix) |
                                +-----------------------+

---

📂 Project Structure

maharashtra_travel_planner/
├── config.py                     # Configuration & ML Weights
├── app.py                        # Application factory & Blueprint loader
├── seed_database.py              # Standalone DB seeder CLI
├── test_app_endpoints.py         # 7-module automated test suite
├── test_recommender.py           # ML Recommender unit test
├── test_demo_scenario.py         # Mahabaleshwar demo scenario test
├── requirements.txt              # Production dependencies
├── .env.example                  # Environment configuration template
├── data/
│   └── maharashtra_travel_data.json  # Authoritative 10-destination dataset
├── database/
│   ├── db.py                     # SQLAlchemy db instance
│   └── seed_data.py              # Comprehensive seeder script
├── models/
│   ├── __init__.py               # Model exports
│   ├── tourism.py                # Destination, Attraction, Route, Hotel, Restaurant
│   ├── ml_features.py            # 11-D ML Feature Vectors
│   ├── user.py                   # User, UserPreference, Favorite
│   └── trip.py                   # Trip, Itinerary, ItineraryItem, UserFeedback
├── ml/
│   ├── __init__.py
│   ├── feature_engineering.py    # Vector normalization & companion bias
│   ├── model_utils.py            # Cosine similarity & subscore math
│   ├── explanations.py           # Explainable AI (XAI) generator
│   └── recommender.py            # Multi-criteria recommendation engine
├── itinerary/
│   ├── __init__.py
│   ├── router.py                 # Transit distances, travel times, transport costs
│   ├── scheduler.py              # Chronological timeline & meal insertion
│   ├── budget.py                 # 5-category budget breakdown & optimizer
│   └── optimizer.py              # Master end-to-end optimizer orchestrator
├── routes/
│   ├── __init__.py
│   ├── auth_routes.py            # Authentication & preference updates
│   ├── public_routes.py          # Landing, Explore, Details, About
│   ├── planner_routes.py         # 3-step Planner flow & feedback
│   ├── api_routes.py             # REST JSON endpoints & AJAX
│   ├── admin_routes.py           # Admin control panel & entity CRUD
│   └── export_routes.py          # ReportLab PDF & JSON exporter
├── static/
│   ├── css/                      # style.css, timeline.css, animations.css, admin.css
│   └── js/                       # main.js, planner.js, map.js, recommendations.js, admin.js
└── templates/
    ├── base.html                 # Master layout with navbar & footer
    ├── index.html                # Landing page with hero & counters
    ├── explore.html              # Destination catalog
    ├── destination_detail.html   # Destination deep-dive guide
    ├── about.html                # AIML documentation & formula
    ├── 404.html & 500.html       # Error pages
    ├── auth/                     # login.html, register.html
    ├── planner/                  # create_trip.html, recommendations.html, itinerary.html, edit_itinerary.html
    ├── trips/                    # my_trips.html
    └── admin/                    # dashboard.html, crud_list.html, edit_*.html

---

⚡ Quick Start Installation

Prerequisites

• Python 3.10+ installed
• Git (optional)

1. Clone or Navigate to Directory

cd "C:\Users\Atharva Mane\.gemini\antigravity\scratch\maharashtra_travel_planner"

2. Install Dependencies

pip install -r requirements.txt

3. Initialize & Seed Database

Populates all 10 destinations, 80 attractions, 80 ML feature vectors, 30 activities, 33 routes, 30 hotels, 30 restaurants, and default accounts:

python seed_database.py

4. Run Application

python app.py

Open http://127.0.0.1:5000 in your browser.

---

🔑 Default Credentials

Account Role	Email Address	Password	Privileges
System Admin	admin@maharashtra.ai	Admin@12345	Full CRUD, ML feature editor, Analytics
Demo Traveler	traveler@example.com	Traveler@123	Create trips, Save itineraries, Feedback

(Or click the 1-click Quick Login buttons on the Sign In page!)

---

🎯 Academic Demonstration Scenario

To demonstrate the system live for academic reviewers:

1. Click "Run Mahabaleshwar Demo" or navigate to Plan Itinerary.
2. Click "✨ Load Demo Preset (Mahabaleshwar Friends Trip)":
   • Destination: Mahabaleshwar (Western Maharashtra)
   • Duration: 3 Days
   • Budget: ₹12,000
   • Group: Friends (4 Travelers)
   • Interests: Nature + Adventure + Photography
   • Daily Window: 08:00 – 20:00
   • Hotel Preference: Mid-range
3. Click "Run AIML Recommender & Generate Itinerary".
4. Observe the Animated Multi-Step AI Processing Screen simulating vector analysis.
5. Review top recommendations (Pratapgad Fort, Arthur's Seat, Elephant's Head Point, Venna Lake) with 94%+ match scores and Explainable AI (XAI) rationale badges.
6. Click "Build Complete Timeline Itinerary" to view:
   • Chronological vertical timeline with breakfast, lunch, and dinner stops.
   • Interactive Leaflet map with route pins.
   • 5-category budget breakdown chart.
   • 1-click "Download PDF Itinerary".

---

🧪 Automated Verification Suite

Run all automated unit and integration tests:

# Run Recommender Engine Unit Test
python test_recommender.py

# Run Demonstration Scenario Test
python test_demo_scenario.py

# Run Full 7-Module Flask Test Suite
python test_app_endpoints.py

---

📜 Authoritative Tourism Coverage

The dataset covers 10 diverse tourism regions across Maharashtra:

1. Lonavala (Western Maharashtra / Pune) — Hill station, Forts, Caves, Waterfalls
2. Mahabaleshwar (Western Maharashtra / Satara) — Sahyadri viewpoints, Strawberries, Heritage forts
3. Matheran (Konkan / Raigad) — Eco-sensitive hill station, Forest trails, Heritage Toy Train
4. Alibaug (Konkan / Raigad) — Coastal beaches, Sea forts, Water sports
5. Tarkarli (Konkan / Sindhudurg) — Scuba diving, Coral reefs, Pristine backwaters
6. Ratnagiri–Ganpatipule (Konkan) — Coastal temples, Mango orchards, Forts
7. Nashik (North Maharashtra) — Vineyards, Godavari Ghats, Jyotirlinga pilgrimage
8. Kolhapur (Southern Maharashtra) — Mahalakshmi Temple, Palace architecture, Cuisine
9. Chhatrapati Sambhajinagar (Marathwada) — UNESCO World Heritage Ajanta & Ellora Caves
10. Tadoba–Andhari Tiger Reserve (Vidarbha / Chandrapur) — Tiger safaris, Wildlife sanctuary

---

© 2026 Maharashtra Smart AI Travel Planner. Built with Python, Flask, Scikit-Learn & ReportLab.