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}