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