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

//! Python bindings for the Aphelion AI Framework.
//!
//! This module provides Python bindings for aphelion-core via PyO3,
//! enabling Python developers to use Aphelion as a frontend for AI
//! engineering tasks.
//!
//! ## Why Python Bindings
//!
//! Aphelion is a framework frontend that provides an easier entrypoint for AI
//! development. These bindings bring that same unified API to Python:
//!
//! - **Unified API**: Consistent interface to Rust AI libraries from Python
//! - **Reusable Components**: Template and share configurations across projects
//! - **Deterministic Builds**: Same config = same hash = reproducible results
//! - **Integration**: Works alongside existing Python ML workflows
//!
//! ## Module Structure
//!
//! All types are exported at the top level:
//!
//! - `ModelConfig`, `ModelConfigBuilder`: Configuration management
//! - `BuildGraph`, `GraphNode`, `NodeId`: DAG representation
//! - `BuildPipeline`, `BuildContext`: Pipeline execution
//! - `NullBackend`: Reference backend for testing
//! - `InMemoryTraceSink`, `TraceEvent`, `TraceLevel`: Diagnostics
//! - `ValidationError`, `NameValidator`, `VersionValidator`, `CompositeValidator`: Validation
//!
//! ## Feature Flags
//!
//! | Feature | Effect |
//! |---------|--------|
//! | `rust-ai-core` | Memory tracking, device detection, dtype utilities |
//! | `cuda` | CUDA GPU support (requires `rust-ai-core`) |
//! | `burn` | Burn backend support |
//! | `cubecl` | CubeCL backend support |
//!
//! ## Example
//!
//! ```python
//! import aphelion
//!
//! # Build configuration
//! config = aphelion.ModelConfig("transformer", "1.0.0")
//! config = config.with_param("d_model", 512)
//!
//! # Build graph
//! graph = aphelion.BuildGraph()
//! encoder = graph.add_node("encoder", config)
//!
//! # Execute pipeline
//! ctx = aphelion.BuildContext.with_null_backend()
//! pipeline = aphelion.BuildPipeline.standard()
//! result = pipeline.execute(ctx, graph)
//!
//! print(f"Hash: {result.stable_hash()}")
//! ```

// Allow clippy false positive with PyO3's PyResult in return types
#![allow(clippy::useless_conversion)]

use pyo3::prelude::*;

mod backend;
mod config;
mod diagnostics;
mod graph;
mod pipeline;
mod validation;

#[cfg(feature = "rust-ai-core")]
mod core;

/// Aphelion Python module - transparent, traceable AI model construction.
///
/// This module provides Python bindings for the Aphelion AI Framework,
/// enabling deterministic model graph construction with cryptographic
/// hashing for reproducibility.
///
/// Quick start:
///     >>> import aphelion
///     >>> config = aphelion.ModelConfig("encoder", "1.0.0")
///     >>> graph = aphelion.BuildGraph()
///     >>> node = graph.add_node("encoder", config)
///     >>> print(graph.stable_hash())
///
/// Module attributes:
///     __version__: Package version string
///     HAS_BURN: True if Burn backend is available
///     HAS_CUBECL: True if CubeCL backend is available
///     HAS_RUST_AI_CORE: True if rust-ai-core integration is available
///     HAS_CUDA: True if CUDA support is available
#[pymodule]
pub fn aphelion(m: &Bound<'_, PyModule>) -> PyResult<()> {
    // Register all submodule types
    config::register(m)?;
    graph::register(m)?;
    backend::register(m)?;
    diagnostics::register(m)?;
    pipeline::register(m)?;
    validation::register(m)?;

    // Register rust-ai-core integration when feature enabled
    #[cfg(feature = "rust-ai-core")]
    core::register(m)?;

    // Version info
    m.add("__version__", env!("CARGO_PKG_VERSION"))?;

    // Feature flags - expose what backends are compiled in
    #[cfg(feature = "burn")]
    m.add("HAS_BURN", true)?;
    #[cfg(not(feature = "burn"))]
    m.add("HAS_BURN", false)?;

    #[cfg(feature = "cubecl")]
    m.add("HAS_CUBECL", true)?;
    #[cfg(not(feature = "cubecl"))]
    m.add("HAS_CUBECL", false)?;

    #[cfg(feature = "rust-ai-core")]
    m.add("HAS_RUST_AI_CORE", true)?;
    #[cfg(not(feature = "rust-ai-core"))]
    m.add("HAS_RUST_AI_CORE", false)?;

    #[cfg(feature = "cuda")]
    m.add("HAS_CUDA", true)?;
    #[cfg(not(feature = "cuda"))]
    m.add("HAS_CUDA", false)?;

    #[cfg(feature = "tritter-accel")]
    m.add("HAS_TRITTER_ACCEL", true)?;
    #[cfg(not(feature = "tritter-accel"))]
    m.add("HAS_TRITTER_ACCEL", false)?;

    Ok(())
}