"""Pluggable asset generator interface (PLAN.md Phase 5).""" from __future__ import annotations from abc import ABC, abstractmethod from typing import Optional from app.models.assets import Asset from app.models.route import TrekkerRoute from app.models.trail_guide import TrailGuide class GeneratorError(Exception): """Missing prerequisite or generation failure; message is user-facing.""" class BaseGenerator(ABC): name: str = "base" description: str = "" requires: list[str] = [] # subset of {"trail_guide", "weather"} def check_requirements(self, route: TrekkerRoute, trail_guide: Optional[TrailGuide], weather: Optional[dict]) -> None: if "trail_guide" in self.requires and trail_guide is None: raise GeneratorError( f"'{self.name}' needs a linked trail guide — link one to this route first" ) if "weather" in self.requires and weather is None: raise GeneratorError( f"'{self.name}' needs cached weather — refresh weather for this route first" ) @abstractmethod def generate(self, route: TrekkerRoute, trail_guide: Optional[TrailGuide], weather: Optional[dict]) -> Asset: ...