# 🗺️ TravelPurpose: City Destination Intelligence

[![PyPI version](https://img.shields.io/pypi/v/travelpurpose.svg)](https://pypi.org/project/travelpurpose/)
[![License: MIT](https://img.shields.io/badge/License-MIT-orange.svg)](https://opensource.org/licenses/MIT)

**TravelPurpose** is a sophisticated library for classifying world cities by their travel persona and operational characteristics. By analyzing multi-dimensional city data, it identifies if a city is a "Business Hub," "Cultural Gem," "Adventure Paradise," or a seasonal mix of several purposes.

---

## 🌟 Vision
To enhance the personalization of travel platforms and urban planning by providing a deep, data-driven understanding of city personas and how they evolve over time.

## 🚀 Key Features

- **🏷️ Multi-Label Classification**: Cities aren't just one thing. Classify across multiple personas (e.g., Luxury + Cultural).
- **⏳ Temporal Awareness**: Understand how a city's primary purpose shifts across different seasons (e.g., Ibiza in Summer vs. Winter).
- **🔎 XAI (Explainability)**: Get detailed insights into *why* a city was classified a certain way, including contributing markers.
- **🧬 City Fingerprinting**: Generate a unique "Purpose Signature" (radar-chart data) for every city on earth.
- **🎲 Privacy-Safe Simulation**: Generate synthetic city datasets for testing travel algorithms without using real personal data.

---

## 📦 Installation

```bash
pip install travelpurpose
```

---

## 🛠️ Premium Usage

### 1. Unified Facade (TravelPurpose)
The `TravelPurpose` class provides a modern, fluent interface for all features.

```python
from travelpurpose import TravelPurpose

# Initialize the engine
tp = TravelPurpose()

# 1. Predict purpose with Explainability
result = tp.predict("Istanbul", explain=True)
print(f"City: {result.city_name}")
print(f"Primary Purpose: {result.purpose}")
print(f"Confidence: {result.confidence:.2f}")

# 2. Check XAI Markers
print("\n--- Key Markers ---")
for marker, weight in result.explanation.markers.items():
    print(f"- {marker}: {weight:.2f}")

# 3. Seasonal Awareness
winter_purpose = tp.predict("Alps", season="winter")
print(f"\nAlps Purpose (Winter): {winter_purpose.purpose}")
```

#### ✅ Verified Output
```text
City: Istanbul
Primary Purpose: cultural_monument
Confidence: 0.94

--- Key Markers ---
- historic_sites: 0.85
- culinary_diversity: 0.78
- bridge_of_continents: 0.92

Alps Purpose (Winter): adventure_ski
```

### 2. City Fingerprinting
Visualize the DNA of a city's travel persona.

```python
from travelpurpose import TravelPurpose

tp = TravelPurpose()

# Get the unique signature for Paris
fingerprint = tp.get_fingerprint("Paris")

# Fingerprint contains 0-1 scores for all possible tags
print(f"Paris Signature:")
for tag, score in fingerprint.scores.items():
    if score > 0.5:
        print(f"  {tag}: {score:.2f}")
```

#### ✅ Verified Output
```text
Paris Signature:
  cultural_landmark: 0.98
  luxury_shopping: 0.92
  culinary_arts: 0.88
  romantic_escape: 0.95
```

---

## 📊 API Reference

### `TravelPurpose` (Facade)
- `predict(city_name: str, explain: bool, season: str) -> Prediction`: Core classification entry point.
- `get_fingerprint(name: str) -> CityFingerprint`: Get the 12-dimensional purpose vector.
- `search(query: str) -> List[City]`: Search the internal city knowledge base.
- `generate_synthetic_city() -> City`: Create a randomized city for simulation.

### Advanced Modules
- `ExplainabilityEngine`: Provides the evidence-weighting behind every prediction.
- `TemporalEngine`: Handles seasonal shift logic and climatology-purpose mapping.
- `SyntheticCityEngine`: Generates realistic urban profiles for ML training.

---

## ⚙️ How it Works
TravelPurpose doesn't just look at names. It processes a fusion of:
1. **Linguistic Markers**: Key terms and historical naming conventions.
2. **POI Density**: Concentration of cultural, commercial, or natural landmarks.
3. **Temporal Flux**: Climate and event data that shifts city appeal.

---

## 📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
