feat: Phase 45 — Test-Time Compute Scaling (v4.0.0-alpha.5)

ARCHITECTURE_V4.md

@@ -590,6 +590,53 @@ technique's general reputation. Different tasks and selection
 strategies are expected to show different — sometimes negligible —
 deltas; the scorecard is the source of truth, not the roadmap's prose.
 
+### Implementation (Phase 45, v4.0.0-alpha.5)
+
+The test-time-compute surface lives in three new modules of
+`aarambh-studio-inference`:
+
+- `best_of_n.rs`: `SelectionStrategy` enum
+  (`Verifier | SelfConsistency | Majority | ProcessReward`), the local
+  `CompletionVerifier` trait (kept local so the inference crate does not
+  depend on the finetune crate that owns `Verifier` / `MathVerifier` /
+  `CodeVerifier` — the CLI binary adapts at the call site),
+  `BestOfNConfig`, `BestOfNEngine`, `BestOfNOutput`, and
+  `SelectionRationale`. `BestOfNEngine` wraps an `InferenceEngine` and
+  reuses `prepare_session` + `fork_with_config` + `decode_sessions` so the
+  prompt KV-cache is prefilled once and the N forks are decoded together
+  in one batched target forward pass. Candidate 0 inherits the input
+  sampler's seed unchanged (N=1 reproduces single-sample byte-for-byte);
+  candidates 1..N are re-seeded `base_seed + i`.
+- `self_consistency.rs`: `extract_final_number` (byte-identical
+  re-declaration of `aarambh_studio_finetune::extract_final_number`,
+  attributed, so no cross-crate dependency), `extract_final_answer`,
+  `majority_vote` (first-occurrence tie-breaking), and
+  `self_consistency_select`.
+- `process_reward.rs`: `ProcessRewardScorer` trait,
+  `HeuristicProcessRewardScorer` (transparent structural scorer: rewards
+  a non-empty thinking block, a final-answer marker, a parsable numeric
+  answer, and a non-trivial step count), and `ProcessRewardHead`
+  (placeholder for a future trained head; returns
+  `AarambhError::Unsupported` until a checkpoint exists — no trained
+  checkpoint ships, per the release audit).
+
+The `aarambh-studio-eval` crate gains `best_of_n_generate` /
+`sample_generate` / `BestOfNOptions` / `BestOfNResult` in `generation.rs`
+and `best_of_n` / `best_of_n_selection` / `best_of_n_seed` fields on
+`EvalConfig`. When `best_of_n` is set, the `gsm8k_subset` and
+`humaneval_lite` tasks compute both single-sample and best-of-N accuracy
+and record `single_sample_accuracy`, `best_of_n_accuracy`, and
+`best_of_n_delta` in their `TaskScore::details` map.
+
+The `aarambh-studio` CLI gains `--best-of-n` / `--selection` /
+`--ground-truth` on `infer` and `--best-of-n` / `--best-of-n-selection` /
+`--best-of-n-seed` on `eval`. Best-of-N is text-only: combining
+`--best-of-n` with `--image` / `--video` / `--document` / `--audio` /
+`--tools` returns `AarambhError::Unsupported`. The `serve` crate is
+unchanged (its `GenerationRequest` wraps `GenerationConfig`, which Phase 45
+leaves untouched — the wrapper-struct approach keeps the server surface
+clean).
+
 ---
 
 ## 60. RLAIF

CHANGELOG.md

@@ -2,6 +2,97 @@
 
 > From first principles. From zero. From Rust.
 
+## [4.0.0-alpha.5] - 2026-08-16
+
+### Added
+
+- **Phase 45 — Test-Time Compute Scaling:** Adds a genuinely new
+  inference-time axis, distinct from the thinking engine (v1 §7):
+  instead of controlling how many tokens *one* generation spends
+  reasoning, this phase generates *multiple candidate completions* and
+  selects among them — the Best-of-N / self-consistency /
+  verifier-guided-selection pattern that sits alongside, not inside, the
+  existing thinking-mode budget system. The two compose freely: each of
+  the N candidates can itself use any thinking mode.
+  - New `SelectionStrategy` enum (`aarambh-studio-inference`):
+    `Verifier | SelfConsistency | Majority | ProcessReward`. The first
+    three are the roadmap-named strategies for verifiable tasks; `ProcessReward`
+    is the open-ended-task fallback from ARCHITECTURE_V4 §59.
+  - New `CompletionVerifier` trait (`aarambh-studio-inference`): local to
+    the inference crate so it does not depend on the finetune crate that
+    owns `Verifier` / `MathVerifier` / `CodeVerifier` — the CLI binary
+    provides a thin `MathVerifierAdapter` at the call site, preserving the
+    existing architectural layering.
+  - New `BestOfNConfig`, `BestOfNEngine`, `BestOfNOutput`,
+    `SelectionRationale` (`aarambh-studio-inference`): `BestOfNEngine`
+    wraps an `InferenceEngine` and reuses `prepare_session` +
+    `fork_with_config` + `decode_sessions` so the prompt KV-cache is
+    prefilled once and the N forks are decoded together in one batched
+    target forward pass. Candidate 0 inherits the input sampler's seed
+    unchanged (N=1 reproduces single-sample byte-for-byte); candidates
+    1..N are re-seeded `base_seed + i`. The wrapper-struct approach leaves
+    `GenerationConfig` and the `serve` crate untouched — best-of-N is a
+    CLI/eval surface only, per the roadmap's explicit scope.
+  - New `self_consistency` module (`aarambh-studio-inference`):
+    `extract_final_number` (byte-identical re-declaration of
+    `aarambh_studio_finetune::extract_final_number`, attributed, so no
+    cross-crate dependency), `extract_final_answer` (number or last
+    non-empty trimmed line), `majority_vote` (first-occurrence
+    tie-breaking), and `self_consistency_select`.
+  - New `process_reward` module (`aarambh-studio-inference`):
+    `ProcessRewardScorer` trait, `HeuristicProcessRewardScorer`
+    (transparent structural scorer: rewards a non-empty thinking block, a
+    final-answer marker, a parsable numeric answer, and a non-trivial step
+    count), and `ProcessRewardHead` (placeholder for a future trained
+    head; `load_process_reward_head` returns `AarambhError::Unsupported`
+    until a checkpoint exists — no trained checkpoint ships, per the
+    release audit).
+  - New eval-harness surface (`aarambh-studio-eval`): `best_of_n_generate`,
+    `sample_generate`, `BestOfNOptions`, `BestOfNResult`, `VerifierFn`
+    type alias in `generation.rs`; `best_of_n`, `best_of_n_selection`,
+    `best_of_n_seed` fields on `EvalConfig`. When `best_of_n` is set, the
+    `gsm8k_subset` and `humaneval_lite` tasks compute both single-sample
+    and best-of-N accuracy and record `single_sample_accuracy`,
+    `best_of_n_accuracy`, and `best_of_n_delta` in their
+    `TaskScore::details` map — the scorecard is the source of truth for
+    whether best-of-N actually helped, never asserted in prose.
+  - New CLI flags: `infer --best-of-n <N> --selection
+    verifier|self-consistency|majority|process-reward [--ground-truth
+    <answer>]`; `eval --best-of-n <N> --best-of-n-selection <strategy>
+    --best-of-n-seed <u64>`. Best-of-N is text-only: combining
+    `--best-of-n` with `--image` / `--video` / `--document` / `--audio` /
+    `--tools` returns `AarambhError::Unsupported` (mirrors
+    `fork_with_config`'s no-tools constraint).
+  - New config: `configs/best_of_n_smoke.toml` (CPU smoke training config
+    that produces a checkpoint the smoke script runs best-of-N inference
+    against; the best-of-N surface is CLI-flag-driven, not a TOML section,
+    per the roadmap); new script `scripts/phase45_smoke.sh`; new doc
+    `docs/phase45_test_time.md`.
+  - Tests (CPU, no cuda, 13 total across the inference and eval crates):
+    `best_of_n_with_n_equal_one_matches_single_sample_generation_exactly`
+    (N=1 backward compat),
+    `self_consistency_majority_vote_selects_the_most_common_final_answer`,
+    `process_reward_score_correlates_positively_with_verifier_score_on_labelled_holdout`
+    (synthetic labelled holdout constructed inline, no external fixture),
+    `best_of_n_accuracy_on_gsm8k_subset_is_measured_not_assumed_to_improve`
+    (asserts the delta is *reported* in the scorecard, not that it
+    improved), plus supporting tests for re-seeding, greedy degeneracy,
+    verifier selection, answer extraction, tie-breaking, PR heuristic
+    monotonicity, strategy parsing, and config validation.
+
+### Honesty note on hardware and scope
+
+i3 supports small N (2–4) for text tasks; larger N is Kaggle-scoped for
+cost reasons, following v1 §12's existing i3 self-learning N-completion
+budget precedent. Whether best-of-N improves accuracy on a given task is
+measured by the eval-harness scorecard, not asserted in prose — different
+tasks and selection strategies are expected to show different, sometimes
+negligible, deltas. The process-reward scorer ships as a transparent
+heuristic plus a trait for a future trained head; the trained head is
+explicitly future work (returns `AarambhError::Unsupported`, not a
+stub macro), and no trained checkpoint ships. Best-of-N is text-only in
+Phase 45; multimodal best-of-N is future work, not a half-implementation.
+
 ## [4.0.0-alpha.4] - 2026-08-16
 
 ### Added

Cargo.toml

@@ -24,7 +24,7 @@ members = [
 resolver = "2"
 
 [workspace.package]
-version = "4.0.0-alpha.4"
+version = "4.0.0-alpha.5"
 edition = "2024"
 rust-version = "1.89"
 description = "From first principles. From zero. From Rust."

README.md

@@ -18,17 +18,23 @@ with hybrid Gated DeltaNet, DeepSeek Sparse Attention,
 fine-grained MoE with shared experts, Multi-Token Prediction (MTP), on-policy
 distillation, native quantization-aware training, native video/document input,
 bounded long-horizon tool-use chains, persistent forgetting diagnostics, and
-Max thinking mode (16,384-token budget). **v4.0.0-alpha.4** continues the v4 arc
+Max thinking mode (16,384-token budget). **v4.0.0-alpha.5** continues the v4 arc
 with Multi-Head Latent Attention (Phase 41), a native Audio modality
-(Phase 42), sparse/grouped MoE dispatch (Phase 43), and multi-node
-distributed training (Phase 44) — a frozen audio
+(Phase 42), sparse/grouped MoE dispatch (Phase 43), multi-node
+distributed training (Phase 44), and test-time compute scaling
+(Phase 45) — a frozen audio
 spectrogram transformer plus trainable projector that lets the model hear and
 reason about audio clips (the same frozen-encoder-plus-projector recipe vision,
 video, and documents use), real sparse expert dispatch where each token
 computes only its assigned top-k experts rather than every expert on every
 token then masked (numerically equivalent to the dense path, faster on CUDA),
-and data-parallel training extended across multiple nodes over a TCP
-rendezvous so the world can scale past a single machine's GPU count.
+data-parallel training extended across multiple nodes over a TCP
+rendezvous so the world can scale past a single machine's GPU count,
+and Best-of-N / self-consistency / verifier-guided / process-reward
+selection that generates N independent candidate completions and selects
+the best one at inference time — a new axis alongside the existing
+thinking-mode budget system, distinct from controlling how many tokens
+one generation spends reasoning.
 
 > [!IMPORTANT]
 > This is a source and engineering project. It does not publish crates to
@@ -260,6 +266,7 @@ CUDA checks require a CUDA-capable environment and are intentionally opt-in.
 | [docs/phase42_audio.md](docs/phase42_audio.md) | Audio encoder, mel-spectrogram, fusion, tuning, inference, and audio-QA evaluation |
 | [docs/phase43_sparse_moe.md](docs/phase43_sparse_moe.md) | Sparse/grouped dispatch design, CPU/CUDA honesty, and equivalence proof |
 | [docs/phase44_multi_node.md](docs/phase44_multi_node.md) | Multi-node topology, TCP rendezvous, single-retry fault policy, and validation paths |
+| [docs/phase45_test_time.md](docs/phase45_test_time.md) | Best-of-N, self-consistency, verifier, and process-reward selection at inference time |
 | [RELEASE.md](RELEASE.md) | Source-release process and artifact policy |
 | [CHANGELOG.md](CHANGELOG.md) | Versioned implementation history |
 
@@ -268,6 +275,8 @@ CUDA checks require a CUDA-capable environment and are intentionally opt-in.
 - No pretrained model, GGUF, adapter, or binary ships — you train your own.
 - MoE uses dense masked dispatch on CPU (sparse dispatch is CUDA-only, Phase 43).
   Multi-node training is data-parallel only (Phase 44), not model/pipeline-parallel.
+  Test-time compute scaling (Phase 45) is text-only and ships a heuristic
+  process-reward scorer plus a trait for a future trained head.
 - Tool chains are generated and orchestrated but never executed by the runtime.
 - Video is visual-only H.264 MP4; audio is WAV PCM only (no MP3/FLAC/Ogg).
 - Documents are pixel-based (no OCR/table parser).
@@ -290,7 +299,7 @@ reproducible bugs and scoped feature requests. Report vulnerabilities through
   author  = {Aarambh Dev Hub},
   year    = {2026},
   url     = {https://github.com/AarambhDevHub/aarambh-studio},
-  version = {4.0.0-alpha.4},
+  version = {4.0.0-alpha.5},
   license = {Apache-2.0}
 }
 ```