src/analyzer/utils/errors.py

"""
Standardized exceptions for the Grant Analyzer system.

Exception Hierarchy:
    GrantAnalyzerError (base)
    ├── DataLoadError          # File I/O, parsing
    ├── ValidationError        # Input validation
    ├── SearchError            # Index/search issues
    ├── LLMError              # API/LLM failures
    └── ConfigError           # Configuration problems
"""

class GrantAnalyzerError(Exception):
    """
    Base exception for all analyzer errors.

    All custom exceptions inherit from this so callers can catch
    all analyzer-specific errors with a single except clause.
    """
    pass


class DataLoadError(GrantAnalyzerError):
    """
    Error loading or parsing grant/supporting data.

    Examples:
        - JSON file not found
        - Malformed JSON
        - Missing required fields
        - Excel read failure
    """
    pass


class ValidationError(GrantAnalyzerError):
    """
    User input validation failure.

    Examples:
        - Invalid grant ID format
        - Empty search query
        - URL not in allowlist
        - Negative funding amount
    """
    pass


class SearchError(GrantAnalyzerError):
    """
    Search or index operation failure.

    Examples:
        - Index file corrupt
        - Index version mismatch
        - Search timeout
        - Too many results
    """
    pass


class LLMError(GrantAnalyzerError):
    """
    LLM API call failure.

    Examples:
        - API key invalid
        - Rate limit exceeded
        - Timeout
        - Model not found
        - Response parsing error
    """
    pass


class ConfigError(GrantAnalyzerError):
    """
    Configuration error.

    Examples:
        - Missing required env var
        - Invalid provider name
        - Conflicting settings
    """
    pass


# Convenience re-exports
__all__ = [
    "GrantAnalyzerError",
    "DataLoadError",
    "ValidationError",
    "SearchError",
    "LLMError",
    "ConfigError",
]