aprender 0.25.1

Aprender provides implementations of classical machine learning algorithms optimized for performance and safety. The library requires no external dependencies beyond the Rust standard library and offers seamless compilation to WebAssembly.

Table of Contents

• Features
• Installation
• Quick Start
• Algorithms
• Model Persistence
• Documentation
• Contributing
• License

Features

• Pure Rust — Zero C/C++ dependencies, memory-safe, thread-safe by default
• SIMD Acceleration — Vectorized operations via trueno backend
• WebAssembly Ready — Compile to WASM for browser and edge deployment
• Native Model Format — .apr format with encryption, signatures, and zero-copy loading
• Interoperability — Export to SafeTensors and GGUF formats

Installation

Add aprender to your Cargo.toml:

[dependencies]
aprender = "0.25"

Optional Features

[dependencies]
aprender = { version = "0.13", features = ["format-encryption", "hf-hub-integration"] }

Quick Start

use aprender::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Training data
    let x = Matrix::from_vec(4, 2, vec![
        1.0, 2.0,
        2.0, 3.0,
        3.0, 4.0,
        4.0, 5.0,
    ])?;
    let y = Vector::from_slice(&[3.0, 5.0, 7.0, 9.0]);

    // Train model
    let mut model = LinearRegression::new();
    model.fit(&x, &y)?;

    // Evaluate
    println!("R² = {:.4}", model.score(&x, &y));

    Ok(())
}

Algorithms

Supervised Learning

Unsupervised Learning

Additional Modules

• Graph Analysis — PageRank, betweenness centrality, community detection
• Time Series — ARIMA forecasting
• Text Processing — Tokenization, TF-IDF, stemming, chat templates
• Neural Networks — Sequential models, transformers, mixture of experts
• Metaheuristics — ACO, Tabu Search, DE, PSO, GA, CMA-ES

Chat Templates

Format LLM conversations for different model families with automatic template detection:

use aprender::text::chat_template::{
    auto_detect_template, ChatMessage, ChatTemplateEngine
};

// Auto-detect template from model name
let template = auto_detect_template("Qwen2-0.5B-Instruct");

let messages = vec![
    ChatMessage::system("You are a helpful assistant."),
    ChatMessage::user("Hello!"),
];

let formatted = template.format_conversation(&messages)?;

Supported Formats:

See examples/chat_template.rs for complete usage.

Verification: All templates are 100% tested via bashrs probar playbooks. See docs/model-verification-checklist.md for coverage status.

Related Crates

Resources

Model Persistence

The .apr format provides secure, efficient model serialization:

use aprender::format::{save, load, ModelType, SaveOptions};

// Save with encryption
save(&model, ModelType::LinearRegression, "model.apr",
    SaveOptions::default()
        .with_encryption("password")
        .with_compression(true))?;

// Load
let model: LinearRegression = load("model.apr", ModelType::LinearRegression)?;

Format Capabilities

• Security — AES-256-GCM encryption, Ed25519 signatures, X25519 key exchange
• Performance — Memory-mapped loading, 600x faster than standard deserialization
• Integrity — CRC32 checksums with automatic corruption detection
• Commercial — License blocks, watermarking, buyer-specific encryption

APR CLI Tool

The apr CLI provides comprehensive model operations for the .apr format.

Installation

cargo install apr-cli

Commands

Quick Examples

# Run model directly (auto-downloads if needed)
apr run hf://openai/whisper-tiny --input audio.wav

# Download and cache models (Ollama-style UX)
apr pull hf://Qwen/Qwen2.5-Coder-1.5B-Instruct-GGUF -o ./models/
apr list  # List cached models

# Validate model integrity
apr validate model.apr --quality

# Convert with quantization
apr convert model.safetensors --quantize int8 -o model-int8.apr

# Lint for best practices
apr lint model.apr

# Export to GGUF (llama.cpp compatible)
apr export model.apr --format gguf -o model.gguf

# Merge models (ensemble)
apr merge model1.apr model2.apr --strategy average -o ensemble.apr

# Create regression test
apr canary create model.apr --input ref.wav --output canary.json

# Check model against canary
apr canary check optimized.apr --canary canary.json

# Publish to HuggingFace Hub
apr publish ./model-dir/ org/model-name --license mit

Showcase: Qwen2.5-Coder Inference

The apr CLI achieves 2.93x Ollama performance on Qwen2.5-Coder-1.5B with GPU acceleration:

# Interactive chat
apr chat qwen2.5-coder-1.5b-q4_k_m.gguf

# Single-shot generation
apr run qwen2.5-coder-1.5b-q4_k_m.gguf --prompt "Write hello world in Rust"

# Production server (OpenAI-compatible API)
apr serve qwen2.5-coder-1.5b-q4_k_m.gguf --port 8080

Benchmark Results (2026-01-18)

See docs/specifications/qwen2.5-coder-showcase-demo.md for full benchmark methodology.

QA & Testing

The project includes comprehensive QA infrastructure for model validation:

# Run full 21-cell QA matrix (modality × format × backend)
cargo run --example qa_run -- --full-matrix

# Run QA falsification suite (Popperian methodology)
cargo run --example qa_falsify

# Single modality test with Ollama comparison
cargo run --example qa_run -- --modality serve --backend cpu --format gguf --with-ollama

QA Matrix Coverage:

• Modalities: run, chat, serve
• Formats: GGUF, SafeTensors, APR
• Backends: CPU, GPU
• Features: Hang detection (60s), garbage output detection, answer verification

See examples/qa_run.rs and examples/qa_falsify.rs for implementation.

Documentation

Contributing

We welcome contributions. Please ensure your changes pass the test suite:

cargo test --all-features
cargo clippy --all-targets -- -D warnings
cargo fmt --check

See CONTRIBUTING.md for guidelines.

License

Aprender is distributed under the MIT License. See LICENSE for details.