Skip to main content

hyprstream_core/cli/commands/
training.rs

1//! Training CLI commands
2//!
3//! Provides training-specific commands that modify adapter weights:
4//! - `training init` - Initialize adapter for training
5//! - `training infer` - Inference with TTT (dirty writes)
6//! - `training batch` - Batch training with checkpoints
7//! - `training checkpoint` - Commit dirty adapter changes
8
9use clap::{Args, Subcommand};
10use std::path::PathBuf;
11
12use super::KVQuantArg;
13
14/// Training management commands
15#[derive(Args)]
16pub struct TrainingCommand {
17    #[command(subcommand)]
18    pub action: TrainingAction,
19}
20
21/// Training actions
22#[derive(Subcommand)]
23pub enum TrainingAction {
24    /// Initialize adapter for training
25    ///
26    /// Creates a new LoRA adapter and configures the model for TTT training.
27    /// Optionally creates a new branch/worktree for isolated training.
28    Init {
29        /// Model reference (e.g., "qwen3-small", "qwen3-small:main")
30        model: String,
31
32        /// Create new branch for isolated training
33        #[arg(long, short = 'B')]
34        branch: Option<String>,
35
36        /// Adapter name (will be auto-prefixed with index)
37        #[arg(long)]
38        adapter: Option<String>,
39
40        /// Explicit index for adapter (auto-increments if not specified)
41        #[arg(long)]
42        index: Option<u32>,
43
44        /// LoRA rank (default: 16)
45        #[arg(long, short = 'r', default_value = "16")]
46        rank: u32,
47
48        /// LoRA alpha (default: 32)
49        #[arg(long, default_value = "32")]
50        alpha: u32,
51
52        /// Training mode: ttt (default), supervised
53        #[arg(long, default_value = "ttt")]
54        mode: String,
55
56        /// Learning rate
57        #[arg(long, short = 'l', default_value = "0.0003")]
58        learning_rate: f32,
59    },
60
61    /// Inference with TTT (dirty writes to adapters)
62    ///
63    /// Runs inference while applying Test-Time Training. This modifies
64    /// the adapter weights during inference. Use `training checkpoint`
65    /// to commit changes when ready.
66    Infer {
67        /// Model reference (e.g., "qwen3-small:experiment")
68        model: String,
69
70        /// Prompt text (reads from stdin if not provided)
71        #[arg(short, long)]
72        prompt: Option<String>,
73
74        /// Image file path for multimodal models
75        #[arg(short = 'i', long)]
76        image: Option<String>,
77
78        /// Maximum tokens to generate
79        #[arg(short = 'm', long)]
80        max_tokens: Option<usize>,
81
82        /// Temperature for sampling (0.0 = deterministic)
83        #[arg(short = 't', long)]
84        temperature: Option<f32>,
85
86        /// Top-p (nucleus) sampling
87        #[arg(long)]
88        top_p: Option<f32>,
89
90        /// Top-k sampling
91        #[arg(long)]
92        top_k: Option<usize>,
93
94        /// Repetition penalty (1.0 = no penalty, >1.0 = penalize)
95        #[arg(short = 'r', long)]
96        repeat_penalty: Option<f32>,
97
98        /// Collect full response before printing (default: stream tokens live)
99        #[arg(long)]
100        sync: bool,
101
102        /// Maximum context length for KV cache allocation
103        #[arg(long, env = "HYPRSTREAM_MAX_CONTEXT")]
104        max_context: Option<usize>,
105
106        /// KV cache quantization type
107        #[arg(long, value_enum, default_value = "none", env = "HYPRSTREAM_KV_QUANT")]
108        kv_quant: KVQuantArg,
109    },
110
111    /// Batch training with checkpoints
112    ///
113    /// Loads model once and processes all input files, applying TTT
114    /// to each. Auto-checkpoints at specified intervals.
115    Batch {
116        /// Model reference (e.g., "qwen3-small:experiment")
117        model: String,
118
119        /// Input file(s) - can specify multiple times
120        #[arg(short, long)]
121        input: Vec<String>,
122
123        /// Input directory to scan for files
124        #[arg(long)]
125        input_dir: Option<PathBuf>,
126
127        /// File pattern for --input-dir (default: "*.txt")
128        #[arg(long, default_value = "*.txt")]
129        pattern: String,
130
131        /// Input format: "text" (raw files) or "jsonl" (structured)
132        #[arg(long, default_value = "text")]
133        format: String,
134
135        /// Max tokens to generate per file (for text format)
136        #[arg(long, default_value = "100")]
137        max_tokens: usize,
138
139        /// Characters to read from each file
140        #[arg(long, default_value = "4000")]
141        chunk_size: usize,
142
143        /// Skip first N files (for resume)
144        #[arg(long, default_value = "0")]
145        skip: usize,
146
147        /// Process only N files
148        #[arg(long)]
149        limit: Option<usize>,
150
151        /// Show progress every N files
152        #[arg(long, default_value = "10")]
153        progress_interval: usize,
154
155        /// Checkpoint (commit) every N files
156        #[arg(long, default_value = "100")]
157        checkpoint_interval: usize,
158
159        /// Test set files for validation (glob pattern)
160        #[arg(long)]
161        test_set: Option<String>,
162
163        /// Maximum context length for KV cache allocation
164        #[arg(long, env = "HYPRSTREAM_MAX_CONTEXT")]
165        max_context: Option<usize>,
166
167        /// KV cache quantization type
168        #[arg(long, value_enum, default_value = "none", env = "HYPRSTREAM_KV_QUANT")]
169        kv_quant: KVQuantArg,
170    },
171
172    /// Commit dirty adapter changes to git
173    ///
174    /// Stages and commits modified adapter safetensor files.
175    /// Use after `training infer` or `training batch` to persist changes.
176    Checkpoint {
177        /// Model reference (e.g., "qwen3-small:experiment")
178        model: String,
179
180        /// Commit message (auto-generated if not provided)
181        #[arg(short, long)]
182        message: Option<String>,
183
184        /// Push to remote after commit
185        #[arg(long)]
186        push: bool,
187
188        /// Remote name for push (default: origin)
189        #[arg(long, default_value = "origin")]
190        remote: String,
191    },
192}