Skip to main content

rlevo_core/
lib.rs

1//! Core types and traits for evolutionary deep reinforcement learning.
2//!
3//! `rlevo-core` defines the shared vocabulary used across the entire `rlevo`
4//! workspace. Every other crate — `rlevo-reinforcement-learning`,
5//! `rlevo-evolution`, `rlevo-environments`, `rlevo-benchmarks` — depends on
6//! these primitives. No concrete algorithms or environments live here.
7//!
8//! # Module map
9//!
10//! | Module | What it provides |
11//! |---|---|
12//! | [`base`] | [`Reward`], [`Observation`], [`State`], [`Action`], [`TensorConvertible`], [`UpdateFunction`] — the primitive trait vocabulary |
13//! | [`action`] | [`DiscreteAction`], [`MultiDiscreteAction`], [`ContinuousAction`] — layered action-space extensions |
14//! | [`state`] | [`MarkovState`], [`BeliefState`], [`HiddenState`], [`LatentState`], [`StateAggregation`], [`Observable`] — POMDP and latent-space extensions |
15//! | [`environment`] | [`Environment`], [`Snapshot`], [`SnapshotBase`], [`EpisodeStatus`], [`EnvironmentError`] — the agent/environment protocol |
16//! | [`reward`] | [`ScalarReward`] — the standard single-value reward concrete type |
17//! | [`evaluation`] | [`BenchEnv`], [`BenchStep`], [`BenchError`] — object-safe environment interface for harnesses |
18//! | [`fitness`] | [`BenchableAgent`], [`FitnessEvaluable`], [`Landscape`], [`Metric`], [`MetricsProvider`] — inference-only agent and fitness evaluation |
19//! | [`objective`] | [`ObjectiveSense`] — the maximise/minimise direction primitive reconciled at one chokepoint |
20//! | [`config`] | [`Validate`], [`ConfigError`] — the shared config-validation convention checked at construction |
21//! | [`bounds`] | [`Bounds`] — an inclusive range valid by construction (invariant `lo <= hi`: rejects `lo > hi` and `NaN`) |
22//! | [`probability`] | [`Probability`] — a `[0, 1]` rate valid by construction (rejects `NaN`, `Inf`, out-of-range) |
23//! | [`rate`] | [`NonNegativeRate`] — a finite non-negative magnitude valid by construction (BLX-α, σ) |
24//! | [`render`] | [`AsciiRenderable`], [`Renderer`](crate::render::Renderer), styled/palette/payload sub-modules — optional debug and TUI visualization layer |
25//! | [`agent`] | Reserved; empty in v0.1.x while the unified agent trait hierarchy stabilizes |
26//! | [`util`] | Shared utility helpers |
27//!
28//! # Const-generic `RANK`
29//!
30//! Several traits — [`Observation`], [`State`], [`Action`] — are parameterized
31//! by a const generic `R` (rank) that denotes the *number of tensor axes*
32//! (equivalent to NumPy's `ndim` or Burn's `Tensor<B, R>`). This encodes
33//! shape compatibility at compile time: a rank-1 observation and a rank-2
34//! observation cannot be mixed up without a compile error.
35//!
36//! ```text
37//! Environment<R, SR, AR>
38//!   ├── StateType     : State<SR>        (shape: [usize; SR])
39//!   ├── ObservationType: Observation<R>  (shape: [usize; R])
40//!   ├── ActionType    : Action<AR>       (shape: [usize; AR])
41//!   └── SnapshotType  : Snapshot<R, ...>
42//! ```
43//!
44//! # Episode loop sketch
45//!
46//! The basic agent/environment interaction loop follows this pattern:
47//!
48//! ```text
49//! env.reset() → Snapshot { observation, reward, status: Running }
50//!   loop:
51//!     agent selects action from observation
52//!     env.step(action) → Snapshot { observation, reward, status }
53//!     break when status.is_done()
54//! ```
55//!
56//! [`EpisodeStatus::Terminated`] and [`EpisodeStatus::Truncated`] are kept
57//! distinct so RL algorithms can bootstrap value correctly at truncation
58//! boundaries.
59//!
60//! [`Reward`]: crate::base::Reward
61//! [`Observation`]: crate::base::Observation
62//! [`State`]: crate::base::State
63//! [`Action`]: crate::base::Action
64//! [`TensorConvertible`]: crate::base::TensorConvertible
65//! [`UpdateFunction`]: crate::base::UpdateFunction
66//! [`DiscreteAction`]: crate::action::DiscreteAction
67//! [`MultiDiscreteAction`]: crate::action::MultiDiscreteAction
68//! [`ContinuousAction`]: crate::action::ContinuousAction
69//! [`MarkovState`]: crate::state::MarkovState
70//! [`BeliefState`]: crate::state::BeliefState
71//! [`HiddenState`]: crate::state::HiddenState
72//! [`LatentState`]: crate::state::LatentState
73//! [`StateAggregation`]: crate::state::StateAggregation
74//! [`Observable`]: crate::state::Observable
75//! [`Environment`]: crate::environment::Environment
76//! [`Snapshot`]: crate::environment::Snapshot
77//! [`SnapshotBase`]: crate::environment::SnapshotBase
78//! [`EpisodeStatus`]: crate::environment::EpisodeStatus
79//! [`EpisodeStatus::Terminated`]: crate::environment::EpisodeStatus::Terminated
80//! [`EpisodeStatus::Truncated`]: crate::environment::EpisodeStatus::Truncated
81//! [`EnvironmentError`]: crate::environment::EnvironmentError
82//! [`ScalarReward`]: crate::reward::ScalarReward
83//! [`BenchEnv`]: crate::evaluation::BenchEnv
84//! [`BenchStep`]: crate::evaluation::BenchStep
85//! [`BenchError`]: crate::evaluation::BenchError
86//! [`BenchableAgent`]: crate::fitness::BenchableAgent
87//! [`FitnessEvaluable`]: crate::fitness::FitnessEvaluable
88//! [`Landscape`]: crate::fitness::Landscape
89//! [`Metric`]: crate::fitness::Metric
90//! [`MetricsProvider`]: crate::fitness::MetricsProvider
91//! [`ObjectiveSense`]: crate::objective::ObjectiveSense
92//! [`Validate`]: crate::config::Validate
93//! [`ConfigError`]: crate::config::ConfigError
94//! [`Bounds`]: crate::bounds::Bounds
95//! [`Probability`]: crate::probability::Probability
96//! [`NonNegativeRate`]: crate::rate::NonNegativeRate
97//! [`AsciiRenderable`]: crate::render::AsciiRenderable
98//! [`Renderer`]: crate::render::Renderer
99
100/// Primitive trait vocabulary: [`Reward`], [`Observation`], [`State`],
101/// [`Action`], [`TensorConvertible`], and [`UpdateFunction`].
102///
103/// All other modules in this crate depend on the types defined here.
104///
105/// [`Reward`]: crate::base::Reward
106/// [`Observation`]: crate::base::Observation
107/// [`State`]: crate::base::State
108/// [`Action`]: crate::base::Action
109/// [`TensorConvertible`]: crate::base::TensorConvertible
110/// [`UpdateFunction`]: crate::base::UpdateFunction
111pub mod base;
112
113/// Layered action-space traits: [`DiscreteAction`], [`MultiDiscreteAction`],
114/// and [`ContinuousAction`].
115///
116/// [`DiscreteAction`]: crate::action::DiscreteAction
117/// [`MultiDiscreteAction`]: crate::action::MultiDiscreteAction
118/// [`ContinuousAction`]: crate::action::ContinuousAction
119pub mod action;
120
121/// Reserved for a future unified agent trait hierarchy.
122///
123/// Empty in v0.3.x. Concrete RL and evolutionary agents currently live in
124/// `rlevo-reinforcement-learning` and `rlevo-evolution` respectively.
125pub mod agent;
126
127/// Shared configuration-validation convention.
128///
129/// Provides [`Validate`], the trait every `*Config` implements to check its
130/// invariants at construction, plus the structured [`ConfigError`] /
131/// [`ConstraintKind`] it returns and ergonomic check helpers. Construction that
132/// consumes a caller-supplied config returns `Result<_, ConfigError>` rather
133/// than panicking (ADR 0026).
134///
135/// [`Validate`]: crate::config::Validate
136/// [`ConfigError`]: crate::config::ConfigError
137/// [`ConstraintKind`]: crate::config::ConstraintKind
138pub mod config;
139
140/// Validated closed-range primitive.
141///
142/// Provides [`Bounds`], an inclusive `[lo, hi]` range over `f32` that is valid
143/// by construction (invariant `lo <= hi`: rejects `lo > hi` and `NaN`, permits a
144/// one-sided infinite endpoint), plus its
145/// [`BoundsError`]. Makes the `f32::clamp` panic and `x.max(lo).min(hi)`
146/// silent-collapse hazards unrepresentable wherever a `Bounds` is held.
147/// Complements the [`config`] convention rather than replacing it (ADR 0027).
148///
149/// [`Bounds`]: crate::bounds::Bounds
150/// [`BoundsError`]: crate::bounds::BoundsError
151pub mod bounds;
152
153/// Agent/environment interaction protocol.
154///
155/// Defines [`Environment`], [`Snapshot`]/[`SnapshotBase`],
156/// [`EpisodeStatus`], and [`EnvironmentError`].
157///
158/// [`Environment`]: crate::environment::Environment
159/// [`Snapshot`]: crate::environment::Snapshot
160/// [`SnapshotBase`]: crate::environment::SnapshotBase
161/// [`EpisodeStatus`]: crate::environment::EpisodeStatus
162/// [`EnvironmentError`]: crate::environment::EnvironmentError
163pub mod environment;
164
165/// Object-safe environment interface for benchmarking harnesses.
166///
167/// [`BenchEnv`] strips the const-generic dimensions from [`Environment`] so
168/// harnesses do not need to be generic over them. Adapters live in
169/// `rlevo-environments` behind the `bench` feature.
170///
171/// [`BenchEnv`]: crate::evaluation::BenchEnv
172/// [`Environment`]: crate::environment::Environment
173pub mod evaluation;
174
175/// Inference-only agent and fitness-evaluation traits.
176///
177/// Provides [`BenchableAgent`], [`FitnessEvaluable`], [`Landscape`],
178/// [`Metric`], and [`MetricsProvider`].
179///
180/// [`BenchableAgent`]: crate::fitness::BenchableAgent
181/// [`FitnessEvaluable`]: crate::fitness::FitnessEvaluable
182/// [`Landscape`]: crate::fitness::Landscape
183/// [`Metric`]: crate::fitness::Metric
184/// [`MetricsProvider`]: crate::fitness::MetricsProvider
185pub mod fitness;
186
187/// Objective direction primitive.
188///
189/// Provides [`ObjectiveSense`], the typed maximise/minimise direction that
190/// reconciles the library's maximise-native engine with cost objectives at a
191/// single chokepoint.
192///
193/// [`ObjectiveSense`]: crate::objective::ObjectiveSense
194pub mod objective;
195
196/// Validated unit-interval probability primitive.
197///
198/// Provides [`Probability`], a value in the closed interval `[0, 1]` valid by
199/// construction (invariant `0.0 <= p <= 1.0`: rejects `NaN`, `Inf`, and
200/// out-of-range values), plus its [`ProbabilityError`]. Makes the silent
201/// all-false-mask degeneracy of a `NaN`/out-of-range Bernoulli rate
202/// unrepresentable wherever a `Probability` is held. Complements the [`config`]
203/// convention rather than replacing it (ADR 0031).
204///
205/// [`Probability`]: crate::probability::Probability
206/// [`ProbabilityError`]: crate::probability::ProbabilityError
207pub mod probability;
208
209/// Validated non-negative rate primitive.
210///
211/// Provides [`NonNegativeRate`], a finite non-negative `f32` valid by
212/// construction (invariant `is_finite() && r >= 0.0`), plus its
213/// [`NonNegativeRateError`]. The unbounded companion to [`Probability`] for
214/// magnitudes such as BLX-α's expansion factor or Gaussian mutation's σ, where
215/// a `NaN`/`Inf` would otherwise poison the offspring tensor (ADR 0031).
216///
217/// [`NonNegativeRate`]: crate::rate::NonNegativeRate
218/// [`NonNegativeRateError`]: crate::rate::NonNegativeRateError
219/// [`Probability`]: crate::probability::Probability
220pub mod rate;
221
222/// Optional rendering layer for debug output and TUI visualization.
223///
224/// Contains [`AsciiRenderable`], [`Renderer`] (via the [`ascii`] sub-module),
225/// styled color primitives ([`styled`] / [`palette`]), and environment
226/// payload types ([`payload`]).
227///
228/// [`AsciiRenderable`]: crate::render::AsciiRenderable
229/// [`Renderer`]: crate::render::Renderer
230/// [`ascii`]: crate::render::ascii
231/// [`styled`]: crate::render::styled
232/// [`palette`]: crate::render::palette
233/// [`payload`]: crate::render::payload
234pub mod render;
235
236/// Concrete reward types.
237///
238/// Provides [`ScalarReward`], the standard single-`f32` reward used by most
239/// environments.
240///
241/// [`ScalarReward`]: crate::reward::ScalarReward
242pub mod reward;
243
244/// Advanced state abstractions for POMDPs and latent representations.
245///
246/// Extends [`base::State`] with [`MarkovState`], [`BeliefState`],
247/// [`HiddenState`], [`LatentState`], [`StateAggregation`], and [`Observable`]
248/// (the modality-changing state→observation projection for `OR != SR`).
249///
250/// [`base::State`]: crate::base::State
251/// [`MarkovState`]: crate::state::MarkovState
252/// [`BeliefState`]: crate::state::BeliefState
253/// [`HiddenState`]: crate::state::HiddenState
254/// [`LatentState`]: crate::state::LatentState
255/// [`StateAggregation`]: crate::state::StateAggregation
256/// [`Observable`]: crate::state::Observable
257pub mod state;
258
259/// Shared utility helpers used across `rlevo-core` modules.
260pub mod util;