aphelion_core/
lib.rs

1//! # aphelion-core
2//!
3//! Core library for the Aphelion AI Framework.
4//!
5//! ## Why This Crate Exists
6//!
7//! Aphelion is a framework frontend that provides an easier entrypoint for AI
8//! engineering in Rust. This crate provides the core infrastructure that unifies
9//! access to Rust AI libraries through a consistent API.
10//!
11//! Building AI systems means integrating multiple libraries: tensor operations,
12//! memory management, device handling, training loops. aphelion-core handles:
13//!
14//! - **Unified API**: One consistent interface to underlying AI libraries
15//!   (rust-ai-core, Candle, Burn, CubeCL).
16//!
17//! - **Reusable Components**: Configurations and pipelines can be templated,
18//!   shared, and versioned for reproducible experiments.
19//!
20//! - **Deterministic graph hashing**: SHA-256 over canonicalized node data ensures
21//!   identical configurations produce identical hashes, regardless of construction order.
22//!
23//! - **Structured tracing**: Every operation emits typed events. No printf debugging.
24//!   Export to JSON for analysis or feed to observability systems.
25//!
26//! - **Backend abstraction**: Write once, run on CPU, GPU, or accelerators. The
27//!   `Backend` trait abstracts hardware differences.
28//!
29//! - **Pipeline composition**: Stages execute in order with hooks for customization.
30//!   Errors propagate with context. Progress is observable.
31//!
32//! ## Module Organization
33//!
34//! | Module | Purpose |
35//! |--------|---------|
36//! | [`config`] | Model configuration with typed parameters and validation |
37//! | [`graph`] | DAG representation of model architecture |
38//! | [`pipeline`] | Stage-based execution with hooks and progress tracking |
39//! | [`backend`] | Hardware abstraction for CPU/GPU/accelerator targets |
40//! | [`diagnostics`] | Structured tracing and event logging |
41//! | [`validation`] | Composable validators for configuration checking |
42//! | [`error`] | Typed errors with context and chaining |
43//! | [`export`] | Serialization of trace events to JSON |
44//!
45//! ## Feature Flags
46//!
47//! | Feature | Effect |
48//! |---------|--------|
49//! | `burn` | Enables Burn deep learning backend integration |
50//! | `cubecl` | Enables CubeCL GPU compute backend |
51//! | `rust-ai-core` | Enables memory tracking, device detection, dtype utilities |
52//! | `cuda` | Enables CUDA support (requires `rust-ai-core`) |
53//! | `tokio` | Enables async pipeline execution |
54//! | `tritter-accel` | Enables Tritter hardware acceleration |
55//! | `python` | Enables Python bindings via PyO3 |
56//! | `wasm` | Enables WebAssembly/TypeScript bindings via wasm-bindgen |
57//!
58//! ## Quick Start
59//!
60//! ```rust
61//! use aphelion_core::prelude::*;
62//!
63//! // Build a model graph
64//! let mut graph = BuildGraph::default();
65//! let encoder = graph.add_node("encoder", ModelConfig::new("enc", "1.0.0"));
66//! let decoder = graph.add_node("decoder", ModelConfig::new("dec", "1.0.0"));
67//! graph.add_edge(encoder, decoder);
68//!
69//! // Execute pipeline
70//! let backend = NullBackend::cpu();
71//! let trace = InMemoryTraceSink::new();
72//! let ctx = BuildContext::new(&backend, &trace);
73//! let result = BuildPipeline::standard().execute(&ctx, graph)?;
74//!
75//! // Hash is deterministic
76//! assert_eq!(result.stable_hash().len(), 64); // SHA-256 hex
77//! # Ok::<(), aphelion_core::error::AphelionError>(())
78//! ```
79
80pub mod backend;
81pub mod config;
82pub mod diagnostics;
83pub mod error;
84pub mod export;
85pub mod graph;
86pub mod pipeline;
87pub mod prelude;
88pub mod rust_ai_core;
89pub mod validation;
90
91#[cfg(feature = "burn")]
92pub mod burn_backend;
93
94#[cfg(feature = "cubecl")]
95pub mod cubecl_backend;
96
97#[cfg(feature = "tritter-accel")]
98pub mod acceleration;
99
100#[cfg(feature = "tritter-accel")]
101pub mod tritter_backend;
102
103#[cfg(feature = "python")]
104pub mod python;
105
106#[cfg(feature = "wasm")]
107pub mod wasm;
108
109pub use aphelion_macros::aphelion_model;
110
111// ============================================================================
112// rust-ai-core Re-exports (when feature enabled)
113// ============================================================================
114
115// Re-export AphelionDevice based on feature
116#[cfg(feature = "rust-ai-core")]
117pub use rust_ai_core::AphelionDevice;
118
119#[cfg(not(feature = "rust-ai-core"))]
120pub use rust_ai_core::placeholder::AphelionDevice;
121
122// Re-export MemoryTracker based on feature
123#[cfg(feature = "rust-ai-core")]
124pub use rust_ai_core::real::MemoryTracker;
125
126#[cfg(not(feature = "rust-ai-core"))]
127pub use rust_ai_core::placeholder::MemoryTracker;
128
129// Re-export real rust-ai-core types when enabled
130#[cfg(feature = "rust-ai-core")]
131pub use rust_ai_core::real::{
132    bytes_per_element, estimate_attention_memory, estimate_tensor_bytes, get_device, init_logging,
133    is_floating_point, warn_if_cpu, DType, DTypeExt, Dequantize, Device, DeviceConfig, LogConfig,
134    PrecisionMode, Quantize, Tensor, ValidatableConfig, DEFAULT_OVERHEAD_FACTOR, RAC_VERSION,
135};
136
137// Re-export GPU types from trit-vsa (requires cuda feature)
138#[cfg(all(feature = "rust-ai-core", feature = "cuda"))]
139pub use trit_vsa::gpu::{GpuDispatchable, GpuError, GpuResult};
140
141// Re-export CubeCL types when both features enabled
142#[cfg(all(feature = "rust-ai-core", feature = "cuda"))]
143pub use rust_ai_core::cubecl::{
144    allocate_output_buffer, candle_to_cubecl_handle, cubecl_to_candle_tensor,
145    has_cubecl_cuda_support, CubeclContext, TensorBuffer,
146};
aphelion_core/lib.rs

aphelion_core/
lib.rs
