refactor: add exception subclasses used by core services

FileStorageError, RayActorError, ToolExecutionError, and UnexpectedError
moved here from phase-2 since this is where they are first raised.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: paultranvan

openrag/components/retriever.py

@@ -27,7 +27,7 @@ def __init__(
         pass
 
     @abstractmethod
-    async def retrieve(self, partition: list[str], query: str) -> list[Document]:
+    async def retrieve(self, partition: list[str], query: str, filter: dict | None = None) -> list[Document]:
         pass
 
 
@@ -43,13 +43,15 @@ async def retrieve(
         self,
         partition: list[str],
         query: str,
+        filter: dict | None = None,
     ) -> list[Document]:
         db = get_vectordb()
         chunks = await db.async_search.remote(
             query=query,
             partition=partition,
             top_k=self.top_k,
             similarity_threshold=self.similarity_threshold,
+            filter=filter,
             with_surrounding_chunks=self.with_surrounding_chunks,
         )
         return chunks
@@ -78,7 +80,7 @@ def __init__(
         prompt: ChatPromptTemplate = ChatPromptTemplate.from_template(MULTI_QUERY_PROMPT)
         self.generate_queries = prompt | llm | StrOutputParser() | (lambda x: x.split("[SEP]"))
 
-    async def retrieve(self, partition: list[str], query: str) -> list[Document]:
+    async def retrieve(self, partition: list[str], query: str, filter: dict | None = None) -> list[Document]:
         db = get_vectordb()
         logger.debug("Generating multiple queries", k_queries=self.k_queries)
         generated_queries = await self.generate_queries.ainvoke(
@@ -92,6 +94,7 @@ async def retrieve(self, partition: list[str], query: str) -> list[Document]:
             partition=partition,
             top_k_per_query=self.top_k,
             similarity_threshold=self.similarity_threshold,
+            filter=filter,
             with_surrounding_chunks=self.with_surrounding_chunks,
         )
         return chunks
@@ -121,7 +124,7 @@ async def get_hyde(self, query: str):
         hyde_document = await self.hyde_generator.ainvoke({"query": query})
         return hyde_document
 
-    async def retrieve(self, partition: list[str], query: str) -> list[Document]:
+    async def retrieve(self, partition: list[str], query: str, filter: dict | None = None) -> list[Document]:
         db = get_vectordb()
         hyde = await self.get_hyde(query)
         queries = [hyde]
@@ -133,6 +136,7 @@ async def retrieve(self, partition: list[str], query: str) -> list[Document]:
             partition=partition,
             top_k_per_query=self.top_k,
             similarity_threshold=self.similarity_threshold,
+            filter=filter,
             with_surrounding_chunks=self.with_surrounding_chunks,
         )
 

openrag/utils/exceptions/__init__.py

@@ -1 +1,2 @@
 from .base import *
+from .common import *

openrag/utils/exceptions/common.py

@@ -0,0 +1,29 @@
+from .base import OpenRAGError
+
+
+class FileStorageError(OpenRAGError):
+    """Raised when file I/O operations fail (save, read, delete)."""
+
+    def __init__(self, message: str, **kwargs):
+        super().__init__(message=message, code="FILE_STORAGE_ERROR", status_code=500, **kwargs)
+
+
+class RayActorError(OpenRAGError):
+    """Raised when a Ray actor operation fails."""
+
+    def __init__(self, message: str, **kwargs):
+        super().__init__(message=message, code="RAY_ACTOR_ERROR", status_code=500, **kwargs)
+
+
+class ToolExecutionError(OpenRAGError):
+    """Raised when tool execution fails."""
+
+    def __init__(self, message: str, **kwargs):
+        super().__init__(message=message, code="TOOL_EXECUTION_ERROR", status_code=500, **kwargs)
+
+
+class UnexpectedError(OpenRAGError):
+    """Raised for unexpected errors that don't match any specific category."""
+
+    def __init__(self, message: str, **kwargs):
+        super().__init__(message=message, code="UNEXPECTED_ERROR", status_code=500, **kwargs)