rust_ai_core/
lib.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tyler Zervas
3
4//! # rust-ai-core
5//!
6//! Shared core utilities for the rust-ai ecosystem, providing unified abstractions
7//! for device selection, error handling, configuration validation, and `CubeCL` interop.
8//!
9//! ## Why This Crate Exists
10//!
11//! The rust-ai ecosystem consists of multiple specialized crates (peft-rs, qlora-rs,
12//! unsloth-rs, etc.) that share common patterns. Without a foundation layer, each crate
13//! would independently implement device selection, error types, and GPU dispatch logic,
14//! leading to inconsistency and code duplication.
15//!
16//! rust-ai-core consolidates these patterns into a single, well-tested foundation that
17//! ensures consistency across the ecosystem and provides a unified user experience.
18//!
19//! ## Design Philosophy
20//!
21//! **CUDA-first**: All operations prefer GPU execution. CPU is a fallback that emits
22//! warnings, not a silent alternative. This design ensures users are immediately aware
23//! when they're not getting optimal performance, rather than silently running slower.
24//!
25//! **Zero-cost abstractions**: Traits compile to static dispatch with no vtable overhead.
26//! The abstraction layer adds no runtime cost compared to direct implementations.
27//!
28//! **Fail-fast validation**: Configuration errors are caught at construction time, not
29//! deep in a training loop. This saves users from wasted compute time.
30//!
31//! ## Modules
32//!
33//! - [`device`] - CUDA-first device selection with environment variable overrides
34//! - [`error`] - Unified error types across all rust-ai crates
35//! - [`traits`] - Common traits for configs, quantization, and GPU dispatch
36//! - [`memory`] - Memory estimation and tracking utilities
37//! - [`dtype`] - Data type utilities and precision helpers
38//! - [`logging`] - Unified logging and observability
39//! - `cubecl` - `CubeCL` ↔ Candle tensor interoperability (requires `cuda` feature)
40//!
41//! ## Quick Start
42//!
43//! ```rust
44//! use rust_ai_core::{get_device, DeviceConfig, CoreError, Result};
45//!
46//! fn main() -> Result<()> {
47//!     // Get CUDA device with automatic fallback + warning
48//!     // Why: Users should know when they're not getting GPU acceleration
49//!     let device = get_device(&DeviceConfig::default())?;
50//!
51//!     // Or with explicit configuration from environment
52//!     // Why: Production deployments need runtime configuration without recompilation
53//!     let config = DeviceConfig::from_env();
54//!     let device = get_device(&config)?;
55//!
56//!     Ok(())
57//! }
58//! ```
59//!
60//! ## Feature Flags
61//!
62//! | Feature | Description | Dependencies |
63//! |---------|-------------|--------------|
64//! | `cuda` | Enable CUDA support via Candle and `CubeCL` kernels | cubecl, cubecl-cuda |
65//!
66//! ## Crate Integration
67//!
68//! All rust-ai crates should depend on rust-ai-core and use its shared types.
69//! This ensures consistent error handling, device selection, and trait implementations
70//! across the ecosystem.
71//!
72//! ```toml
73//! [dependencies]
74//! rust-ai-core = { version = "0.1", features = ["cuda"] }
75//! ```
76//!
77//! ## Environment Variables
78//!
79//! | Variable | Description | Example |
80//! |----------|-------------|---------|
81//! | `RUST_AI_FORCE_CPU` | Force CPU execution | `1` or `true` |
82//! | `RUST_AI_CUDA_DEVICE` | Select CUDA device ordinal | `0`, `1` |
83//! | `RUST_LOG` | Control logging level | `rust_ai_core=debug` |
84
85#![warn(missing_docs)]
86#![warn(clippy::all)]
87#![warn(clippy::pedantic)]
88#![allow(clippy::module_name_repetitions)]
89
90pub mod device;
91pub mod dtype;
92pub mod error;
93pub mod logging;
94pub mod memory;
95pub mod traits;
96
97#[cfg(feature = "cuda")]
98pub mod cubecl;
99
100// Re-exports for convenience.
101//
102// Why: Users shouldn't need to navigate the module hierarchy for common types.
103// Flat re-exports provide a clean, discoverable API surface.
104pub use device::{get_device, warn_if_cpu, DeviceConfig};
105pub use dtype::{bytes_per_element, is_floating_point, DTypeExt};
106pub use error::{CoreError, Result};
107pub use logging::{init_logging, LogConfig};
108pub use memory::{estimate_tensor_bytes, MemoryTracker};
109pub use traits::{Dequantize, GpuDispatchable, Quantize, ValidatableConfig};
110
111#[cfg(feature = "cuda")]
112pub use cubecl::{
113    allocate_output_buffer, candle_to_cubecl_handle, cubecl_to_candle_tensor,
114    has_cubecl_cuda_support, TensorBuffer,
115};
116
117/// Crate version for runtime version checking.
118///
119/// Why: Dependent crates may need to verify compatibility at runtime,
120/// especially when loading serialized data that includes version info.
121pub const VERSION: &str = env!("CARGO_PKG_VERSION");
rust_ai_core/lib.rs

rust_ai_core/
lib.rs
