blr_active/
lib.rs

1//! # blr-active: Active Learning Orchestration for Bayesian Linear Regression
2//!
3//! This crate provides active learning algorithms and orchestration logic for
4//! iterative sensor calibration, built on top of the `blr-core` crate's BLR+ARD fitting.
5//!
6//! `blr-active` implements the 4-phase calibration workflow that drives a BLR+ARD model
7//! from an initial rough fit to a precision-targeted, noise-aware calibration.
8//!
9//! ```text
10//! blr-core  (pure math: BLR+ARD, noise estimation, basis functions)
11//!     └── blr-active  (this crate: active learning loop, precision tiers, sessions)
12//! ```
13//!
14//! ## Architecture
15//!
16//! The 4-phase calibration workflow:
17//!
18//! ```text
19//! Phase 0: Noise characterisation
20//!   NoiseCalibrationSession → estimate σ_noise → select PrecisionLevel
21//!         │
22//!         ▼
23//! Phase 1: Exploration
24//!   CalibrationSession → collect initial data → fit BLR+ARD
25//!         │
26//!         ▼
27//! Phase 2: Active learning
28//!   CalibrationSession::next_iteration() → recommend sample → user measures → add_measurement()
29//!         │  (repeat until precision goal is met or noise floor is hit)
30//!         ▼
31//! Phase 3: Convergence / completion
32//!   CalibrationSession → export_history_json() → store results
33//! ```
34//!
35//! ## Modules
36//!
37//! - [`active_learning`] — 5 active learning algorithms (variance, mutual info, goal-based, etc.)
38//! - [`calibration_session`] — User-facing noise-aware precision targeting session ([`NoiseCalibrationSession`])
39//! - [`goal_assessment`] — Feasibility classification for precision goals ([`assess_goal_feasibility`])
40//! - [`precision_tiers`] — Precision tier definitions (Low/Moderate/High/Max) ([`PrecisionLevel`])
41//! - [`error`] — [`ALError`] type with `From<BLRError>` bridge
42//!
43//! **Note:** Certificate metadata is in `sensor-calibration-component` (application layer).
44//!
45//! ## Quick Start
46//!
47//! ```rust,no_run
48//! use blr_active::{NoiseCalibrationSession, CalibrationSession, SessionConfig};
49//! use blr_core::noise_estimation::{NoiseEstimate, SensorType};
50//!
51//! // Phase 0: characterise sensor noise from initial measurements
52//! let noise_est = NoiseEstimate {
53//!     point_estimate: 0.03,
54//!     lower_bound: 0.027,
55//!     upper_bound: 0.033,
56//!     confidence: "stable".to_string(),
57//! };
58//! let mut noise_session = NoiseCalibrationSession::new(SensorType::Hall, noise_est);
59//!
60//! // Inspect precision tiers to choose a goal
61//! for tier in noise_session.precision_tiers.iter() {
62//!     println!("{:?}: target std = {:.4}", tier.level, tier.absolute_tolerance);
63//! }
64//!
65//! // Phase 1-3: active learning loop
66//! let config = SessionConfig::default();
67//! let mut session = CalibrationSession::new(config, |x: f64| vec![1.0, x], 2);
68//! // ... add measurements, call next_iteration(), check IterationOutcome
69//! ```
70//!
71//! ## Feature Flags
72//!
73//! | Feature | Default | Description |
74//! |---------|---------|-------------|
75//! | `std`   | ✓       | Enable standard library support (required for blr-core) |
76//!
77//! ## References
78//!
79//! - Settles, B. (2009). "Active Learning Literature Survey."
80//!   University of Wisconsin–Madison, Technical Report 1648.
81//! - MacKay, D. J. C. (1992). "Information-Based Objective Functions for Active Data Selection."
82//!   *Neural Computation*, 4(4), 590–604.
83
84pub mod active_learning;
85pub mod calibration_session;
86pub mod error;
87pub mod goal_assessment;
88pub mod precision_tiers;
89
90pub use active_learning::acquisition::RecommendedSample;
91pub use active_learning::noise_floor::{
92    detect_noise_floor, detect_noise_floor_default, NoiseFloorConfig, NoiseFloorDiagnostic,
93};
94pub use active_learning::orchestration::{
95    CalibrationSession, IterationOutcome, PrecisionRecord, SampleRecord, SessionConfig,
96};
97pub use active_learning::precision::{
98    assess_precision, percentile, PrecisionAssessment, PrecisionStatus,
99};
100pub use active_learning::variance::{posterior_std, posterior_std_grid, posterior_variance};
101pub use calibration_session::{ActiveLearningConfig, NoiseCalibrationSession};
102pub use error::{ALError, ALResult};
103pub use goal_assessment::{assess_goal_feasibility, CalibrationGoal, GoalFeasibility};
104pub use precision_tiers::{
105    compute_precision_tiers, Feasibility, PrecisionLevel, PrecisionTierInfo,
106};
blr_active/lib.rs

blr_active/
lib.rs
