bayesmith.artifacts.results

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

Module contract

The five answers, and the four shapes a posterior can take (§0.5).

A Result is what an execution produced, in the form a later reader can
believe: every array is a :class:``bayesmith.artifacts.base.NamedArray`` copied
in and handed back read-only, every reference to another artifact carries the
revision and kind it points at, and nothing here holds a runtime object.

**A posterior is not one thing.** §0.5 fixes four representations and keeps
them apart rather than flattening them into "draws plus optional weights": iid
exact draws, importance-weighted draws with their diagnostics, a closed-form
family, and a fitted conditional estimator that is only a reference. A weighted
sample whose weights were dropped is a WRONG unweighted sample rather than a
lossy one, which is precisely why the union is tagged by class.

**The mapping from task to result is a bijection, and it lives here.**
``PRIMARY_RESULT_BY_TASK`` is in this module, not in ``tasks``, because the
dependency runs ``tasks ← results`` and a constant placed for tidiness in the
lower module would close a cycle. It is checked in both directions: five keys
that cover ``TaskKind`` AND five distinct values that cover ``ResultKind``, the
pair of checks that would have caught the 5:4 mapping this protocol shipped
once already.

**Unavailable is None, and the field stays.** A diagnostic that was not
computed is ``None`` rather than NaN, and the field is not dropped -- the shape
of a Result is part of the schema, so a reader can tell "not computed" from
"this kind of result has no such number". The single exception is
``log_evidence``, which must be finite: an evidence result whose evidence is
missing is not an evidence result.

Layering: ``_codec ← identity ← base ← tasks ← results`` (§0.1).

ResultKind

Defined in bayesmith.artifacts.results, line 92.

class ResultKind(StrEnum)

The five answers of §0 ruling 1, one per task kind.

POSTERIOR = 'posterior'
EVIDENCE = 'evidence'
PREDICTIVE = 'predictive'
POINT_ESTIMATE = 'point_estimate'
SIMULATION = 'simulation'

LogDensityAvailability

Defined in bayesmith.artifacts.results, line 103.

class LogDensityAvailability(StrEnum)

How much of the log density this result can answer for (§0.5).

Three levels rather than a bool, because "I can score the joint" and "I can
score each observation" are different capabilities and only the second
supports pointwise cross-validation.

NONE = 'none'
JOINT = 'joint'
POINTWISE = 'pointwise'

UncertaintyKind

Defined in bayesmith.artifacts.results, line 117.

class UncertaintyKind(StrEnum)

Which of the three an uncertainty record holds (§0.5).

A covariance and a precision are inverses of one another and a standard
error is neither; a single unlabelled matrix would be read as whichever the
consumer expected, and would be wrong silently rather than loudly.

COVARIANCE = 'covariance'
PRECISION = 'precision'
STANDARD_ERROR = 'standard_error'

UncertaintyRecord

Defined in bayesmith.artifacts.results, line 424.

class UncertaintyRecord
kind: UncertaintyKind
arrays: tuple[NamedArray, ...]

A point estimate's uncertainty, labelled with what it actually is.

DrawsPosterior

Defined in bayesmith.artifacts.results, line 236.

class DrawsPosterior
draws: tuple[NamedArray, ...]
chain_shape: tuple[int, int] | None = None
method: str = ''

Equally weighted draws, with the chain structure that produced them.

``chain_shape`` is ``None`` for iid draws and ``(chains, per_chain)`` for a
sampler that ran chains. ``None`` is not ``(1, n)``: the first says the
draws have no chain structure to diagnose, the second says a diagnostic
over one chain is possible, and R-hat means different things to each.

WeightedDrawsPosterior

Defined in bayesmith.artifacts.results, line 277.

class WeightedDrawsPosterior
draws: tuple[NamedArray, ...]
log_weights: NamedArray
ess: float | None = None
khat: float | None = None
unreliable: bool = False
method: str = ''

Importance-weighted draws, with the diagnostics that say whether to
believe them.

``unreliable`` is a stored verdict rather than something a reader
recomputes from ``khat``: the threshold that produced it belongs to the run
that took it, and a consumer applying today's threshold to yesterday's khat
would silently re-judge a result nobody re-ran.

AnalyticPosterior

Defined in bayesmith.artifacts.results, line 319.

class AnalyticPosterior
family: str
parameters: tuple[NamedArray, ...]
moments: tuple[NamedArray, ...] = ()

A closed-form posterior: the family and its parameters, not a sample.

The protocol keeps this arm for a genuinely analytic posterior and refuses
the temptation to fill it from draws (§0.5). Sample moments in the
``parameters`` of a "gaussian" would be a claim of exactness that nothing
took.

FittedConditionalPosterior

Defined in bayesmith.artifacts.results, line 344.

class FittedConditionalPosterior
estimator_ref: ArtifactRef
simulation_bank_ref: ArtifactRef | None = None
training_run_id: str | None = None
validation_report_refs: tuple[ArtifactRef, ...] = ()

An amortized posterior, as REFERENCES to what was fitted (§0 ruling 4).

No estimator object, no callable, no weights blob: the estimator and the
simulation bank it was trained on are artifacts of their own, and this arm
records which ones plus the run that fitted them. R1 freezes the schema and
fits nothing.

PosteriorRepresentation

Defined in bayesmith.artifacts.results, line 367.

PosteriorRepresentation = DrawsPosterior | WeightedDrawsPosterior | AnalyticPosterior | FittedConditionalPosterior

POSTERIOR_REPRESENTATIONS

Defined in bayesmith.artifacts.results, line 373.

POSTERIOR_REPRESENTATIONS: tuple[type, ...] = (DrawsPosterior, WeightedDrawsPosterior, AnalyticPosterior, FittedConditionalPosterior)

EvidenceComponent

Defined in bayesmith.artifacts.results, line 395.

class EvidenceComponent
name: str
log_value: float
standard_error: float | None = None
method: str = ''
artifact_refs: tuple[ArtifactRef, ...] = ()

One additive term of a log evidence, and how it was obtained (§0.5).

The split between exact and residual components is what makes a hybrid
evidence auditable: a number that is closed-form and a number that was
sampled carry different warrants, and a single total would hide which part
the error bar belongs to.

PosteriorResult

Defined in bayesmith.artifacts.results, line 442.

class PosteriorResult
meta: ArtifactMeta
run: RunRecord
representation: PosteriorRepresentation
latent_names: tuple[str, ...]
eliminated_latents: tuple[str, ...] = ()
reconstruction_ref: ArtifactRef | None = None
log_density_availability: LogDensityAvailability = LogDensityAvailability.NONE
pointwise_log_likelihood: NamedArray | None = None
predictive_ready: bool = False
report_refs: tuple[ArtifactRef, ...] = ()

A posterior over the model's latents, in one of four representations.

``latent_names`` and ``eliminated_latents`` are disjoint by construction:
an eliminated latent is one the plan integrated out, so it is exactly the
set that has no draws here. ``reconstruction_ref`` points at what can put
them back, and may only be present when something was eliminated.

EvidenceResult

Defined in bayesmith.artifacts.results, line 526.

class EvidenceResult
meta: ArtifactMeta
run: RunRecord
log_evidence: float
standard_error: float | None = None
posterior_representation: PosteriorRepresentation | None = None
normalization_audit_refs: tuple[ArtifactRef, ...] = ()
exact_components: tuple[EvidenceComponent, ...] = ()
residual_component: EvidenceComponent | None = None
repeat_result_refs: tuple[ArtifactRef, ...] = ()
consistency_report_ref: ArtifactRef | None = None

A log marginal likelihood, its error bar, and its decomposition.

PredictiveResult

Defined in bayesmith.artifacts.results, line 575.

class PredictiveResult
meta: ArtifactMeta
run: RunRecord
source_posterior_ref: ArtifactRef
conditioning_data: Fingerprint | None = None
prediction_design: Fingerprint | None = None
conditioned_sites: tuple[str, ...] = ()
latent_draws: tuple[NamedArray, ...] = ()
replicated_draws: tuple[NamedArray, ...] = ()
pointwise_log_density: NamedArray | None = None
observation_unit: str | None = None
grouping: str | None = None
report_refs: tuple[ArtifactRef, ...] = ()

Draws pushed through the model onto observations, held-out or replicated.

Latent and replicated draws share ONE draw axis, because they are two views
of the same posterior sample; a result whose halves disagreed about how
many draws there were could not be zipped back together.

PointEstimateResult

Defined in bayesmith.artifacts.results, line 635.

class PointEstimateResult
meta: ArtifactMeta
run: RunRecord
estimand: Estimand
values: tuple[NamedArray, ...]
objective: float | None = None
uncertainty: UncertaintyRecord | None = None
gradient_norm: float | None = None
residual: float | None = None
iterations: int | None = None
local_only: bool = False
report_refs: tuple[ArtifactRef, ...] = ()

One point of the posterior, with what the optimiser or solver knows.

``local_only`` is the honest field: an optimiser reports a stationary
point, and calling it THE MAP would be a global claim nothing verified.

SimulationResult

Defined in bayesmith.artifacts.results, line 678.

class SimulationResult
meta: ArtifactMeta
run: RunRecord
parameter_source: ParameterSource
parameters: tuple[NamedArray, ...] = ()
latent_draws: tuple[NamedArray, ...] = ()
observation_draws: tuple[NamedArray, ...] = ()
prediction_design: Fingerprint | None = None
report_refs: tuple[ArtifactRef, ...] = ()

Forward draws from a parameter source. No conditioning, no verdict.

Result

Defined in bayesmith.artifacts.results, line 716.

Result = PosteriorResult | EvidenceResult | PredictiveResult | PointEstimateResult | SimulationResult

RESULT_CLASSES

Defined in bayesmith.artifacts.results, line 725.

RESULT_CLASSES: dict[ResultKind, type] = {ResultKind.POSTERIOR: PosteriorResult, ResultKind.EVIDENCE: EvidenceResult, ResultKind.PREDICTIVE: PredictiveResult, ResultKind.POINT_ESTIMATE: PointEstimateResult, ResultKind.SIMULATION: SimulationResult}

result_kind

Defined in bayesmith.artifacts.results, line 738.

result_kind(result: Result) -> ResultKind

Which of the five ``result`` is, by exact type.

PRIMARY_RESULT_BY_TASK

Defined in bayesmith.artifacts.results, line 752.

PRIMARY_RESULT_BY_TASK = MappingProxyType({TaskKind.POSTERIOR: ResultKind.POSTERIOR, TaskKind.EVIDENCE: ResultKind.EVIDENCE, TaskKind.PREDICTIVE: ResultKind.PREDICTIVE, TaskKind.POINT_ESTIMATE: ResultKind.POINT_ESTIMATE, TaskKind.SIMULATION: ResultKind.SIMULATION})