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}