Skip to content

geno_lewm.errors

errors

GenoLeWM exception hierarchy and error-code registry.

This module is the single source of truth for the runtime error model defined in docs/spec/04-error-model.md and RFC-0012. Every other subsystem raises typed exceptions from this hierarchy.

Discipline (summary; see the spec for the full table):

  • Caller-supplied invalid data -> InputError family
  • Misconfiguration / missing fields -> ConfigError family
  • Capacity, IO, network -> ResourceError family
  • Training-loop instability -> TrainingError family
  • Eval harness failures -> EvalError family
  • Export / runtime backend failures -> DeployError family
  • Receipt/hash consistency failure -> ProvenanceError family
  • Bugs we caught -> InternalError family

GenoLeWMError

GenoLeWMError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: Exception

Root of the GenoLeWM exception hierarchy.

Every typed exception in this package inherits from GenoLeWMError. Subclasses must set a code class attribute that matches an entry in :data:ERROR_CODES.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

to_dict

to_dict() -> dict[str, Any]

Return the structured payload as a plain dict.

The output is JSON-serializable provided details values are JSON-native. Keys mirror the structured-log error event so the CLI dispatcher and observability layer can pass it through without translation.

Source code in geno_lewm/errors.py
def to_dict(self) -> dict[str, Any]:
    """Return the structured payload as a plain dict.

    The output is JSON-serializable provided ``details`` values are
    JSON-native. Keys mirror the structured-log ``error`` event so
    the CLI dispatcher and observability layer can pass it through
    without translation.
    """
    return {
        "code": self.code,
        "message": self.message,
        "details": self.details,
        "remediation": self.remediation,
    }

to_json

to_json() -> str

Return the structured payload as a JSON string.

Adds a UTC ts field so log sinks receive a self-contained record.

Source code in geno_lewm/errors.py
def to_json(self) -> str:
    """Return the structured payload as a JSON string.

    Adds a UTC ``ts`` field so log sinks receive a self-contained
    record.
    """
    payload = self.to_dict()
    payload["ts"] = datetime.now(tz=timezone.utc).isoformat()
    return json.dumps(payload, sort_keys=True, default=str)

ConfigError

ConfigError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: GenoLeWMError

Configuration is malformed or incompatible.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

SchemaCompatError

SchemaCompatError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: ConfigError

An on-disk artifact's schema MAJOR version is incompatible.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

MissingConfigError

MissingConfigError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: ConfigError

A required configuration field is absent.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

UnknownTopLevelKeyError

UnknownTopLevelKeyError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: ConfigError

A configuration payload contained a top-level key not in the schema.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

InputError

InputError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: GenoLeWMError

Caller-supplied input violates a documented invariant.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

InvalidEditError

InvalidEditError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: InputError

An EditSpec fails one of its constructor invariants.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

UnsupportedEditError

UnsupportedEditError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: InputError

An edit's type or length is outside the v1 scope (RFC-0003).

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

WindowMismatchError

WindowMismatchError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: InputError

Window reference bases do not match EditSpec.ref at rel_pos.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

OverlappingEditsError

OverlappingEditsError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: InputError

Two or more edits in a haplotype overlap in genomic coordinates.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

OutOfWindowError

OutOfWindowError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: InputError

An edit's rel_pos falls outside the encoder window.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

VcfParseError

VcfParseError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: InputError

A VCF or FASTA input is malformed.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

ResourceError

ResourceError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: GenoLeWMError

Capacity, IO, or network failure.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

CacheCorruptError

CacheCorruptError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: ResourceError

A cache shard failed an integrity check.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

DiskFullError

DiskFullError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: ResourceError

Storage was exhausted during a write.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

OutOfMemoryError

OutOfMemoryError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: ResourceError

Re-raise of CUDA / host OOM with attached GenoLeWM context.

Intentionally shadows the builtin OutOfMemoryError only inside this module's namespace; downstream code that needs the builtin can use builtins.OutOfMemoryError.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

ModelNotFoundError

ModelNotFoundError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: ResourceError

A model checkpoint is missing locally and cannot be downloaded.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

RuntimeSetupError

RuntimeSetupError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: ResourceError

First-run network setup step (download / verification) failed.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

NetworkCallProhibitedError

NetworkCallProhibitedError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: ResourceError

A post-setup network call was attempted under fail-closed policy.

See RFC-0010 §3.7 ("on-device fail-closed").

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

TrainingError

TrainingError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: GenoLeWMError

Training-loop-specific failure.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

CollapseDetectedError

CollapseDetectedError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: TrainingError

A representation-collapse alert tripped (RFC-0005).

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

NaNLossError

NaNLossError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: TrainingError

Loss became NaN or Inf.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

DataLoaderError

DataLoaderError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: TrainingError

Data pipeline raised an exception the trainer cannot recover from.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

EvalError

EvalError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: GenoLeWMError

Evaluation harness failure.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

EvalDatasetError

EvalDatasetError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: EvalError

A benchmark file or dataset could not be loaded.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

EvalRegressionError

EvalRegressionError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: EvalError

A smoke-eval gate threshold was breached.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

DeployError

DeployError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: GenoLeWMError

Export or runtime backend failure.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

ExportFormatError

ExportFormatError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: DeployError

Conversion to ONNX, Core ML, or GGUF failed.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

QuantizationError

QuantizationError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: DeployError

int8 or int4 calibration failed.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

BackendUnsupportedError

BackendUnsupportedError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: DeployError

Requested runtime backend is not available on the host.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

ProvenanceError

ProvenanceError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: GenoLeWMError

Receipt or artifact-provenance failure (RFC-0011).

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

ManifestHashMismatchError

ManifestHashMismatchError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: ProvenanceError

Recomputed manifest hash does not match the stated model_id.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

InputCommitmentMismatchError

InputCommitmentMismatchError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: ProvenanceError

Recomputed input commitment does not match the receipt.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

OutputCommitmentMismatchError

OutputCommitmentMismatchError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: ProvenanceError

Recomputed output bytes do not match the receipt.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

ProvenanceKindUnsupportedError

ProvenanceKindUnsupportedError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: ProvenanceError

Verifier does not understand the receipt provenance kind.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

ReceiptSchemaError

ReceiptSchemaError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: ProvenanceError

Receipt JSON failed schema validation.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

InternalError

InternalError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: GenoLeWMError

A bug we caught; should never surface to end users.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

InvariantViolation

InvariantViolation(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: InternalError

A runtime invariant marked INV-* was breached.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

UnreachableError

UnreachableError(message: str = '', *, details: Mapping[str, Any] | None = None, remediation: str | None = None)

Bases: InternalError

Control flow reached a branch marked unreachable.

Source code in geno_lewm/errors.py
def __init__(
    self,
    message: str = "",
    *,
    details: Mapping[str, Any] | None = None,
    remediation: str | None = None,
) -> None:
    super().__init__(message)
    self.message = message
    self.details: dict[str, Any] = dict(details) if details else {}
    self.remediation = remediation

ErrorCodeEntry

ErrorCodeEntry(code: str, exception_class: type[GenoLeWMError], summary: str)

A single immutable row in the error-code registry.

Source code in geno_lewm/errors.py
def __init__(self, code: str, exception_class: type[GenoLeWMError], summary: str) -> None:
    self.code = code
    self.exception_class = exception_class
    self.summary = summary

exit_code_for

exit_code_for(exc: BaseException) -> int

Return the CLI exit code for exc.

Used by geno_lewm.cli._dispatch. Non-GenoLeWM exceptions map to exit code 1 ("uncategorized failure"); KeyboardInterrupt maps to 130.

Source code in geno_lewm/errors.py
def exit_code_for(exc: BaseException) -> int:
    """Return the CLI exit code for ``exc``.

    Used by ``geno_lewm.cli._dispatch``. Non-GenoLeWM exceptions map to
    exit code 1 ("uncategorized failure"); ``KeyboardInterrupt`` maps to
    130.
    """
    if isinstance(exc, KeyboardInterrupt):
        return 130
    if not isinstance(exc, GenoLeWMError):
        return 1
    for family, code in _EXIT_CODE_BY_FAMILY:
        if isinstance(exc, family):
            return code
    return 1