aphelion-core 1.2.8

Core library for Aphelion AI framework - unified frontend for AI model development
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

//! # aphelion-core
//!
//! Core library for the Aphelion AI Framework.
//!
//! ## Why This Crate Exists
//!
//! Aphelion is a framework frontend that provides an easier entrypoint for AI
//! engineering in Rust. This crate provides the core infrastructure that unifies
//! access to Rust AI libraries through a consistent API.
//!
//! Building AI systems means integrating multiple libraries: tensor operations,
//! memory management, device handling, training loops. aphelion-core handles:
//!
//! - **Unified API**: One consistent interface to underlying AI libraries
//!   (rust-ai-core, Candle, Burn, CubeCL).
//!
//! - **Reusable Components**: Configurations and pipelines can be templated,
//!   shared, and versioned for reproducible experiments.
//!
//! - **Deterministic graph hashing**: SHA-256 over canonicalized node data ensures
//!   identical configurations produce identical hashes, regardless of construction order.
//!
//! - **Structured tracing**: Every operation emits typed events. No printf debugging.
//!   Export to JSON for analysis or feed to observability systems.
//!
//! - **Backend abstraction**: Write once, run on CPU, GPU, or accelerators. The
//!   `Backend` trait abstracts hardware differences.
//!
//! - **Pipeline composition**: Stages execute in order with hooks for customization.
//!   Errors propagate with context. Progress is observable.
//!
//! ## Module Organization
//!
//! | Module | Purpose |
//! |--------|---------|
//! | [`config`] | Model configuration with typed parameters and validation |
//! | [`graph`] | DAG representation of model architecture |
//! | [`pipeline`] | Stage-based execution with hooks and progress tracking |
//! | [`backend`] | Hardware abstraction for CPU/GPU/accelerator targets |
//! | [`diagnostics`] | Structured tracing and event logging |
//! | [`validation`] | Composable validators for configuration checking |
//! | [`error`] | Typed errors with context and chaining |
//! | [`export`] | Serialization of trace events to JSON |
//!
//! ## Feature Flags
//!
//! | Feature | Effect |
//! |---------|--------|
//! | `burn` | Enables Burn deep learning backend integration |
//! | `cubecl` | Enables CubeCL GPU compute backend |
//! | `rust-ai-core` | Enables memory tracking, device detection, dtype utilities |
//! | `cuda` | Enables CUDA support (requires `rust-ai-core`) |
//! | `tokio` | Enables async pipeline execution |
//! | `tritter-accel` | Enables Tritter hardware acceleration |
//!
//! ## Quick Start
//!
//! ```rust
//! use aphelion_core::prelude::*;
//!
//! // Build a model graph
//! let mut graph = BuildGraph::default();
//! let encoder = graph.add_node("encoder", ModelConfig::new("enc", "1.0.0"));
//! let decoder = graph.add_node("decoder", ModelConfig::new("dec", "1.0.0"));
//! graph.add_edge(encoder, decoder);
//!
//! // Execute pipeline
//! let backend = NullBackend::cpu();
//! let trace = InMemoryTraceSink::new();
//! let ctx = BuildContext::new(&backend, &trace);
//! let result = BuildPipeline::standard().execute(&ctx, graph)?;
//!
//! // Hash is deterministic
//! assert_eq!(result.stable_hash().len(), 64); // SHA-256 hex
//! # Ok::<(), aphelion_core::error::AphelionError>(())
//! ```

pub mod backend;
pub mod config;
pub mod diagnostics;
pub mod error;
pub mod export;
pub mod graph;
pub mod pipeline;
pub mod prelude;
pub mod rust_ai_core;
pub mod validation;

#[cfg(feature = "burn")]
pub mod burn_backend;

#[cfg(feature = "cubecl")]
pub mod cubecl_backend;

#[cfg(feature = "tritter-accel")]
pub mod acceleration;

#[cfg(feature = "tritter-accel")]
pub mod tritter_backend;

#[cfg(feature = "python")]
pub mod python;

pub use aphelion_macros::aphelion_model;

// ============================================================================
// rust-ai-core Re-exports (when feature enabled)
// ============================================================================

// Re-export AphelionDevice based on feature
#[cfg(feature = "rust-ai-core")]
pub use rust_ai_core::AphelionDevice;

#[cfg(not(feature = "rust-ai-core"))]
pub use rust_ai_core::placeholder::AphelionDevice;

// Re-export MemoryTracker based on feature
#[cfg(feature = "rust-ai-core")]
pub use rust_ai_core::real::MemoryTracker;

#[cfg(not(feature = "rust-ai-core"))]
pub use rust_ai_core::placeholder::MemoryTracker;

// Re-export real rust-ai-core types when enabled
#[cfg(feature = "rust-ai-core")]
pub use rust_ai_core::real::{
    bytes_per_element, estimate_attention_memory, estimate_tensor_bytes, get_device, init_logging,
    is_floating_point, warn_if_cpu, DType, DTypeExt, Dequantize, Device, DeviceConfig,
    GpuDispatchable, LogConfig, PrecisionMode, Quantize, Tensor, ValidatableConfig,
    DEFAULT_OVERHEAD_FACTOR, RAC_VERSION,
};

// Re-export CubeCL types when both features enabled
#[cfg(all(feature = "rust-ai-core", feature = "cuda"))]
pub use rust_ai_core::cubecl::{
    allocate_output_buffer, candle_to_cubecl_handle, cubecl_to_candle_tensor,
    has_cubecl_cuda_support, CubeclContext, TensorBuffer,
};