Problem
The codebase uses generic Exception for all error cases:
raise Exception("Processing failed") # processor.py:291
raise Exception(f"finish reason: {finish_reason}") # processor.py:440
This makes it difficult to:
- Catch specific error types
- Provide meaningful error messages to users
- Debug issues in production
Proposed Solution
Create a custom exception hierarchy in src/pageindex/exceptions.py:
class PageIndexError(Exception):
"""Base exception for all PageIndex errors."""
pass
class DocumentParseError(PageIndexError):
"""Raised when document parsing fails."""
pass
class TOCExtractionError(PageIndexError):
"""Raised when TOC extraction fails."""
pass
class LLMResponseError(PageIndexError):
"""Raised when LLM returns invalid or unexpected response."""
pass
class ConfigurationError(PageIndexError):
"""Raised when configuration is invalid."""
pass
class ConversionError(PageIndexError):
"""Raised when document conversion fails."""
pass
Acceptance Criteria
Files to Modify
- Create
src/pageindex/exceptions.py
src/pageindex/pdf/processor.py
src/pageindex/pdf/toc.py
src/pageindex/markdown/processor.py
src/pageindex/batch.py
src/pageindex/llm.py
Problem
The codebase uses generic
Exceptionfor all error cases:This makes it difficult to:
Proposed Solution
Create a custom exception hierarchy in
src/pageindex/exceptions.py:Acceptance Criteria
exceptions.pywith exception hierarchyraise Exception(...)with specific exception typesexcept Exceptionwith specific catches where appropriateFiles to Modify
src/pageindex/exceptions.pysrc/pageindex/pdf/processor.pysrc/pageindex/pdf/toc.pysrc/pageindex/markdown/processor.pysrc/pageindex/batch.pysrc/pageindex/llm.py