src/context/models.py

"""Environmental and contextual data models for urban planning"""

from typing import List, Dict, Optional, Any
from pydantic import BaseModel, Field
from enum import Enum
from datetime import datetime


class AreaType(str, Enum):
    """Urban area classification"""
    DOWNTOWN = "downtown"
    URBAN_NEIGHBORHOOD = "urban_neighborhood"
    SUBURBAN = "suburban"
    RURAL = "rural"
    MIXED_USE = "mixed_use"
    INDUSTRIAL = "industrial"
    COMMERCIAL_CORRIDOR = "commercial_corridor"


class TransitAccessLevel(str, Enum):
    """Transit accessibility levels"""
    EXCELLENT = "excellent"  # <5 min walk to frequent transit
    GOOD = "good"  # 5-10 min walk to frequent transit
    MODERATE = "moderate"  # 10-15 min walk or infrequent service
    LIMITED = "limited"  # 15+ min walk or very infrequent
    NONE = "none"  # No transit access


class BuiltEnvironment(BaseModel):
    """Physical built environment characteristics"""

    location_id: str = Field(..., description="Unique location identifier")
    name: str = Field(..., description="Location name")
    area_type: AreaType = Field(..., description="Type of urban area")

    # Density and land use
    population_density: int = Field(
        ..., description="People per square mile"
    )
    housing_density: int = Field(
        ..., description="Housing units per square mile"
    )
    land_use_mix: float = Field(
        ..., ge=0, le=1,
        description="Mixed use score (0=single use, 1=highly mixed)"
    )

    # Transportation infrastructure
    transit_access: TransitAccessLevel = Field(
        ..., description="Public transit accessibility"
    )
    bike_infrastructure: int = Field(
        ..., ge=1, le=10,
        description="Quality of bike infrastructure (1-10)"
    )
    sidewalk_coverage: float = Field(
        ..., ge=0, le=1,
        description="Percentage of streets with sidewalks"
    )
    parking_availability: int = Field(
        ..., ge=1, le=10,
        description="Parking availability (1-10)"
    )

    # Amenities and services
    walkability_score: int = Field(
        ..., ge=0, le=100,
        description="Walk Score (0-100)"
    )
    parks_access: int = Field(
        ..., ge=1, le=10,
        description="Access to parks and green space (1-10)"
    )
    retail_access: int = Field(
        ..., ge=1, le=10,
        description="Access to retail and services (1-10)"
    )

    # Building characteristics
    building_age: str = Field(
        ..., description="Predominant building age (e.g., 'pre-1950', '1950-2000', 'post-2000')"
    )
    historic_district: bool = Field(
        default=False, description="Located in historic district"
    )

    # Infrastructure condition
    infrastructure_condition: int = Field(
        ..., ge=1, le=10,
        description="Overall infrastructure condition (1-10)"
    )

    description: str = Field(
        ..., description="Narrative description of the area"
    )


class SocialContext(BaseModel):
    """Social and community characteristics"""

    location_id: str = Field(..., description="Links to BuiltEnvironment location_id")

    # Demographics
    median_age: int = Field(..., ge=0)
    median_income: int = Field(..., ge=0, description="Median household income")
    poverty_rate: float = Field(..., ge=0, le=1, description="Percentage below poverty line")

    # Diversity
    racial_diversity_index: float = Field(
        ..., ge=0, le=1,
        description="Diversity index (0=homogeneous, 1=highly diverse)"
    )
    language_diversity: int = Field(
        ..., ge=1, le=10,
        description="Language diversity (1-10)"
    )

    # Community characteristics
    homeownership_rate: float = Field(
        ..., ge=0, le=1,
        description="Percentage of owner-occupied housing"
    )
    resident_stability: float = Field(
        ..., ge=0, le=1,
        description="Percentage living in same house 5+ years"
    )
    community_organization_strength: int = Field(
        ..., ge=1, le=10,
        description="Strength of community organizations (1-10)"
    )

    # Recent trends
    gentrification_pressure: int = Field(
        ..., ge=1, le=10,
        description="Level of gentrification pressure (1-10)"
    )
    recent_demographic_changes: List[str] = Field(
        default_factory=list,
        description="Notable demographic shifts"
    )

    cultural_character: str = Field(
        ..., description="Description of cultural identity and character"
    )


class TemporalContext(BaseModel):
    """Time-based contextual information"""

    # Time of day
    time_of_day: str = Field(
        ..., description="Time period (morning_rush, midday, evening_rush, night)"
    )
    day_of_week: str = Field(
        ..., description="Day of week"
    )
    season: str = Field(
        ..., description="Season (spring, summer, fall, winter)"
    )

    # Recent events
    recent_events: List[str] = Field(
        default_factory=list,
        description="Recent relevant events or meetings"
    )
    upcoming_decisions: List[str] = Field(
        default_factory=list,
        description="Upcoming planning decisions or votes"
    )

    # Current conditions
    weather: Optional[str] = Field(
        None, description="Current weather conditions"
    )
    special_circumstances: List[str] = Field(
        default_factory=list,
        description="Any special circumstances (construction, events, etc.)"
    )


class EconomicContext(BaseModel):
    """Economic conditions and trends"""

    location_id: str = Field(..., description="Links to BuiltEnvironment location_id")

    # Employment
    unemployment_rate: float = Field(..., ge=0, le=1)
    major_employers: List[str] = Field(default_factory=list)
    job_growth_rate: float = Field(..., description="Annual job growth rate")

    # Business
    small_business_density: int = Field(
        ..., ge=1, le=10,
        description="Concentration of small businesses (1-10)"
    )
    commercial_vacancy_rate: float = Field(
        ..., ge=0, le=1,
        description="Commercial property vacancy rate"
    )

    # Housing market
    median_home_price: int = Field(..., ge=0)
    median_rent: int = Field(..., ge=0, description="Median monthly rent")
    housing_cost_burden: float = Field(
        ..., ge=0, le=1,
        description="Percentage of households paying >30% income on housing"
    )

    # Investment
    recent_investment: List[str] = Field(
        default_factory=list,
        description="Recent major investments or developments"
    )
    planned_developments: List[str] = Field(
        default_factory=list,
        description="Planned future developments"
    )

    economic_trends: str = Field(
        ..., description="Narrative description of economic conditions and trends"
    )


class EnvironmentalContext(BaseModel):
    """Complete environmental context combining all dimensions"""

    context_id: str = Field(..., description="Unique context identifier")
    built_environment: BuiltEnvironment
    social_context: SocialContext
    temporal_context: TemporalContext
    economic_context: EconomicContext

    # Additional metadata
    metadata: Dict[str, Any] = Field(
        default_factory=dict,
        description="Additional flexible metadata"
    )

    def get_context_summary(self) -> str:
        """Generate text summary for LLM context"""
        return f"""
LOCATION: {self.built_environment.name} ({self.built_environment.area_type})

Built Environment:
- Area type: {self.built_environment.area_type}
- Population density: {self.built_environment.population_density:,} people/sq mi
- Transit access: {self.built_environment.transit_access}
- Walkability: {self.built_environment.walkability_score}/100
- {self.built_environment.description}

Social Context:
- Median income: ${self.social_context.median_income:,}
- Homeownership rate: {self.social_context.homeownership_rate:.1%}
- Gentrification pressure: {self.social_context.gentrification_pressure}/10
- {self.social_context.cultural_character}

Economic Context:
- Median home price: ${self.economic_context.median_home_price:,}
- Median rent: ${self.economic_context.median_rent:,}/month
- {self.economic_context.economic_trends}

Temporal Context:
- Time: {self.temporal_context.time_of_day}, {self.temporal_context.day_of_week}
- Season: {self.temporal_context.season}
- Recent events: {', '.join(self.temporal_context.recent_events) if self.temporal_context.recent_events else 'None'}
""".strip()

    class Config:
        """Pydantic config"""
        use_enum_values = True