entrenar/
lib.rs

1//! # Entrenar: Training & Optimization Library
2//!
3//! Entrenar provides a tape-based autograd engine with optimizers, LoRA/QLoRA,
4//! quantization (QAT/PTQ), model merging (TIES/DARE/SLERP), and knowledge distillation.
5//!
6//! ## Architecture
7//!
8//! - **autograd**: Tape-based automatic differentiation
9//! - **optim**: Optimizers (SGD, Adam, AdamW)
10//! - **lora**: Low-rank adaptation with QLoRA support
11//! - **quant**: Quantization-aware training and post-training quantization
12//! - **merge**: Model merging methods
13//! - **distill**: Knowledge distillation
14//! - **config**: Declarative YAML configuration
15//! - **train**: High-level training loop
16//! - **io**: Model saving and loading (JSON, YAML formats)
17//! - **hf_pipeline**: HuggingFace model fetching and distillation
18//! - **citl**: Compiler-in-the-Loop training with RAG-based fix suggestions (feature-gated)
19//! - **efficiency**: Cost tracking, device detection, and performance benchmarking
20//! - **eval**: Model evaluation framework with metrics, comparison, and drift detection
21//! - **sovereign**: Air-gapped deployment and distribution packaging
22//! - **research**: Academic research artifacts, citations, and archive deposits
23//! - **ecosystem**: PAIML stack integrations (Batuta, Realizar, Ruchy)
24//! - **dashboard**: Real-time training monitoring and WASM bindings
25//! - **yaml_mode**: Declarative YAML Mode Training (v1.0 spec)
26//! - **transformer**: Transformer layers with autograd support
27//! - **moe**: Mixture of Experts sparse routing layer
28//! - **decision**: Decision pattern storage and CITL trainer (GH-28, GH-29)
29//! - **cli**: Command-line interface handlers
30//! - **finetune**: Fine-tuning pipeline with Popperian QA (SPEC-FT-001)
31
32// Test code uses unwrap/expect-family freely (established convention; see
33// crates/aprender-core/src/lib.rs).
34#![cfg_attr(test, allow(clippy::disallowed_methods))]
35// Pedantic doc-formatting lints: allowed per workspace policy.
36#![allow(clippy::doc_lazy_continuation)]
37// PMAT-132: every `unsafe { ... }` block (incl. the CUDA forward/backward paths)
38// carries a `// SAFETY:` comment. Promote the workspace `warn` to a hard error for
39// this crate now that the lib is fully cleared, so regressions fail the build.
40#![deny(clippy::undocumented_unsafe_blocks)]
41
42// Contract assertions from YAML (pv codegen)
43#[macro_use]
44#[allow(unused_macros)]
45mod generated_contracts;
46
47// Fallback macros for contracts not yet in build.rs codegen
48// (embedding-lookup-v1 was added in provable-contracts 0.2 but
49// entrenar's build.rs hasn't been updated to generate it yet)
50#[cfg(not(feature = "__has_embedding_contract"))]
51macro_rules! contract_pre_embedding_lookup {
52    () => {{}};
53    ($input:expr) => {{
54        let _ = &$input;
55    }};
56}
57#[cfg(not(feature = "__has_embedding_contract"))]
58#[allow(unused_macros)]
59macro_rules! contract_post_embedding_lookup {
60    ($result:expr) => {{
61        let _ = &$result;
62    }};
63}
64
65// Fallback stubs for contract macros not in generated_contracts.rs.
66// PMAT-517: These MUST cover every contract_pre_*/contract_post_* used in source
67// but not generated by provable-contracts codegen. Without these, crates.io builds
68// fail because the binding.yaml is not available outside the workspace.
69// Run `bash scripts/check_publish_safety.sh` to verify completeness.
70macro_rules! contract_pre_data_read { () => {{}}; ($($x:expr),+ $(,)?) => {{ $(let _ = &$x;)+ }}; }
71macro_rules! contract_pre_data_mut { () => {{}}; ($($x:expr),+ $(,)?) => {{ $(let _ = &$x;)+ }}; }
72macro_rules! contract_pre_transpose_tracked { () => {{}}; ($($x:expr),+ $(,)?) => {{ $(let _ = &$x;)+ }}; }
73#[allow(unused_macros)]
74macro_rules! contract_pre_with_resident_weights { () => {{}}; ($($x:expr),+ $(,)?) => {{ $(let _ = &$x;)+ }}; }
75#[allow(unused_macros)]
76macro_rules! contract_pre_alignment_enforcement { () => {{}}; ($($x:expr),+ $(,)?) => {{ $(let _ = &$x;)+ }}; }
77#[allow(unused_macros)]
78macro_rules! contract_pre_geometric_mean { () => {{}}; ($($x:expr),+ $(,)?) => {{ $(let _ = &$x;)+ }}; }
79#[allow(unused_macros)]
80macro_rules! contract_pre_layer_composition { () => {{}}; ($($x:expr),+ $(,)?) => {{ $(let _ = &$x;)+ }}; }
81#[allow(unused_macros)]
82macro_rules! contract_pre_mqs_pass_rate { () => {{}}; ($($x:expr),+ $(,)?) => {{ $(let _ = &$x;)+ }}; }
83
84pub mod aprender_compat;
85pub mod autograd;
86#[cfg(feature = "citl")]
87pub mod citl;
88pub mod cli;
89pub mod config;
90pub mod dashboard;
91pub mod decision;
92pub mod distill;
93pub mod ecosystem;
94pub mod efficiency;
95pub mod eval;
96#[cfg(not(target_arch = "wasm32"))]
97pub mod finetune;
98pub mod generative;
99#[cfg(not(target_arch = "wasm32"))]
100pub mod gpu;
101#[cfg(all(not(target_arch = "wasm32"), feature = "hub"))]
102pub mod hf_pipeline;
103pub mod inference;
104pub mod integrity;
105pub mod io;
106pub mod lora;
107pub mod merge;
108pub mod models;
109pub mod moe;
110pub mod monitor;
111pub mod numerical;
112pub mod optim;
113pub mod pipeline;
114pub mod prune;
115pub mod quality;
116pub mod quant;
117pub mod research;
118pub mod run;
119pub mod safety;
120pub mod search;
121pub mod server;
122pub mod sovereign;
123pub mod sovereign_array;
124pub mod staging;
125pub mod storage;
126pub mod tokenizer;
127pub mod trace;
128pub mod tracking;
129pub mod train;
130pub mod training;
131pub mod transformer;
132#[cfg(feature = "viz")]
133pub mod viz;
134pub mod yaml_mode;
135
136pub mod error;
137
138// Re-export commonly used types
139pub use autograd::{backward, Context, Tensor};
140pub use error::{Error, Result};
entrenar/lib.rs

entrenar/
lib.rs
