Skip to main content

qualia_cli/cli/
llm.rs

1use clap::Subcommand;
2use std::path::PathBuf;
3
4#[derive(Subcommand, Debug)]
5pub enum LlmAction {
6    List {
7        #[arg(long)]
8        vault_path: Option<PathBuf>,
9    },
10    Duplicates {
11        #[arg(long)]
12        vault_path: Option<PathBuf>,
13    },
14    Load {
15        model: String,
16        #[arg(long)]
17        vault_path: Option<PathBuf>,
18    },
19    Status,
20    Eval {
21        prompt: String,
22        /// Explicit native profile, actor selection, model and preparation budgets (JSON).
23        #[arg(long)]
24        authority: Option<PathBuf>,
25        #[arg(long)]
26        orchestrated: bool,
27        #[arg(long)]
28        stream: bool,
29        #[arg(long)]
30        lora: Option<PathBuf>,
31    },
32    Evict {
33        model_id: String,
34    },
35    Test {
36        #[arg(long)]
37        vault_path: Option<PathBuf>,
38        #[arg(long, value_delimiter = ',')]
39        models: Option<Vec<String>>,
40        #[arg(long)]
41        quantization: Option<String>,
42        #[arg(long)]
43        details: bool,
44    },
45    Validate {
46        #[arg(long)]
47        vault_path: Option<PathBuf>,
48        #[arg(long)]
49        strict: bool,
50    },
51    ComprehensiveTest {
52        #[arg(long)]
53        vault_path: Option<PathBuf>,
54        model: String,
55        #[arg(long)]
56        details: bool,
57    },
58    Benchmark {
59        #[arg(long)]
60        vault_path: Option<PathBuf>,
61        #[arg(long, value_delimiter = ',')]
62        models: Option<Vec<String>>,
63        #[arg(long)]
64        iterations: Option<u32>,
65        #[arg(long)]
66        warmup: Option<u32>,
67    },
68    Report {
69        #[arg(long)]
70        vault_path: Option<PathBuf>,
71        #[arg(long)]
72        output: Option<PathBuf>,
73        #[arg(long)]
74        format: Option<String>,
75    },
76    Convert {
77        input: PathBuf,
78        #[arg(short, long)]
79        out: PathBuf,
80        #[arg(long, default_value_t = 14)]
81        page_log2: u16,
82        #[arg(long, default_value = "auto")]
83        layout: String,
84    },
85    /// Extract Qwen3.8 Flash Next's PLE table to NVMe and create its native HMC contract.
86    #[command(name = "prepare-qwen4exp")]
87    PrepareQwen4Exp {
88        /// Existing Qwen4Exp GGUF source (the non-PLE trunk remains here).
89        input: PathBuf,
90        /// New `.hmc` output path; it must not already exist.
91        #[arg(short, long)]
92        out: PathBuf,
93        /// New raw PLE output on the fast NVMe volume; it must not already exist.
94        #[arg(long)]
95        ple_out: PathBuf,
96    },
97    /// Audit a Qwen4Exp HMC package against its external GGUF source.
98    #[command(name = "verify-qwen4exp")]
99    VerifyQwen4Exp {
100        /// Existing `.hmc` package. The GGUF is resolved from its source contract.
101        package: PathBuf,
102    },
103    /// Read and dequantize sampled PLE rows from the NVMe payload using fixed buffers.
104    #[command(name = "probe-qwen4exp-ple")]
105    ProbeQwen4ExpPle {
106        /// Existing `.hmc` package that references the extracted NVMe PLE file.
107        package: PathBuf,
108    },
109    /// Select the real PLE n-gram rows for token IDs and gather them directly from NVMe.
110    #[command(name = "gather-qwen4exp-ple")]
111    GatherQwen4ExpPle {
112        /// Existing `.hmc` package that references the extracted NVMe PLE file.
113        package: PathBuf,
114        /// Token IDs in decode order (comma-separated).
115        #[arg(long, value_delimiter = ',', num_args = 1..)]
116        token_ids: Vec<u32>,
117    },
118    /// Execute Qwen4Exp's complete trained PLE residual update from C: rows and E: projections.
119    #[command(name = "probe-qwen4exp-ple-block")]
120    ProbeQwen4ExpPleBlock {
121        /// Existing `.hmc` package with C:-resident PLE and external trunk contract.
122        package: PathBuf,
123        /// Token ID used for the PLE n-gram lookup and initial residual embedding.
124        #[arg(long, default_value_t = 151644)]
125        token_id: u32,
126    },
127    /// Execute a trained four-stream Hyper-Connection mix from the external Qwen4Exp trunk.
128    #[command(name = "probe-qwen4exp-hyper")]
129    ProbeQwen4ExpHyper {
130        package: PathBuf,
131        #[arg(long, default_value_t = 0)]
132        layer: u32,
133        /// Use the layer's FFN Hyper-Connection; default is its token-mixer Hyper-Connection.
134        #[arg(long)]
135        ffn: bool,
136        #[arg(long, default_value_t = 151644)]
137        token_id: u32,
138    },
139    /// Execute Qwen4Exp's trained GatedDeltaNet recurrence for one actual token-mixer layer.
140    #[command(name = "probe-qwen4exp-gdn")]
141    ProbeQwen4ExpGdn {
142        package: PathBuf,
143        /// GatedDeltaNet layer (must be one of the recurrent layers, not QSA).
144        #[arg(long, default_value_t = 0)]
145        layer: u32,
146        #[arg(long, default_value_t = 151644)]
147        token_id: u32,
148    },
149    /// Execute one complete trained recurrent Qwen4Exp layer (Hyper → GDN → Hyper → MoE).
150    #[command(name = "probe-qwen4exp-layer")]
151    ProbeQwen4ExpLayer {
152        package: PathBuf,
153        #[arg(long, default_value_t = 0)]
154        layer: u32,
155        #[arg(long, default_value_t = 151644)]
156        token_id: u32,
157    },
158    /// Execute one trained Qwen4Exp sparse-attention token mixer and its four-cell indexer.
159    #[command(name = "probe-qwen4exp-qsa")]
160    ProbeQwen4ExpQsa {
161        package: PathBuf,
162        /// QSA layer (3, 7, …, 47); recurrent layers are rejected.
163        #[arg(long, default_value_t = 3)]
164        layer: u32,
165        #[arg(long, default_value_t = 151644)]
166        token_id: u32,
167    },
168    /// Read one token-embedding row directly from the external Qwen4Exp trunk.
169    #[command(name = "probe-qwen4exp-trunk")]
170    ProbeQwen4ExpTrunk {
171        /// Existing `.hmc` package that identifies the external source GGUF.
172        package: PathBuf,
173        /// Token embedding row to read.
174        #[arg(long, default_value_t = 151644)]
175        token_id: u32,
176    },
177    /// Activate the native Qwen4Exp package without mapping the external GGUF.
178    #[command(name = "activate-qwen4exp")]
179    ActivateQwen4Exp {
180        /// Existing `.hmc` package with C:-resident PLE and external trunk contract.
181        package: PathBuf,
182    },
183    /// Exercise one real routed Qwen4Exp MoE operator through selected E: expert planes.
184    #[command(name = "probe-qwen4exp-moe")]
185    ProbeQwen4ExpMoe {
186        /// Existing `.hmc` package with C:-resident PLE and external trunk contract.
187        package: PathBuf,
188        /// Transformer layer containing the MoE block.
189        #[arg(long, default_value_t = 0)]
190        layer: u32,
191        /// Token embedding used as the operator input. This is not a full decode command.
192        #[arg(long, default_value_t = 151644)]
193        token_id: u32,
194        /// Optional validated C: expert tile. It is used only when this token routes to
195        /// the tile's exact layer/expert identity; otherwise the probe fails closed.
196        #[arg(long)]
197        tile: Option<PathBuf>,
198    },
199    /// Promote exactly one routed Qwen4Exp expert from E: into a budgeted C: HMC tile.
200    #[command(name = "promote-qwen4exp-expert")]
201    PromoteQwen4ExpExpert {
202        /// Existing native HMC package.
203        package: PathBuf,
204        #[arg(long)]
205        layer: u16,
206        #[arg(long)]
207        expert: u16,
208        /// Explicit C:-resident cache directory. The command never chooses a directory itself.
209        #[arg(long)]
210        cache_dir: PathBuf,
211        /// Hard cap for only this cache directory's Qwen expert tiles.
212        #[arg(long, default_value_t = 8)]
213        max_cache_gib: u64,
214    },
215    /// Exercise one C:-resident Qwen expert HMC tile with a real source embedding.
216    #[command(name = "probe-qwen4exp-expert-tile")]
217    ProbeQwen4ExpExpertTile {
218        package: PathBuf,
219        /// The explicit promoted `.qwen-expert.hmc` tile on C:.
220        tile: PathBuf,
221        #[arg(long, default_value_t = 151644)]
222        token_id: u32,
223    },
224    /// Real multi-token Qwen4Exp generation; select --authority or --developer.
225    /// Native streamed path:
226    /// embedding → PLE → 48 layers (HC→GDN|QSA→HC→MoE) → final HC mixer → argmax → decode.
227    #[command(name = "decode-qwen4exp")]
228    DecodeQwen4Exp {
229        /// Existing `.hmc` package with C:-resident PLE and external trunk contract.
230        package: PathBuf,
231        /// Governed execution using an existing authenticated profile and retained source identities.
232        #[arg(long, conflicts_with = "developer", required_unless_present = "developer")]
233        authority: Option<PathBuf>,
234        /// Explicit developer/debug execution using the numerical engine without product policy admission.
235        #[arg(long, conflicts_with = "authority")]
236        developer: bool,
237        /// Prompt text encoded by the model's own GGUF tokenizer.
238        #[arg(long)]
239        prompt: Option<String>,
240        /// Raw prompt token IDs (comma-separated); overrides --prompt.
241        #[arg(long, value_delimiter = ',', num_args = 1..)]
242        token_ids: Vec<u32>,
243        /// Wrap the prompt in the model's chat template (instruct models).
244        #[arg(long)]
245        chat: bool,
246        /// Maximum generated tokens.
247        #[arg(long, default_value_t = 16)]
248        max_tokens: usize,
249        /// Per-QSA-layer K/V + indexer cache capacity in tokens.
250        #[arg(long, default_value_t = 4096)]
251        context: usize,
252        /// Map the trunk GGUF read-only so the OS page cache keeps its
253        /// weights in RAM instead of streaming rows from disk each pass.
254        #[arg(long)]
255        trunk_mmap: bool,
256    },
257    /// Developer/debug lab instrument: run the prompt prefix through the real 48-layer graph,
258    /// then trace the final token's step — per-layer fingerprint/RMS/abs-max
259    /// for every stage plus the top-k vocabulary logits.
260    #[command(name = "probe-qwen4exp-trace")]
261    ProbeQwen4ExpTrace {
262        /// Existing `.hmc` package with C:-resident PLE and external trunk contract.
263        package: PathBuf,
264        /// Prompt text encoded by the model's own GGUF tokenizer.
265        #[arg(long)]
266        prompt: Option<String>,
267        /// Raw prompt token IDs (comma-separated); overrides --prompt.
268        #[arg(long, value_delimiter = ',', num_args = 1..)]
269        token_ids: Vec<u32>,
270        /// Wrap the prompt in the model's chat template.
271        #[arg(long)]
272        chat: bool,
273        /// Per-QSA-layer K/V + indexer cache capacity in tokens.
274        #[arg(long, default_value_t = 4096)]
275        context: usize,
276        /// Number of vocabulary logits to print.
277        #[arg(long, default_value_t = 8)]
278        topk: usize,
279        /// Token IDs to rank against the whole vocabulary (comma-separated);
280        /// reports each token's logit and its rank (0 = argmax).
281        #[arg(long, value_delimiter = ',', num_args = 1..)]
282        rank_tokens: Vec<u32>,
283        /// Write every traced stage vector to this file (u32 layer, u32 name
284        /// len, name, u32 count, f32 values) for offline numeric comparison.
285        #[arg(long)]
286        dump: Option<PathBuf>,
287    },
288    Optimize {
289        input: PathBuf,
290        #[arg(short, long)]
291        out: Option<PathBuf>,
292        #[arg(long)]
293        skip_passport: bool,
294    },
295    Passport {
296        #[arg(long)]
297        reprobe: bool,
298        #[arg(long, default_value_t = 2048)]
299        gemv_n: usize,
300        #[arg(long)]
301        cache: Option<PathBuf>,
302        #[arg(long)]
303        apply_env_hint: bool,
304        #[arg(long)]
305        decode_proxy: Option<Option<PathBuf>>,
306        #[arg(long, default_value_t = 16)]
307        decode_proxy_tokens: u32,
308    },
309    DecodeProxy {
310        model: PathBuf,
311        #[arg(long, default_value_t = 16)]
312        tokens: u32,
313    },
314    /// Fixed-step model-only decoder benchmark (no product helpers, EOS, or fallback).
315    RawDecodeBench {
316        model: PathBuf,
317        #[arg(long, default_value_t = 256)]
318        steps: u32,
319        #[arg(long, default_value_t = 1)]
320        warmups: u16,
321        #[arg(long, default_value_t = 5)]
322        runs: u16,
323        #[arg(long, default_value = "Q8_0")]
324        quantization: String,
325        #[arg(long, default_value = "Write a sequence of distinct short words:")]
326        prompt: String,
327        /// Deterministically cycle the encoded prompt to exactly this many prefill tokens.
328        #[arg(long)]
329        target_prompt_tokens: Option<u32>,
330        /// Explicit evidence directory to create. It must not already exist.
331        #[arg(long)]
332        retain_artifacts: Option<PathBuf>,
333    },
334    Mode {
335        name: Option<String>,
336    },
337    PathSelect {
338        #[arg(long)]
339        reprobe: bool,
340        #[arg(long)]
341        apply: bool,
342    },
343    Profile {
344        name: Option<String>,
345    },
346    Lab {
347        action: String,
348        #[arg(long)]
349        model: Option<PathBuf>,
350        #[arg(long, default_value_t = 0)]
351        tokens: u32,
352        #[arg(long, default_value_t = 256)]
353        n_in: usize,
354        #[arg(long, default_value_t = 64)]
355        n_out: usize,
356        #[arg(long, default_value_t = 512)]
357        gemv_n: usize,
358        #[arg(long)]
359        out: Option<PathBuf>,
360        #[arg(long, default_value_t = 2.0)]
361        hours: f64,
362        #[arg(long, default_value_t = 8)]
363        max_generations: u32,
364        #[arg(long)]
365        ollama_model: Option<String>,
366        #[arg(long, default_value = "http://127.0.0.1:11434")]
367        ollama_url: String,
368        #[arg(long, default_value_t = false)]
369        no_ollama: bool,
370    },
371    Ground {
372        prompt: String,
373        answer: String,
374    },
375    SeedGrounding,
376    CudaTcBench {
377        #[arg(long, default_value_t = 256)]
378        side: usize,
379    },
380    Explore {
381        input: PathBuf,
382        #[arg(short, long)]
383        out: Option<PathBuf>,
384        #[arg(long, default_value_t = 16)]
385        tokens: u32,
386        #[arg(long, default_value = "auto")]
387        layouts: String,
388        #[arg(long)]
389        skip_convert: bool,
390        #[arg(long)]
391        sweep_ffn_f16: bool,
392        #[arg(long)]
393        modes: Option<String>,
394    },
395}