utils/context_builder.py

"""

Context Package Builder for Unified AI Course Generation (v3)



Supabase story_spots 테이블 + walking_network.json을 기반으로

Gemini에 전달할 지역 컨텍스트 패키지를 조합합니다.



v3 변경사항:

- SELECT * 제거 → 명시적 컬럼 선택 (Q-H7)

- pgVector 시맨틱 검색 지원 (spot_embeddings 테이블)

- 벡터 검색 실패 시 기존 전체 로드 폴백 유지



Usage:

    from utils.context_builder import ContextBuilder

    builder = ContextBuilder()

    context = builder.build_zone_context("A", theme="history", max_spots=30)

"""

import asyncio
import json
import os
import logging
import time
from typing import Dict, List, Any, Optional, Tuple
from pathlib import Path

from utils.geo import haversine
from utils.osrm_distance import get_walking_distances

logger = logging.getLogger(__name__)

# ============ Constants ============

WALKING_SPEED_KMH = 4.0
DISTANCE_MULTIPLIER = 1.3

# 스팟 수 제한 (토큰 예산 내)
MAX_SPOTS_PER_ZONE = 50
MAX_SPOTS_TOTAL = 30  # AI에게 전달할 최대 후보 스팟 수

# story_spots 명시적 컬럼 선택 (SELECT * 대체, Q-H7)
SPOT_SELECT_COLUMNS = (
    "id, name, name_en, name_zh, category, lat, lng, address, "
    "story_title, story_content, story_source, tips, "
    "tags_tier1, tags_tier2, meta, "
    "main_image_url, thumbnail_url, generated_image_url, "
    "priority_score, status, zone, cluster_id, "
    "village, source_book, historical_period"
)

# 카테고리 한글 매핑
CATEGORY_KR = {
    "beach": "해변", "coastline": "해안", "harbor": "포구", "oreum": "오름",
    "forest": "숲", "village": "마을", "shrine": "신당", "fortress": "성곽",
    "beacon": "봉수대", "wetland": "습지", "traditional": "전통", "ruins": "유적",
    "cafe": "카페", "restaurant": "음식점", "market": "시장", "school": "학교",
    "community": "마을회관", "product": "특산물",
}

# 활동성 범위 매칭 (light 유저도 moderate 산책 코스를 볼 수 있어야 함)
ACTIVITY_COMPATIBLE = {
    "light": {"light", "moderate"},
    "moderate": {"light", "moderate", "active"},
    "active": {"moderate", "active"},
}

# 테마 교차 매칭 (healing ↔ nature, photo ↔ nature)
THEME_COMPATIBLE = {
    "healing": {"healing", "nature"},
    "nature": {"nature", "healing"},
    "photo": {"photo", "nature"},
    "history": {"history"},
    "food": {"food"},
}

# 최소 후보 스팟 수 (이 이하면 필터 단계적 완화)
MIN_SPOTS_THRESHOLD = 3

# DB 캐시 TTL (초)
SPOTS_CACHE_TTL_SECONDS = 300  # 5분


class ContextBuilder:
    """Gemini 컨텍스트 패키지 빌더"""

    def __init__(self, data_dir: Optional[str] = None):
        if data_dir is None:
            # 여러 경로 후보에서 data/ 디렉토리 탐색
            # 실제 파일(walking_network.json) 존재 여부로 판단
            # - HF Space:  /app/data/ (deploy workflow가 복사)
            # - 로컬 개발: project_root/data/
            # 주의: /data는 HF persistent storage root이므로 후순위
            base = Path(__file__).parent.parent  # backend/ 또는 /app/
            candidates = [
                base / "data",          # /app/data/ (HF Space)
                base.parent / "data",  # project_root/data/ (로컬 개발)
            ]
            for candidate in candidates:
                if (candidate / "walking_network.json").exists():
                    data_dir = str(candidate)
                    break
            if data_dir is None:
                # 파일 없어도 디렉토리라도 있는 경로 사용
                for candidate in candidates:
                    if candidate.exists():
                        data_dir = str(candidate)
                        break
            if data_dir is None:
                data_dir = str(candidates[0])

        self._data_dir = data_dir
        self._spots: List[Dict] = []
        self._spots_by_id: Dict[str, Dict] = {}
        self._network: Dict = {}
        self._network_loaded = False
        self._spots_loaded = False
        self._spots_loaded_at: float = 0.0  # TTL 캐시용 타임스탬프
        # 스토리라인 캐시
        self._storylines: List[Dict] = []
        self._storylines_loaded = False
        self._storylines_loaded_at: float = 0.0

    @staticmethod
    def _row_to_spot(row: Dict[str, Any]) -> Dict[str, Any]:
        """DB row → spot dict 변환 (기존 코드와 호환되는 포맷)"""
        spot: Dict[str, Any] = {
            "id": row["id"],
            "name": row["name"],
            "name_en": row.get("name_en"),
            "name_zh": row.get("name_zh"),
            "category": row["category"],
            "location": {
                "lat": float(row["lat"]),
                "lng": float(row["lng"]),
                "address": row.get("address", ""),
            },
            "story": {
                "title": row.get("story_title", ""),
                "content": row.get("story_content", ""),
                "source": row.get("story_source", ""),
                "tips": row.get("tips", ""),
            },
            "tags": {
                "tier1": row.get("tags_tier1") or {},
                "tier2": row.get("tags_tier2") or [],
            },
            "meta": row.get("meta") or {},
            "media": {
                "main_image": row.get("main_image_url"),
                "thumbnail": row.get("thumbnail_url"),
                "generated_image": row.get("generated_image_url"),
            },
            "priority_score": row.get("priority_score", 5),
            "status": row.get("status", "active"),
        }
        # zone / cluster_id: DB에 있으면 포함
        if row.get("zone") is not None:
            spot["zone"] = row["zone"]
        if row.get("cluster_id") is not None:
            spot["cluster_id"] = row["cluster_id"]
        # 향토지 메타데이터 (마을, 출처, 시대)
        if row.get("village"):
            spot["village"] = row["village"]
        if row.get("source_book"):
            spot["source_book"] = row["source_book"]
        if row.get("historical_period"):
            spot["historical_period"] = row["historical_period"]
        return spot

    def _load_spots_from_db(self) -> bool:
        """Supabase story_spots 테이블에서 active 스팟 로드. 성공 시 True."""
        try:
            from db import get_supabase
            supabase = get_supabase()
            result = supabase.table("story_spots") \
                .select(SPOT_SELECT_COLUMNS) \
                .eq("status", "active") \
                .execute()

            rows = result.data or []
            self._spots = [self._row_to_spot(r) for r in rows]
            self._spots_by_id = {s["id"]: s for s in self._spots}
            self._spots_loaded = True
            self._spots_loaded_at = time.monotonic()
            logger.info(f"ContextBuilder loaded {len(self._spots)} spots from Supabase")
            return True
        except Exception as e:
            logger.error(f"Failed to load spots from Supabase: {e}")
            return False

    async def search_spots_by_vector(

        self,

        theme: Optional[str] = None,

        activity_level: Optional[str] = None,

        mood: Optional[List[str]] = None,

        zone: Optional[str] = None,

        max_spots: int = MAX_SPOTS_TOTAL,

    ) -> Optional[List[Dict]]:
        """

        pgVector 시맨틱 검색으로 관련 스팟 조회.



        사용자 취향(테마/무드/활동성)을 자연어 쿼리로 변환하여

        임베딩 유사도 기반으로 스팟을 검색합니다.



        Returns:

            성공 시 spot dict 리스트, 실패/임베딩 미존재 시 None (폴백 트리거)

        """
        try:
            from db import get_supabase
            from utils.embedding_generator import generate_query_embedding

            supabase = get_supabase()

            # 1. 임베딩 존재 여부 확인
            stats = supabase.rpc("get_embedding_stats").execute()
            if stats.data:
                embedded_count = stats.data.get("embedded_spots", 0)
                if embedded_count == 0:
                    logger.info("[vector_search] No embeddings found, falling back")
                    return None

            # 2. 쿼리 텍스트 구성
            query_text = self._build_search_query(theme, activity_level, mood)
            if not query_text:
                logger.info("[vector_search] Empty query, falling back")
                return None

            # 3. 쿼리 임베딩 생성
            query_embedding = await generate_query_embedding(query_text)

            # 4. RPC 호출: search_similar_spots
            # Supabase RPC에 vector 타입을 문자열로 전달
            embedding_str = "[" + ",".join(str(v) for v in query_embedding) + "]"
            rpc_params: Dict[str, Any] = {
                "query_embedding": embedding_str,
                "limit_count": max_spots,
                "threshold": 0.25,  # 넓은 threshold로 충분한 후보 확보
            }
            if zone:
                rpc_params["filter_zone"] = zone

            result = await asyncio.to_thread(
                lambda: supabase.rpc("search_similar_spots", rpc_params).execute()
            )

            if not result.data:
                logger.info("[vector_search] No results from vector search")
                return None

            # 5. RPC 결과를 _row_to_spot 형식으로 변환
            #    search_similar_spots는 spot_id를 반환하므로 id로 매핑
            spots = []
            for row in result.data:
                row["id"] = row.pop("spot_id", row.get("id"))
                spot = self._row_to_spot(row)
                spot["_similarity"] = row.get("similarity", 0.0)
                spots.append(spot)

            logger.info(
                f"[vector_search] Found {len(spots)} spots via semantic search "
                f"(query: {query_text[:60]}...)"
            )
            return spots

        except ImportError:
            logger.warning("[vector_search] embedding_generator not available, falling back")
            return None
        except Exception as e:
            logger.warning(f"[vector_search] Failed: {e}, falling back to full load")
            return None

    @staticmethod
    def _build_search_query(

        theme: Optional[str] = None,

        activity_level: Optional[str] = None,

        mood: Optional[List[str]] = None,

    ) -> str:
        """사용자 취향 조건을 벡터 검색용 자연어 쿼리로 변환."""
        parts: List[str] = []

        theme_descriptions = {
            "healing": "힐링 치유 평화로운 고요한 자연 쉼",
            "nature": "자연 숲 해변 오름 산책 풍경 경치",
            "photo": "사진 포토스팟 인스타 뷰포인트 풍경",
            "history": "역사 문화 유적 전통 마을 이야기",
            "food": "음식 맛집 카페 시장 먹거리 제주 특산물",
            "random": "다양한 제주 여행 산책 관광",
        }
        if theme:
            parts.append(theme_descriptions.get(theme, f"{theme} 제주 여행"))

        activity_descriptions = {
            "light": "가벼운 산책 편안한 걷기",
            "moderate": "적당한 산책 코스 걷기",
            "active": "활동적인 등산 트레킹 하이킹",
        }
        if activity_level:
            parts.append(activity_descriptions.get(activity_level, ""))

        mood_descriptions = {
            "romantic": "로맨틱 커플 연인",
            "adventurous": "모험 탐험 새로운",
            "peaceful": "평화 고요 조용한",
            "cultural": "문화 예술 전통",
            "social": "친구 가족 함께",
        }
        if mood:
            for m in mood:
                parts.append(mood_descriptions.get(m, m))

        if not parts:
            parts.append("제주 애월 도보 여행 코스")

        return " ".join(parts)

    def _is_spots_cache_expired(self) -> bool:
        """스팟 캐시 TTL 만료 여부"""
        if not self._spots_loaded:
            return True
        elapsed = time.monotonic() - self._spots_loaded_at
        return elapsed >= SPOTS_CACHE_TTL_SECONDS

    def _is_storylines_cache_expired(self) -> bool:
        """스토리라인 캐시 TTL 만료 여부"""
        if not self._storylines_loaded:
            return True
        elapsed = time.monotonic() - self._storylines_loaded_at
        return elapsed >= SPOTS_CACHE_TTL_SECONDS

    def _load_storylines_from_db(self) -> bool:
        """Supabase storylines + storyline_spots 테이블에서 스토리라인 로드"""
        try:
            from db import get_supabase
            supabase = get_supabase()

            # 모든 active 스토리라인 로드
            sl_result = supabase.table("storylines") \
                .select("*") \
                .eq("status", "active") \
                .execute()

            sl_rows = sl_result.data or []
            if not sl_rows:
                self._storylines = []
                self._storylines_loaded = True
                self._storylines_loaded_at = time.monotonic()
                return True

            storylines_map = {sl["id"]: {**sl, "spots": []} for sl in sl_rows}

            # 모든 storyline_spots를 한 번에 로드
            ss_result = supabase.table("storyline_spots") \
                .select("*") \
                .in_("storyline_id", list(storylines_map.keys())) \
                .order("spot_order") \
                .execute()

            for ss in (ss_result.data or []):
                sl_id = ss["storyline_id"]
                if sl_id in storylines_map:
                    storylines_map[sl_id]["spots"].append(ss)

            self._storylines = list(storylines_map.values())
            self._storylines_loaded = True
            self._storylines_loaded_at = time.monotonic()
            logger.info(f"ContextBuilder loaded {len(self._storylines)} storylines")
            return True
        except Exception as e:
            logger.error(f"Failed to load storylines from DB: {e}")
            return False

    def find_matching_storylines(

        self,

        lat: float,

        lng: float,

        theme: Optional[str] = None,

        duration_minutes: int = 60,

        max_results: int = 3,

    ) -> List[Dict]:
        """

        사용자 위치 + 취향에 맞는 스토리라인 매칭



        스코어 계산:

        - 위치 근접도: 최대 50점 (반경 내 50, 반경 1.5x 내 25, 이상 0)

        - 테마 매칭: 최대 30점 (정확 30, 호환 15, 미지정 10)

        - 시간 적합도: 최대 20점 (20% 이내 20, 50% 이내 10)



        Returns: [{storyline: {...}, score: int, distance_km: float}]

        """
        self._ensure_loaded()

        if not self._storylines:
            return []

        scored = []
        for sl in self._storylines:
            score = 0

            # 1. 위치 근접도 (max 50)
            sl_lat = float(sl.get("center_lat") or 0)
            sl_lng = float(sl.get("center_lng") or 0)
            sl_radius = float(sl.get("radius_km") or 2.0)

            if not sl_lat or not sl_lng:
                continue

            dist = haversine(lat, lng, sl_lat, sl_lng)

            if dist > sl_radius * 2:
                continue  # 반경 2배 초과 → 스킵

            if dist <= sl_radius:
                score += 50
            elif dist <= sl_radius * 1.5:
                score += 25

            # 2. 테마 매칭 (max 30)
            sl_theme = sl.get("theme")
            if theme and sl_theme:
                if theme == sl_theme:
                    score += 30
                elif sl_theme in THEME_COMPATIBLE.get(theme, set()):
                    score += 15
                # 테마 불일치 = 0점
            elif not theme:
                score += 10  # 테마 미지정 → 약간의 보너스

            # 3. 시간 적합도 (max 20)
            sl_minutes = sl.get("estimated_minutes") or 60
            diff_ratio = abs(duration_minutes - sl_minutes) / max(duration_minutes, 1)
            if diff_ratio <= 0.2:
                score += 20
            elif diff_ratio <= 0.5:
                score += 10

            # 4. 스팟 유효성 검증: 모든 스팟이 실제로 존재하는지 확인
            sl_spots = sl.get("spots", [])
            all_valid = all(
                ss.get("spot_id") in self._spots_by_id
                for ss in sl_spots
            )
            if not all_valid or not sl_spots:
                logger.warning(f"[storyline] Skipping {sl['id']}: missing spots")
                continue

            scored.append({
                "storyline": sl,
                "score": score,
                "distance_km": round(dist, 3),
            })

        scored.sort(key=lambda x: -x["score"])
        return scored[:max_results]

    def _ensure_loaded(self):
        """데이터 lazy loading (스팟: DB + TTL 캐시, 네트워크: 파일, 스토리라인: DB + TTL 캐시)"""
        # 네트워크 데이터는 정적 파일에서 한 번만 로드
        if not self._network_loaded:
            network_path = os.path.join(self._data_dir, "walking_network.json")
            try:
                with open(network_path, "r", encoding="utf-8") as f:
                    self._network = json.load(f)
                logger.info(f"ContextBuilder loaded network: "
                            f"{len(self._network.get('layer1_clusters', {}))} clusters")
            except FileNotFoundError as e:
                logger.error(f"Network file not found: {e}")
            except json.JSONDecodeError as e:
                logger.error(f"Network JSON parse error: {e}")
            self._network_loaded = True

        # 스팟 데이터: DB에서 로드 + TTL 캐시 (만료 시 재로드)
        if self._is_spots_cache_expired():
            if not self._load_spots_from_db():
                # DB 실패 시: 이전 캐시 데이터 유지, TTL 리셋
                if self._spots:
                    self._spots_loaded_at = time.monotonic()
                    logger.warning(f"DB reload failed, keeping {len(self._spots)} cached spots")
                else:
                    logger.error("DB load failed and no cached spots available")

        # 스토리라인: DB에서 로드 + TTL 캐시 (실패해도 기존 흐름에 영향 없음)
        if self._is_storylines_cache_expired():
            if not self._load_storylines_from_db():
                if self._storylines:
                    self._storylines_loaded_at = time.monotonic()
                    logger.warning(f"Storyline reload failed, keeping {len(self._storylines)} cached")
                else:
                    self._storylines_loaded = True  # 빈 상태로 마킹하여 반복 시도 방지

    def get_zone_for_location(self, lat: float, lng: float) -> str:
        """좌표에 가장 가까운 존 반환"""
        self._ensure_loaded()
        zones = self._network.get("zones", {})
        best_zone = "C"
        best_dist = float('inf')
        for zone_id, zone in zones.items():
            lat_range = zone.get("lat_range", (0, 0))
            lng_range = zone.get("lng_range", (0, 0))
            center_lat = (lat_range[0] + lat_range[1]) / 2
            center_lng = (lng_range[0] + lng_range[1]) / 2
            dist = haversine(lat, lng, center_lat, center_lng)
            if dist < best_dist:
                best_dist = dist
                best_zone = zone_id
        return best_zone

    def get_nearby_zones(self, zone_id: str) -> List[str]:
        """인접 존 목록"""
        self._ensure_loaded()
        adj = self._network.get("zone_adjacency", {})
        return adj.get(zone_id, [])

    def _get_radius_candidates(

        self,

        lat: float,

        lng: float,

        radius_km: float,

    ) -> List[Dict]:
        """반경 내 활성 스팟 + 거리 계산 (필터 전 단계)"""
        self._ensure_loaded()
        candidates = []
        for spot in self._spots:
            if spot.get("status", "active") != "active":
                continue
            s_lat = spot["location"]["lat"]
            s_lng = spot["location"]["lng"]
            dist = haversine(lat, lng, s_lat, s_lng)
            if dist <= radius_km:
                candidates.append({**spot, "_distance_km": round(dist, 3)})
        return candidates

    def _apply_filters(

        self,

        candidates: List[Dict],

        theme: Optional[str] = None,

        activity_level: Optional[str] = None,

        mood: Optional[List[str]] = None,

        use_theme_compat: bool = True,

        use_activity_range: bool = True,

    ) -> List[Dict]:
        """조건 필터 적용 (범위 매칭 지원)"""
        filtered = []
        # 테마 호환 세트
        if theme and use_theme_compat:
            accepted_themes = THEME_COMPATIBLE.get(theme, {theme})
        elif theme:
            accepted_themes = {theme}
        else:
            accepted_themes = None

        # 활동성 호환 세트
        if activity_level and use_activity_range:
            accepted_activities = ACTIVITY_COMPATIBLE.get(activity_level, {activity_level})
        elif activity_level:
            accepted_activities = {activity_level}
        else:
            accepted_activities = None

        for spot in candidates:
            tags = spot.get("tags", {}).get("tier1", {})

            # 테마 필터
            if accepted_themes:
                spot_themes = set(tags.get("theme", []))
                if not spot_themes & accepted_themes:
                    # 음식 테마면 restaurant/cafe 카테고리 허용
                    if theme == "food" and spot["category"] in ("restaurant", "cafe"):
                        pass
                    else:
                        continue

            # 활동성 필터 (범위 매칭)
            if accepted_activities:
                spot_activity = tags.get("activity_level")
                if spot_activity and spot_activity not in accepted_activities:
                    continue

            # 분위기 필터 (하나라도 매칭)
            if mood:
                spot_moods = tags.get("mood", [])
                if spot_moods and not any(m in spot_moods for m in mood):
                    continue

            filtered.append(spot)
        return filtered

    def filter_spots(

        self,

        lat: float,

        lng: float,

        radius_km: float = 3.0,

        theme: Optional[str] = None,

        activity_level: Optional[str] = None,

        mood: Optional[List[str]] = None,

        max_spots: int = MAX_SPOTS_TOTAL,

    ) -> List[Dict]:
        """

        조건에 맞는 스팟 필터링 + 거리순 정렬

        최소 스팟 보장을 위해 단계적 필터 완화 적용



        Returns: [{...spot_data, _distance_km: float}]

        """
        # 반경 내 후보 (필터 전)
        candidates = self._get_radius_candidates(lat, lng, radius_km)

        # 1단계: 전체 필터 적용 (테마 호환 + 활동성 범위 매칭)
        result = self._apply_filters(candidates, theme, activity_level, mood)

        # 2단계: 스팟 부족 시 단계적 필터 완화
        if len(result) < MIN_SPOTS_THRESHOLD:
            # 2-1: mood 필터 제거
            result = self._apply_filters(candidates, theme, activity_level, mood=None)
            if len(result) >= MIN_SPOTS_THRESHOLD:
                logger.info(f"[filter] Relaxed mood filter: {len(result)} spots")

        if len(result) < MIN_SPOTS_THRESHOLD:
            # 2-2: activity_level + mood 필터 제거 (테마만 유지)
            result = self._apply_filters(candidates, theme, activity_level=None, mood=None)
            if len(result) >= MIN_SPOTS_THRESHOLD:
                logger.info(f"[filter] Relaxed activity filter: {len(result)} spots")

        if len(result) < MIN_SPOTS_THRESHOLD:
            # 2-3: 반경 2배 확장 + 테마만
            expanded = self._get_radius_candidates(lat, lng, radius_km * 2)
            result = self._apply_filters(expanded, theme, activity_level=None, mood=None)
            if len(result) >= MIN_SPOTS_THRESHOLD:
                logger.info(f"[filter] Expanded radius to {radius_km * 2}km: {len(result)} spots")

        if len(result) < MIN_SPOTS_THRESHOLD:
            # 2-4: 최후 수단 - 테마도 해제, 반경 2배 내 모든 스팟
            result = self._get_radius_candidates(lat, lng, radius_km * 2)
            logger.warning(f"[filter] All filters dropped, using {len(result)} spots in {radius_km * 2}km")

        # 관련성 스코어 계산 후 정렬 (테마/무드 매칭 → priority_score → 거리)
        for spot in result:
            score = spot.get("priority_score", 5) * 10  # 기본 0-100
            tags = spot.get("tags", {}).get("tier1", {})

            # 테마 정확 매칭 보너스
            if theme:
                spot_themes = set(tags.get("theme", []))
                if theme in spot_themes:
                    score += 30  # 정확 매칭
                elif spot_themes & THEME_COMPATIBLE.get(theme, set()):
                    score += 15  # 호환 매칭

            # 무드 매칭 보너스
            if mood:
                spot_moods = set(tags.get("mood", []))
                matched = len(spot_moods & set(mood))
                score += matched * 10  # 무드당 10점

            # 활동성 매칭 보너스
            if activity_level:
                spot_activity = tags.get("activity_level")
                if spot_activity == activity_level:
                    score += 10

            spot["_relevance_score"] = score

        result.sort(key=lambda s: (-s["_relevance_score"], s["_distance_km"]))

        # 거리 다양성 보장: 가까운 스팟만 밀집되지 않도록 밴드별 분배
        # (관련성 높은 스팟 우선 + 다양한 거리 대역에서 고르게 선택)
        if len(result) > max_spots and radius_km > 0:
            result = self._ensure_distance_diversity(result, max_spots, radius_km)
        else:
            result = result[:max_spots]

        return result

    def _ensure_distance_diversity(

        self,

        spots: List[Dict],

        max_spots: int,

        radius_km: float,

    ) -> List[Dict]:
        """

        거리 대역별 분배로 후보 스팟의 공간적 다양성 보장.

        가까운 곳만 밀집되면 AI가 0.2km 코스를 만드는 문제 방지.



        3개 밴드로 나누어 각 밴드에서 최소 비율을 확보:

        - 근거리 (0 ~ 33%): 후보의 50%

        - 중거리 (33% ~ 66%): 후보의 30%

        - 원거리 (66% ~ 100%): 후보의 20%

        """
        band_boundaries = [radius_km * 0.33, radius_km * 0.66, radius_km]
        band_quotas = [
            max(5, int(max_spots * 0.50)),  # 근거리: 50%
            max(3, int(max_spots * 0.30)),  # 중거리: 30%
            max(2, int(max_spots * 0.20)),  # 원거리: 20%
        ]

        bands: List[List[Dict]] = [[], [], []]
        for spot in spots:
            dist = spot.get("_distance_km", 0)
            if dist <= band_boundaries[0]:
                bands[0].append(spot)
            elif dist <= band_boundaries[1]:
                bands[1].append(spot)
            else:
                bands[2].append(spot)

        selected: List[Dict] = []
        remaining: List[Dict] = []

        for i, (band, quota) in enumerate(zip(bands, band_quotas)):
            selected.extend(band[:quota])
            remaining.extend(band[quota:])

        # 쿼터 미달 밴드가 있으면 나머지에서 채움 (관련성순 유지)
        if len(selected) < max_spots:
            remaining.sort(key=lambda s: (-s.get("_relevance_score", 0), s["_distance_km"]))
            selected.extend(remaining[:max_spots - len(selected)])

        # 최종 정렬: 관련성 → 거리
        selected.sort(key=lambda s: (-s.get("_relevance_score", 0), s["_distance_km"]))

        band_counts = [min(len(b), q) for b, q in zip(bands, band_quotas)]
        logger.info(f"[filter] Distance diversity: bands={band_counts}, "
                    f"total={len(selected)}/{len(spots)} spots")

        return selected[:max_spots]

    async def build_area_context(

        self,

        lat: float,

        lng: float,

        radius_km: float = 3.0,

        theme: Optional[str] = None,

        activity_level: Optional[str] = None,

        mood: Optional[List[str]] = None,

        duration_minutes: int = 60,

        use_vector_search: bool = True,

    ) -> Tuple[str, str, List[Dict]]:
        """

        AI에 전달할 지역 컨텍스트 빌드



        Args:

            use_vector_search: True면 pgVector 시맨틱 검색 시도 (폴백: 기존 방식)



        Returns:

            (area_context_text, distance_table_text, filtered_spots)

        """
        # 제주도 범위 검증
        JEJU_LAT_RANGE = (33.1, 33.6)
        JEJU_LNG_RANGE = (126.1, 127.0)

        if not (JEJU_LAT_RANGE[0] <= lat <= JEJU_LAT_RANGE[1] and JEJU_LNG_RANGE[0] <= lng <= JEJU_LNG_RANGE[1]):
            logger.warning(f"좌표가 제주 범위 밖: lat={lat}, lng={lng}")
            # 기본 중심점으로 대체
            lat, lng = 33.46, 126.31

        await asyncio.to_thread(self._ensure_loaded)

        spots = None

        # 1차: pgVector 시맨틱 검색 (테마/무드가 있을 때 효과적)
        if use_vector_search and (theme or mood):
            zone_id = self.get_zone_for_location(lat, lng)
            vector_spots = await self.search_spots_by_vector(
                theme=theme,
                activity_level=activity_level,
                mood=mood,
                zone=zone_id,
                max_spots=MAX_SPOTS_TOTAL * 2,  # 넉넉하게 가져와서 반경 필터 적용
            )
            if vector_spots:
                # 벡터 검색 결과에 반경 필터 적용
                radius_filtered = []
                for spot in vector_spots:
                    s_lat = spot["location"]["lat"]
                    s_lng = spot["location"]["lng"]
                    dist = haversine(lat, lng, s_lat, s_lng)
                    if dist <= radius_km * 1.5:  # 벡터 검색은 약간 넓은 반경 허용
                        spot["_distance_km"] = round(dist, 3)
                        radius_filtered.append(spot)

                if len(radius_filtered) >= MIN_SPOTS_THRESHOLD:
                    # 유사도 + 거리 복합 정렬
                    for spot in radius_filtered:
                        sim = spot.get("_similarity", 0.5)
                        dist = spot.get("_distance_km", 0)
                        spot["_relevance_score"] = int(sim * 100) + spot.get("priority_score", 5) * 5
                    radius_filtered.sort(
                        key=lambda s: (-s["_relevance_score"], s["_distance_km"])
                    )
                    spots = radius_filtered[:MAX_SPOTS_TOTAL]
                    logger.info(
                        f"[build_area_context] Using vector search: "
                        f"{len(spots)} spots (from {len(vector_spots)} candidates)"
                    )

        # 2차: 기존 필터 기반 검색 (폴백)
        if spots is None:
            spots = self.filter_spots(lat, lng, radius_km, theme, activity_level, mood)

        if not spots:
            return ("후보 스팟이 없습니다.", "", [])

        # 2. 지역 컨텍스트 텍스트 조합
        zone_id = self.get_zone_for_location(lat, lng)
        zone_info = self._network.get("zones", {}).get(zone_id, {})

        lines = []
        lines.append(f"# 지역: {zone_info.get('name', zone_id)} ({zone_info.get('description', '')})")
        lines.append(f"# 반경 {radius_km}km 내 후보 스팟 {len(spots)}개")
        lines.append("")

        # 스팟 목록 (압축 형식)
        lines.append("## 스팟 목록")
        lines.append("ID|이름|카테고리|좌표|우선순위|스토리요약")
        for s in spots:
            cat_kr = CATEGORY_KR.get(s["category"], s["category"])
            story = s.get("story", {})
            content = story.get("content", "")
            # 스토리 요약 (80자)
            if content and "카테고리에 속합니다" not in content:
                summary = content[:80].replace("\n", " ")
            else:
                summary = f"{s['name']} - {cat_kr}"

            line = (
                f"{s['id']}|{s['name']}|{cat_kr}|"
                f"{s['location']['lat']:.4f},{s['location']['lng']:.4f}|"
                f"p{s.get('priority_score', 5)}|{summary}"
            )
            lines.append(line)

        area_context = "\n".join(lines)

        # 3. 거리표 빌드 (OSRM 사용)
        distance_lines = await self._build_distance_table(spots, duration_minutes)

        return (area_context, distance_lines, spots)

    async def _build_distance_table(self, spots: List[Dict], duration_minutes: int) -> str:
        """스팟 간 도보 거리표 생성 (OSRM Table API, 폴백: Haversine × 1.3)"""
        if len(spots) <= 1:
            return ""

        max_walkable_km = (duration_minutes / 60) * WALKING_SPEED_KMH

        # OSRM Table API로 실제 도보 거리+시간 계산
        spot_distances, _, spot_durations, _ = await get_walking_distances(spots)

        lines = []
        max_dist = 0
        pairs = []

        for (id_a, id_b), dist in spot_distances.items():
            walk_min = spot_durations.get((id_a, id_b), max(1, round(dist / WALKING_SPEED_KMH * 60)))
            if dist <= max_walkable_km * 1.5:  # 도보 가능 범위 내만
                pairs.append((id_a, id_b, dist, walk_min))
                max_dist = max(max_dist, dist)

        # 거리순 정렬, 상위 100개만
        pairs.sort(key=lambda x: x[2])
        pairs = pairs[:100]

        lines.append("## 도보 거리표 (OSRM 실측, 제주 보정 적용)")
        for a, b, dist, walk_min in pairs:
            name_a = self._spots_by_id.get(a, {}).get("name", a)
            name_b = self._spots_by_id.get(b, {}).get("name", b)
            lines.append(f"{a}({name_a}) → {b}({name_b}): {dist:.2f}km, {walk_min}분")

        # 클러스터 메모
        if max_dist > 0 and max_dist < max_walkable_km * 0.5:
            lines.append("")
            lines.append(f"⚠️ 모든 스팟이 {max_dist:.1f}km 이내에 밀집되어 있습니다.")
            lines.append("→ 이동 시간이 희망 시간보다 짧을 수 있으며, 이는 정상입니다.")

        return "\n".join(lines)

    def build_spot_details_for_stories(self, spot_ids: List[str]) -> str:
        """스토리 생성을 위한 스팟 상세 정보"""
        self._ensure_loaded()

        lines = []
        for i, sid in enumerate(spot_ids):
            spot = self._spots_by_id.get(sid)
            if not spot:
                continue

            story = spot.get("story", {})
            original = story.get("content", "")
            source = story.get("source", "")

            lines.append(f"### 스팟 {i+1}: {spot['name']} ({sid})")
            lines.append(f"- 카테고리: {CATEGORY_KR.get(spot['category'], spot['category'])}")
            lines.append(f"- 위치: {spot['location'].get('address', '')}")
            if original and "카테고리에 속합니다" not in original:
                lines.append(f"- 기존 스토리: {original}")
            if source and source != "kakao":
                lines.append(f"- 출처: {source}")
            lines.append("")

        return "\n".join(lines)

    def get_spots_count(self) -> int:
        """로드된 스팟 수"""
        self._ensure_loaded()
        return len(self._spots)


# Singleton instance
_builder: Optional[ContextBuilder] = None


def get_context_builder() -> ContextBuilder:
    """싱글톤 ContextBuilder 인스턴스 반환"""
    global _builder
    if _builder is None:
        _builder = ContextBuilder()
    return _builder