helena 0.1.0

Core types and component interfaces for helena, a latent data-to-waveform generation platform.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

//! Generator-output diagnostics and dependency-free audio-quality metrics.
//!
//! The latent diagnostics are the backend- and codec-free arm of the objective
//! bakeoff: they measure seed diversity, conditioning response, and ordered
//! response curves over generated [`Latent<Continuous>`](crate::Latent) sequences,
//! plus the bakeoff's decision criteria, the per-SNR clean-target loss curve
//! ([`PerSnrLossCurve`]) and the few-step sampling gap ([`StepGapCurve`]). The
//! preservation metrics ask whether the output keeps the source's structure
//! (correlation, rank order, embedding neighborhoods). The waveform metrics
//! operate after decode over [`Pcm`](crate::Pcm) and stay limited to cheap
//! time-domain statistics. Spectral metrics live in `helena-eval` because they
//! carry the FFT dependency. The uncertainty layer ([`ClusterBootstrap`]) wraps
//! any of these per-item scores in a clustered bootstrap confidence interval, so a
//! metric difference is read against its own sampling noise. Behind the
//! off-by-default `meta-eval` feature, the pairwise arm (`BradleyTerry`) aggregates
//! blocked human comparisons into a system ranking, and the meta-evaluation arm
//! (`rank_agreement`) measures whether an automated metric tracks that human
//! judgment instead of assuming it does.
//!
//! **The families are separate on purpose, and there is no overall-score type.**
//! Fidelity, diversity, faithfulness, mechanism diagnostics, and human preference
//! answer different questions and can move in different directions, so this module
//! keeps them as distinct measures rather than blending them into one number
//! (PRD §15, the evaluation-trustworthiness note). Automated metrics are candidate
//! evidence until they are checked against human judgment on the same conditioning
//! items — which is why the human/meta-eval layer is its own feature-gated arm, not
//! a hidden post-processing convention.
//!
//! The kind axis is carried by the type: the latent diagnostics consume
//! [`Latent<Continuous>`](crate::Latent) whose payload is a
//! [`FrameSeq`](crate::FrameSeq), finite and rank-2 by construction, so "these are
//! tokens" and "these hold a NaN" are unrepresentable rather than validated. The
//! waveform metrics take [`Pcm`](crate::Pcm), finite and whole-framed by
//! construction, for the same reason.
//!
//! See `mod.adoc` in this directory for the design note behind these boundaries.

mod common;
mod latent;
#[cfg(feature = "meta-eval")]
mod metaeval;
#[cfg(feature = "meta-eval")]
mod pairwise;
mod preservation;
mod uncertainty;
mod waveform;

pub use latent::{
    CleanTargetLoss, GenerationDiagnostics, PerSnrLossCurve, ResponseCurve, SnrBin, StepGap,
    StepGapCurve, generate_grid, grid_cell_distances, grid_distance, sample_dispersion,
    sample_grid, sweep_response,
};
#[cfg(feature = "meta-eval")]
pub use metaeval::{
    MetricScore, MetricScores, PairedPermutationTest, RankAgreement, RankAgreementIntervals,
    SoftPairwiseAccuracy, SoftPairwiseAccuracyInterval, kendall_tau_b, rank_agreement,
    rank_agreement_intervals, soft_pairwise_accuracy, soft_pairwise_accuracy_interval,
    spearman_rho,
};
#[cfg(feature = "meta-eval")]
pub use pairwise::{BradleyTerry, Judgment, Outcome, Reliability};
pub use preservation::{CorrelationPreservation, NeighborhoodPreservation};
pub use uncertainty::{ClusterBootstrap, ConfidenceInterval};
pub use waveform::{SignalPreservation, WaveformQuality, noise_floor};