bayesmith.artifacts.reports
Source-derived signatures and contracts. See the reference index for coverage and conventions.
Module contract
What compilation decided, and what a judgement about a result says. Three records with one purpose: a plan that cannot be read back is a black box that happened to run, and a verdict that cannot be read back is an opinion. **An analysis report is an interpretation, never a copy of the graph.** It holds a :class:``bayesmith.artifacts.identity.ModelRef``, the graph's structure fingerprint and structured findings. §0 ruling 4 is nearest to being broken here, because this record is MADE by reading a Graph -- so it is the one that must hold none of it. **A plan record is a schedule.** Blocks keep their declared order, because that order is what will run; a parameter belongs to exactly one block, because two blocks claiming it is a schedule with no answer to which draws it. The ``premises`` it lists are the codes a :class:``bayesmith.artifacts.refusal.Refusal`` names in ``failed_premise`` when one of them turns out to be false -- one vocabulary, both directions. That vocabulary is :data:`bayesmith.artifacts.refusal.PREMISES`, which is not enforced HERE because a plan record is also read by consumers whose premises this package has never heard of; what holds bayesmith's own plans and refusals to it is ``tests/dispatch/test_task_protocol.py``, so the claim above is checked rather than merely stated. **An evaluation report has two axes.** §0 ruling 7: whether the check applied and what it concluded are different questions, so they are different enums. Which combinations of the two are legal, and how several reports aggregate into one gate verdict, are pinned in :mod:``bayesmith.artifacts.gates`` -- one home for one decision. Layering: ``base``, ``identity`` and ``refusal`` (§0.1). The code validators are refusal's, since that module is where "a code, not prose" is decided.
AnalysisFinding AnalysisReport PlanBlockRecord InferencePlanRecord Applicability Conclusion EvaluationReport
AnalysisFinding
Defined in bayesmith.artifacts.reports, line 101.
class AnalysisFinding
code: str
conclusion: str
scope: ScopeRef
measurements: tuple[tuple[str, object], ...] = ()
grounds: tuple[str, ...] = ()One thing compilation concluded about the graph, and what it measured. ``grounds`` is a tuple of reason CODES rather than of nested findings: at compile time the support for a conclusion is a set of checks that passed, and naming them keeps the record flat enough to read. It is the same idea as a refusal's ``grounds`` -- what stands behind the claim, structured -- which is why it carries the same name.
AnalysisReport
Defined in bayesmith.artifacts.reports, line 138.
class AnalysisReport
meta: ArtifactMeta
model_ref: ModelRef
graph_fingerprint: Fingerprint
findings: tuple[AnalysisFinding, ...] = ()
candidate_routes: tuple[str, ...] = ()Compile-time reading of a graph: what it is, and what could run on it. ``candidate_routes`` is a PREFERENCE order, so it is neither sorted nor deduplicated into a set -- reordering it would rerank the routes, and a repeated route would make one option look like two.
PlanBlockRecord
Defined in bayesmith.artifacts.reports, line 169.
class PlanBlockRecord
names: tuple[str, ...]
method: str
reason_codes: tuple[str, ...] = ()
kappa: float | None = None
tolerance: float | None = None
approximation: ApproximationRecord | None = NoneOne block of the schedule: which parameters, by which method, and why. ``kappa`` and ``tolerance`` are the numbers that justify the method where it has them, and ``None`` where the method has no such knob -- an exact elimination has no tolerance to report, and reporting 0 would say it had one and met it perfectly.
InferencePlanRecord
Defined in bayesmith.artifacts.reports, line 207.
class InferencePlanRecord
meta: ArtifactMeta
task_id: str
model_ref: ModelRef
analysis_report_ref: ArtifactRef | None = None
blocks: tuple[PlanBlockRecord, ...] = ()
exact_elimination: tuple[str, ...] = ()
residual_parameters: tuple[str, ...] = ()
backend: str = 'auto'
premises: tuple[str, ...] = ()
budget: ComputeBudget = _NO_BUDGET
quality_gate: str | None = None
fallback_policy: str | None = NoneThe compiled plan, as a record: what will run, on what, under what. The analysis report it was built from is a PARENT, not merely a field. §0.3 retires a plan through the inputs it was made from, so a plan whose reading of the graph is not in its lineage would outlive a change to that reading.
Applicability
Defined in bayesmith.artifacts.reports, line 276.
class Applicability(StrEnum)Whether the check could say anything about this subject (§0 ruling 7). ``INAPPLICABLE`` and ``UNVERIFIABLE`` are different answers: the first says the check does not apply to this kind of result, the second says it applies but the inputs it needs are missing. Collapsing them would make "we cannot check this" and "there is nothing to check" one status, and only one of those is worth chasing.
APPLICABLE = 'applicable'
INAPPLICABLE = 'inapplicable'
UNVERIFIABLE = 'unverifiable'Conclusion
Defined in bayesmith.artifacts.reports, line 292.
class Conclusion(StrEnum)What an applicable check concluded, and what a gate aggregates to. One enum for both levels on purpose. A report's conclusion and a gate's verdict are the same three answers about different scopes, and two enums with identical members would be two types nothing stops a caller swapping -- the mistake ``ApproximationClass`` and ``TargetFidelity`` are kept apart to avoid is the OPPOSITE case: there, one word means two things.
PASS = 'pass'
FAIL = 'fail'
ABSTAIN = 'abstain'EvaluationReport
Defined in bayesmith.artifacts.reports, line 327.
class EvaluationReport
meta: ArtifactMeta
subject_ref: ArtifactRef
report_kind: str
applicability: Applicability
conclusion: Conclusion
findings: tuple[Finding, ...] = ()One check's judgement of one result, on the two axes of §0 ruling 7. The legal combinations are refused HERE, where the report is built, rather than where a gate reads it: an inapplicable check reporting PASS has passed nothing, and an aggregator handed one would count it faithfully.