Architecture
The design separates model meaning, task-aware compilation, numerical execution and statistical assessment.
Graph is the hierarchical model boundary
Flowchart as a hierarchical model is the central representation idea. The Graph owns generative dependencies, conditional laws, deterministic calculations and conditioning data. Its factorization gives statistical meaning to the model; compilation then asks which parts admit exact treatment and which need numerical inference.
The model graph and the execution lifecycle below answer different questions. A model edge names a variable dependency. A lifecycle arrow describes which software layer consumes an artifact. See one hierarchy as both a flowchart and a joint density.
Follow the main dependency path
- GraphProbability laws
and dependencies - CompilerTask-specific premises
and execution plan - ExecutionExact primitives
or backend adapters - EvaluationReports about
completed Results
Open the interactive architecture map — execution flow, ownership and the 0.9 boundary.
Five responsibilities
| Layer | Owns | Does not own |
|---|---|---|
| Model representation | Graph, nodes, tracing, factors, shapes and conditioning. | Sampler selection or quality verdicts. |
| Analysis and compilation | Structure, eligibility, task-specific plans, refusal grounds. | New interpretations of a declared probability law. |
| Execution | Exact solves, sampling adapters, reconstruction, Result and run record. | Changing the question after seeing a result. |
| Evaluation | Applicability, diagnostics projections, predictive checks, comparisons. | Mutating a Result or choosing the next inference engine. |
| Workflow control | Future orchestration, policy, budgets and action state. | A second implementation of inference. |
The complete workflow-control layer is a roadmap item. Existing Tasks, Results and reports provide its seams, not a claim that the whole control plane is already implemented.
Artifact data model
bayesmith.artifacts is a lightweight data layer. It avoids JAX, graphs and live backend handles at module import. Graph-aware runtime binding belongs in dispatch; a schema field stores a reference or value rather than a callable. This boundary makes serialization and invalidation independently testable.
Package ownership
The Overview states which semantics bayesmith owns and which numerical capabilities belong to the libraries it uses. Two consequences are architectural. Backend adapters translate contracts rather than duplicate an engine, so a route's public behaviour is bayesmith's and its arithmetic may be someone else's. Local generic optimization and the neural estimator remain reference implementations with explicit limits, not a claim to own those algorithm families.
marginal supplies nuisance-integrated likelihood components, each dataset's likelihood with its own nuisances integrated away. The graph-level evidence is assembled by the task-aware layer instead, in dispatch.evidence, and only for a whole-graph exact linear-Gaussian plan; see evidence and model comparison. The deprecated evidence namespace must not acquire a different meaning when compatibility ends.
One normative design
This chapter explains the structure for users and contributors. The top-level design remains the single normative decision document. Module specifications refine it; dated measurement records do not silently override it. Its ten package-wide invariants, and the machinery that holds the code to them, are on principles and verification. Continue with extension contracts.