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`] — 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//! | [`render`] | [`AsciiRenderable`], [`Renderer`](crate::render::Renderer), styled/palette/payload sub-modules — optional debug and TUI visualization layer |
20//! | [`agent`] | Reserved; empty in v0.1.x while the unified agent trait hierarchy stabilizes |
21//! | [`util`] | Shared utility helpers |
22//!
23//! # Const-generic `RANK`
24//!
25//! Several traits — [`Observation`], [`State`], [`Action`] — are parameterized
26//! by a const generic `R` (rank) that denotes the *number of tensor axes*
27//! (equivalent to NumPy's `ndim` or Burn's `Tensor<B, R>`). This encodes
28//! shape compatibility at compile time: a rank-1 observation and a rank-2
29//! observation cannot be mixed up without a compile error.
30//!
31//! ```text
32//! Environment<R, SR, AR>
33//! ├── StateType : State<SR> (shape: [usize; SR])
34//! ├── ObservationType: Observation<R> (shape: [usize; R])
35//! ├── ActionType : Action<AR> (shape: [usize; AR])
36//! └── SnapshotType : Snapshot<R, ...>
37//! ```
38//!
39//! # Episode loop sketch
40//!
41//! The basic agent/environment interaction loop follows this pattern:
42//!
43//! ```text
44//! env.reset() → Snapshot { observation, reward, status: Running }
45//! loop:
46//! agent selects action from observation
47//! env.step(action) → Snapshot { observation, reward, status }
48//! break when status.is_done()
49//! ```
50//!
51//! [`EpisodeStatus::Terminated`] and [`EpisodeStatus::Truncated`] are kept
52//! distinct so RL algorithms can bootstrap value correctly at truncation
53//! boundaries.
54//!
55//! [`Reward`]: crate::base::Reward
56//! [`Observation`]: crate::base::Observation
57//! [`State`]: crate::base::State
58//! [`Action`]: crate::base::Action
59//! [`TensorConvertible`]: crate::base::TensorConvertible
60//! [`UpdateFunction`]: crate::base::UpdateFunction
61//! [`DiscreteAction`]: crate::action::DiscreteAction
62//! [`MultiDiscreteAction`]: crate::action::MultiDiscreteAction
63//! [`ContinuousAction`]: crate::action::ContinuousAction
64//! [`MarkovState`]: crate::state::MarkovState
65//! [`BeliefState`]: crate::state::BeliefState
66//! [`HiddenState`]: crate::state::HiddenState
67//! [`LatentState`]: crate::state::LatentState
68//! [`StateAggregation`]: crate::state::StateAggregation
69//! [`Environment`]: crate::environment::Environment
70//! [`Snapshot`]: crate::environment::Snapshot
71//! [`SnapshotBase`]: crate::environment::SnapshotBase
72//! [`EpisodeStatus`]: crate::environment::EpisodeStatus
73//! [`EpisodeStatus::Terminated`]: crate::environment::EpisodeStatus::Terminated
74//! [`EpisodeStatus::Truncated`]: crate::environment::EpisodeStatus::Truncated
75//! [`EnvironmentError`]: crate::environment::EnvironmentError
76//! [`ScalarReward`]: crate::reward::ScalarReward
77//! [`BenchEnv`]: crate::evaluation::BenchEnv
78//! [`BenchStep`]: crate::evaluation::BenchStep
79//! [`BenchError`]: crate::evaluation::BenchError
80//! [`BenchableAgent`]: crate::fitness::BenchableAgent
81//! [`FitnessEvaluable`]: crate::fitness::FitnessEvaluable
82//! [`Landscape`]: crate::fitness::Landscape
83//! [`Metric`]: crate::fitness::Metric
84//! [`MetricsProvider`]: crate::fitness::MetricsProvider
85//! [`AsciiRenderable`]: crate::render::AsciiRenderable
86//! [`Renderer`]: crate::render::Renderer
87
88/// Primitive trait vocabulary: [`Reward`], [`Observation`], [`State`],
89/// [`Action`], [`TensorConvertible`], and [`UpdateFunction`].
90///
91/// All other modules in this crate depend on the types defined here.
92///
93/// [`Reward`]: crate::base::Reward
94/// [`Observation`]: crate::base::Observation
95/// [`State`]: crate::base::State
96/// [`Action`]: crate::base::Action
97/// [`TensorConvertible`]: crate::base::TensorConvertible
98/// [`UpdateFunction`]: crate::base::UpdateFunction
99pub mod base;
100
101/// Layered action-space traits: [`DiscreteAction`], [`MultiDiscreteAction`],
102/// and [`ContinuousAction`].
103///
104/// [`DiscreteAction`]: crate::action::DiscreteAction
105/// [`MultiDiscreteAction`]: crate::action::MultiDiscreteAction
106/// [`ContinuousAction`]: crate::action::ContinuousAction
107pub mod action;
108
109/// Reserved for a future unified agent trait hierarchy.
110///
111/// Empty in v0.1.x. Concrete RL and evolutionary agents currently live in
112/// `rlevo-reinforcement-learning` and `rlevo-evolution` respectively.
113pub mod agent;
114
115/// Agent/environment interaction protocol.
116///
117/// Defines [`Environment`], [`Snapshot`]/[`SnapshotBase`],
118/// [`EpisodeStatus`], and [`EnvironmentError`].
119///
120/// [`Environment`]: crate::environment::Environment
121/// [`Snapshot`]: crate::environment::Snapshot
122/// [`SnapshotBase`]: crate::environment::SnapshotBase
123/// [`EpisodeStatus`]: crate::environment::EpisodeStatus
124/// [`EnvironmentError`]: crate::environment::EnvironmentError
125pub mod environment;
126
127/// Object-safe environment interface for benchmarking harnesses.
128///
129/// [`BenchEnv`] strips the const-generic dimensions from [`Environment`] so
130/// harnesses do not need to be generic over them. Adapters live in
131/// `rlevo-environments` behind the `bench` feature.
132///
133/// [`BenchEnv`]: crate::evaluation::BenchEnv
134/// [`Environment`]: crate::environment::Environment
135pub mod evaluation;
136
137/// Inference-only agent and fitness-evaluation traits.
138///
139/// Provides [`BenchableAgent`], [`FitnessEvaluable`], [`Landscape`],
140/// [`Metric`], and [`MetricsProvider`].
141///
142/// [`BenchableAgent`]: crate::fitness::BenchableAgent
143/// [`FitnessEvaluable`]: crate::fitness::FitnessEvaluable
144/// [`Landscape`]: crate::fitness::Landscape
145/// [`Metric`]: crate::fitness::Metric
146/// [`MetricsProvider`]: crate::fitness::MetricsProvider
147pub mod fitness;
148
149/// Optional rendering layer for debug output and TUI visualization.
150///
151/// Contains [`AsciiRenderable`], [`Renderer`] (via the [`ascii`] sub-module),
152/// styled color primitives ([`styled`] / [`palette`]), and environment
153/// payload types ([`payload`]).
154///
155/// [`AsciiRenderable`]: crate::render::AsciiRenderable
156/// [`Renderer`]: crate::render::Renderer
157/// [`ascii`]: crate::render::ascii
158/// [`styled`]: crate::render::styled
159/// [`palette`]: crate::render::palette
160/// [`payload`]: crate::render::payload
161pub mod render;
162
163/// Concrete reward types.
164///
165/// Provides [`ScalarReward`], the standard single-`f32` reward used by most
166/// environments.
167///
168/// [`ScalarReward`]: crate::reward::ScalarReward
169pub mod reward;
170
171/// Advanced state abstractions for POMDPs and latent representations.
172///
173/// Extends [`base::State`] with [`MarkovState`], [`BeliefState`],
174/// [`HiddenState`], [`LatentState`], and [`StateAggregation`].
175///
176/// [`base::State`]: crate::base::State
177/// [`MarkovState`]: crate::state::MarkovState
178/// [`BeliefState`]: crate::state::BeliefState
179/// [`HiddenState`]: crate::state::HiddenState
180/// [`LatentState`]: crate::state::LatentState
181/// [`StateAggregation`]: crate::state::StateAggregation
182pub mod state;
183
184/// Shared utility helpers used across `rlevo-core` modules.
185pub mod util;