aprender 0.31.2

Next-generation ML framework in pure Rust — `cargo install aprender` for the `apr` CLI
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

<!-- PCU: examples-evolutionary-merge | contract: contracts/apr-page-examples-evolutionary-merge-v1.yaml -->
<!-- Example: cargo run -p aprender-core --example evolutionary_merge -->
<!-- Status: enforced -->

# Case Study: Evolutionary Merge Optimization

**Ticket**: GH-444 | **Contract**: `merge.md §evolutionary`

## Overview

Evolutionary merge uses CMA-ES (Covariance Matrix Adaptation Evolution Strategy)
to automatically find optimal merge weights when combining multiple model
checkpoints. Instead of manually tuning weights, the optimizer explores the
weight space and finds the combination that minimizes a user-defined objective
(e.g., perplexity on calibration data).

## API

```rust
use aprender::format::converter::evolutionary_merge::{
    evolutionary_merge, EvolutionaryMergeConfig,
};
use aprender::format::MergeStrategy;

let config = EvolutionaryMergeConfig {
    num_models: 3,
    max_evaluations: 100,
    strategy: MergeStrategy::Weighted,
    sigma: 0.3,    // CMA-ES step size
    seed: 42,      // Reproducibility
    ..Default::default()
};

let result = evolutionary_merge(&models, &config, |merged| {
    // Return score to MINIMIZE (e.g., perplexity)
    evaluate_perplexity(&merged)
});

println!("Optimal weights: {:?}", result.weights);
println!("Best score: {:.4}", result.best_score);

// Use result.merge_options directly with apr_merge
```

## Key Design Decisions

1. **Softmax parameterization**: Raw CMA-ES parameters are mapped through
   softmax to ensure weights are always positive and sum to 1.0.
2. **In-memory merging**: Tensor merging happens in-memory without file I/O,
   enabling fast objective function evaluation during optimization.
3. **Strategy-agnostic**: Works with Average, Weighted, and SLERP strategies.
   TIES/DARE density and drop_rate can also be optimized.

## Falsification Tests

| Test | Property |
|------|----------|
| FALSIFY-EVOL-MERGE-001 | Weights always sum to 1.0 |
| FALSIFY-EVOL-MERGE-002 | CMA-ES improves over equal-weight baseline |
| FALSIFY-EVOL-MERGE-003 | Result produces valid MergeOptions |

## Run the Example

```bash
cargo run --example evolutionary_merge
```