Struct MetaTrainingRecord 

pub struct MetaTrainingRecord {
    pub corpus_id: String,
    pub features: CorpusFeatures,
    pub best_config: PipelineConfig,
    pub best_score: f64,
    pub score_lift: Option<f64>,
    pub metric_name: String,
    pub strategy: String,
    pub timestamp: String,
}

One observation for the meta-learner: “on this corpus profile, this config was found to be best under this metric.”

Fields

corpus_id: String

User-supplied corpus identifier. Not used by the model — just for human-readable provenance in logs and training-set audits.

features: CorpusFeatures

Low-dim profile of the corpus. Input to the meta-model.

best_config: PipelineConfig

The config that won the tuner run. Target of the meta-model.

best_score: f64

The score achieved by best_config under metric_name.

score_lift: Option<f64>

Normalized improvement of best_score over the run’s mean trial score, as a fraction of the available headroom: (best − mean) / (1 − mean), clamped to [0, 1].

Unlike best_score, this is comparable across corpora of different intrinsic difficulty — a 0.9 on an easy corpus and a 0.6 on a hard one can represent the same “the tuner found real signal” evidence. A lift near 0 means the landscape was flat and the winning config is weak evidence. DistanceWeightedMetaModel prefers this over best_score when present. None for records created before this field existed or from runs with fewer than 2 trials.

metric_name: String

Which quality metric was being optimized. Records with different metrics aren’t directly comparable; both shipped models stratify to the dominant metric at fit time.

strategy: String

Short description of the search strategy, e.g. "random{budget=24,seed=...}". Free-form — for auditing only.

timestamp: String

RFC 3339 timestamp (or any string). Free-form.

Implementations

impl MetaTrainingRecord

pub fn from_tune_result( corpus_id: impl Into<String>, features: CorpusFeatures, report: &TuneReport, strategy_label: impl Into<String>, ) -> Self

Build a record from the ingredients of one tuner run.

corpus_id and strategy_label are free-form strings the caller provides for provenance — the tuner doesn’t know either on its own. timestamp defaults to seconds-since-Unix-epoch (sortable, unambiguous, dependency-free); swap in your own format via Self::with_timestamp if you want human-readable.

pub fn with_timestamp(self, ts: impl Into<String>) -> Self

Replace the timestamp. Useful when the caller has a preferred format (e.g. an RFC 3339 string from chrono).

pub fn save_list(records: &[Self], path: impl AsRef<Path>) -> Result<()>

Save a list of records as a JSON array to disk. Creates parent directories as needed.

Kept for callers who want a pretty-printed snapshot (backups, audits, diffs). The default on-disk store uses JSONL under Self::append_to_default_store for O(1) appends — read it back via Self::load_default_store, which auto-detects legacy array files as well.

pub fn load_list(path: impl AsRef<Path>) -> Result<Vec<Self>>

Load a list of records from disk.

Accepts both a JSON array (legacy format and what save_list writes) and JSON Lines (one record per line, the new append format). Detection is first-character based: [ ⇒ array, anything else ⇒ JSONL. Returns an empty vec if the file doesn’t exist.

pub fn default_store_path() -> Result<PathBuf>

Default on-disk training-store path: ~/.sphereql/meta_records.json.

pub fn append_to_default_store(&self) -> Result<PathBuf>

Append this record to the user’s default training store.

Constant-time per call: opens the file in append mode and writes one JSON-encoded line. Previously this loaded every record, pushed the new one, and rewrote the entire file — O(N) per append, which dominated at N → 10k.

Existing stores written in legacy array format keep working; on the first append we re-emit the file as JSONL (one-time O(N) migration), then subsequent appends are O(1).

pub fn append_to(&self, path: impl AsRef<Path>) -> Result<()>

Append this record to an arbitrary JSONL file. Creates the file and any missing parent directories on first call.

pub fn load_default_store() -> Result<Vec<Self>>

Load all records from the user’s default training store. Returns an empty vec if the store doesn’t exist yet.

pub fn adjust_score_with_feedback( &self, summary: &FeedbackSummary, alpha: f64, ) -> f64

Blend this record’s automated best_score with a feedback summary’s mean_score into a single adjusted score.

alpha ∈ [0, 1] controls how much weight to give feedback:

• 0.0 returns best_score unchanged (ignore feedback).
• 1.0 returns the feedback mean (trust feedback entirely).
• 0.5 weights them equally.

alpha is clamped to [0, 1]. When summary belongs to a different corpus than self the function still computes the blend — verifying corpus_id alignment is the caller’s responsibility; this keeps the API composable under custom lookup schemes.

Note: this blends best_score, not Self::score_lift. The result is on the raw-score scale, which is not comparable across corpora of different difficulty — don’t substitute it for score_lift in cross-corpus comparisons.

Trait Implementations

impl Clone for MetaTrainingRecord

fn clone(&self) -> MetaTrainingRecord

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MetaTrainingRecord

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for MetaTrainingRecord

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for MetaTrainingRecord

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.