Crate rust_ai_core 

rust-ai-core

Shared core utilities for the rust-ai ecosystem, providing unified abstractions for device selection, error handling, configuration validation, and CubeCL interop.

Why This Crate Exists

The rust-ai ecosystem consists of multiple specialized crates (peft-rs, qlora-rs, unsloth-rs, etc.) that share common patterns. Without a foundation layer, each crate would independently implement device selection, error types, and GPU dispatch logic, leading to inconsistency and code duplication.

rust-ai-core consolidates these patterns into a single, well-tested foundation that ensures consistency across the ecosystem and provides a unified user experience.

Design Philosophy

CUDA-first: All operations prefer GPU execution. CPU is a fallback that emits warnings, not a silent alternative. This design ensures users are immediately aware when they’re not getting optimal performance, rather than silently running slower.

Zero-cost abstractions: Traits compile to static dispatch with no vtable overhead. The abstraction layer adds no runtime cost compared to direct implementations.

Fail-fast validation: Configuration errors are caught at construction time, not deep in a training loop. This saves users from wasted compute time.

Modules

• device - CUDA-first device selection with environment variable overrides
• error - Unified error types across all rust-ai crates
• traits - Common traits for configs, quantization, and GPU dispatch
• memory - Memory estimation and tracking utilities
• dtype - Data type utilities and precision helpers
• logging - Unified logging and observability
• cubecl - CubeCL ↔ Candle tensor interoperability (requires cuda feature)

Quick Start

use rust_ai_core::{get_device, DeviceConfig, CoreError, Result};

fn main() -> Result<()> {
    // Get CUDA device with automatic fallback + warning
    // Why: Users should know when they're not getting GPU acceleration
    let device = get_device(&DeviceConfig::default())?;

    // Or with explicit configuration from environment
    // Why: Production deployments need runtime configuration without recompilation
    let config = DeviceConfig::from_env();
    let device = get_device(&config)?;

    Ok(())
}

Feature Flags

Feature	Description	Dependencies
cuda	Enable CUDA support via Candle and CubeCL kernels	cubecl, cubecl-cuda
python	Enable Python bindings via PyO3	pyo3, numpy

Crate Integration

All rust-ai crates should depend on rust-ai-core and use its shared types. This ensures consistent error handling, device selection, and trait implementations across the ecosystem.

[dependencies]
rust-ai-core = { version = "0.1", features = ["cuda"] }

Environment Variables

Variable	Description	Example
RUST_AI_FORCE_CPU	Force CPU execution	1 or true
RUST_AI_CUDA_DEVICE	Select CUDA device ordinal	0, 1
RUST_LOG	Control logging level	rust_ai_core=debug

Re-exports

pub use device::get_device;

pub use device::warn_if_cpu;

pub use device::DeviceConfig;

pub use dtype::bytes_per_element;

pub use dtype::is_floating_point;

pub use dtype::DTypeExt;

pub use error::CoreError;

pub use error::Result;

pub use logging::init_logging;

pub use logging::LogConfig;

pub use memory::estimate_tensor_bytes;

pub use memory::MemoryTracker;

pub use traits::Dequantize;

pub use traits::GpuDispatchable;

pub use traits::Quantize;

pub use traits::ValidatableConfig;

Modules

device

CUDA-first device selection with environment variable overrides.

dtype

Data type utilities and precision helpers.

error

Unified error types for the rust-ai ecosystem.

logging

Unified logging and observability for the rust-ai ecosystem.

memory

Memory estimation and tracking utilities for GPU operations.

traits

Common traits for the rust-ai ecosystem.

Macros

log_metric

Macro to log a training metric with consistent field names.

Constants

VERSION

Crate version for runtime version checking.