"""
TravelPurpose - City Travel Purpose Classification Library

A production-grade Python library for classifying world cities by travel purpose
using multi-source data from public travel platforms and knowledge bases.

v2.0 NEW FEATURES:
- Explainability (explain=True): Understand WHY predictions are made
- Temporal/seasonal awareness: Purpose changes with seasons
- City fingerprints: Unique purpose signatures for each city
- Confidence decomposition: See what contributes to confidence
- Synthetic city generator: Privacy-safe data generation
"""

from typing import Optional
from travelpurpose.classifier import load, predict_purpose, search, tags
from travelpurpose.explainability import ExplainabilityEngine
from travelpurpose.temporal import TemporalEngine
from travelpurpose.fingerprint import CityFingerprint
from travelpurpose.synthetic.engine import SyntheticCityEngine, SyntheticCityConfig

__version__ = "2.2.2"
__author__ = "Travel Purpose Contributors"

class TravelPurpose:
    """
    Central facade for TravelPurpose library.
    Provides unified access to classification, explainability, and temporal engines.
    """
    def __init__(self):
        self._classifier = None
        self.explainability = ExplainabilityEngine()
        self.temporal = TemporalEngine()
        self.synthetic = SyntheticCityEngine()

    def predict(self, city_name: str, explain: bool = False, season: str = None):
        """Classifies a city by its travel purpose."""
        # Use existing predict_purpose function
        return predict_purpose(city_name, explain=explain, season=season)

    def search(self, query: str):
        """Searches for cities in the database."""
        return search(query)

    def get_fingerprint(self, city_name: str) -> CityFingerprint:
        """Returns a unique purpose signature for a city."""
        return CityFingerprint(city_name)

    def generate_synthetic_city(self, config: Optional[SyntheticCityConfig] = None):
        """Generates a privacy-safe synthetic city."""
        return self.synthetic.generate(config)

__all__ = [
    "TravelPurpose",
    # Core API
    "predict_purpose",
    "tags",
    "search",
    "load",
    # v2.0 NEW: Advanced features
    "ExplainabilityEngine",
    "TemporalEngine",
    "CityFingerprint",
    "SyntheticCityEngine",
    "SyntheticCityConfig",
    # Meta
    "__version__",
]
