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}