"""NER port interface (hexagonal architecture)."""

from __future__ import annotations

from typing import TYPE_CHECKING, Protocol

if TYPE_CHECKING:
    from noteflow.domain.entities.named_entity import NamedEntity


class NerPort(Protocol):
    """Port for named entity recognition.

    This is the domain port that the application layer uses.
    Infrastructure adapters (like NerEngine) implement this protocol.
    """

    def extract(self, text: str) -> list[NamedEntity]:
        """Extract named entities from text.

        Args:
            text: Input text to analyze.

        Returns:
            List of extracted entities (deduplicated by normalized text).
        """
        ...

    def extract_from_segments(
        self,
        segments: list[tuple[int, str]],
    ) -> list[NamedEntity]:
        """Extract entities from multiple segments with tracking.

        Processes each segment individually and tracks which segments
        contain each entity via segment_ids. Entities appearing in
        multiple segments are deduplicated with merged segment lists.

        Args:
            segments: List of (segment_id, text) tuples.

        Returns:
            Entities with segment_ids populated (deduplicated across segments).
        """
        ...

    def is_ready(self) -> bool:
        """Check if the NER engine is loaded and ready.

        Returns:
            True if model is loaded and ready for inference.
        """
        ...
