limbic-critic

Reward-shaping and modulator-mapping primitive for SNNs: map an environment objective into a local ModulatorVector. This is not a full actor–critic, learned value function, or RL training framework.

Mission

limbic-critic turns a scalar observation (plus optional risk / stress / surprise signals) into constrained neuromodulator concentrations. Downstream plasticity rules such as neuromod::rm_stdp can consume those scalars — but this crate does not depend on neuromod. Convert ModulatorVector → NeuroModulators in plasticity-lab (the bridge) or in your application.

What “TD” means here: TDCritic keeps an exponential moving average of successive objective deltas (objective − prev_objective). That EMA is tanh-mapped into dopamine; |delta|.tanh() becomes acetylcholine. It is not a learned V(s) / advantage estimator and does not run an actor–critic loop.

Architecture (condensed):

• Environment trait — abstract interface for any measurable external system (simulation score, trading PnL, LLM loss, etc.)
• Critics (shapers) — SimpleCritic clamps the current observation; TDCritic maps an EMA of objective deltas into signed dopamine. try_assess is the poisoning-safe path: it returns CriticError on NaN / ±∞ and does not update TDCritic state. assess keeps IEEE f32 passthrough for compatibility (a non-finite TD objective can poison later steps).
• Modulator mapping — constrained f32 fields for dopamine (shaped reward / delta), serotonin (risk/volatility), acetylcholine (surprise / |delta|), and norepinephrine (stress/telemetry)

MSRV: Rust 1.98.1 (rust-version in Cargo.toml, rust-toolchain.toml, and CI). CI Build & Test runs on Linux, macOS, and Windows.

Getting Started

Until published on crates.io, depend on the git repository:

[dependencies]
limbic-critic = { git = "https://github.com/Limen-Neural/limbic-critic" }

After publish:

cargo add limbic-critic

Run the generic environment example:

cargo run --example generic_environment

Ecosystem

Sibling crates live under the Limen-Neural organization. This crate does not take Cargo dependencies on those siblings; integration happens in application or bridge crates.

Scope and Ownership Boundaries

See the full matrix: docs/BOUNDARY_MATRIX.md (LIM-9 / GH#9).

Owns:

• Reward shaping / modulator mapping (SimpleCritic, TDCritic)
• The Environment trait
• Local ModulatorVector output structure

Does not own:

• Actor–critic loops, policy gradients, or learned value networks
• Training loops or SNN model definitions
• Domain-specific rewards (mining, trading, games)
• Environment implementations (belong in apps/adapters)
• Neuromodulator dynamics / decay (upstream SNN crates)
• Conversion of ModulatorVector → neuromod::NeuroModulators (bridge: plasticity-lab)

Forbidden:

• Inter-repo Cargo dependencies on sibling crates such as neuromod, plasticity-lab, or other SNN primitives (keeps the crate modular and decoupled)

Development

cargo check
cargo test
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --check

# Coverage (the exact invocation the coverage workflow runs)
cargo install cargo-llvm-cov cargo-nextest
cargo llvm-cov nextest --all-features --profile ci --lcov --output-path lcov.info
# HTML report: cargo llvm-cov --all-features --html

CONTRIBUTING.md carries the authoritative pre-PR check list, including the cargo package content assertions that CI gates on.

These development commands, hygiene improvements, test assertions, MSRV declaration, artifact cleanup, and Codecov integration were contributed by the following GitHub issues (bundled as beads lc-r97 / PR #28):

• GH-16: Remove tracked CI log artifacts
• GH-17: Remove unused serde dependency
• GH-18: Add serotonin/volatility assertions for critic assess()
• GH-24: Add rust-version MSRV to Cargo.toml
• GH-27: Add Codecov coverage reporting (cargo-llvm-cov + badge)

Coverage

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE-2.0 or Apache-2.0)
• MIT license (LICENSE-MIT or MIT)

at your option.