pc_rl_core/
lib.rs

1// Author: Julian Bolivar
2// Version: 1.0.0
3// Date: 2026-03-25
4
5//! Predictive Coding Actor-Critic framework.
6//!
7//! A publishable reinforcement learning library implementing a novel architecture where the
8//! actor uses iterative top-down/bottom-up predictive coding inference loops instead of
9//! standard feedforward passes, combined with a standard MLP critic for value estimation.
10//!
11//! # Key Components
12//!
13//! - [`PcActor`] — Predictive coding network with variable hidden topology, iterative
14//!   inference loop, and surprise scoring.
15//! - [`MlpCritic`] — Standard MLP value function with MSE loss backpropagation.
16//! - [`PcActorCritic`] — Integrated agent: act, learn (episodic/continuous), surprise-based
17//!   scheduling, save/load.
18//! - [`serializer`] — JSON weight persistence with checkpointing support.
19
20pub mod activation;
21pub mod error;
22pub mod layer;
23pub mod linalg;
24pub mod matrix;
25pub mod mlp_critic;
26pub mod pc_actor;
27pub mod pc_actor_critic;
28pub mod serializer;
29
30pub use activation::Activation;
31pub use error::PcError;
32pub use layer::{Layer, LayerDef};
33pub use linalg::cpu::CpuLinAlg;
34pub use linalg::golub_kahan::{GolubKahanSvd, SvdError};
35pub use linalg::LinAlg;
36pub use matrix::{
37    argmax_masked, cca_neuron_alignment, rms_error, sample_from_probs, softmax_masked, Matrix,
38    GRAD_CLIP, WEIGHT_CLIP,
39};
40pub use mlp_critic::{MlpCritic, MlpCriticConfig, MlpCriticWeights};
41pub use pc_actor::{InferResult, PcActor, PcActorConfig, SelectionMode};
42pub use pc_actor_critic::{ActivationCache, PcActorCritic, PcActorCriticConfig, TrajectoryStep};
43pub use serializer::{
44    checkpoint_filename, load_agent, load_agent_generic, save_agent, save_checkpoint,
45    AgentMetadata, PcActorWeights, SaveFile, TrainingMetrics,
46};
47
48/// Type alias: CPU-backed layer.
49pub type LayerCpu = Layer<CpuLinAlg>;
50/// Type alias: CPU-backed PC actor.
51pub type PcActorCpu = PcActor<CpuLinAlg>;
52/// Type alias: CPU-backed MLP critic.
53pub type MlpCriticCpu = MlpCritic<CpuLinAlg>;
54/// Type alias: CPU-backed PC actor-critic agent.
55pub type PcActorCriticCpu = PcActorCritic<CpuLinAlg>;
pc_rl_core/lib.rs

pc_rl_core/
lib.rs
