Expert guidance for the aprender next-generation ML library. Enforces realizar-first architecture, tracing-based debugging, bashrs shell quality, and Certeza tiered quality gates (96.94% coverage).
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.
**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).
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
```
**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
```
| Task | aprender | realizar | trueno |
|------|----------|----------|--------|
| Model Training | ✅ Primary | ❌ Never | Compute |
| Model Serving | ❌ FORBIDDEN | ✅ Primary | Compute |
| HTTP/REST API | ❌ Never | ✅ Primary | ❌ |
| KV Cache | ❌ Never | ✅ Primary | Storage |
**STOP. Before debugging performance issues by reading code, USE TRACING TOOLS.**
```bash
realizar run model.safetensors --prompt "test" --trace
realizar run model.gguf --prompt "Hi" --trace=tokenize,sample,decode
realizar run model.safetensors --prompt "test" --trace --trace-output trace.json
cat trace.json | jq '.[] | {step: .step, duration_ms: .duration_ms}'
```
```bash
apr trace model.gguf # Layer-by-layer timing
apr profile model.gguf # Roofline analysis (memory vs compute)
apr bench model.safetensors # Throughput measurement
```
**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
**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;
```
**CRITICAL: Use bashrs, NOT shellcheck.**
```bash
cargo install bashrs
bashrs lint scripts/*.sh
bashrs purify scripts/ci.sh
bashrs make lint Makefile
bashrs make purify Makefile
bashrs gate --strict .
```
**Required for all .sh files:**
**bashrs-Style Coverage Pattern (CRITICAL):**
```bash
make coverage
xdg-open target/coverage/html/index.html # Linux
open target/coverage/html/index.html # macOS
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
```bash
gh run list --workflow=ci.yml --limit 5
gh run download <run-id> -n mutants-results
cargo mutants --no-times --timeout 300 --in-place -- --all-features
cargo mutants --no-times --timeout 120 --file src/loss/mod.rs
```
**Target:** ≥80% mutation score
| Model | CPU (tok/s) | GPU (tok/s) | Memory |
|-------|-------------|-------------|--------|
| 1B Q4_K | 100+ | 500+ | 600MB |
| 7B Q4_K | 30+ | 150+ | 4GB |
| 13B Q4_K | 15+ | 80+ | 8GB |
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
```
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
**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`
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/aprender-pure-rust-ml-development/raw