agent_search_gateway.errors

 1"""Stable gateway error taxonomy and user-facing constants."""
 2
 3from enum import StrEnum
 4
 5
 6class ErrorCode(StrEnum):
 7    BAD_REQUEST = "bad_request"
 8    EMPTY_QUERY = "empty_query"
 9    INVALID_URL = "invalid_url"
10    URL_NOT_ADMITTED = "url_not_admitted"
11    NO_KEYWORD_SEARCH_PROVIDERS = "no_keyword_search_providers"
12    NO_LLM_SEARCH_PROVIDERS = "no_llm_search_providers"
13    NO_URL_FETCH_PROVIDERS = "no_url_fetch_providers"
14    NO_ACADEMIC_SEARCH_PROVIDERS = "no_academic_search_providers"
15    ALL_PROVIDERS_FAILED = "all_providers_failed"
16    LLM_STAGE_FAILED = "llm_stage_failed"
17    PROTOCOL_ERROR = "protocol_error"
18    CONFIG_ERROR = "config_error"
19    DAEMON_SHUTTING_DOWN = "daemon_shutting_down"
20
21
22UNAVAILABLE_MESSAGE = (
23    "URL unavailable: it may have failed content validation or been flagged as unsafe."
24)
25
26
27class GatewayError(Exception):
28    """Base typed failure crossing orchestration boundaries."""
29
30    def __init__(
31        self,
32        code: ErrorCode,
33        message: str,
34        *,
35        reason: str | None = None,
36    ) -> None:
37        super().__init__(message)
38        self.code = code
39        self.message = message
40        self.reason = reason
41
42
43class InputFailure(GatewayError):
44    """Invalid user input or request-state combination."""
45
46
47class ExecutionFailure(GatewayError):
48    """Dependency or execution-path failure."""
49
50
51class ProtocolFailure(ExecutionFailure):
52    """Malformed local or provider protocol data."""
53
54
55class ConfigFailure(GatewayError):
56    """Invalid daemon startup configuration."""
57
58
59class ParserFailure(ExecutionFailure):
60    """Restricted parser rejected an execution result."""
61
62    def __init__(self, message: str) -> None:
63        super().__init__(ErrorCode.PROTOCOL_ERROR, message)
64
65
66class DaemonUnavailable(Exception):
67    """The local daemon socket is missing or refusing connections."""