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
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

//! # helena — the core vocabulary
//!
//! helena is a latent data-to-waveform generation platform (see
//! `docs/PRD.adoc`); its engine is a trained causal continuous-latent VAE
//! whose latent is a real-time control surface (PRD §9.2, resolved
//! 2026-06-30). This crate holds the vocabulary every other crate speaks:
//! the domain types that flow through the pipeline, the seams the swappable
//! components implement, and the laws their implementations must obey. The
//! design is `docs/target_arch/refoundation.adoc`; its axioms in one line:
//! **types carry axes, values carry numbers**.
//!
//! ```text
//! source data ──▶ SourceEncoder ──▶ Conditioning ──▶ LatentGenerator<K>
//!                                                          │
//!                                                     Latent<K>  (on a TimeBase)
//!                                                          │
//!                                              AudioDecoder<K> / StreamingDecoder<K>
//!                                                          ▼
//!                                                     Pcm / PcmBlock
//! ```
//!
//! ```
//! use helena::{SourceBatch, SourceFingerprint, Tensor};
//!
//! // The host-side vocabulary is serde-friendly and backend-free: assemble a
//! // batch of source features and stamp it with a typed provenance
//! // fingerprint (PRD NFR-010).
//! let batch = SourceBatch::new(vec![Tensor::vector([0.5, -0.5, 0.25])]);
//! let stamp = SourceFingerprint::of(&batch)?;
//! assert!(stamp.to_string().starts_with("sha256:"));
//! # Ok::<(), helena::Error>(())
//! ```
//!
//! ## The axes the types carry
//!
//! - **Latent kind** ([`latent`]): [`Latent<K>`] is generic over the sealed
//!   [`LatentKind`] markers [`Continuous`] / [`Tokens`], so kind mismatches
//!   don't type-check; the dynamic [`AnyLatent`] exists only at
//!   serialization edges with one checked gate back in.
//! - **Time base** ([`time`]): [`Pcm`] carries a nonzero [`SampleRate`];
//!   every [`Latent<K>`] carries a [`TimeBase`] (rate over stride, exact).
//!   [`Frames`] and [`Samples`] are distinct counts.
//! - **Causality** ([`plan`], [`stream`]): streaming decoders are built from
//!   a [`CausalPlan`] checked against a [`LatencyBudget`] *before weights
//!   exist*, and their sessions obey the bit-exactness law in [`laws`].
//! - **Lifecycle** ([`manifest`], [`config`], [`latent_norm`]): raw
//!   deserialized documents and validated specs are different types.
//! - **Provenance** ([`provenance`]): fingerprints are typed and composed;
//!   sidecars travel in versioned envelopes.
//!
//! The tensor backend is **Burn**. The core stays backend-agnostic by
//! speaking Burn's host-side [`TensorData`] at its boundaries: [`Tensor`] is
//! the raw serde-friendly carrier, and the domain newtypes ([`Pcm`],
//! [`FrameSeq`], the [`Conditioning`] slots) own rank, finiteness, and axis
//! semantics. Models in the outer crates are generic over `B: Backend` and
//! convert at their edges.
//!
//! ## Crate map
//! - [`time`] — clocks ([`SampleRate`], [`TimeBase`]) and counts.
//! - [`signal`] — time-domain audio ([`Pcm`], [`PcmBlock`]).
//! - [`tensor`] — the raw host-side carrier over [`TensorData`].
//! - [`latent`] — kinds, payloads ([`FrameSeq`], [`TokenGrid`]),
//!   [`Latent<K>`], [`AnyLatent`], and the [`Conditioning`] bundle.
//! - [`seams`] — the component contracts (PRD §13) and generation
//!   parameters ([`SeedPolicy`]).
//! - [`stream`] — the streaming contract (PRD NFR-004).
//! - [`plan`] — causal topology arithmetic, checked at construction.
//! - [`laws`] — the conformance laws implementations instantiate as tests.
//! - [`provenance`] — typed fingerprints and versioned sidecar envelopes.
//! - [`latent_norm`] — per-dimension standardization (GEN-8), fitted by
//!   construction.
//! - [`diffusion`] — the variance-preserving v-prediction kernel and levers
//!   (the §16.4 baseline posture's objective core).
//! - [`eval`] — dependency-free diagnostics and the feature-gated
//!   meta-evaluation arm.
//! - [`stats`] — streaming moment accumulation.
//! - [`config`] / [`manifest`] / [`artifact`] — the raw→validated document
//!   boundary and stamped artifact metadata.
//! - [`error`] — the shared [`Error`] / [`Result`].

#![forbid(unsafe_code)]
#![deny(missing_docs)]
#![deny(rustdoc::broken_intra_doc_links)]
#![warn(missing_debug_implementations)]

pub mod artifact;
pub mod config;
pub mod diffusion;
pub mod error;
pub mod eval;
pub mod latent;
pub mod latent_norm;
pub mod laws;
pub mod manifest;
pub mod plan;
pub mod probe;
pub mod provenance;
pub mod seams;
pub mod signal;
pub mod stats;
pub mod stream;
pub mod tensor;
pub mod time;

pub use artifact::{CodecInfo, GeneratedArtifact, GenerationRecord, Stamp};
pub use burn_tensor::TensorData;
pub use config::{
    ConfigFingerprint, ExperimentSpec, RawExperimentConfig, Recipe, RecipeFingerprint,
};
pub use error::{Error, Result};
pub use latent::{
    AnyLatent, Conditioning, Continuous, FrameSeq, Framed, GlobalLatent, KindTag, Latent,
    LatentBlock, LatentKind, Mask, Metadata, TemporalLatent, TokenGrid, Tokens,
};
pub use latent_norm::{LatentNorm, NormFitter};
pub use manifest::{ItemPath, Manifest, ManifestItem, RawDatasetManifest, SourceKind};
pub use plan::{CausalLayer, CausalPlan, CheckedPlan, LatencyBudget, MORPH_BAND_MAX_SECONDS};
pub use probe::{Formant, Layer, Partial, Probe, Stratum, Vibrato};
pub use provenance::{Fingerprint, SchemaVersion, SidecarEnvelope, SourceFingerprint};
pub use seams::{
    AudioCodec, AudioDecoder, AudioEncoder, ClipDuration, Clocked, GenerationParams, GuidanceScale,
    LatentGenerator, Seed, SeedPolicy, SourceBatch, SourceEncoder, Temperature,
};
/// The [`Metadata`] value type, re-exported so the whole public API is
/// nameable without a direct serde_json dependency.
pub use serde_json::Value;
pub use signal::{ChannelLayout, Pcm, PcmBlock};
pub use stream::{StreamSession, StreamSpec, StreamingDecoder};
pub use tensor::Tensor;
pub use time::{Frames, SampleRate, Samples, TimeBase};