travelpurpose 2.2.3

Travel Purpose Prediction Library

🗺️ TravelPurpose: City Destination Intelligence

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

pip install travelpurpose

---

🛠️ Premium Usage

1. Unified Facade (TravelPurpose)

The TravelPurpose class provides a modern, fluent interface for all features.

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

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.

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

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.