bayesmith.artifacts.refusal

Source-derived signatures and contracts. See the reference index for coverage and conventions.

Module contract

Structured refusal: why a route does not apply, and what to do instead.

§0 ruling 3 in code. A refusal is a JUDGEMENT -- the premise this route needs
is false -- and it is carried as data: a stable ``failed_premise`` code, a
non-empty tuple of :class:``Finding`` with the numbers that were measured, a
:class:``ScopeRef`` saying what it is about, and a non-empty tuple of
:class:``Remedy`` saying where to go. The human messages explain; nothing reads
them.

**The field is called ``grounds`` and never ``evidence``.** Frozen by §0 ruling
3, and not a matter of taste: this package computes marginal likelihoods, and
"evidence" is already the name of a number here. A refusal field with that
name would collide with the quantity in the next module along, in a codebase
whose sibling repository has to translate one refusal into the other.

**A refusal is not an exception wearing a schema.** A malformed Graph, a
programming error, an exhausted device: those stay exceptions. What becomes a
Refusal is the statistical case -- the likelihood is not Gaussian, the operator
is not affine, the condition number is past what the tolerance allows.

**Both lists are non-empty.** No grounds is a verdict with nothing behind it;
no remedies is a dead end. Each is refused where the caller who could still
supply them is standing.

Layering: ``base`` and ``tasks`` (§0.1). A refusal holds the whole Task it
refused, because "which question was this an answer to" is the first thing a
consumer asks and a task id would send them looking.

ScopeKind ScopeRef Finding Remedy Conservatism FallbackOption Refusal CAPABILITY_UNAVAILABLE_R1 PREMISES

ScopeKind

Defined in bayesmith.artifacts.refusal, line 174.

class ScopeKind(StrEnum)

What a finding or a refusal is ABOUT.

Kept small and structural: these are the things this package can name and
a consumer can look up. A free-text scope would be a second message field.

MODEL = 'model'
NODE = 'node'
PARAMETER = 'parameter'
PLATE = 'plate'
BLOCK = 'block'
DATA = 'data'
TASK = 'task'
BACKEND = 'backend'

ScopeRef

Defined in bayesmith.artifacts.refusal, line 193.

class ScopeRef
kind: ScopeKind
name: str

One thing, named by kind and by name.

Finding

Defined in bayesmith.artifacts.refusal, line 206.

class Finding
code: str
message: str
observed: object = None
expected: object = None
artifact_refs: tuple[ArtifactRef, ...] = ()

One measured reason, with the numbers that produced it.

``observed`` and ``expected`` are the pair a consumer compares: what was
measured, and what the premise required. They are canonical values -- a
scalar or a tuple of them -- so they survive the codec and cannot become a
runtime handle. G11's lesson is exactly this class: the failing path must
return what the passing path measured, because a number rendered into a
sentence is a number nobody downstream can use.

Remedy

Defined in bayesmith.artifacts.refusal, line 233.

class Remedy
action: str
message: str
parameters: tuple[tuple[str, object], ...] = ()

Somewhere to go: an action code, an explanation, and its arguments.

``parameters`` is sorted and key-unique like every other option table here,
so "the same remedy" is one value however the caller spelled it.

Conservatism

Defined in bayesmith.artifacts.refusal, line 255.

class Conservatism(StrEnum)

How a fallback compares to the route that refused.

Named rather than assumed. "We fell back" reads as "we were careful", and
sometimes the offered route is the cheaper, weaker one -- a caller
consenting to an automatic fallback needs to know which of those they are
consenting to.

EQUIVALENT = 'equivalent'
MORE_CONSERVATIVE = 'more_conservative'
LESS_CONSERVATIVE = 'less_conservative'

FallbackOption

Defined in bayesmith.artifacts.refusal, line 271.

class FallbackOption
task_kind: TaskKind
backend: str
conservatism: Conservatism = Conservatism.EQUIVALENT
automatic: bool = False

A route the caller could take instead, and whether it would be automatic.

Refusal

Defined in bayesmith.artifacts.refusal, line 289.

class Refusal
meta: ArtifactMeta
task: Task
failed_premise: str
grounds: tuple[Finding, ...]
scope: ScopeRef
remedies: tuple[Remedy, ...]
fallback: FallbackOption | None = None

What is returned when a task cannot be answered as asked (§0 ruling 1).

It stands in for the artifact that did not happen -- a plan that could not
be compiled, or a result that could not be produced -- so its envelope
carries that kind. It is never filed as an evaluation report: a report is a
judgement ABOUT an artifact, and a refusal is the absence of one.

CAPABILITY_UNAVAILABLE_R1

Defined in bayesmith.artifacts.refusal, line 66.

CAPABILITY_UNAVAILABLE_R1: str = 'capability_unavailable_r1'

PREMISES

Defined in bayesmith.artifacts.refusal, line 93.

PREMISES: frozenset[str] = frozenset({CAPABILITY_UNAVAILABLE_R1, 'backend_supported', 'model_source_identified', 'task_options_recognised', 'gaussian_likelihood', 'affine_prediction', 'log_linear_route', 'whole_graph_exact_solve', 'local_mode_certified', 'graph_has_latents', 'named_latents_declared', 'posterior_data_mismatch', 'predictive_noise_unsupported', 'evidence_prior_proper', 'evidence_prior_normalised', 'evidence_prior_undeclared', 'evidence_residual_integral_required', 'evidence_requires_x64', 'evidence_residual_method_unsupported', 'evidence_conditional_prior_proper'})