Aphelion Framework

A Rust framework for building AI model pipelines with deterministic, traceable execution.

What It Does

Aphelion provides infrastructure for constructing and executing AI model build pipelines. It handles:

• Graph Construction: DAG-based model architecture representation with deterministic hashing
• Configuration Management: Type-safe parameters with validation and semantic versioning
• Pipeline Orchestration: Composable stages with hooks, progress tracking, and conditional execution
• Backend Abstraction: Hardware-agnostic interface for CPU, GPU, and accelerator backends
• Diagnostics: Structured tracing with exportable event logs

What It Does Not Do

Aphelion is not a tensor library or neural network implementation. It does not:

• Perform matrix operations or automatic differentiation
• Provide pre-built neural network layers
• Train models or run inference directly

For those capabilities, integrate with backends like Burn via the burn feature flag.

Installation

[dependencies]
aphelion-core = "1.0"
serde_json = "1.0"  # Required for parameter values

Optional features:

[dependencies]
aphelion-core = { version = "1.0", features = ["burn", "tokio"] }

Core Concepts

Build Graph

A directed acyclic graph representing model architecture. Each node contains configuration and metadata.

use aphelion_core::prelude::*;

let mut graph = BuildGraph::default();

// Add nodes with configuration
let input = graph.add_node("input", ModelConfig::new("encoder", "1.0.0"));
let hidden = graph.add_node("hidden", ModelConfig::new("transformer", "1.0.0"));
let output = graph.add_node("output", ModelConfig::new("decoder", "1.0.0"));

// Define data flow
graph.add_edge(input, hidden);
graph.add_edge(hidden, output);

// Deterministic hash for reproducibility
let hash = graph.stable_hash();

The graph hash is computed using SHA-256 over canonicalized node data. Identical graphs produce identical hashes regardless of construction order.

Configuration

Type-safe configuration with parameter validation:

use aphelion_core::config::ModelConfig;

let config = ModelConfig::new("transformer", "2.0.0")
    .with_param("d_model", serde_json::json!(512))
    .with_param("n_heads", serde_json::json!(8))
    .with_param("n_layers", serde_json::json!(6))
    .with_param("dropout", serde_json::json!(0.1));

// Type-safe retrieval
let d_model: u32 = config.param("d_model")?;
let dropout: f64 = config.param_or("dropout", 0.0)?;
let batch_size: u32 = config.param_or_default("batch_size")?; // Uses Default::default()

Pipeline Execution

Pipelines execute stages in sequence with optional hooks:

use aphelion_core::prelude::*;
use aphelion_core::pipeline::{ValidationStage, HashingStage};

// Create execution context
let backend = NullBackend::cpu();
let trace = InMemoryTraceSink::new();
let ctx = BuildContext::new(&backend, &trace);

// Build pipeline
let pipeline = BuildPipeline::new()
    .with_stage(Box::new(ValidationStage))
    .with_stage(Box::new(HashingStage))
    .with_pre_hook(|ctx| {
        println!("Starting build on {}", ctx.backend.name());
        Ok(())
    })
    .with_post_hook(|_ctx, graph| {
        println!("Completed. Hash: {}", graph.stable_hash());
        Ok(())
    })
    .with_progress(|stage, current, total| {
        println!("[{}/{}] {}", current, total, stage);
    });

// Execute
let result = pipeline.execute(&ctx, graph)?;

Preset pipelines for common workflows:

let pipeline = BuildPipeline::standard();      // Validation + hashing
let pipeline = BuildPipeline::for_training();  // + training hooks
let pipeline = BuildPipeline::for_inference(); // Minimal, hashing only

Custom Pipeline Stages

Implement the PipelineStage trait:

use aphelion_core::pipeline::{PipelineStage, BuildContext};
use aphelion_core::graph::BuildGraph;
use aphelion_core::error::AphelionResult;

struct OptimizationStage;

impl PipelineStage for OptimizationStage {
    fn name(&self) -> &str {
        "optimization"
    }

    fn execute(&self, ctx: &BuildContext, graph: &mut BuildGraph) -> AphelionResult<()> {
        ctx.trace.info("optimization", "Running graph optimizations");
        // Optimization logic here
        Ok(())
    }
}

Custom Backends

Implement the Backend trait for hardware integration:

use aphelion_core::backend::{Backend, DeviceCapabilities};
use aphelion_core::error::AphelionResult;

struct MyGpuBackend {
    device_id: u32,
}

impl Backend for MyGpuBackend {
    fn name(&self) -> &str { "my_gpu" }
    fn device(&self) -> &str { "cuda:0" }

    fn capabilities(&self) -> DeviceCapabilities {
        DeviceCapabilities {
            supports_f16: true,
            supports_bf16: true,
            supports_tf32: true,
            max_memory_bytes: Some(8 * 1024 * 1024 * 1024),
            compute_units: Some(2560),
        }
    }

    fn is_available(&self) -> bool { true }
    fn initialize(&mut self) -> AphelionResult<()> { Ok(()) }
    fn shutdown(&mut self) -> AphelionResult<()> { Ok(()) }
}

Diagnostics and Tracing

Structured event logging with helper methods:

use aphelion_core::diagnostics::{InMemoryTraceSink, TraceSinkExt};

let trace = InMemoryTraceSink::new();

// Helper methods reduce boilerplate
trace.info("model.init", "Initializing model");
trace.warn("config.deprecated", "Parameter 'old_name' is deprecated");
trace.error("validation.failed", "Invalid configuration detected");

// Export to JSON
let json = trace.to_json();

Validation

Composable validators for configuration checking:

use aphelion_core::validation::{CompositeValidator, NameValidator, VersionValidator};

let validator = CompositeValidator::new()
    .with_validator(Box::new(NameValidator))
    .with_validator(Box::new(VersionValidator));

match validator.validate(&config) {
    Ok(_) => println!("Configuration valid"),
    Err(errors) => {
        for error in errors {
            eprintln!("Validation error: {}", error);
        }
    }
}

Async Execution

With the tokio feature enabled:

#[tokio::main]
async fn main() -> AphelionResult<()> {
    let pipeline = BuildPipeline::new()
        .with_async_stage(Box::new(ValidationStage))
        .with_async_stage(Box::new(HashingStage));

    let result = pipeline.execute_async(&ctx, graph).await?;
    Ok(())
}

Error Handling

All operations return AphelionResult<T>. Errors include context for debugging:

use aphelion_core::error::AphelionError;

// Create errors with context
let error = AphelionError::validation("Invalid parameter value")
    .in_stage("config_parsing")
    .for_field("hidden_size");

// Errors chain via std::error::Error::source()
if let Some(source) = error.source() {
    eprintln!("Caused by: {}", source);
}

Project Structure

aphelion-framework-rs/
├── crates/
│   ├── aphelion-core/      # Core library (~6000 lines)
│   ├── aphelion-macros/    # Proc macros (#[aphelion_model])
│   ├── aphelion-tests/     # Integration tests
│   └── aphelion-examples/  # Usage examples
├── docs/
│   ├── ARCHITECTURE.md     # System design
│   └── API-GUIDE.md        # Usage patterns
└── SPEC.md                 # Success criteria

Testing

# Run all tests
cargo test --workspace

# With async support
cargo test --workspace --features tokio

# With all features
cargo test --workspace --all-features

Test coverage: 252 tests across unit, integration, and documentation tests.

Design Principles

Determinism: Graph hashes are reproducible. BTreeMap ensures ordered iteration. No implicit randomness.

Explicit over implicit: No hidden state. Configuration is explicit. Errors are typed and contextual.

Composition over inheritance: Pipelines compose stages. Validators compose validators. Backends implement traits.

Zero-cost abstractions: Feature flags gate optional dependencies. Unused code is not compiled.

Documentation

Examples

Run examples from the workspace:

cargo run --package aphelion-examples --example basic_usage
cargo run --package aphelion-examples --example custom_backend
cargo run --package aphelion-examples --example pipeline_stages
cargo run --package aphelion-examples --example validation

Version History

Contributing

1. Fork the repository
2. Create a feature branch from develop
3. Write tests for new functionality
4. Ensure cargo test --workspace --all-features passes
5. Ensure cargo clippy --workspace --all-features -- -D warnings passes
6. Submit a pull request to develop

License

MIT License

Copyright (c) 2026 Tyler Zervas (tzervas)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.