Enum ExtendedCommands 

pub enum ExtendedCommands {
    Chat {

        file: PathBuf,
        temperature: f32,
        top_p: f32,
        max_tokens: usize,
        system: Option<String>,
        inspect: bool,
        no_gpu: bool,
        gpu: bool,
        trace: bool,
        trace_steps: Option<Vec<String>>,
        trace_verbose: bool,
        trace_output: Option<PathBuf>,
        trace_level: String,
        profile: bool,
        backend: Option<String>,
    
},
    Bench {
        file: PathBuf,
        warmup: usize,
        iterations: usize,
        max_tokens: usize,
        prompt: Option<String>,
        fast: bool,
        brick: Option<String>,
        percentiles: Vec<f64>,
    },
    Eval {

        file: PathBuf,
        dataset: String,
        text: Option<String>,
        max_tokens: usize,
        threshold: f32,
        task: Option<String>,
        data: Option<PathBuf>,
        model_size: Option<String>,
        num_classes: usize,
        generate_card: bool,
        device: String,
        samples: usize,
        temperature: f32,
    
},
    Profile {

        file: PathBuf,
        granular: bool,
        format: String,
        focus: Option<String>,
        detect_naive: bool,
        threshold: f64,
        compare_hf: Option<String>,
        energy: bool,
        perf_grade: bool,
        callgraph: bool,
        fail_on_naive: bool,
        output: Option<PathBuf>,
        ci: bool,
        assert_throughput: Option<f64>,
        assert_p99: Option<f64>,
        assert_p50: Option<f64>,
        warmup: usize,
        measure: usize,
        tokens: usize,
        ollama: bool,
        no_gpu: bool,
        compare: Option<PathBuf>,
    
},
    Qa {

        file: PathBuf,
        assert_tps: Option<f64>,
        assert_speedup: Option<f64>,
        assert_gpu_speedup: Option<f64>,
        skip_golden: bool,
        skip_throughput: bool,
        skip_ollama: bool,
        skip_gpu_speedup: bool,
        skip_contract: bool,
        skip_format_parity: bool,
        skip_ptx_parity: bool,
        safetensors_path: Option<PathBuf>,
        iterations: usize,
        warmup: usize,
        max_tokens: usize,
        json: bool,
        verbose: bool,
        min_executed: Option<usize>,
        previous_report: Option<PathBuf>,
        regression_threshold: Option<f64>,
        skip_gpu_state: bool,
        skip_metadata: bool,
        skip_capability: bool,
        assert_classifier_head: bool,
    
},
    Parity {
        file: PathBuf,
        prompt: String,
        assert: bool,
    },
    PtxMap {
        file: PathBuf,
        kernel: Option<String>,
        reverse: Option<String>,
        json: bool,
        verbose: bool,
        prefill: bool,
    },
    Ptx {
        file: Option<PathBuf>,
        kernel: Option<String>,
        strict: bool,
        bugs: bool,
        json: bool,
        verbose: bool,
    },
    Tune {

        file: Option<PathBuf>,
        method: String,
        rank: Option<u32>,
        vram: f64,
        plan: bool,
        model: Option<String>,
        freeze_base: bool,
        train_data: Option<PathBuf>,
        json: bool,
        task: Option<String>,
        budget: usize,
        strategy: String,
        scheduler: String,
        scout: bool,
        data: Option<PathBuf>,
        num_classes: usize,
        model_size: Option<String>,
        from_scout: Option<PathBuf>,
        max_epochs: usize,
        time_limit: Option<String>,
    
},
    Monitor {
        dir: Option<PathBuf>,
        refresh_ms: u64,
        compact: bool,
        json: bool,
        format: String,
    },
    Runs {
        command: RunsCommands,
    },
    Experiment {
        command: ExperimentCommands,
    },
    Cbtop {

        model: Option<String>,
        attach: Option<String>,
        model_path: Option<PathBuf>,
        headless: bool,
        json: bool,
        output: Option<PathBuf>,
        ci: bool,
        throughput: Option<f64>,
        brick_score: Option<u32>,
        warmup: usize,
        iterations: usize,
        speculative: bool,
        speculation_k: usize,
        draft_model: Option<PathBuf>,
        concurrent: usize,
        simulated: bool,
    
},
    Probar {
        command: ProbarSubcommand,
    },
    CompareHf {
        file: PathBuf,
        hf: String,
        tensor: Option<String>,
        threshold: f64,
        json: bool,
    },
    Modelfile {
        command: ModelfileSubcommand,
    },
    Hex {

        file: PathBuf,
        tensor: Option<String>,
        limit: usize,
        stats: bool,
        list: bool,
        json: bool,
        header: bool,
        blocks: bool,
        distribution: bool,
        contract: bool,
        entropy: bool,
        raw: bool,
        offset: String,
        width: usize,
        slice: Option<String>,
    
},
    Tree {
        file: PathBuf,
        filter: Option<String>,
        format: String,
        sizes: bool,
        depth: Option<usize>,
    },
    Flow {
        file: PathBuf,
        layer: Option<String>,
        component: String,
        verbose: bool,
        json: bool,
    },
    Qualify {
        file: PathBuf,
        tier: String,
        timeout: u64,
        json: bool,
        verbose: bool,
        skip: Option<Vec<String>>,
    },
    Train {
        command: TrainCommands,
    },
    Pretrain {

        dataset: PathBuf,
        tokenizer: PathBuf,
        run_dir: PathBuf,
        mode: PretrainMode,
        lr: Option<f32>,
        num_steps: usize,
        warmup_steps: Option<usize>,
        batch_size: usize,
        seq_length: usize,
        steps_per_epoch: usize,
        seed: u64,
        target_val_loss: Option<f32>,
        vocab_size: u32,
        synthetic: bool,
        device: String,
        init: Option<PathBuf>,
        force_under_provisioned: bool,
        val_shard: Option<PathBuf>,
    
},
    Tokenize {
        command: TokenizeCommands,
    },
    Data {
        command: DataCommands,
    },
    Pipeline {
        command: PipelineCommands,
    },
    Diagnose {
        checkpoint_dir: PathBuf,
        data: Option<PathBuf>,
        model_size: Option<String>,
        num_classes: usize,
    },
    OllamaChatLint {
        response_file: PathBuf,
        stream: bool,
    },
    OllamaToolsLint {
        response_file: PathBuf,
        request_file: Option<PathBuf>,
        stream: bool,
    },
    DrySamplingLint {
        observation_file: PathBuf,
    },
    AwqLint {
        observation_file: PathBuf,
    },
    Fp8Lint {
        observation_file: PathBuf,
    },
    Nf4Lint {
        observation_file: PathBuf,
    },
    GptqLint {
        observation_file: PathBuf,
    },
    OomLint {
        report_file: PathBuf,
        stderr_file: Option<PathBuf>,
    },
    NcclDiagLint {
        diag_file: PathBuf,
        exit_code: Option<i32>,
        require_doc_link: bool,
    },
    ReactTraceLint {
        trace_file: PathBuf,
        max_iterations: Option<i64>,
        require_grammar: bool,
    },
    HangTraceLint {
        trace_dir: PathBuf,
        mode: String,
        world_size: usize,
        exit_code: Option<i32>,
        expected_exit_code: Option<i32>,
    },
    DdpMetricsLint {
        metrics_1gpu_file: PathBuf,
        metrics_ngpu_file: PathBuf,
        world_size: i64,
        scaling_floor: f64,
        loss_tolerance: f64,
    },
    AudioInspectLint {
        json_file: PathBuf,
        expected_sample_rate: Option<u32>,
        expected_channels: Option<u32>,
    },
    AttnParityLint {
        parity_file: Option<PathBuf>,
        provenance_file: Option<PathBuf>,
        head_dim_error_file: Option<PathBuf>,
        tol_abs: f64,
        tol_cos: f64,
    },
    AttnVizLint {
        attn_file: Option<PathBuf>,
        html_file: Option<PathBuf>,
        expected_heatmaps: usize,
        tolerance: f64,
        epsilon: f64,
    },
    CheckFiniteLint {
        error_file: Option<PathBuf>,
        list_file: Option<PathBuf>,
        min_layers: usize,
    },
    EmbedVizLint {
        csv_file: PathBuf,
        expected_vocab_size: Option<usize>,
        csv_file_b: Option<PathBuf>,
    },
    ExplainTokenLint {
        jsonl_file: PathBuf,
        tolerance: f64,
        require_greedy: bool,
    },
    GpuMemtraceLint {
        trace_file: PathBuf,
    },
    KvTimelineLint {
        timeline_file: PathBuf,
        preempt_threshold: f64,
    },
    OtlpLint {
        otlp_file: PathBuf,
        require_apr_span: bool,
        require_genai_attrs: bool,
        expect_trace_id: Option<String>,
    },
    PrometheusLint {
        metrics_file: PathBuf,
        content_type: Option<String>,
        require_k07_metrics: bool,
    },
    ToolUseLint {
        observation_file: PathBuf,
    },
    GbnfLint {
        observation_file: PathBuf,
    },
    TypicalPLint {
        observation_file: PathBuf,
    },
    GradNorm {
        history_file: PathBuf,
        max_grad_norm: Option<f64>,
        spike_window: usize,
        spike_multiplier: f64,
    },
    RegistryQuotaLint {
        observation_file: PathBuf,
    },
    ImatrixLint {
        observation_file: PathBuf,
    },
    EmbeddingsLint {
        observation_file: PathBuf,
    },
    UnifiedSearchLint {
        observation_file: PathBuf,
    },
    RmGcLint {
        observation_file: PathBuf,
    },
    SharedCacheLint {
        observation_file: PathBuf,
    },
    Ppl {
        log_probs_file: PathBuf,
    },
    QuantPreservationLint {
        reference: PathBuf,
        requant: PathBuf,
    },
    Shard {
        file: PathBuf,
        max_shard_size: String,
        output: PathBuf,
    },
    Unshard {
        input: PathBuf,
        output: PathBuf,
    },
    Tools(ToolCommands),
    Rerank {

        model: PathBuf,
        input_ids: Option<String>,
        token_type_ids: Option<String>,
        query: Option<String>,
        passage: Option<String>,
        passages: Vec<String>,
        sort: bool,
        top_k: usize,
        vocab: Option<PathBuf>,
        hidden_dim: usize,
        num_layers: usize,
        num_heads: usize,
        intermediate_dim: usize,
        vocab_size: usize,
        max_position_embeddings: usize,
        type_vocab_size: usize,
        num_labels: usize,
        with_pooler: bool,
        raw_logit: bool,
        json: bool,
    
},
    Embed {

        model: PathBuf,
        text: Vec<String>,
        text_file: Option<PathBuf>,
        vocab: PathBuf,
        pool: String,
        normalize: bool,
        hidden_dim: usize,
        num_layers: usize,
        num_heads: usize,
        intermediate_dim: usize,
        vocab_size: usize,
        max_position_embeddings: usize,
        type_vocab_size: usize,
        json: bool,
    
},
}

Extended CLI commands (analysis, profiling, QA, benchmarks, and advanced tools).

Flattened into Commands via #[command(flatten)] so all subcommands remain top-level from the user’s perspective (e.g., apr chat, apr profile).

Variants

Chat

Interactive chat with language model

Fields

file: PathBuf

Path to .apr model file

temperature: f32

Sampling temperature (0 = greedy, higher = more random)

top_p: f32

Nucleus sampling threshold

max_tokens: usize

Maximum tokens to generate per response

system: Option<String>

System prompt to set model behavior

inspect: bool

Show inspection info (top-k probs, tokens/sec)

no_gpu: bool

Disable GPU acceleration (use CPU)

gpu: bool

Force GPU acceleration (requires CUDA)

trace: bool

Enable inference tracing (APR-TRACE-001)

trace_steps: Option<Vec<String>>

Trace specific steps only (comma-separated)

trace_verbose: bool

Verbose tracing

trace_output: Option<PathBuf>

Save trace output to JSON file

trace_level: String

Trace detail level (none, basic, layer, payload)

profile: bool

Enable inline Roofline profiling (PMAT-SHOWCASE-METHODOLOGY-001)

backend: Option<String>

PMAT-488: Compute backend override (cuda, cpu, wgpu)

Bench

Benchmark throughput (spec H12: >= 10 tok/s)

Fields

file: PathBuf

Path to model file

warmup: usize

Number of warmup iterations

iterations: usize

Number of measurement iterations

max_tokens: usize

Max tokens to generate per iteration

prompt: Option<String>

Test prompt

fast: bool

Use realizar for fast inference (vs aprender baseline)

brick: Option<String>

Benchmark specific brick

percentiles: Vec<f64>

Comma-separated latency percentile points for JSON output (CRUX-E-07). Default: 50,95,99. Values must be in (0, 100].

Eval

Evaluate model perplexity (spec H13: PPL <= 20) or classification metrics

Fields

file: PathBuf

Path to model file or checkpoint directory

dataset: String

Dataset: wikitext-2, lambada, or custom

text: Option<String>

Custom text (when dataset=custom)

max_tokens: usize

Maximum tokens to evaluate

threshold: f32

Perplexity threshold for pass/fail

task: Option<String>

Task type: omit for perplexity, “classify” for classification eval

data: Option<PathBuf>

Test data file (JSONL) for classification evaluation

model_size: Option<String>

Model size hint: “0.5B”, “tiny” (for classification eval)

num_classes: usize

Number of output classes (default: 5)

generate_card: bool

Generate HuggingFace model card (README.md) in checkpoint dir

device: String

Device for inference: “cpu” (default) or “cuda” (GPU-accelerated, ALB-089)

samples: usize

Number of samples per problem for pass@k (ALB-088, default: 1)

temperature: f32

Sampling temperature (0.0 = greedy, 0.8 = standard for pass@k>1)

Profile

Deep profiling with Roofline analysis

Fields

file: PathBuf

Path to model file

granular: bool

Layer-by-layer granular analysis

format: String

Output format (human, json, flamegraph)

focus: Option<String>

Focus on specific operation

detect_naive: bool

Detect naive implementations

threshold: f64

GFLOPS threshold for naive detection

compare_hf: Option<String>

Compare against HuggingFace baseline

energy: bool

Measure energy consumption (requires RAPL)

perf_grade: bool

Compute performance grade (vs Ollama baseline)

callgraph: bool

Show call graph

fail_on_naive: bool

Exit non-zero if naive implementation detected

output: Option<PathBuf>

Output file path for flamegraph SVG (GH-174, PMAT-182)

ci: bool

Enable CI mode with assertion checks (exits 1 on failure)

assert_throughput: Option<f64>

Minimum throughput in tok/s (CI assertion, exits 1 if below)

assert_p99: Option<f64>

Maximum p99 latency in ms (CI assertion, exits 1 if above)

assert_p50: Option<f64>

Maximum p50 latency in ms (CI assertion, exits 1 if above)

warmup: usize

Warmup passes before measurement (default: 3)

measure: usize

Measurement passes (default: 10)

tokens: usize

Number of tokens to generate per measurement pass (default: 32)

ollama: bool

Compare against Ollama baseline (runs ollama for comparison)

no_gpu: bool

Disable GPU (force CPU-only profiling)

compare: Option<PathBuf>

Compare against another model format (F-PROFILE-011)

Qa

Falsifiable QA checklist for model releases

Fields

file: PathBuf

Path to model file

assert_tps: Option<f64>

Minimum throughput threshold in tok/s

assert_speedup: Option<f64>

Minimum speedup vs Ollama

assert_gpu_speedup: Option<f64>

Minimum GPU vs CPU speedup (F-PERF-042)

skip_golden: bool

Skip golden output test

skip_throughput: bool

Skip throughput benchmark

skip_ollama: bool

Skip Ollama parity comparison

skip_gpu_speedup: bool

Skip GPU vs CPU speedup test (F-PERF-042)

skip_contract: bool

Skip tensor contract validation (PMAT-235)

skip_format_parity: bool

Skip cross-format parity test (F-QUAL-032)

skip_ptx_parity: bool

Skip PTX parity validation (GH-219)

safetensors_path: Option<PathBuf>

SafeTensors model path for cross-format parity test (F-QUAL-032)

iterations: usize

Number of benchmark iterations

warmup: usize

Number of warmup iterations

max_tokens: usize

Maximum tokens to generate

json: bool

Output as JSON (for CI integration)

verbose: bool

Verbose output

min_executed: Option<usize>

Minimum number of gates that must execute (fail if fewer)

previous_report: Option<PathBuf>

Previous QA report for regression detection

regression_threshold: Option<f64>

Maximum allowed performance regression ratio (default: 0.10 = 10%)

skip_gpu_state: bool

Skip GPU state isolation test

skip_metadata: bool

Skip metadata plausibility validation (Bug 210, GH-222)

skip_capability: bool

Skip GPU capability match gate (GH-280)

assert_classifier_head: bool

Assert classifier head presence and shape (F-CLASS-004)

Parity

GPU/CPU parity check (PMAT-232: genchi genbutsu — see where GPU diverges)

Fields

file: PathBuf

Path to GGUF model file

prompt: String

Prompt text (default: “What is 2+2?”)

assert: bool

Assert parity (exit non-zero on divergence)

PtxMap

Model-to-PTX source mapping (Mieruka: make GPU kernel dispatch visible)

Fields

file: PathBuf

Path to GGUF model file

kernel: Option<String>

Filter to specific kernel (e.g., –kernel Q4KGemv)

reverse: Option<String>

Reverse lookup: kernel name -> which layers/steps use it

json: bool

Output as JSON

verbose: bool

Full PTX snippets and detailed analysis

prefill: bool

Show batched prefill kernel variants instead of decode

Ptx

PTX analysis and bug detection (register pressure, roofline)

Fields

file: Option<PathBuf>

Path to a PTX source file

kernel: Option<String>

Analyze a named kernel from trueno-gpu

strict: bool

Strict mode (no performance whitelist)

bugs: bool

Show only bug analysis (skip register/memory/roofline)

json: bool

Output as JSON

verbose: bool

Verbose output (include PTX source listing)

Tune

ML tuning: LoRA/QLoRA configuration, memory planning, and HPO (GH-176, SPEC-TUNE-2026-001)

Fields

file: Option<PathBuf>

Path to model file (optional if using –model)

method: String

Tuning method: auto, full, lora, qlora

rank: Option<u32>

LoRA rank (default: auto-selected)

vram: f64

Available VRAM in GB

plan: bool

Only plan configuration, don’t train

model: Option<String>

Model size for planning (e.g., “7B”, “1.5B”)

freeze_base: bool

Freeze base model weights

train_data: Option<PathBuf>

Training data file (JSONL format)

json: bool

Output as JSON (for CI integration)

task: Option<String>

Task type for HPO: classify (SPEC-TUNE-2026-001)

budget: usize

Number of HPO trials (default: 10)

strategy: String

HPO search strategy: tpe, grid, random

scheduler: String

HPO scheduler: asha, median, none

scout: bool

Scout mode: 1 epoch per trial for fast exploration

data: Option<PathBuf>

Training data file for HPO (JSONL format)

num_classes: usize

Number of output classes for classification

model_size: Option<String>

Model size hint for HPO (e.g., “0.5B”, “1.5B”)

from_scout: Option<PathBuf>

Warm-start from scout phase results directory

max_epochs: usize

Maximum epochs per trial (full mode, default: 20)

time_limit: Option<String>

Maximum wall-clock time (e.g., “8h”, “30m”)

Monitor

Attach live TUI to a running training session

Fields

dir: Option<PathBuf>

Experiment output directory (same as finetune -o)

refresh_ms: u64

Refresh interval in milliseconds

compact: bool

Compact display mode

json: bool

Output JSON lines instead of TUI (for LLM agents and CI)

format: String

Output format: tui (default), json, text

Runs

List, show, and compare training experiment runs

Fields

command: RunsCommands

Experiment

Interactive experiment browser (TUI with loss curves)

Fields

command: ExperimentCommands

Cbtop

ComputeBrick pipeline monitor (cbtop)

Fields

model: Option<String>

Model name (e.g., qwen2.5-coder-1.5b)

attach: Option<String>

Attach to running realizar process

model_path: Option<PathBuf>

Path to GGUF model file for real profiling

headless: bool

Run in headless mode (no TUI, for CI/automation)

json: bool

Output JSON format (requires –headless)

output: Option<PathBuf>

Output file path (requires –headless)

ci: bool

CI mode: exit with code 1 if thresholds not met

throughput: Option<f64>

Minimum throughput threshold in tok/s (for –ci)

brick_score: Option<u32>

Minimum brick score threshold 0-100 (for –ci)

warmup: usize

Number of warmup iterations before measurement

iterations: usize

Number of measurement iterations

speculative: bool

PAR-100: Enable speculative decoding benchmark

speculation_k: usize

PAR-100: Number of tokens to draft speculatively (default: 4)

draft_model: Option<PathBuf>

PAR-099: Path to draft model for speculative decoding

concurrent: usize

PAR-102: Number of concurrent requests

simulated: bool

Use simulated data (for CI testing only)

Probar

Probar testing framework (GH-876 — visual regression, replay, more).

GH-876 Milestone 1: apr probar tensor migrates the existing flat apr probar <FILE> behavior (PMAT-481 tensor visual regression). The remaining probador subcommands (test, record, coverage, playbook, comply, av-sync, audio, video, animation, stress, llm) land in follow-up PRs that delegate to the probador library.

Fields

command: ProbarSubcommand

CompareHf

Compare APR model against HuggingFace source

Fields

file: PathBuf

Path to .apr model file

hf: String

HuggingFace repo ID (e.g., openai/whisper-tiny)

tensor: Option<String>

Filter tensors by name pattern

threshold: f64

Comparison threshold (default: 1e-5)

json: bool

Output as JSON

Modelfile

CRUX-K-11: parse Ollama-style Modelfile DSL into apr config.

Fields

command: ModelfileSubcommand

Hex

Format-aware binary forensics (10X better than xxd)

Fields

file: PathBuf

Path to model file (APR, GGUF, or SafeTensors)

tensor: Option<String>

Filter tensors by name pattern

limit: usize

Limit bytes/values to display

stats: bool

Show tensor statistics

list: bool

List tensor names only

json: bool

Output as JSON

header: bool

Annotated file header (magic, version, tensor count, metadata)

blocks: bool

Q4K/Q6K/Q8_0 super-block structure with field annotations

distribution: bool

Value histogram + entropy + kurtosis analysis

contract: bool

Layout contract verification overlay per tensor

entropy: bool

Per-region byte entropy analysis

raw: bool

Raw bytes (like xxd but format-aware, with ASCII column)

offset: String

Start at byte offset (supports 0x prefix for hex)

width: usize

Bytes per row for raw output (default: 16)

slice: Option<String>

Slice range for partial tensor reads (e.g., 0:3 for first 3 elements)

Tree

Model architecture tree view

Fields

file: PathBuf

Path to .apr model file

filter: Option<String>

Filter by component pattern

format: String

Output format: ascii, dot, mermaid, json

sizes: bool

Show tensor sizes

depth: Option<usize>

Maximum tree depth

Flow

Data flow visualization

Fields

file: PathBuf

Path to .apr model file

layer: Option<String>

Filter by layer pattern

component: String

Component to visualize: full, encoder, decoder, etc.

verbose: bool

Verbose output with statistics

json: bool

Output as JSON

Qualify

Cross-subcommand smoke test (does every tool handle this model?)

Fields

file: PathBuf

Path to model file (APR, GGUF, or SafeTensors)

tier: String

Testing tier: smoke (Phase 1), standard (+contracts), full (+playbook)

timeout: u64

Timeout per gate in seconds

json: bool

Output as JSON

verbose: bool

Show subcommand output (disable stdout suppression)

skip: Option<Vec<String>>

Skip specific gates (comma-separated)

Train

Training pipeline (plan/apply) — forjar-style pre-flight validation

Fields

command: TrainCommands

Pretrain

Pretraining loop driver (SHIP-TWO-001 MODEL-2).

Wires the pretraining loop shape defined by contracts/training-loop-pretrain-v1.yaml. Executes a synthetic decreasing-loss drive by default so GATE-TRAIN-005 / -007 / -008 divergence-and-NaN guards can be exercised without an actual 370M compute run. Real corpus wiring is a follow-up ticket.

Fields

dataset: PathBuf

Dataset path (tokenized shard index or raw corpus).

tokenizer: PathBuf

Tokenizer directory (vocab.json + merges.txt).

run_dir: PathBuf

Run output directory — checkpoints + metadata go to {run_dir}/ckpt/.

mode: PretrainMode

Training regime — finetune (MODEL-1) or from-scratch (MODEL-2 cold start). Per contract training-loop-pretrain-v1 §hyperparameter_defaults, this atomically flips (regime, lr_max, warmup_steps, target_val_loss) unless explicit –lr / –warmup-steps / –target-val-loss override.

lr: Option<f32>

Peak learning rate after warmup. Omit to inherit mode default (finetune: 5e-5, from-scratch: 3e-4).

num_steps: usize

Warmup + cosine decay total steps.

warmup_steps: Option<usize>

Number of warmup steps. Omit to inherit mode default (finetune: 100, from-scratch: 1000).

batch_size: usize

Micro-batch size.

seq_length: usize

Sequence length per example.

steps_per_epoch: usize

Steps per epoch — controls per-epoch artifact cadence.

seed: u64

GATE-TRAIN-006 fixed RNG seed.

target_val_loss: Option<f32>

Target val_loss. Omit to inherit mode default (finetune: 2.2, from-scratch: 3.0).

vocab_size: u32

Vocabulary size (required for --mode from-scratch INV-TRAIN-005 regime-dependent cap: 2·ln(vocab_size)). MODEL-2 uses 50257.

synthetic: bool

Synthetic-drive only — do not attempt real compute, exercise loop gates only. INV-TRAIN-010: absent = real compute (drive_real), present = synthetic (drive_synthetic).

device: String

Training backend. Grammar (contract gpu-training-backend-v1 INV-GPUTRAIN-001): ^(cpu|cuda(:[0-9]|:1[0-5])?|auto)$. Default auto uses CUDA if available, else CPU (the only spelling that may fall back silently — all other values hard-fail on missing runtime per GATE-GPUTRAIN-002).

init: Option<PathBuf>

Initial weights from a pretrained APR file (contract apr-pretrain-from-init-v1). Per spec §49’s MODEL-2 pretrained-init pivot: when present, load weights from <PATH> instead of random-init. Composes with --mode finetune (canonical) or --mode from-scratch (allowed but non-canonical — emits a warning). Missing, corrupted, or arch-mismatched APR files exit non-zero before step 1 (no silent random-init fallback).

force_under_provisioned: bool

SPEC §83 P0-J: bypass the Chinchilla compute-optimal hard gate (chinchilla-gate-v1). Default is fail-fast when D/N < 10× (severely under-provisioned per Hoffmann et al. 2022). Pass this flag to acknowledge the under-provisioning and proceed anyway (e.g. for ablation studies, resumed runs, or smoke tests).

val_shard: Option<PathBuf>

SPEC §84 P2-F: shared held-out validation shard.

When provided, the val-loss eval reads HELD_OUT_BATCHES batches from this separate .bin-shards directory instead of stealing the first 16 batches of --dataset. This makes val_loss comparable across runs whose --dataset composition changes (P2-C’s audit-falsified result was confounded by val sets being drawn from different corpus distributions — qwen-v2 = codeparrot only, qwen-v3 = codeparrot + the-stack-dedup).

Path semantics: directory of .bin shards (same format as --dataset). Operator tokenizes the held-out corpus independently via apr tokenize encode-corpus --max-docs N to a separate output dir, then passes that dir here. The shard contract is contracts/dataset-thestack-python-v1.yaml.

When omitted, falls back to the historical “first 16 batches of –dataset” behaviour for backwards compatibility.

Tokenize

Tokenizer training pipeline (plan/apply) — BPE vocabulary learning

Fields

command: TokenizeCommands

Data

Data quality pipeline (audit, split, balance) — powered by alimentar

Fields

command: DataCommands

Pipeline

Pipeline orchestration (plan/apply/status) — wraps forjar DAG engine

Fields

command: PipelineCommands

Diagnose

Automated Five Whys diagnosis on a training checkpoint

Fields

checkpoint_dir: PathBuf

Path to checkpoint directory

data: Option<PathBuf>

Test data file (JSONL) for evaluation

model_size: Option<String>

Model size hint: “0.5B”, “tiny”

num_classes: usize

Number of output classes (default: 5)

OllamaChatLint

Lint an Ollama /api/chat response for schema + NDJSON invariants (CRUX-C-04)

Fields

response_file: PathBuf

Path to captured /api/chat response (JSON object, or NDJSON if –stream)

stream: bool

Treat input as NDJSON stream (one frame per line)

OllamaToolsLint

Lint an Ollama /api/chat function-calling response (CRUX-I-04)

Fields

response_file: PathBuf

Path to captured /api/chat response (JSON object, or NDJSON if –stream)

request_file: Option<PathBuf>

Optional captured request JSON — enables tool-name allowlist gate (every called tool name must appear in request.tools[*].function.name)

stream: bool

Treat input as NDJSON stream (one frame per line)

DrySamplingLint

Lint a captured DRY-sampling observation (CRUX-C-23)

Fields

observation_file: PathBuf

Path to observation JSON

AwqLint

Lint a captured AWQ quality/compression/flags observation (CRUX-B-08)

Fields

observation_file: PathBuf

Path to captured AWQ observation JSON

Fp8Lint

Lint a captured FP8 (E4M3) round-trip + SM-capability observation (CRUX-B-11)

Fields

observation_file: PathBuf

Path to captured observation JSON (frobenius, capability blocks)

Nf4Lint

Lint a captured NF4 codebook/roundtrip/storage/parity observation (CRUX-B-10)

Fields

observation_file: PathBuf

Path to captured NF4 observation JSON

GptqLint

Lint a captured GPTQ compression/cosine/flags observation (CRUX-B-09)

Fields

observation_file: PathBuf

Path to captured GPTQ observation JSON

OomLint

Lint a captured CUDA OOM postmortem report (CRUX-F-13)

Fields

report_file: PathBuf

Path to captured OOM postmortem JSON (e.g. /tmp/apr-oom-.json)

stderr_file: Option<PathBuf>

Optional captured stderr log to verify the OOM_REPORT breadcrumb

NcclDiagLint

Lint a captured NCCL failure-diagnostics JSON from stderr (CRUX-F-15)

Fields

diag_file: PathBuf

Path to captured stderr JSON diagnostic

exit_code: Option<i32>

Optional observed exit code (gate: >= 128 = NCCL class)

require_doc_link: bool

Require the suggest field to cite an nvidia.com / NVIDIA/nccl URL

ReactTraceLint

Lint a captured apr agent --trace ReAct loop trace (CRUX-I-06)

Fields

trace_file: PathBuf

Path to captured trace JSON

max_iterations: Option<i64>

Optional max_iterations budget the trace was produced under

require_grammar: bool

Require the scratchpad to parse cleanly as Thought/Action/Observation blocks

HangTraceLint

Lint a captured $APR_TRACE_DIR hang stack-dump directory (CRUX-F-14)

Fields

trace_dir: PathBuf

Path to the captured trace directory

mode: String

Inspection mode: timeout (expects per-rank dumps) or success (expects empty dir)

world_size: usize

Expected world_size when mode=timeout (number of rank{N}.py.txt files)

exit_code: Option<i32>

Actual exit code from the run under inspection (for exit-code gate)

expected_exit_code: Option<i32>

Expected exit code (typically 124 for timeout, 1 for other error, 0 for success)

DdpMetricsLint

Lint two captured apr finetune --parallel ddp --json outputs (N=1, N=k) (CRUX-D-11)

Fields

metrics_1gpu_file: PathBuf

Path to N=1 metrics JSON

metrics_ngpu_file: PathBuf

Path to N=world_size metrics JSON

world_size: i64

World size used for –metrics-ngpu-file run (>= 2)

scaling_floor: f64

Scaling-efficiency floor (default 0.85, PyTorch DDP convention)

loss_tolerance: f64

Loss-parity relative tolerance (default 0.01)

AudioInspectLint

Lint a captured apr dataset audio-inspect --format json body (CRUX-H-13)

Fields

json_file: PathBuf

Path to captured JSON body

expected_sample_rate: Option<u32>

Optional expected sample_rate (typically the --resample-to arg)

expected_channels: Option<u32>

Optional expected channel count (1 = mono after –mono)

AttnParityLint

Lint captured flash-attn2 parity + provenance JSON outputs (CRUX-L-02)

Fields

parity_file: Option<PathBuf>

Path to captured apr kernel parity --impl flash2 --ref naive --json body

provenance_file: Option<PathBuf>

Path to captured apr run --attn flash2 --json body for provenance check

head_dim_error_file: Option<PathBuf>

Path to captured head_dim error JSON

tol_abs: f64

Max absolute diff tolerance (default 5e-3, FlashAttention-2 bound)

tol_cos: f64

Min cosine similarity floor (default 0.9999)

AttnVizLint

Lint a captured apr attn-viz attention dump (CRUX-F-17)

Fields

attn_file: Option<PathBuf>

Path to attention dump in JSON form (4-D [layers][heads][rows][cols] floats)

html_file: Option<PathBuf>

Path to HTML heatmap output

expected_heatmaps: usize

Minimum <svg|<canvas open-tag count expected in HTML (|layers|*|heads|)

tolerance: f64

Row-softmax normalization tolerance (default 1e-5)

epsilon: f64

Causal-mask zero epsilon (default 1e-9)

CheckFiniteLint

Lint a captured apr trace --check-finite error JSON and/or --list coverage JSON (CRUX-F-11)

Fields

error_file: Option<PathBuf>

Captured stderr JSON from apr trace --check-finite on a poisoned model

list_file: Option<PathBuf>

Captured stdout JSON from apr trace --check-finite --list

min_layers: usize

Minimum layer-coverage count when --list-file is supplied (default 100)

EmbedVizLint

Lint a captured apr debug embed-viz CSV (CRUX-F-18)

Fields

csv_file: PathBuf

Path to captured embed-viz CSV (token_id,token_str,x,y)

expected_vocab_size: Option<usize>

Expected row count == vocab_size (optional)

csv_file_b: Option<PathBuf>

Second CSV captured under the same seed for determinism check (optional)

ExplainTokenLint

Lint a captured apr explain --format jsonl token-selection trace (CRUX-F-19)

Fields

jsonl_file: PathBuf

Path to captured JSONL body (one sampled-token record per line)

tolerance: f64

Tolerance for Σ post_prob ≈ 1.0 (default 1e-5)

require_greedy: bool

Assert greedy decoding: sampled_id must equal argmax(pre_prob)

GpuMemtraceLint

Lint a captured GPU memory Chrome Trace Event Format JSON (CRUX-F-07)

Fields

trace_file: PathBuf

Path to captured Chrome Trace JSON from apr profile --gpu-memory-trace

KvTimelineLint

Lint a captured KV-cache utilization timeline (CRUX-F-06)

Fields

timeline_file: PathBuf

Path to captured apr profile --kv-timeline --json body

preempt_threshold: f64

Preemption threshold (default 0.95, vLLM canonical)

OtlpLint

Lint a captured OTLP/JSON ExportTraceServiceRequest body (CRUX-K-08)

Fields

otlp_file: PathBuf

Path to captured OTLP/JSON export body

require_apr_span: bool

Require at least one apr.inference span to be present

require_genai_attrs: bool

Require gen_ai.* and apr.tokens.* attribute keys on some span

expect_trace_id: Option<String>

Verify W3C trace-context propagation: expect this 32-hex traceId

PrometheusLint

Lint a captured Prometheus /metrics response (CRUX-K-07)

Fields

metrics_file: PathBuf

Path to captured /metrics response body (text/plain; version=0.0.4)

content_type: Option<String>

Optional captured Content-Type header to verify against version=0.0.4

require_k07_metrics: bool

Require the K-07 metric set (apr_num_requests_running, …) to be present

ToolUseLint

Lint a captured OpenAI tool-use response (CRUX-C-11)

Fields

observation_file: PathBuf

Path to captured OpenAI tool-use response JSON

GbnfLint

Lint a GBNF grammar-constrained observation (CRUX-C-10)

Fields

observation_file: PathBuf

Path to captured GBNF observation JSON

TypicalPLint

Lint a typical-p sampling observation (CRUX-C-22)

Fields

observation_file: PathBuf

GradNorm

Gradient-norm telemetry analysis (CRUX-F-09)

Fields

history_file: PathBuf

Path to JSON file of per-step grad-norm records

max_grad_norm: Option<f64>

Maximum allowed clipped grad-norm (for cap-violation check)

spike_window: usize

Rolling-median window size for spike detection (in steps)

spike_multiplier: f64

Multiplier threshold for spike detection

RegistryQuotaLint

Lint a captured registry byte-quota observation (CRUX-A-22)

Fields

observation_file: PathBuf

Path to captured quota/atomic/ceiling observation JSON

ImatrixLint

Lint a captured imatrix calibration observation (CRUX-B-07)

Fields

observation_file: PathBuf

Path to captured imatrix observation JSON

EmbeddingsLint

Lint a captured /v1/embeddings observation (CRUX-C-13)

Fields

observation_file: PathBuf

UnifiedSearchLint

Lint a captured Hub+local unified-search merge observation (CRUX-A-23)

Fields

observation_file: PathBuf

Path to captured unified-search observation JSON

RmGcLint

Lint a captured apr rm / apr gc blob-GC observation (CRUX-A-25)

Fields

observation_file: PathBuf

Path to captured rm/gc observation JSON

SharedCacheLint

Lint a captured APR_MODELS shared-cache observation (CRUX-A-21)

Fields

observation_file: PathBuf

Path to captured dedup/permission observation JSON

Ppl

Perplexity classifier (CRUX-E-02)

Fields

log_probs_file: PathBuf

JSON file containing an array of per-token natural-log probabilities (e.g. [-1.2, -0.5, -2.1, ...]). Required.

QuantPreservationLint

Validate dequant→requant metadata preservation (CRUX-B-19)

Fields

reference: PathBuf

Reference GGUF (pre-roundtrip)

requant: PathBuf

Requantized GGUF (post-roundtrip)

Shard

Split a safetensors file into shards + weight-map index (CRUX-B-05)

Fields

file: PathBuf

Single-file safetensors model to split

max_shard_size: String

Maximum size of each shard (e.g. 5GB, 500MB, 1.5GiB)

output: PathBuf

Output directory for shards + model.safetensors.index.json

Unshard

Reconstruct a single safetensors file from a sharded directory (CRUX-B-05)

Fields

input: PathBuf

Sharded directory containing model.safetensors.index.json

output: PathBuf

Output single-file safetensors path

Tools(ToolCommands)

Publishing, conversion, and analysis tools

Rerank

Score a query/passage pair (or rank multiple passages) with a BERT cross-encoder loaded from an APR v2 file (GH-326 Phase 3).

Wraps aprender_core::models::bert::CrossEncoder::load_from_reader

• score(). The APR must contain the canonical HF BERT tensor names (see models::bert::expected_bert_tensor_names).

Tokenisation is NOT applied here — caller passes pre-tokenised input_ids + token_type_ids as comma-delimited u32 lists. A dedicated tokeniser-aware mode is Phase 3b follow-up scope.

Fields

model: PathBuf

Path to the APR file containing the cross-encoder weights.

input_ids: Option<String>

Pre-tokenised input ids (comma-separated u32s). Mutually exclusive with --query+--passage+--vocab (Phase 3b). Example: --input-ids 101,2024,102,3456,102 for [CLS] q [SEP] p [SEP].

token_type_ids: Option<String>

Pre-tokenised token-type ids (comma-separated u32s). Same length as --input-ids. 0 for query side, 1 for passage.

query: Option<String>

Phase 3b — query text. Pair with --passage + --vocab to enable in-process WordPiece tokenisation. The tokeniser builds [CLS] query [SEP] passage [SEP] with token_type_ids = 0 for the query side and 1 for the passage side.

passage: Option<String>

Phase 3b — passage text. Required when --query is supplied in single-pair mode (use --passages for batch ranking).

passages: Vec<String>

Phase 5 — batch ranking mode (#326). Passage candidates to score against --query. May be supplied multiple times: apr rerank model.apr --query "..." --passages "p1" --passages "p2". Mutually exclusive with --passage. Output is one score[i] line per passage in input order, OR a JSON array of {passage, logit, score} objects sorted by descending score when --sort is set.

sort: bool

Phase 5 — sort batch output by descending score (highest relevance first). Only meaningful with --passages and --json. Default: preserve input order.

top_k: usize

Phase 5 — limit to top-K passages after sorting. Implies --sort. Default 0 (no limit).

vocab: Option<PathBuf>

Phase 3b — path to a WordPiece vocab.txt (one token per line, line index = token id). Required when --query is supplied. Must contain entries for [CLS], [SEP], and [UNK]. Phase 4 accepts HuggingFace tokenizer.json (extension-detected).

hidden_dim: usize

Override hidden_dim (default: 384 / MiniLM-L-6).

num_layers: usize

Override num_layers (default: 6 / MiniLM-L-6).

num_heads: usize

Override num_heads (default: 12 / MiniLM-L-6).

intermediate_dim: usize

Override intermediate_dim (default: 1536 / MiniLM-L-6).

vocab_size: usize

Override vocab_size (default: 30522 / bert-base-uncased).

max_position_embeddings: usize

Override max_position_embeddings (default: 512).

type_vocab_size: usize

Override type_vocab_size (default: 2).

num_labels: usize

Number of labels in the classifier head (default: 1 for regression-style relevance scoring).

with_pooler: bool

Load the optional BERT pooler dense layer (default: true). Cross-encoders that skip the pooler should pass --with-pooler false.

raw_logit: bool

Emit the raw logit instead of the sigmoid-mapped relevance score.

json: bool

Output as JSON.

Embed

Produce sentence embeddings from a BERT bi-encoder (GH-326 Phase 6).

First-stage dense retrieval companion to apr rerank. Loads an encoder-only BertModel (e.g. sentence-transformers/all-MiniLM-L6-v2), tokenises the input text with WordPiece, runs the full encoder forward, then pools the hidden states with one of: --pool cls — take the [CLS] hidden state --pool mean — mean over non-padding token positions (default; sentence-transformers convention) Optionally L2-normalises the result (--normalize, default true, matches sentence-transformers).

Fields

model: PathBuf

Path to the APR file containing the encoder weights (BertModel).

text: Vec<String>

Text to encode. Repeatable: apr embed model.apr --text "a" --text "b" --vocab tok.json.

text_file: Option<PathBuf>

Phase 7 (GH-326) — read texts from a file, one per line. Concatenated with --text inputs in order: --text first, then --text-file rows. Blank lines and lines starting with # are skipped. Useful for RAG-style first-stage retrieval where the second-stage rerank candidate set (50-100 documents) is the embed input.

vocab: PathBuf

Path to a WordPiece vocab.txt or HF tokenizer.json.

pool: String

Pooling strategy (cls or mean). Default: mean (matches sentence-transformers convention).

normalize: bool

L2-normalise the output embedding. Default: true (matches sentence-transformers convention). Pass --normalize false to keep raw magnitudes.

hidden_dim: usize

Override hidden_dim (default: 384 / MiniLM).

num_layers: usize

Override num_layers (default: 6 / MiniLM-L-6).

num_heads: usize

Override num_heads.

intermediate_dim: usize

Override intermediate_dim.

vocab_size: usize

Override vocab_size.

max_position_embeddings: usize

Override max_position_embeddings.

type_vocab_size: usize

Override type_vocab_size.

json: bool

Output as JSON.

Trait Implementations

impl Debug for ExtendedCommands

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromArgMatches for ExtendedCommands

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut<'b>( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Subcommand for ExtendedCommands

fn augment_subcommands<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_subcommands_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

fn has_subcommand(__clap_name: &str) -> bool

Test whether Self can parse a specific subcommand