Skip to main content

rigspark_cli/
accessible_recommend.rs

1use crate::accessible_text::{identifier, single_line};
2use rigspark_core::{
3    catalog::{Catalog, PerfDataset},
4    ranking::{AdviceOptions, recommend_detailed},
5    reports::{recommendation_text, safe_recommendation_command},
6    sizing::{Hardware, memory_capacity},
7};
8use serde_json::Value;
9use std::{
10    collections::HashMap,
11    io::{self, Write},
12};
13use tokio::sync::mpsc::Receiver;
14use tokio_util::sync::CancellationToken;
15
16pub const MAX_ROWS: usize = 20;
17pub const MAX_DOCUMENT_BYTES: usize = 256 * 1024;
18const MAX_ITEMS: usize = 1_000;
19const BOUNDED_NOTICE: &str =
20    "[output bounded; refine the search or inspect a numbered item for more]\n";
21
22#[derive(Debug, PartialEq, Eq)]
23pub enum RecommendOutcome {
24    Exited,
25    Cancelled,
26    PrintCommand { command: String },
27}
28
29#[derive(Debug)]
30struct Row {
31    display: String,
32    summary: String,
33    search: String,
34    evidence: String,
35    need: f64,
36}
37
38#[derive(Debug)]
39pub struct Recommendation {
40    machine: String,
41    scope: String,
42    rows: Vec<Row>,
43    wont_fit: Vec<String>,
44    command: Option<String>,
45    final_text: String,
46    usable: f64,
47}
48
49fn invalid(message: &str) -> io::Error {
50    io::Error::new(io::ErrorKind::InvalidInput, message)
51}
52
53fn text(value: &Value) -> io::Result<&str> {
54    value
55        .as_str()
56        .ok_or_else(|| invalid("missing recommendation text evidence"))
57}
58
59fn number(value: &Value) -> io::Result<f64> {
60    value
61        .as_f64()
62        .filter(|number| number.is_finite())
63        .ok_or_else(|| invalid("missing recommendation numeric evidence"))
64}
65
66fn legacy_fixed(value: f64, precision: usize) -> String {
67    let binary_ticks = value * 2.0_f64.powi(precision as i32 + 1);
68    let rounded = if binary_ticks.fract() == 0.0 && binary_ticks % 2.0 == 1.0 {
69        let scale = 10.0_f64.powi(precision as i32);
70        (value * scale).round() / scale
71    } else {
72        value
73    };
74    format!("{rounded:.precision$}")
75}
76
77fn gib(bytes: f64) -> String {
78    format!("{} GiB", legacy_fixed(bytes / 1_073_741_824.0, 1))
79}
80
81fn list(values: &[String]) -> String {
82    if values.is_empty() {
83        "none".into()
84    } else {
85        values.join(", ")
86    }
87}
88
89fn safe_id(value: &str) -> bool {
90    !value.is_empty()
91        && !value.starts_with('-')
92        && value.bytes().all(|byte| {
93            byte.is_ascii_lowercase() || byte.is_ascii_digit() || b"._:/-".contains(&byte)
94        })
95        && !value.split('/').any(|part| part == "..")
96}
97
98fn bounded_document(value: String) -> String {
99    let budget = MAX_DOCUMENT_BYTES - BOUNDED_NOTICE.len();
100    let mut kept = String::new();
101    for line in value.split_inclusive('\n') {
102        if kept.len() + line.len() > budget {
103            kept.push_str(BOUNDED_NOTICE);
104            return kept;
105        }
106        kept.push_str(line);
107    }
108    kept
109}
110
111fn check_inputs(catalog: &Catalog, hardware: &Hardware) -> io::Result<()> {
112    if catalog.models.len() > MAX_ITEMS || hardware.gpu.len() > 128 {
113        return Err(invalid("recommendation input collection limit exceeded"));
114    }
115    let mut nodes = 0usize;
116    for model in &catalog.models {
117        if model.capabilities.len() > MAX_ITEMS || model.quantizations.len() > MAX_ITEMS {
118            return Err(invalid("recommendation input collection limit exceeded"));
119        }
120        nodes += 32 + model.capabilities.len() + model.quantizations.len() * 8;
121        if nodes > 100_000 {
122            return Err(invalid("recommendation input node limit exceeded"));
123        }
124    }
125    for bytes in [
126        hardware.total_ram_bytes,
127        hardware.free_ram_bytes,
128        hardware.free_disk_bytes,
129    ]
130    .into_iter()
131    .chain(hardware.gpu.iter().map(|gpu| gpu.vram_bytes))
132    {
133        if !bytes.is_finite()
134            || !(0.0..=9_007_199_254_740_991.0).contains(&bytes)
135            || bytes.fract() != 0.0
136        {
137            return Err(invalid("invalid hardware byte count"));
138        }
139    }
140    Ok(())
141}
142
143pub fn build_recommendation(
144    catalog: &Catalog,
145    hardware: &Hardware,
146    perf: &PerfDataset,
147    options: &AdviceOptions,
148) -> io::Result<Recommendation> {
149    check_inputs(catalog, hardware)?;
150    let report = recommend_detailed(catalog, hardware, perf, options).map_err(io::Error::other)?;
151    let hardware_json = serde_json::to_value(hardware).map_err(io::Error::other)?;
152    let (kind, usable) = memory_capacity(hardware);
153    let gpus = hardware_json["gpu"]
154        .as_array()
155        .ok_or_else(|| invalid("missing GPU evidence"))?
156        .iter()
157        .map(|gpu| {
158            Ok(format!(
159                "{} {}",
160                text(&gpu["vendor"])?,
161                gib(number(&gpu["vramBytes"])?)
162            ))
163        })
164        .collect::<io::Result<Vec<_>>>()?;
165    let machine = format!(
166        "{}/{}; {} usable {kind}; RAM {} total, {} free; disk {} free; GPUs {}",
167        text(&hardware_json["platform"])?,
168        text(&hardware_json["arch"])?,
169        gib(usable),
170        gib(hardware.total_ram_bytes),
171        gib(hardware.free_ram_bytes),
172        gib(hardware.free_disk_bytes),
173        list(&gpus)
174    );
175    let context = options.context.map_or_else(
176        || {
177            if options.max_context {
178                "maximum".into()
179            } else {
180                "default".into()
181            }
182        },
183        |tokens| tokens.to_string(),
184    );
185    let scope = format!(
186        "Scope: task {}; context {context}; backend {}; {}",
187        single_line(options.task.as_deref().unwrap_or("any"))?,
188        single_line(options.backend.as_deref().unwrap_or("ollama"))?,
189        if options.available_backends.is_some() {
190            "installed backends only"
191        } else {
192            "all compatible backends"
193        }
194    );
195    let models: HashMap<_, _> = catalog
196        .models
197        .iter()
198        .map(|model| (model.id.as_str(), model))
199        .collect();
200    if models.len() != catalog.models.len() {
201        return Err(invalid("duplicate recommendation model id"));
202    }
203    let ranked = report["ranked"]
204        .as_array()
205        .ok_or_else(|| invalid("missing ranked models"))?;
206    let mut rows = Vec::with_capacity(ranked.len());
207    for entry in ranked {
208        let id = text(&entry["id"])?;
209        let model = models
210            .get(id)
211            .ok_or_else(|| invalid("ranked model missing from catalog"))?;
212        let capabilities = model
213            .capabilities
214            .iter()
215            .map(|value| single_line(value))
216            .collect::<io::Result<Vec<_>>>()?;
217        let backends = entry["backends"]
218            .as_array()
219            .ok_or_else(|| invalid("missing backend evidence"))?
220            .iter()
221            .map(|value| single_line(text(value)?))
222            .collect::<io::Result<Vec<_>>>()?;
223        let provenance = &entry["throughputEvidence"];
224        let estimate = &entry["estTokPerSec"];
225        let unknown = provenance["unknownReason"].as_str();
226        let label = if estimate.is_null() {
227            "unknown".into()
228        } else {
229            format!(
230                "{}\u{2013}{} tok/s",
231                number(&estimate["lowTokPerSec"])?,
232                number(&estimate["highTokPerSec"])?
233            )
234        };
235        let unknown_label =
236            unknown.map_or(String::new(), |reason| format!("; unknown reason {reason}"));
237        let source = single_line(&format!(
238            "{}{}",
239            text(&provenance["source"])?,
240            unknown.map_or(String::new(), |reason| format!("; {reason}"))
241        ))?;
242        let context_evidence = if let Some(tokens) = options.tokens(model) {
243            format!(
244                "{tokens} tokens; weights {} bytes; {}",
245                number(&entry["weightsBytes"])?,
246                if entry["kvCacheBytes"].is_null() {
247                    "KV cache unknown".into()
248                } else {
249                    format!("KV cache {} bytes", number(&entry["kvCacheBytes"])?)
250                }
251            )
252        } else if options.max_context {
253            if entry["maxContextTokens"].is_null() {
254                "maximum context unknown".into()
255            } else {
256                format!(
257                    "maximum context {} tokens; bound by {}",
258                    number(&entry["maxContextTokens"])?,
259                    text(&entry["boundBy"])?
260                )
261            }
262        } else {
263            "default context footprint".into()
264        };
265        let scores = &entry["scores"];
266        let display = identifier(id)?;
267        let verdict = text(&entry["verdict"])?;
268        let evidence = format!(
269            "{display}; rank {}; {}; {}; {}; verdict {verdict}; throughput {}{unknown_label}; backends {}; score {}; capabilities {}; license {}; context {}; {}; throughput backend {}; source {source}; scores quality {}, fit {}, speed {}, recency {}, capability {}",
270            number(&entry["rank"])?,
271            single_line(&model.params)?,
272            single_line(text(&entry["quant"])?)?,
273            gib(number(&entry["requiredBytes"])?),
274            single_line(&label)?,
275            list(&backends),
276            legacy_fixed(number(&entry["score"])?, 2),
277            list(&capabilities),
278            single_line(&model.license)?,
279            model.context_length,
280            single_line(&context_evidence)?,
281            single_line(text(&provenance["backend"])?)?,
282            legacy_fixed(number(&scores["quality"])?, 2),
283            legacy_fixed(number(&scores["fit"])?, 2),
284            legacy_fixed(number(&scores["speed"])?, 2),
285            legacy_fixed(number(&scores["recency"])?, 2),
286            legacy_fixed(number(&scores["capability"])?, 2)
287        );
288        let search = format!(
289            "{} {} {} {verdict}",
290            if safe_id(id) { id } else { "" },
291            capabilities.join(" "),
292            backends.join(" ")
293        )
294        .to_lowercase();
295        rows.push(Row {
296            need: number(&entry["requiredBytes"])?,
297            display,
298            summary: format!(
299                "#{} | {} | {} | {verdict} | {} | {}",
300                number(&entry["rank"])?,
301                single_line(text(&entry["quant"])?)?,
302                gib(number(&entry["requiredBytes"])?),
303                single_line(&label)?,
304                legacy_fixed(number(&entry["score"])?, 2),
305            ),
306            search,
307            evidence,
308        });
309    }
310    let wont_fit = report["wontFit"]
311        .as_array()
312        .ok_or_else(|| invalid("missing non-fitting models"))?
313        .iter()
314        .map(|entry| {
315            Ok(format!(
316                "{}; {}",
317                identifier(text(&entry["id"])?)?,
318                single_line(text(&entry["reason"])?)?
319            ))
320        })
321        .collect::<io::Result<Vec<_>>>()?;
322    let command = safe_recommendation_command(&report).map(str::to_owned);
323    let final_text = recommendation_text(&report, options);
324    Ok(Recommendation {
325        machine,
326        scope,
327        rows,
328        wont_fit,
329        command,
330        final_text,
331        usable,
332    })
333}
334
335impl Recommendation {
336    pub fn usable_bytes(&self) -> f64 {
337        self.usable
338    }
339
340    pub fn need_bytes(&self) -> impl Iterator<Item = f64> + '_ {
341        self.rows.iter().map(|row| row.need)
342    }
343}
344
345impl Recommendation {
346    pub fn visual_rows(&self) -> impl ExactSizeIterator<Item = (&str, &str, &str, &str)> {
347        self.rows.iter().map(|row| {
348            (
349                row.display.as_str(),
350                row.summary.as_str(),
351                row.search.as_str(),
352                row.evidence.as_str(),
353            )
354        })
355    }
356
357    pub fn visual_overview(&self) -> Vec<String> {
358        let mut lines = vec![
359            self.machine.clone(),
360            self.scope.clone(),
361            format!("Won't fit: {}", self.wont_fit.len()),
362        ];
363        lines.extend(self.wont_fit.iter().cloned());
364        lines
365    }
366
367    pub fn print_command(&self) -> Option<&str> {
368        self.command.as_deref()
369    }
370
371    pub fn final_text(&self) -> &str {
372        &self.final_text
373    }
374
375    fn help(&self) -> String {
376        format!(
377            "Commands: /text search; number details; ? help;{} q quit\n",
378            if self.command.is_some() {
379                " p finish and print result;"
380            } else {
381                ""
382            }
383        )
384    }
385
386    pub fn format(&self) -> String {
387        let mut output = format!(
388            "rigspark / Recommend / Accessible\n1. Machine\n{}\n{}\n2. Ranked models\n",
389            self.machine, self.scope
390        );
391        for (index, row) in self.rows.iter().take(MAX_ROWS).enumerate() {
392            output.push_str(&format!("{}. {}\n", index + 1, row.evidence));
393        }
394        if self.rows.len() > MAX_ROWS {
395            output.push_str(&format!(
396                "Showing first {MAX_ROWS} of {}; use /text to refine.\n",
397                self.rows.len()
398            ));
399        }
400        output.push_str("3. Won't fit\n");
401        if self.wont_fit.is_empty() {
402            output.push_str("None\n");
403        }
404        for (index, row) in self.wont_fit.iter().take(MAX_ROWS).enumerate() {
405            output.push_str(&format!("{}. {row}\n", index + 1));
406        }
407        if self.wont_fit.len() > MAX_ROWS {
408            output.push_str(&format!(
409                "Showing first {MAX_ROWS} of {}; use catalog --all to inspect the rest.\n",
410                self.wont_fit.len()
411            ));
412        }
413        output.push_str("4. Controls\n");
414        output.push_str(&self.help());
415        bounded_document(output)
416    }
417
418    fn filtered(&self, query: &str) -> Vec<&Row> {
419        let needle = query.to_lowercase();
420        self.rows
421            .iter()
422            .filter(|row| row.search.contains(&needle))
423            .collect()
424    }
425
426    fn search(&self, query: &str) -> String {
427        let rows = self.filtered(query);
428        let mut output = format!("Filter: {}\n", if query.is_empty() { "off" } else { query });
429        if rows.is_empty() {
430            output.push_str("No results\n");
431        }
432        for (index, row) in rows.iter().take(MAX_ROWS).enumerate() {
433            output.push_str(&format!("{}. {}\n", index + 1, row.evidence));
434        }
435        if rows.len() > MAX_ROWS {
436            output.push_str(&format!(
437                "Showing first {MAX_ROWS} of {}; refine search for more.\n",
438                rows.len()
439            ));
440        }
441        bounded_document(output)
442    }
443
444    fn details(&self, query: &str, index: usize) -> String {
445        self.filtered(query).get(index).map_or_else(
446            || "No such result.\n".into(),
447            |row| {
448                bounded_document(format!(
449                    "Details: {}\n{}. {}\n",
450                    row.display,
451                    index + 1,
452                    row.evidence
453                ))
454            },
455        )
456    }
457}
458
459fn write_frame(output: &mut impl Write, text: &str) -> io::Result<()> {
460    output.write_all(text.as_bytes())?;
461    output.flush()
462}
463
464pub async fn run_recommendation(
465    recommendation: &Recommendation,
466    input: &mut Receiver<io::Result<String>>,
467    output: &mut impl Write,
468    cancellation: &CancellationToken,
469) -> io::Result<RecommendOutcome> {
470    if cancellation.is_cancelled() {
471        return Ok(RecommendOutcome::Cancelled);
472    }
473    write_frame(output, &recommendation.format())?;
474    let mut query = String::new();
475    loop {
476        let raw = tokio::select! {
477            biased;
478            () = cancellation.cancelled() => return Ok(RecommendOutcome::Cancelled),
479            line = input.recv() => match line {
480                None => return Ok(RecommendOutcome::Exited),
481                Some(line) => line?,
482            }
483        };
484        let bounded = single_line(&raw)?;
485        let line = bounded.trim();
486        match line {
487            "q" => return Ok(RecommendOutcome::Exited),
488            "?" => write_frame(output, &recommendation.help())?,
489            "p" if recommendation.command.is_some() => {
490                return Ok(RecommendOutcome::PrintCommand {
491                    command: recommendation
492                        .command
493                        .clone()
494                        .ok_or_else(|| invalid("missing print command"))?,
495                });
496            }
497            line if line.starts_with('/') => {
498                query = line[1..].trim().into();
499                write_frame(output, &recommendation.search(&query))?;
500            }
501            line if !line.is_empty()
502                && line.len() <= 3
503                && !line.starts_with('0')
504                && line.bytes().all(|byte| byte.is_ascii_digit()) =>
505            {
506                let index = line
507                    .parse::<usize>()
508                    .map_err(|_| invalid("invalid result number"))?
509                    - 1;
510                write_frame(output, &recommendation.details(&query, index))?;
511            }
512            _ => write_frame(output, "Unknown command. Enter ? for help.\n")?,
513        }
514        tokio::task::yield_now().await;
515    }
516}