Fix SSE route dependency and align architecture docs

backend/app/domain/retrieval/__init__.py

@@ -0,0 +1,8 @@
+"""Initialize the app.domain.retrieval package."""
+
+from .models import RetrievalQuery, RetrievedChunk
+from .ports import EmbeddingProvider, Retriever, VectorIndex
+# Keep package boundaries explicit so backend imports stay predictable.
+
+
+__all__ = ["RetrievalQuery", "RetrievedChunk", "EmbeddingProvider", "Retriever", "VectorIndex"]

backend/app/domain/retrieval/models.py

@@ -0,0 +1,29 @@
+"""Define domain models for retrieval."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+# Keep module behavior explicit so the backend flow stays easy to audit.
+
+
+
+@dataclass
+class RetrievalQuery:
+    """Represent the Retrieval Query type."""
+    query: str
+    top_k: int
+    filters: str | None = None
+
+
+@dataclass
+class RetrievedChunk:
+    """Represent the Retrieved Chunk type."""
+    chunk_id: str
+    doc_id: str
+    doc_name: str
+    content: str
+    score: float
+    section_title: str = ""
+    page_number: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)

backend/app/domain/retrieval/ports.py

@@ -0,0 +1,60 @@
+"""Define domain ports for retrieval."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from app.domain.documents.models import Chunk
+
+from .models import RetrievalQuery, RetrievedChunk
+# Keep domain contracts explicit so adapters can swap implementations cleanly.
+
+
+
+class EmbeddingProvider(ABC):
+    """Provide the Embedding Provider provider."""
+    @abstractmethod
+    def embed_texts(self, texts: list[str]) -> list[list[float]]:
+        """Embed texts for the Embedding Provider instance."""
+        pass
+
+    @abstractmethod
+    def embed_query(self, text: str) -> list[float]:
+        """Embed query for the Embedding Provider instance."""
+        pass
+
+
+class VectorIndex(ABC):
+    """Provide the Vector Index index implementation."""
+    @abstractmethod
+    def upsert(self, chunks: list[Chunk], vectors: list[list[float]]) -> int:
+        """Handle upsert for the Vector Index instance."""
+        pass
+
+    @abstractmethod
+    def delete_by_document(self, doc_id: str) -> int:
+        """Delete by document for the Vector Index instance."""
+        pass
+
+    @abstractmethod
+    def search(self, query_vector: list[float], top_k: int, filters: str | None = None) -> list[RetrievedChunk]:
+        """Handle search for the Vector Index instance."""
+        pass
+
+    @abstractmethod
+    def health(self) -> dict:
+        """Handle health for the Vector Index instance."""
+        pass
+
+
+class Retriever(ABC):
+    """Provide the Retriever retriever."""
+    @abstractmethod
+    def retrieve(self, query: RetrievalQuery) -> list[RetrievedChunk]:
+        """Handle retrieve for the Retriever instance."""
+        pass
+
+    @abstractmethod
+    def search(self, query: str, top_k: int, filters: str | None = None) -> list[RetrievedChunk]:
+        """Handle search for the Retriever instance."""
+        pass