Skip to main content

nexcore_cognition/
lib.rs

1//! # nexcore-cognition
2//!
3//! Typed cognitive engine — the transformer algorithm as strict Rust.
4//!
5//! ## Meta-cognitive origin
6//!
7//! This crate captures the fundamental algorithm behind large language model
8//! cognition: attention selects, transformation processes, generation builds.
9//! Each module maps to an observable pattern in how neural networks process
10//! information, translated faithfully into Rust's type system.
11//!
12//! ## Architecture (bottom-up)
13//!
14//! ```text
15//! pipeline ──► generator ──► block ──► attention + feed_forward
16//!                              │          │            │
17//!                              ▼          ▼            ▼
18//!                          normalize   mask         tensor
19//!                          residual                   │
20//!                          embedding                error
21//! ```
22//!
23//! ## T1 Primitive grounding
24//!
25//! | Module       | Primitives                       | Cognitive role           |
26//! |-------------|----------------------------------|--------------------------|
27//! | tensor      | N, Σ, ×, ∂, κ                   | Numerical substrate      |
28//! | embedding   | μ, λ, N                          | Symbol → vector          |
29//! | attention   | κ, →, N, μ, Σ                    | Relevance selection      |
30//! | feed_forward| μ, ς                             | Nonlinear transformation |
31//! | residual    | π, Σ                             | Context preservation     |
32//! | normalize   | ∂, N                             | Signal stability         |
33//! | block       | σ, ∃                             | Composable unit          |
34//! | mask        | ∂, →, ∝                          | Causal constraint        |
35//! | generator   | σ, ρ, ∝, →, ∂                   | Autoregressive output    |
36//! | sample      | N, ∂, ν, κ                       | Stochastic selection     |
37//! | metrics     | κ, N, ν, μ                       | Self-measurement         |
38//! | pipeline    | σ, →, Σ, κ                       | Full cognitive flow      |
39
40#![warn(missing_docs)]
41#![cfg_attr(
42    not(test),
43    deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)
44)]
45#![forbid(unsafe_code)]
46
47pub mod error;
48pub mod tensor;
49
50// Layer 2: modules that depend only on tensor
51pub mod embedding;
52pub mod mask;
53pub mod normalize;
54pub mod residual;
55
56// Layer 3: the cognitive core
57pub mod attention;
58pub mod feed_forward;
59
60// Layer 4: composition — the complete engine
61pub mod block;
62pub mod generator;
63pub mod metrics;
64pub mod pipeline;
65pub mod sample;
66
67/// Create a seeded or OS-random `StdRng` for use with the cognitive engine.
68///
69/// Downstream crates (e.g., nexcore-mcp) call this instead of depending on `rand` directly.
70pub fn make_rng(seed: Option<u64>) -> rand::rngs::StdRng {
71    use rand::SeedableRng;
72    match seed {
73        Some(s) => rand::rngs::StdRng::seed_from_u64(s),
74        None => rand::rngs::StdRng::from_os_rng(),
75    }
76}