kontextual-engine/src/kontextual_engine/errors.py

"""Shared diagnostics and structured errors."""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any


@dataclass(frozen=True)
class Diagnostic:
    """A structured finding emitted by engine operations."""

    severity: str
    code: str
    message: str
    details: dict[str, Any] = field(default_factory=dict)

    def to_dict(self) -> dict[str, Any]:
        return {
            "severity": self.severity,
            "code": self.code,
            "message": self.message,
            "details": dict(self.details),
        }


class KontextualError(Exception):
    """Base class for explicit engine failures."""

    code = "kontextual.error"

    def __init__(self, message: str, *, details: dict[str, Any] | None = None) -> None:
        super().__init__(message)
        self.details = details or {}

    def diagnostic(self, *, severity: str = "error") -> Diagnostic:
        return Diagnostic(
            severity=severity,
            code=self.code,
            message=str(self),
            details=dict(self.details),
        )


class NotFoundError(KontextualError):
    code = "kontextual.not_found"


class DuplicateResourceError(KontextualError):
    code = "kontextual.duplicate"


class ValidationError(KontextualError):
    code = "kontextual.validation"


class AuthorizationError(KontextualError):
    code = "kontextual.authorization"


class AdapterUnavailableError(KontextualError):
    code = "kontextual.adapter_unavailable"