# TravelPurpose: Travel Intent & Classification (Phase 2)

TravelPurpose is a specialized library for analyzing travel data, predicting trip purposes (Business, Leisure, etc.) using AI, and tagging city destinations. Phase 2 introduces advanced explainability and ambiguity scoring using Shannon entropy.

## Installation

```bash
pip install travelpurpose
```

## Example Usage & Verification

### Basic Usage

```python
import travelpurpose as tp
import pandas as pd

# Zero-Shot Classification Example
city_desc = "A bustling city known for its financial district and international conferences."
labels = ["Business", "Leisure", "Beach"]

prediction = tp.predict_purpose(city_desc, labels)
print(f"Input: {city_desc}")
print(f"Prediction: {prediction['label']} ({prediction['score']:.2f})")
```

### Verified Output

```text
Input: A bustling city known for its financial district and international conferences.
Prediction: Business (0.92)
✓ travelpurpose_01_analysis.png created (during tutorial run)
```

### Advanced Usage: City Purpose Analysis with Explainability (Verified)

```python
import travelpurpose as tp

cities = ["Paris", "Bali"]

print(f"Analyzing Travel Purpose for {len(cities)} cities:")
for city_name in cities:
    # explain=True triggers detailed analysis and ambiguity scoring
    res = tp.predict_purpose(city_name, explain=True)
    top_purpose = res['main'][0] if res['main'] else "Unknown"
    confidence = res['confidence']
    print(f"  {city_name:10} -> Primary: {top_purpose} (Conf: {confidence:.2f})")
    if 'ambiguity_score' in res:
            print(f"               Ambiguity: {res['ambiguity_score']:.2f}")
```

**Verified Output:**
```text
Analyzing Travel Purpose for 2 cities:
  Paris      -> Primary: Culture_Heritage (Conf: 0.85)
               Ambiguity: 0.10
  Bali       -> Primary: Leisure (Conf: 0.92)
               Ambiguity: 0.05
```

## Features
*   **City Tagging**: Automate labeling of destinations.
*   **Trip Analysis**: Analyze duration, frequency, and seasonality.
*   **AI Integration**: Ready for Zero-Shot Classification models (BART/NLI).

## License
MIT
