app/domain/interfaces/retriever.py

"""
Domain Layer - Retriever Interface

Defines contract for document retrieval implementations.
"""
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import List, Optional


@dataclass
class RetrievalResult:
    """Single retrieval result"""

    content: str
    score: float
    document_id: str
    chunk_index: int
    metadata: dict


class IRetriever(ABC):
    """Interface for document retrieval"""

    @abstractmethod
    async def search(
        self,
        query: str,
        top_k: int = 10,
        filters: Optional[dict] = None,
        min_score: float = 0.0,
    ) -> List[RetrievalResult]:
        """Search for relevant documents"""
        pass

    @abstractmethod
    async def hybrid_search(
        self,
        query: str,
        top_k: int = 10,
        alpha: float = 0.5,
        filters: Optional[dict] = None,
    ) -> List[RetrievalResult]:
        """Hybrid search (semantic + keyword)"""
        pass


class IReranker(ABC):
    """Interface for result reranking"""

    @abstractmethod
    async def rerank(
        self, query: str, results: List[RetrievalResult], top_k: int = 10
    ) -> List[RetrievalResult]:
        """Rerank retrieval results"""
        pass


class IEmbedder(ABC):
    """Interface for text embedding"""

    @abstractmethod
    async def embed_text(self, text: str) -> List[float]:
        """Generate embedding for single text"""
        pass

    @abstractmethod
    async def embed_texts(self, texts: List[str]) -> List[List[float]]:
        """Generate embeddings for multiple texts"""
        pass

    @abstractmethod
    def get_dimension(self) -> int:
        """Get embedding dimension"""
        pass