Skip to content
Merged
Show file tree
Hide file tree
Changes from 7 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions REFACTORING_DECISION_LOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,23 @@ match reality, then record the reasoning here.

## Template for future entries

## Phase 1 — Registry + Exceptions (2026-04-21)

**1. Exceptions keep HTTP status_code on the class (OpenRAG style), not in
a separate error handler mapping (mandragora style).**
- Why: Existing code reads `exc.status_code` in multiple places. Switching
to a pure domain exception + API-layer mapping dict would require changing
every consumer now, which is unnecessary churn in Phase 1.
- Alternative considered: mandragora's pattern (bare exceptions in core/,
status code mapping in api/error_handlers.py). Cleaner for hexagonal
purity but rejected for backward compatibility.
- Follow-up: strip status codes from core exceptions in Phase 10 when
api/error_handlers.py is built. The error handler will own the mapping.

---

## Template for future entries

```
Comment on lines 58 to 77

ghost Apr 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Phase 1 section is inserted in the wrong place, creating a duplicate Template heading.

The pre-existing ## Template for future entries is still at line 58, the new Phase 1 content is dropped between it and its code fence, and a second ## Template for future entries is re-added at line 75. This both misplaces Phase 1 under the template heading and triggers markdownlint MD024. The Phase 1 block should go above the single template entry:

📝 Proposed fix
 ---
 
-## Template for future entries
-
-## Phase 1 — Registry + Exceptions (2026-04-21)
+## Phase 1 — Registry + Exceptions (2026-04-21)
 
 **1. Exceptions keep HTTP status_code on the class (OpenRAG style), not in
 a separate error handler mapping (mandragora style).**
 ...
 - Follow-up: strip status codes from core exceptions in Phase 10 when
   api/error_handlers.py is built. The error handler will own the mapping.
 
 ---
 
 ## Template for future entries
 

Phase N — [short title] ([YYYY-MM-DD])

...

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## Template for future entries
## Phase 1 — Registry + Exceptions (2026-04-21)
**1. Exceptions keep HTTP status_code on the class (OpenRAG style), not in
a separate error handler mapping (mandragora style).**
- Why: Existing code reads `exc.status_code` in multiple places. Switching
to a pure domain exception + API-layer mapping dict would require changing
every consumer now, which is unnecessary churn in Phase 1.
- Alternative considered: mandragora's pattern (bare exceptions in core/,
status code mapping in api/error_handlers.py). Cleaner for hexagonal
purity but rejected for backward compatibility.
- Follow-up: strip status codes from core exceptions in Phase 10 when
api/error_handlers.py is built. The error handler will own the mapping.
---
## Template for future entries
```
---
## Phase 1 — Registry + Exceptions (2026-04-21)
**1. Exceptions keep HTTP status_code on the class (OpenRAG style), not in
a separate error handler mapping (mandragora style).**
- Why: Existing code reads `exc.status_code` in multiple places. Switching
to a pure domain exception + API-layer mapping dict would require changing
every consumer now, which is unnecessary churn in Phase 1.
- Alternative considered: mandragora's pattern (bare exceptions in core/,
status code mapping in api/error_handlers.py). Cleaner for hexagonal
purity but rejected for backward compatibility.
- Follow-up: strip status codes from core exceptions in Phase 10 when
api/error_handlers.py is built. The error handler will own the mapping.
---
## Template for future entries
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)

[warning] 75-75: Multiple headings with the same content

(MD024, no-duplicate-heading)


[warning] 77-77: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@REFACTORING_DECISION_LOG.md` around lines 58 - 77, The Phase 1 block is
inserted inside and after the existing "## Template for future entries" header,
creating a duplicate template heading and MD024; move the entire "## Phase 1 —
Registry + Exceptions (2026-04-21)" section (including its content and the
trailing separator) so it appears above the single "## Template for future
entries" entry, remove the duplicate "## Template for future entries" that was
re-added, and ensure the template's closing code fence and formatting remain
intact; look for the headings "## Phase 1 — Registry + Exceptions (2026-04-21)"
and "## Template for future entries" to locate the blocks to reorder.

## Phase N — [short title] ([YYYY-MM-DD])

Expand Down
Empty file removed openrag/core/catalog/__init__.py
Empty file.
366 changes: 366 additions & 0 deletions openrag/core/utils/exceptions.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,366 @@
"""Unified exception hierarchy for OpenRAG.

All exceptions inherit from OpenRAGError and carry a machine-readable
``code``, an HTTP ``status_code``, and an optional ``extra`` dict.

The hierarchy is organised by concern:

OpenRAGError
+-- ConfigError
+-- RegistryError
+-- PipelineError
+-- AuthError
| +-- AuthenticationError (401)
+-- ValidationError (422)
+-- NotFoundError (404)
| +-- DocumentNotFoundError
| +-- PartitionNotFoundError
| +-- UserNotFoundError
+-- QuotaExceededError (429)
+-- ServiceUnavailableError (503)
| +-- CircuitBreakerOpenError
+-- InferenceError (503)
| +-- LLMParsingError (502)
| +-- InferenceTimeoutError (504)
| +-- InferenceConnectionError (503)
+-- StorageError (500)
| +-- MilvusError
| +-- PostgresError
+-- EmbeddingError (500)
| +-- EmbeddingAPIError
| +-- EmbeddingResponseError (422)
| +-- UnexpectedEmbeddingError
+-- VDBError (500)
+-- VDBConnectionError (503)
+-- VDBInsertError (422)
+-- VDBDeleteError (422)
+-- VDBSearchError (422)
+-- VDBFileIDAlreadyExistsError (409)
+-- VDBPartitionNotFound (404)
+-- VDBFileNotFoundError (404)
+-- VDBUserNotFound (404)
+-- VDBMembershipNotFound (404)
+-- VDBSchemaMigrationRequiredError (503)
+-- VDBCreateOrLoadCollectionError (422)
+-- UnexpectedVDBError (500)
"""

from __future__ import annotations


ghost Apr 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Ruff I001 import-sort failure is blocking the lint CI job.

Pipeline failure: ruff check failed (I001): Import block is un-sorted or un-formatted at line 48. Run ruff check --fix locally (or uv run ruff format) before pushing.

🧰 Tools
🪛 GitHub Actions: Linting

[error] 48-48: ruff check failed (I001): Import block is un-sorted or un-formatted

🪛 GitHub Check: lint (3.12)

[failure] 48-48: Ruff (I001)
openrag/core/utils/exceptions.py:48:1: I001 Import block is un-sorted or un-formatted

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@openrag/core/utils/exceptions.py` around lines 48 - 50, The import block in
openrag/core/utils/exceptions.py is not sorted ( Ruff I001 )—ensure the imports
(including the existing "from __future__ import annotations") are ordered per
ruff/isort rules (future imports first, then stdlib, third-party, local) and
that spacing between groups is correct; either run "ruff check --fix" (or "uv
run ruff format") to auto-fix, or manually reorder the import statements to
match isort conventions and re-run ruff until no I001 errors remain.

# ---------------------------------------------------------------------------
# Root
# ---------------------------------------------------------------------------

class OpenRAGError(Exception):
"""Base class for all OpenRAG exceptions.

Preserves the existing API: message, code, status_code, to_dict().
"""

def __init__(
self,
message: str,
code: str = "OPENRAG_ERROR",
status_code: int = 500,
**kwargs,
):
self.message = message
self.code = code
self.status_code = status_code
self.extra = kwargs or {}
super().__init__(f"{self.code}: {self.message}")
Comment on lines +55 to +72

ghost Apr 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Stale Exception.args after subclass mutation of code/status_code.

OpenRAGError.__init__ calls super().__init__(f"{self.code}: {self.message}"), which freezes the parent's args tuple at construction time. Several subclasses (AuthenticationError, CircuitBreakerOpenError, LLMParsingError, InferenceTimeoutError, InferenceConnectionError, MilvusError, PostgresError) call super().__init__(...) first and then overwrite self.code/self.status_code. The effect:

  • exc.code / exc.status_code / to_dict() → new (correct) values
  • str(exc) / logging %s of the exception → stale parent code, e.g. "STORAGE_ERROR: ..." on a MilvusError, "AUTH_ERROR: ..." on an AuthenticationError

This silently degrades log/trace quality. Two safe fixes:

♻️ Option A — pass `code`/`status_code` through `super().__init__`
 class AuthenticationError(AuthError):
     def __init__(self, message: str, **kwargs):
-        super().__init__(message, **kwargs)
-        self.code = "AUTHENTICATION_ERROR"
-        self.status_code = 401
+        super().__init__(message, **kwargs)
+        self.code = "AUTHENTICATION_ERROR"
+        self.status_code = 401
+        self.args = (f"{self.code}: {self.message}",)
♻️ Option B (preferred) — make `OpenRAGError.__str__` compute lazily
 class OpenRAGError(Exception):
     def __init__(self, message, code="OPENRAG_ERROR", status_code=500, **kwargs):
         self.message = message
         self.code = code
         self.status_code = status_code
         self.extra = kwargs or {}
-        super().__init__(f"{self.code}: {self.message}")
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"{self.code}: {self.message}"

This keeps the current public string format while letting subclass mutations propagate consistently.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
class OpenRAGError(Exception):
"""Base class for all OpenRAG exceptions.
Preserves the existing API: message, code, status_code, to_dict().
"""
def __init__(
self,
message: str,
code: str = "OPENRAG_ERROR",
status_code: int = 500,
**kwargs,
):
self.message = message
self.code = code
self.status_code = status_code
self.extra = kwargs or {}
super().__init__(f"{self.code}: {self.message}")
class OpenRAGError(Exception):
"""Base class for all OpenRAG exceptions.
Preserves the existing API: message, code, status_code, to_dict().
"""
def __init__(
self,
message: str,
code: str = "OPENRAG_ERROR",
status_code: int = 500,
**kwargs,
):
self.message = message
self.code = code
self.status_code = status_code
self.extra = kwargs or {}
super().__init__(message)
def __str__(self) -> str:
return f"{self.code}: {self.message}"
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@openrag/core/utils/exceptions.py` around lines 55 - 72, OpenRAGError
currently freezes Exception.args by passing the formatted string to
super().__init__, causing subclass changes to self.code/self.status_code to be
lost in str(exc); fix by changing OpenRAGError.__init__ to call
super().__init__(message) (or no formatted arg) and add a __str__ method on
OpenRAGError that returns f"{self.code}: {self.message}" so stringification is
computed lazily and respects subclasses (affects OpenRAGError.__init__ and add
OpenRAGError.__str__).


def to_dict(self) -> dict:
return {
"detail": f"[{self.code}]: {self.message}",
"extra": self.extra,
}


# ---------------------------------------------------------------------------
# Config & registry
# ---------------------------------------------------------------------------

class ConfigError(OpenRAGError):
"""Configuration-related errors."""

def __init__(self, message: str, **kwargs):
super().__init__(message, code="CONFIG_ERROR", status_code=500, **kwargs)


class RegistryError(OpenRAGError):
"""Registry lookup errors (unknown component name)."""

def __init__(self, message: str, **kwargs):
super().__init__(message, code="REGISTRY_ERROR", status_code=500, **kwargs)


class PipelineError(OpenRAGError):
"""Pipeline execution errors."""

def __init__(self, message: str, **kwargs):
super().__init__(message, code="PIPELINE_ERROR", status_code=500, **kwargs)


# ---------------------------------------------------------------------------
# Auth
# ---------------------------------------------------------------------------

class AuthError(OpenRAGError):
"""Authentication / authorization errors."""

def __init__(self, message: str, **kwargs):
super().__init__(message, code="AUTH_ERROR", status_code=403, **kwargs)


class AuthenticationError(AuthError):
"""Missing or invalid credentials. Maps to HTTP 401."""

def __init__(self, message: str, **kwargs):
super().__init__(message, **kwargs)
self.code = "AUTHENTICATION_ERROR"
self.status_code = 401


# ---------------------------------------------------------------------------
# Validation
# ---------------------------------------------------------------------------

class ValidationError(OpenRAGError):
"""Input validation or business rule violation. Maps to HTTP 422."""

def __init__(self, message: str, **kwargs):
super().__init__(message, code="VALIDATION_ERROR", status_code=422, **kwargs)


# ---------------------------------------------------------------------------
# Not found
# ---------------------------------------------------------------------------

class NotFoundError(OpenRAGError):
"""Requested resource not found. Maps to HTTP 404."""

def __init__(self, message: str, code: str = "NOT_FOUND", **kwargs):
super().__init__(message, code=code, status_code=404, **kwargs)


class DocumentNotFoundError(NotFoundError):
def __init__(self, message: str, **kwargs):
super().__init__(message, code="DOCUMENT_NOT_FOUND", **kwargs)


class PartitionNotFoundError(NotFoundError):
def __init__(self, message: str, **kwargs):
super().__init__(message, code="PARTITION_NOT_FOUND", **kwargs)


class UserNotFoundError(NotFoundError):
def __init__(self, message: str, **kwargs):
super().__init__(message, code="USER_NOT_FOUND", **kwargs)


# ---------------------------------------------------------------------------
# Quota
# ---------------------------------------------------------------------------

class QuotaExceededError(OpenRAGError):
"""File quota exceeded. Maps to HTTP 429."""

def __init__(self, message: str, **kwargs):
super().__init__(message, code="QUOTA_EXCEEDED", status_code=429, **kwargs)


# ---------------------------------------------------------------------------
# Infrastructure — service availability
# ---------------------------------------------------------------------------

class ServiceUnavailableError(OpenRAGError):
"""External service unavailable after retry exhaustion. Maps to HTTP 503."""

def __init__(self, message: str, **kwargs):
super().__init__(message, code="SERVICE_UNAVAILABLE", status_code=503, **kwargs)


class CircuitBreakerOpenError(ServiceUnavailableError):
"""Circuit breaker is open. Maps to HTTP 503."""

def __init__(self, service_type: str, **kwargs):
self.service_type = service_type
super().__init__(
f"Circuit breaker open for {service_type} — service unavailable",
**kwargs,
)
self.code = "CIRCUIT_BREAKER_OPEN"

Comment on lines +194 to +201

ghost Apr 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

CircuitBreakerOpenError will crash if a caller passes code= via **kwargs.

ServiceUnavailableError.__init__ already forwards a hard-coded code="SERVICE_UNAVAILABLE" to OpenRAGError.__init__. If any caller (or raise_from/wrapper) passes code= or status_code= into CircuitBreakerOpenError(**kwargs), you get TypeError: got multiple values for keyword argument 'code'. Same latent risk exists for every subclass that forwards **kwargs through a parent that also injects code/status_code (e.g. AuthenticationError → AuthError forwards kwargs then AuthError adds code="AUTH_ERROR").

Consider popping code/status_code from kwargs in the leaf class before forwarding, or setting them only after super().__init__ (combined with the __str__ fix above).

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@openrag/core/utils/exceptions.py` around lines 188 - 195,
CircuitBreakerOpenError (and other leaf subclasses like AuthenticationError →
AuthError) can raise TypeError when callers pass code/status_code via **kwargs
because the subclass also injects a hard-coded code; to fix, remove any incoming
code and status_code from kwargs before calling the parent __init__ (e.g., pop
'code' and 'status_code' from kwargs in CircuitBreakerOpenError.__init__) or
alternatively call super().__init__(**kwargs) first and then set
self.code/self.status_code to the intended hard-coded values (apply the same
pattern to other subclasses such as AuthenticationError/AuthError and anywhere
raise_from/wrappers may forward kwargs).


# ---------------------------------------------------------------------------
# Inference
# ---------------------------------------------------------------------------

class InferenceError(OpenRAGError):
"""Base for all inference service failures. Maps to HTTP 503."""

def __init__(self, message: str, **kwargs):
super().__init__(message, code="INFERENCE_ERROR", status_code=503, **kwargs)


class LLMParsingError(InferenceError):
"""LLM returned invalid JSON. Maps to HTTP 502."""

def __init__(self, raw_response: str, parse_error: str | None = None, **kwargs):
self.raw_response = raw_response[:500]
self.parse_error = parse_error
super().__init__(
f"LLM returned invalid JSON: {self.raw_response[:100]}...",
**kwargs,
)
self.code = "LLM_PARSING_ERROR"
self.status_code = 502


class InferenceTimeoutError(InferenceError):
"""Inference request timed out. Maps to HTTP 504."""

def __init__(self, message: str, **kwargs):
super().__init__(message, **kwargs)
self.code = "INFERENCE_TIMEOUT"
self.status_code = 504


class InferenceConnectionError(InferenceError):
"""Cannot reach inference service. Maps to HTTP 503."""

def __init__(self, message: str, **kwargs):
super().__init__(message, **kwargs)
self.code = "INFERENCE_CONNECTION_ERROR"


# ---------------------------------------------------------------------------
# Storage
# ---------------------------------------------------------------------------

class StorageError(OpenRAGError):
"""Base for storage failures. Maps to HTTP 500."""

def __init__(self, message: str, **kwargs):
super().__init__(message, code="STORAGE_ERROR", status_code=500, **kwargs)


class MilvusError(StorageError):
"""Milvus-specific failures."""

def __init__(self, message: str, **kwargs):
super().__init__(message, **kwargs)
self.code = "MILVUS_ERROR"


class PostgresError(StorageError):
"""Postgres-specific failures."""

def __init__(self, message: str, **kwargs):
super().__init__(message, **kwargs)
self.code = "POSTGRES_ERROR"


# ---------------------------------------------------------------------------
# Embedding (preserves existing OpenRAG exception classes)
# ---------------------------------------------------------------------------

class EmbeddingError(OpenRAGError):
"""Base exception for all embedding-related errors."""

def __init__(self, message: str, code: str = "EMBEDDING_ERROR", status_code: int = 500, **kwargs):
super().__init__(message, code=code, status_code=status_code, **kwargs)


class EmbeddingAPIError(EmbeddingError):
"""API error with the embedding provider."""

def __init__(self, message: str, **kwargs):
super().__init__(message, code="EMBEDDING_API_ERROR", status_code=500, **kwargs)


class EmbeddingResponseError(EmbeddingError):
"""Invalid or unexpected response from embedding provider."""

def __init__(self, message: str, **kwargs):
super().__init__(message, code="EMBEDDING_RESPONSE_ERROR", status_code=422, **kwargs)


class UnexpectedEmbeddingError(EmbeddingError):
"""Unexpected error in embedding operations."""

def __init__(self, message: str, **kwargs):
super().__init__(message, code="EMBEDDING_UNEXPECTED_ERROR", status_code=500, **kwargs)


# ---------------------------------------------------------------------------
# Vector database (preserves existing OpenRAG exception classes)
# ---------------------------------------------------------------------------

class VDBError(OpenRAGError):
"""Base exception for all vector database-related errors."""

def __init__(self, message: str, code: str = "VDB_ERROR", status_code: int = 500, **kwargs):
super().__init__(message, code=code, status_code=status_code, **kwargs)


class VDBConnectionError(VDBError):
def __init__(self, message: str, **kwargs):
super().__init__(message, code="VDB_CONNECTION_ERROR", status_code=503, **kwargs)


class VDBCreateOrLoadCollectionError(VDBError):
def __init__(self, message: str, **kwargs):
super().__init__(message, code="VDB_COLLECTION_ERROR", status_code=422, **kwargs)


class VDBInsertError(VDBError):
def __init__(self, message: str, status_code: int = 422, **kwargs):
super().__init__(message, code="VDB_INSERT_ERROR", status_code=status_code, **kwargs)


class VDBFileIDAlreadyExistsError(VDBError):
def __init__(self, message: str, **kwargs):
super().__init__(message, code="VDB_FILE_ALREADY_EXISTS", status_code=409, **kwargs)


class VDBDeleteError(VDBError):
def __init__(self, message: str, status_code: int = 422, **kwargs):
super().__init__(message, code="VDB_DELETE_ERROR", status_code=status_code, **kwargs)


class VDBSearchError(VDBError):
def __init__(self, message: str, **kwargs):
super().__init__(message, code="VDB_SEARCH_ERROR", status_code=422, **kwargs)


class VDBPartitionNotFound(VDBError):
def __init__(self, message: str, **kwargs):
super().__init__(message, code="VDB_PARTITION_NOT_FOUND", status_code=404, **kwargs)


class VDBFileNotFoundError(VDBError):
def __init__(self, message: str, **kwargs):
super().__init__(message, code="VDB_FILE_NOT_FOUND", status_code=404, **kwargs)


class VDBUserNotFound(VDBError):
def __init__(self, message: str, **kwargs):
super().__init__(message, code="VDB_USER_NOT_FOUND", status_code=404, **kwargs)


class VDBMembershipNotFound(VDBError):
def __init__(self, message: str, **kwargs):
super().__init__(message, code="VDB_MEMBERSHIP_NOT_FOUND", status_code=404, **kwargs)


class VDBSchemaMigrationRequiredError(VDBError):
def __init__(self, message: str, **kwargs):
super().__init__(message, code="VDB_SCHEMA_MIGRATION_REQUIRED", status_code=503, **kwargs)


class UnexpectedVDBError(VDBError):
def __init__(self, message: str, **kwargs):
super().__init__(message, code="VDB_UNEXPECTED_ERROR", status_code=500, **kwargs)
Loading