"""Protocol surface for the GPR component (ARCH-05).

Phase 1: mirrors ``IGlobalPlaceRecognition`` from ``core/gpr.py``.
Adapters move here in Plan 05 (GPR).
"""
from __future__ import annotations

from typing import List, Protocol, runtime_checkable

import numpy as np

from gps_denied.schemas.gpr import DatabaseMatch, TileCandidate


@runtime_checkable
class GlobalPlaceRecognition(Protocol):
    """Coarse localisation surface (mirrors IGlobalPlaceRecognition)."""

    def retrieve_candidate_tiles(
        self, image: np.ndarray, top_k: int
    ) -> List[TileCandidate]: ...

    def compute_location_descriptor(self, image: np.ndarray) -> np.ndarray: ...

    def query_database(
        self, descriptor: np.ndarray, top_k: int
    ) -> List[DatabaseMatch]: ...

    def rank_candidates(
        self, candidates: List[TileCandidate]
    ) -> List[TileCandidate]: ...

    def load_index(self, flight_id: str, index_path: str) -> bool: ...

    def retrieve_candidate_tiles_for_chunk(
        self, chunk_images: List[np.ndarray], top_k: int
    ) -> List[TileCandidate]: ...

    def compute_chunk_descriptor(self, chunk_images: List[np.ndarray]) -> np.ndarray: ...


# Backwards-compat alias.
IGlobalPlaceRecognition = GlobalPlaceRecognition
