Aprender: Pure Rust ML Development

Expert guidance for working with aprender, a next-generation machine learning library written in pure Rust. Implements TOP 10 ML algorithms with 742 tests and 96.94% code coverage.

Core Principles

**CRITICAL ARCHITECTURE RULES:**

1. **Realizar-First (v2.0.0):** ALL inference/serving MUST use `realizar` crate. The `aprender` crate is TRAINING ONLY.

2. **Trace Before Reading:** Use `--trace` flag and profiling tools before debugging performance issues.

3. **bashrs for Shell Scripts:** Use `bashrs` (NOT shellcheck) for all shell script linting.

4. **Certeza Quality Gates:** Follow 4-tier validation (Tier 1: <1s, Tier 2: <5s, Tier 3: 1-5min, Tier 4: CI/CD).

Build & Quality Gates

When building or validating code:

1. **Quick Feedback (Tier 1 - <1s):**

```bash

make tier1

# Or: cargo fmt --check && cargo clippy -- -W all && cargo check

```

2. **Pre-Commit (Tier 2 - <5s):**

```bash

make tier2

# Or: cargo test --lib && cargo clippy -- -D warnings

```

3. **Pre-Push (Tier 3 - 1-5min):**

```bash

make tier3

# Includes: full tests, 96.94% coverage, complexity checks

```

4. **Full Test Suite:**

```bash

cargo test # All 742 tests

cargo test --lib # Unit tests only

cargo bench # Criterion benchmarks

```

Realizar-First Inference Architecture

**FORBIDDEN - DO NOT DO THIS:**

```rust

// ❌ WRONG - uses aprender for inference (0.3 tok/s)

use aprender::models::Qwen2Model;

let model = Qwen2Model::new_uninitialized(&config);

model.generate(&input_ids, 32, 0.7, 0.9); // SLOW!

```

**REQUIRED - Use realizar:**

```rust

// ✅ CORRECT - uses realizar (225+ tok/s)

use realizar::Model;

let model = Model::load_safetensors(&path)?;

let output = model.generate(&input_ids, config)?;

```

**BEST - Use apr CLI:**

```bash

cargo run --bin apr --features inference -- run model.safetensors \

--prompt "What is 2+2?" --max-tokens 32

```

Responsibility Matrix

|------|----------|----------|--------|

Mandatory Tracing-Based Debugging

**STOP. Before debugging performance issues by reading code, USE TRACING TOOLS.**

Inference Tracing (realizar)

```bash

Full tracing

realizar run model.safetensors --prompt "test" --trace

Trace specific steps

realizar run model.gguf --prompt "Hi" --trace=tokenize,sample,decode

JSON output for analysis

realizar run model.safetensors --prompt "test" --trace --trace-output trace.json

cat trace.json | jq '.[] | {step: .step, duration_ms: .duration_ms}'

```

Profiling Tools

```bash

apr CLI profiling

apr trace model.gguf # Layer-by-layer timing

apr profile model.gguf # Roofline analysis (memory vs compute)

apr bench model.safetensors # Throughput measurement

Per-token timing (verify O(n) vs O(n²) complexity)

Constant time per token → KV cache working (O(n))

Token N takes N× longer → KV cache broken (O(n²))

```

**Debugging Workflow:**

1. Run with `--trace` to get timing data

2. Check per-token timing for complexity issues

3. Only then read code to understand WHY

Quantized Kernel Layout Safety (LAYOUT-001)

**CRITICAL: GGUF/APR use ROW-MAJOR layout. Use correct kernels!**

**FORBIDDEN (produces garbage output):**

```rust

// ❌ NEVER USE - column-major kernels for row-major data

use trueno::backends::q4k::matmul_q4k_f32_colmajor;

use trueno::backends::q6k::matmul_q6k_f32_colmajor;

```

**REQUIRED (row-major, correct for GGUF/APR):**

```rust

// ✅ ALWAYS USE for GGUF/APR data

use crate::quantize::fused_q4k_parallel_matvec;

use crate::quantize::fused_q6k_parallel_matvec;

```

Shell Script Quality (bashrs)

**CRITICAL: Use bashrs, NOT shellcheck.**

```bash

Install bashrs

cargo install bashrs

Lint shell scripts

bashrs lint scripts/*.sh

Purify scripts (determinism + idempotency + safety)

bashrs purify scripts/ci.sh

Lint and purify Makefiles

bashrs make lint Makefile

bashrs make purify Makefile

Full quality gate

bashrs gate --strict .

```

**Required for all .sh files:**

`set -euo pipefail` at start

No `ls` for iteration (use `find`)

Quote all variables

Explicit error handling

Coverage Analysis (96.94% Target: ≥95%)

**bashrs-Style Coverage Pattern (CRITICAL):**

```bash

Generate coverage (recommended)

make coverage

View HTML report

xdg-open target/coverage/html/index.html # Linux

open target/coverage/html/index.html # macOS

Quick summary

make coverage-summary

```

**Makefile Coverage Pattern:**

```makefile

coverage:

@cargo llvm-cov clean --workspace

@mkdir -p target/coverage

# Disable mold linker (breaks LLVM instrumentation)

@test -f ~/.cargo/config.toml && mv ~/.cargo/config.toml ~/.cargo/config.toml.cov-backup || true

# Phase 1: Run tests with instrumentation

@cargo llvm-cov --no-report --all-features

# Phase 2: Generate reports

@cargo llvm-cov report --html --output-dir target/coverage/html

@cargo llvm-cov report --lcov --output-path target/coverage/lcov.info

# Restore config

@test -f ~/.cargo/config.toml.cov-backup && mv ~/.cargo/config.toml.cov-backup ~/.cargo/config.toml || true

@cargo llvm-cov report --summary-only

```

**Key Elements:**

1. Clean workspace first (`cargo llvm-cov clean --workspace`)

2. Disable mold linker (breaks instrumentation)

3. Two-phase report (`--no-report` first, then separate `report`)

4. Always restore cargo config

Mutation Testing

```bash

CI automatically runs mutation tests on every PR

View CI results

gh run list --workflow=ci.yml --limit 5

gh run download <run-id> -n mutants-results

Local execution (when working)

cargo mutants --no-times --timeout 300 --in-place -- --all-features

Test specific file

cargo mutants --no-times --timeout 120 --file src/loss/mod.rs

```

**Target:** ≥80% mutation score

Performance Targets (Ollama Parity)

|-------|-------------|-------------|--------|

| 1B Q4_K | 100+ | 500+ | 600MB |

| 7B Q4_K | 30+ | 150+ | 4GB |

| 13B Q4_K | 15+ | 80+ | 8GB |

Testing Strategy

Target: 60% unit, 30% property tests, 10% integration

```bash

cargo test # All 742 tests

cargo test --lib # Unit tests only

cargo test --test integration # Integration tests

cargo test --test property_tests # Property-based tests

cargo test --doc # Doctests

```

Architecture Patterns

1. **Trait-Based Multiple Dispatch** - Julia-inspired

2. **Backend Agnostic** - CPU (SIMD), GPU, WASM via Trueno

3. **Three-Tier API:**

- High: `Estimator` trait (sklearn-like)

- Mid: `Optimizer`, `Loss`, `Regularizer`

- Low: Direct Trueno primitives

Key Dependencies

**Runtime:** `trueno = "0.4.0"` (SIMD tensors)

**Testing:** `proptest`, `criterion`

**Quality:** `pmat` v2.200.0, `cargo-mutants`, `bashrs`

Common Tasks

**Add a new algorithm:**

1. Implement `Estimator` trait

2. Add unit tests (60% target)

3. Add property tests (30% target)

4. Run `make tier3` (full validation)

**Debug slow inference:**

1. Run `apr profile model.safetensors`

2. Check Roofline analysis

3. Use `--trace` for per-layer timing

4. Verify you're using `realizar` (not `aprender`)

**Fix shell script:**

1. Run `bashrs lint script.sh`

2. Add `set -euo pipefail` at start

3. Quote all variables

4. Run `bashrs purify script.sh`

**Pre-commit checklist:**

1. `make tier1` (fast feedback)

2. `make tier2` (pre-commit)

3. If touching critical code: `make tier3`

Important Files

`src/lib/db/schema.ts` - Database schema

`realizar/src/inference_trace.rs` - Tracing infrastructure

`docs/specifications/` - Detailed specs

`Makefile` - Quality gate shortcuts

`Cargo.toml` - Workspace-level lints

Constraints

**Zero unsafe code** (`unsafe_code = "forbid"`)

**Pure Rust** - No Python/C bindings

**Banned deps:** serde, rayon, tokio, thiserror, ndarray

**Workspace-level lints** - All crates inherit from workspace

Aprender: Pure Rust ML Development

Aprender: Pure Rust ML Development

Core Principles

Build & Quality Gates

Realizar-First Inference Architecture

Responsibility Matrix

Mandatory Tracing-Based Debugging

Inference Tracing (realizar)

Full tracing

Trace specific steps

JSON output for analysis

Profiling Tools

apr CLI profiling

Per-token timing (verify O(n) vs O(n²) complexity)

Constant time per token → KV cache working (O(n))

Token N takes N× longer → KV cache broken (O(n²))

Quantized Kernel Layout Safety (LAYOUT-001)

Shell Script Quality (bashrs)

Install bashrs

Lint shell scripts

Purify scripts (determinism + idempotency + safety)

Lint and purify Makefiles

Full quality gate

Coverage Analysis (96.94% Target: ≥95%)

Generate coverage (recommended)

View HTML report

Quick summary

Mutation Testing

CI automatically runs mutation tests on every PR

View CI results

Local execution (when working)

Test specific file

Performance Targets (Ollama Parity)

Testing Strategy

Architecture Patterns

Key Dependencies

Common Tasks

Important Files

Constraints

Reviews (0)