docs: expand public API rustdoc and gate CI on cargo doc (#36)

Document ModulatorVector field semantics, SimpleCritic/TDCritic
assess mappings and ranges (dopamine [0,1] vs [-1,1]), TDCritic
state/alpha, and Environment trait methods. Add module-level
usage examples with stub environments. Fail CI when rustdoc
warnings appear via RUSTDOCFLAGS=-D warnings.

Closes #22
Closes #23

Author: rmems

.github/workflows/ci.yml

@@ -43,6 +43,11 @@ jobs:
       - name: Clippy (lint)
         run: cargo clippy --all-targets --all-features -- -D warnings
 
+      - name: Build documentation
+        run: cargo doc --no-deps --all-features
+        env:
+          RUSTDOCFLAGS: "-D warnings"
+
       - name: Build
         run: cargo build --all-features
 

src/critic.rs

@@ -1,26 +1,107 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-//! RL Critic and Reward Shaping
+//! RL critic and reward shaping.
 //!
-//! This module contains the core logic for translating environmental
-//! observations into neuromodulatory signals.
+//! Translates an [`Environment`] observation into a
+//! [`ModulatorVector`] of neuromodulator
+//! concentrations. Two critics are provided:
+//!
+//! - [`SimpleCritic`] — stateless, maps the immediate objective and optional
+//!   environment signals.
+//! - [`TDCritic`] — stateful temporal-difference critic that tracks reward
+//!   improvement over time.
+//!
+//! # Quick start
+//!
+//! ```rust
+//! use limbic_critic::{Environment, SimpleCritic, TDCritic, ModulatorVector};
+//!
+//! /// Minimal stub environment used only for documentation examples.
+//! struct StubEnv {
+//!     objective: f32,
+//!     surprise: f32,
+//! }
+//!
+//! impl Environment for StubEnv {
+//!     fn objective(&self) -> f32 {
+//!         self.objective
+//!     }
+//!     fn surprise(&self) -> f32 {
+//!         self.surprise
+//!     }
+//! }
+//!
+//! let env = StubEnv {
+//!     objective: 0.75,
+//!     surprise: 0.3,
+//! };
+//!
+//! // Stateless mapping: dopamine ∈ [0, 1], ACh from Environment::surprise
+//! let simple: ModulatorVector = SimpleCritic::assess(&env);
+//! assert!((0.0..=1.0).contains(&simple.dopamine));
+//! assert_eq!(simple.acetylcholine, 0.3);
+//!
+//! // Temporal-difference critic: dopamine ∈ [-1, 1] after tanh of EMA(TD)
+//! let mut td = TDCritic::new(0.1);
+//! let first = td.assess(&env);
+//! assert!((-1.0..=1.0).contains(&first.dopamine));
+//! ```
 
 use crate::environment::Environment;
 use crate::modulators::ModulatorVector;
 
-/// A stateless critic that calculates neuromodulator levels from the
-/// environment's immediate signals.
+/// A stateless critic that maps immediate environment signals to neuromodulators.
+///
+/// `SimpleCritic` stores no history. It therefore cannot compute temporal
+/// surprise on its own: acetylcholine is read directly from
+/// [`Environment::surprise`] and clamped to `[0.0, 1.0]`. Use [`TDCritic`]
+/// when acetylcholine should be derived from the absolute TD error
+/// (`abs(td_error).tanh()`).
+///
+/// # Mapping
+///
+/// | Field | Source | Range |
+/// |-------|--------|-------|
+/// | `dopamine` | `env.objective()` if positive, else `0.0` | `[0.0, 1.0]` |
+/// | `serotonin` | `env.volatility()` | `[0.0, 1.0]` |
+/// | `acetylcholine` | `env.surprise()` | `[0.0, 1.0]` |
+/// | `norepinephrine` | `env.stress()` | `[0.0, 1.0]` |
+///
+/// # Example
 ///
-/// `SimpleCritic` intentionally does not infer acetylcholine from temporal
-/// objective deltas because it stores no previous state. Instead,
-/// acetylcholine is read directly from [`Environment::surprise`] and clamped
-/// to the valid modulator range. Use [`TDCritic`] when acetylcholine should be
-/// derived from temporal-difference surprise (`abs(td_error).tanh()`).
+/// ```rust
+/// use limbic_critic::{Environment, SimpleCritic};
+///
+/// struct StubEnv;
+/// impl Environment for StubEnv {
+///     fn objective(&self) -> f32 { 0.8 }
+///     fn surprise(&self) -> f32 { 0.4 }
+/// }
+///
+/// let mods = SimpleCritic::assess(&StubEnv);
+/// assert_eq!(mods.dopamine, 0.8);
+/// assert_eq!(mods.acetylcholine, 0.4);
+/// ```
 pub struct SimpleCritic;
 
 impl SimpleCritic {
-    /// Calculates neuromodulator concentrations based on the current
-    /// state of the environment.
+    /// Calculate neuromodulator concentrations from the current environment.
+    ///
+    /// # Dopamine
+    ///
+    /// Positive [`Environment::objective`] values are clamped to
+    /// **`[0.0, 1.0]`**. Negative or zero objectives produce `dopamine = 0.0`
+    /// (no negative reward signal).
+    ///
+    /// # Acetylcholine
+    ///
+    /// Taken from [`Environment::surprise`] and clamped to **`[0.0, 1.0]`**.
+    /// This critic does **not** infer ACh from objective deltas.
+    ///
+    /// # Other fields
+    ///
+    /// - `serotonin` ← [`Environment::volatility`] clamped to `[0.0, 1.0]`
+    /// - `norepinephrine` ← [`Environment::stress`] clamped to `[0.0, 1.0]`
     pub fn assess(env: &impl Environment) -> ModulatorVector {
         let objective = env.objective();
 
@@ -44,14 +125,75 @@ impl SimpleCritic {
     }
 }
 
-/// A critic that calculates reward based on the Temporal Difference (TD) error.
+/// A stateful temporal-difference (TD) critic.
+///
+/// Tracks the previous objective and an exponential moving average (EMA) of
+/// the TD error so that dopamine reflects *change* in reward rather than
+/// absolute level. Acetylcholine is derived from surprise in the TD signal
+/// (`abs(td_error).tanh()`), not from [`Environment::surprise`].
+///
+/// # Internal state
+///
+/// | Field | Meaning |
+/// |-------|---------|
+/// | `prev_objective` | Objective observed on the previous [`assess`](Self::assess) call; starts at `0.0`. |
+/// | `ema_reward` | EMA of successive TD errors (`objective - prev_objective`); starts at `0.0`. |
+/// | `alpha` | EMA learning rate in `(0, 1]`. Higher values weight recent TD errors more heavily. |
+///
+/// # Mapping
+///
+/// | Field | Source | Range |
+/// |-------|--------|-------|
+/// | `dopamine` | `ema_reward.tanh()` | **`[-1.0, 1.0]`** |
+/// | `serotonin` | `env.volatility()` | `[0.0, 1.0]` |
+/// | `acetylcholine` | `abs(td_error).tanh()` | `[0.0, 1.0]` |
+/// | `norepinephrine` | `env.stress()` | `[0.0, 1.0]` |
+///
+/// # Example
+///
+/// ```rust
+/// use limbic_critic::{Environment, TDCritic};
+///
+/// struct StubEnv(f32);
+/// impl Environment for StubEnv {
+///     fn objective(&self) -> f32 { self.0 }
+/// }
+///
+/// let mut td = TDCritic::new(0.1);
+/// let step1 = td.assess(&StubEnv(0.0));
+/// let step2 = td.assess(&StubEnv(1.0));
+/// // Improvement produces a higher (more positive) dopamine signal.
+/// assert!(step2.dopamine > step1.dopamine);
+/// ```
 pub struct TDCritic {
     prev_objective: f32,
     ema_reward: f32,
     alpha: f32, // Learning rate for the EMA
 }
 
 impl TDCritic {
+    /// Create a new TD critic with the given EMA learning rate.
+    ///
+    /// `alpha` controls how quickly the internal EMA of TD errors adapts:
+    ///
+    /// - **Small `alpha`** (e.g. `0.05`) — smooth, slow reaction to changes.
+    /// - **Large `alpha`** (e.g. `0.5`) — fast tracking of recent TD errors.
+    ///
+    /// Initial state:
+    /// - `prev_objective = 0.0`
+    /// - `ema_reward = 0.0`
+    ///
+    /// The first [`assess`](Self::assess) call therefore treats the TD error
+    /// as `objective - 0.0`.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use limbic_critic::TDCritic;
+    ///
+    /// let critic = TDCritic::new(0.2);
+    /// // critic is ready; call assess(&env) on each time step
+    /// ```
     pub fn new(alpha: f32) -> Self {
         Self {
             prev_objective: 0.0,
@@ -60,7 +202,26 @@ impl TDCritic {
         }
     }
 
-    /// Calculates neuromodulator concentrations based on the TD error.
+    /// Calculate neuromodulator concentrations from the TD error.
+    ///
+    /// # Algorithm
+    ///
+    /// 1. `td_error = env.objective() - prev_objective`
+    /// 2. Store the current objective as `prev_objective` for the next call.
+    /// 3. `acetylcholine = abs(td_error).tanh()`, clamped to `[0.0, 1.0]`.
+    /// 4. Update EMA: `ema_reward ← (1 - alpha) * ema_reward + alpha * td_error`.
+    /// 5. `dopamine = ema_reward.tanh()`, clamped to **`[-1.0, 1.0]`**.
+    /// 6. `serotonin` / `norepinephrine` from `volatility` / `stress`, each
+    ///    clamped to `[0.0, 1.0]`.
+    ///
+    /// Unlike [`SimpleCritic::assess`], this method mutates internal state and
+    /// can produce **negative dopamine** when recent TD errors are negative
+    /// (worsening outcomes).
+    ///
+    /// # Parameters
+    ///
+    /// - `env` — environment providing the current objective (and optional
+    ///   stress / volatility signals).
     pub fn assess(&mut self, env: &impl Environment) -> ModulatorVector {
         let objective = env.objective();
         let td_error = objective - self.prev_objective;

src/environment.rs

@@ -1,50 +1,123 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-//! Environment Trait
+//! Environment interface for critic evaluation.
 //!
-//! Defines the interface for any external system that the `limbic-critic`
-//! needs to evaluate. This trait abstracts the source of the objective
-//! function, allowing the critic to be agnostic to whether it's evaluating
-//! a trading bot, a game AI, or a hardware system.
+//! The [`Environment`] trait abstracts the external system that a critic
+//! observes — a trading bot, game AI, hardware controller, LLM training loop,
+//! or any other process that can expose a scalar objective (and optional
+//! risk / stress / surprise signals).
+//!
+//! Critics such as [`SimpleCritic`](crate::SimpleCritic) and
+//! [`TDCritic`](crate::TDCritic) depend only on this trait, remaining
+//! agnostic to domain-specific details.
+//!
+//! # Implementing `Environment`
+//!
+//! Only [`objective`](Environment::objective) is required. The other methods
+//! default to `0.0` and can be overridden when the corresponding modulator
+//! channel is useful:
+//!
+//! | Method | Default | Used by critics as |
+//! |--------|---------|--------------------|
+//! | [`objective`](Environment::objective) | *(required)* | reward / TD target |
+//! | [`volatility`](Environment::volatility) | `0.0` | serotonin |
+//! | [`surprise`](Environment::surprise) | `0.0` | acetylcholine (`SimpleCritic` only) |
+//! | [`stress`](Environment::stress) | `0.0` | norepinephrine |
+//!
+//! # Example
+//!
+//! ```rust
+//! use limbic_critic::{Environment, SimpleCritic};
+//!
+//! struct TradingBot {
+//!     pnl: f32,
+//!     market_vol: f32,
+//! }
+//!
+//! impl Environment for TradingBot {
+//!     fn objective(&self) -> f32 {
+//!         self.pnl
+//!     }
+//!     fn volatility(&self) -> f32 {
+//!         self.market_vol
+//!     }
+//! }
+//!
+//! let bot = TradingBot {
+//!     pnl: 0.6,
+//!     market_vol: 0.25,
+//! };
+//! let mods = SimpleCritic::assess(&bot);
+//! assert_eq!(mods.dopamine, 0.6);
+//! assert_eq!(mods.serotonin, 0.25);
+//! ```
 
+/// Interface for any external system that a limbic critic can evaluate.
+///
+/// Implementors provide at least a scalar objective; optional methods supply
+/// secondary signals that map onto serotonin, acetylcholine, and
+/// norepinephrine channels.
+///
+/// See the [module-level documentation](self) for the full mapping table and
+/// a worked example.
 pub trait Environment {
     /// Returns the current scalar objective value from the environment.
     ///
-    /// This value represents the primary metric that the critic should
-    /// optimize. It could be profit-and-loss, cross-entropy loss,
-    /// game score, or any other performance indicator.
+    /// This is the primary metric the critic optimizes — profit-and-loss,
+    /// cross-entropy loss (negated), game score, accuracy, or any other
+    /// performance indicator.
+    ///
+    /// Prefer a stable, domain-normalized scale when possible. Critics also
+    /// apply their own clamps / nonlinearities (`clamp`, `tanh`) so raw
+    /// unnormalized values are accepted, but extreme magnitudes will saturate
+    /// the resulting modulators.
+    ///
+    /// # Used by
     ///
-    /// The value should be normalized to a consistent range if possible,
-    /// although the critic's reward shaping functions should also be
-    /// robust to unnormalized inputs.
+    /// - [`SimpleCritic`](crate::SimpleCritic): positive values → dopamine in
+    ///   `[0, 1]`; non-positive → dopamine `0`.
+    /// - [`TDCritic`](crate::TDCritic): difference from the previous objective
+    ///   drives the TD error and thus dopamine / acetylcholine.
     fn objective(&self) -> f32;
 
-    /// Returns a scalar value representing environmental volatility or risk.
+    /// Returns environmental volatility or risk.
     ///
-    /// This is optional and can be used to modulate serotonin levels.
-    /// For a trading bot, this might be market volatility.
-    /// For a game, it could be the number of enemies on screen.
-    /// Defaults to 0.0 if not implemented.
+    /// Optional. Mapped to **serotonin** (clamped to `[0.0, 1.0]`) by both
+    /// critics. Defaults to `0.0` if not overridden.
+    ///
+    /// Domain examples:
+    /// - Trading: realized or implied market volatility.
+    /// - Games: number of threats / enemy density.
+    /// - Training: loss variance over a recent window.
     fn volatility(&self) -> f32 {
         0.0
     }
 
-    /// Returns a scalar value representing environmental surprise or novelty.
+    /// Returns environmental surprise or novelty.
+    ///
+    /// Optional. Used by [`SimpleCritic`](crate::SimpleCritic) as the source
+    /// of **acetylcholine** (clamped to `[0.0, 1.0]`).
+    /// [`TDCritic`](crate::TDCritic) ignores this method and instead derives
+    /// acetylcholine from `abs(td_error).tanh()`. Defaults to `0.0` if not
+    /// overridden.
     ///
-    /// This is optional and can be used to modulate acetylcholine levels in
-    /// stateless critics. For a trading bot, this might be anomaly score.
-    /// For a game, it could be unexpected state changes or newly discovered
-    /// entities. Defaults to 0.0 if not implemented.
+    /// Domain examples:
+    /// - Trading: anomaly or regime-change score.
+    /// - Games: unexpected state transitions or newly discovered entities.
+    /// - Sensors: prediction residual / novelty detector output.
     fn surprise(&self) -> f32 {
         0.0
     }
 
-    /// Returns a scalar value representing system stress or instability.
+    /// Returns system stress or instability.
+    ///
+    /// Optional. Mapped to **norepinephrine** (clamped to `[0.0, 1.0]`) by
+    /// both critics. Defaults to `0.0` if not overridden.
     ///
-    /// This is optional and can be used to modulate norepinephrine levels.
-    /// For a hardware system, this might be temperature or power draw.
-    /// For a software system, it could be error rates or latency.
-    /// Defaults to 0.0 if not implemented.
+    /// Domain examples:
+    /// - Hardware: temperature, power draw, thermal throttling.
+    /// - Software: error rate, p99 latency, queue depth.
+    /// - Agents: resource depletion or constraint violation severity.
     fn stress(&self) -> f32 {
         0.0
     }