errors.py

"""Typed failure modes for the agentic pipeline.

Every specialist tool raises one of these rather than a bare Exception, so the
controller can turn a failure into a structured execution-trace entry instead of
a stack trace. Each carries a machine-readable `code` used in API responses.
"""
from __future__ import annotations


class SatQueryError(Exception):
    """Base class for all recoverable SatQuery failures."""

    code = "satquery_error"
    http_status = 400

    def __init__(self, message: str, **context: object) -> None:
        super().__init__(message)
        self.message = message
        self.context = context

    def to_dict(self) -> dict:
        return {"code": self.code, "message": self.message, "context": self.context}


class ImageNotFoundError(SatQueryError):
    code = "image_not_found"
    http_status = 404


class UnsupportedFormatError(SatQueryError):
    code = "unsupported_format"
    http_status = 415


class InvalidImageError(SatQueryError):
    """File exists and has a known extension but could not be decoded."""

    code = "invalid_image"
    http_status = 422


class EmptyQueryError(SatQueryError):
    code = "empty_query"
    http_status = 422


class ModelUnavailableError(SatQueryError):
    """Backend weights or remote model server could not be reached."""

    code = "model_unavailable"
    http_status = 503


class NotCoRegisteredError(SatQueryError):
    """Two images of a pair are not aligned well enough for joint analysis."""

    code = "not_co_registered"
    http_status = 422


class TooFewImagesError(SatQueryError):
    """The task needs more images than were supplied (or too many)."""

    code = "too_few_images"
    http_status = 422


class ModalityMismatchError(SatQueryError):
    """Supplied sensor modalities do not match what the task requires."""

    code = "modality_mismatch"
    http_status = 422


class UnregisteredFormatError(SatQueryError):
    """File format carries no georeferencing, so results are not map-locatable.

    PNG/JPEG inputs are accepted in benchmark mode but flagged: the answer is
    still valid, its coordinates are not.
    """

    code = "unregistered_format"
    http_status = 422


class CorruptImageError(SatQueryError):
    """File is present and typed correctly but cannot be decoded or is empty."""

    code = "corrupt_image"
    http_status = 422