1use crate::accessible_text::{identifier, single_line};
2use rigspark_core::{
3 catalog::{Catalog, CatalogModel},
4 ranking::backends,
5 sizing::{Architecture, Hardware, SizingRequest, evaluate, memory_capacity},
6};
7use serde::{Deserialize, Serialize};
8use std::io::{self, Write};
9use tokio::sync::mpsc::Receiver;
10use tokio_util::sync::CancellationToken;
11
12const ROW_LIMIT: usize = 20;
13const NESTED_LIMIT: usize = 10;
14const COLLECTION_LIMIT: usize = 1000;
15const NODE_LIMIT: usize = 100_000;
16const TEXT_LIMIT: usize = 1024 * 1024;
17pub const MAX_CATALOG_FRAME_BYTES: usize = 256 * 1024;
18pub const MAX_CATALOG_INPUT_BYTES: usize = 256;
19const NOTICE: &str = "[output bounded; refine the search or inspect a numbered item for more]\n";
20const HELP: &str = "Commands: /text search; number details; ? help; q quit\n";
21
22#[derive(Debug, Clone, Default, Deserialize)]
23#[serde(deny_unknown_fields)]
24pub struct CatalogRefresh {
25 pub added: Vec<String>,
26 pub updated: Vec<String>,
27 pub removed: Vec<String>,
28 pub skipped: Vec<String>,
29 pub capped: Vec<String>,
30}
31
32#[derive(Debug, Clone, Default, Deserialize)]
33#[serde(default, deny_unknown_fields)]
34pub struct CatalogOptions {
35 pub all: bool,
36 pub refresh: Option<CatalogRefresh>,
37}
38
39#[derive(Debug)]
40struct CatalogRow {
41 display: String,
42 summary: String,
43 evidence: String,
44 search: String,
45}
46
47#[derive(Debug)]
48pub struct CatalogPresentation {
49 machine: String,
50 filter: &'static str,
51 total: usize,
52 rows: Vec<CatalogRow>,
53 refresh: String,
54}
55
56fn invalid(message: &str) -> io::Error {
57 io::Error::new(io::ErrorKind::InvalidInput, message)
58}
59
60fn collection(length: usize) -> io::Result<()> {
61 if length > COLLECTION_LIMIT {
62 return Err(invalid("catalog collection exceeds 1000 entries"));
63 }
64 Ok(())
65}
66
67fn text(value: &str) -> io::Result<()> {
68 if value.len() > TEXT_LIMIT {
69 return Err(invalid("catalog text exceeds 1 MiB"));
70 }
71 Ok(())
72}
73
74fn number(value: f64) -> io::Result<()> {
75 if !value.is_finite()
76 || !(0.0..=9_007_199_254_740_991.0).contains(&value)
77 || value.fract() != 0.0
78 {
79 return Err(invalid("catalog bytes must be nonnegative safe integers"));
80 }
81 Ok(())
82}
83
84fn validate(catalog: &Catalog, hardware: &Hardware, options: &CatalogOptions) -> io::Result<()> {
85 collection(catalog.models.len())?;
86 collection(hardware.gpu.len())?;
87 for bytes in [
88 hardware.total_ram_bytes,
89 hardware.free_ram_bytes,
90 hardware.free_disk_bytes,
91 ] {
92 number(bytes)?;
93 }
94 for gpu in &hardware.gpu {
95 number(gpu.vram_bytes)?;
96 }
97 let mut nodes = 16 + hardware.gpu.len() * 3;
98 for model in &catalog.models {
99 collection(model.capabilities.len())?;
100 collection(model.quantizations.len())?;
101 if model.quantizations.is_empty() {
102 return Err(invalid("missing catalog quantization"));
103 }
104 nodes += 32 + model.capabilities.len() + model.quantizations.len() * 8;
105 for value in [
106 &model.id,
107 &model.family,
108 &model.params,
109 &model.license,
110 &model.release_date,
111 ]
112 .into_iter()
113 .chain(model.active_params.iter())
114 .chain(model.capabilities.iter())
115 .chain(model.source.ollama.iter())
116 .chain(model.source.hf.iter())
117 {
118 text(value)?;
119 }
120 if model
121 .benchmark_proxy
122 .is_some_and(|value| !value.is_finite())
123 {
124 return Err(invalid("invalid catalog benchmark"));
125 }
126 if let Some(source) = &model.source.gguf {
127 for value in [&source.repo, &source.revision, &source.file, &source.sha256] {
128 text(value)?;
129 }
130 }
131 if let Some(source) = &model.source.mlx {
132 collection(source.files.len())?;
133 nodes += 4 + source.files.len() * 4;
134 text(&source.repo)?;
135 text(&source.revision)?;
136 for file in &source.files {
137 text(&file.file)?;
138 text(&file.sha256)?;
139 number(file.bytes)?;
140 }
141 }
142 for quant in &model.quantizations {
143 text(&quant.name)?;
144 if let Some(digest) = &quant.sha256 {
145 text(digest)?;
146 }
147 }
148 if nodes > NODE_LIMIT {
149 return Err(invalid("catalog input node limit exceeded"));
150 }
151 }
152 if let Some(refresh) = &options.refresh {
153 for values in [
154 &refresh.added,
155 &refresh.updated,
156 &refresh.removed,
157 &refresh.skipped,
158 &refresh.capped,
159 ] {
160 collection(values.len())?;
161 nodes += values.len() + 1;
162 for value in values {
163 text(value)?;
164 }
165 }
166 }
167 if nodes > NODE_LIMIT {
168 return Err(invalid("catalog input node limit exceeded"));
169 }
170 Ok(())
171}
172
173fn gib(bytes: f64) -> String {
174 let value = bytes / 1_073_741_824.0;
175 let quarter_ticks = value * 4.0;
176 let rounded = if quarter_ticks.fract() == 0.0 && quarter_ticks % 2.0 == 1.0 {
177 (value * 10.0).round() / 10.0
178 } else {
179 value
180 };
181 format!("{rounded:.1} GiB")
182}
183
184fn label(value: &impl Serialize) -> io::Result<String> {
185 let value = serde_json::to_value(value).map_err(io::Error::other)?;
186 value
187 .as_str()
188 .map(str::to_owned)
189 .ok_or_else(|| invalid("invalid catalog label"))
190}
191
192fn omitted(values: &[String]) -> String {
193 let visible = values
194 .iter()
195 .take(NESTED_LIMIT)
196 .cloned()
197 .collect::<Vec<_>>()
198 .join(", ");
199 let visible = if visible.is_empty() {
200 "none".into()
201 } else {
202 visible
203 };
204 if values.len() > NESTED_LIMIT {
205 format!("{visible} (+{} more)", values.len() - NESTED_LIMIT)
206 } else {
207 visible
208 }
209}
210
211fn lines(values: &[String]) -> io::Result<Vec<String>> {
212 values.iter().map(|value| single_line(value)).collect()
213}
214
215fn sources(model: &CatalogModel) -> io::Result<String> {
216 let mut result = Vec::new();
217 if let Some(source) = &model.source.ollama {
218 result.push(format!("ollama {}", single_line(source)?));
219 }
220 if let Some(source) = &model.source.hf {
221 result.push(format!("hf {}", single_line(source)?));
222 }
223 if let Some(source) = &model.source.gguf {
224 result.push(format!(
225 "gguf {}@{} {} sha256:{}",
226 single_line(&source.repo)?,
227 single_line(&source.revision)?,
228 single_line(&source.file)?,
229 single_line(&source.sha256)?
230 ));
231 }
232 if let Some(source) = &model.source.mlx {
233 let files = source
234 .files
235 .iter()
236 .map(|file| {
237 Ok(format!(
238 "{} sha256:{} {} bytes",
239 single_line(&file.file)?,
240 single_line(&file.sha256)?,
241 file.bytes
242 ))
243 })
244 .collect::<io::Result<Vec<_>>>()?;
245 result.push(format!(
246 "mlx {}@{}; {}",
247 single_line(&source.repo)?,
248 single_line(&source.revision)?,
249 omitted(&files)
250 ));
251 }
252 Ok(omitted(&result))
253}
254
255fn actionable(value: &str) -> bool {
256 !value.is_empty()
257 && !value.starts_with('-')
258 && !value.split('/').any(|segment| segment == "..")
259 && value.bytes().all(|byte| {
260 byte.is_ascii_lowercase() || byte.is_ascii_digit() || b"._:/-".contains(&byte)
261 })
262}
263
264pub fn build_catalog(
265 catalog: &Catalog,
266 hardware: &Hardware,
267 options: &CatalogOptions,
268) -> io::Result<CatalogPresentation> {
269 validate(catalog, hardware, options)?;
270 let mut models = catalog.models.iter().collect::<Vec<_>>();
271 models.sort_by(|left, right| {
272 right
273 .release_date
274 .cmp(&left.release_date)
275 .then_with(|| left.id.cmp(&right.id))
276 });
277 let mut rows = Vec::new();
278 for model in models {
279 let sizing = evaluate(&SizingRequest {
280 model: model.sizing(),
281 hardware: hardware.clone(),
282 context: None,
283 })
284 .map_err(io::Error::other)?;
285 if !options.all && !sizing.fit.fits {
286 continue;
287 }
288 let smallest = model
289 .quantizations
290 .iter()
291 .enumerate()
292 .min_by(|(left, left_quant), (right, right_quant)| {
293 sizing.required[*left]
294 .total_cmp(&sizing.required[*right])
295 .then_with(|| left_quant.name.cmp(&right_quant.name))
296 })
297 .ok_or_else(|| invalid("missing catalog quantization"))?;
298 let quant = sizing.fit.quant.as_ref().unwrap_or(smallest.1);
299 let required = sizing
300 .fit
301 .required_bytes
302 .unwrap_or(sizing.required[smallest.0]);
303 let display = identifier(&model.id)?;
304 let family = single_line(&model.family)?;
305 let architecture = match model.architecture {
306 Architecture::Dense => "dense",
307 Architecture::Moe => "moe",
308 };
309 let fit = sizing.fit.reason.unwrap_or("fit");
310 let release = single_line(&model.release_date)?;
311 let capabilities = lines(&model.capabilities)?;
312 let quantizations = model
313 .quantizations
314 .iter()
315 .map(|entry| {
316 let digest = entry
317 .sha256
318 .as_deref()
319 .map(single_line)
320 .transpose()?
321 .unwrap_or_else(|| "unknown (not sourced)".into());
322 let verified = if entry.digest_verified == Some(true) {
323 "verified"
324 } else if entry.sha256.is_none() {
325 "size-only"
326 } else {
327 "not verified"
328 };
329 Ok(format!(
330 "{} disk {} RAM {} VRAM {} SHA-256 {digest} Digest: {verified}",
331 single_line(&entry.name)?,
332 gib(entry.disk_bytes),
333 gib(entry.min_ram_bytes),
334 gib(entry.min_vram_bytes)
335 ))
336 })
337 .collect::<io::Result<Vec<_>>>()?;
338 let active = model
339 .active_params
340 .as_deref()
341 .map(single_line)
342 .transpose()?
343 .map(|value| format!(", {value} active"))
344 .unwrap_or_default();
345 let kv = model
346 .kv_bytes_per_token
347 .map(|value| value.to_string())
348 .unwrap_or_else(|| "unknown (attention geometry not sourced)".into());
349 let benchmark = model
350 .benchmark_proxy
351 .map(|value| value.to_string())
352 .unwrap_or_else(|| "unknown (not sourced)".into());
353 let supported = backends(model, hardware)
354 .into_iter()
355 .map(str::to_owned)
356 .collect::<Vec<_>>();
357 let evidence = format!(
358 "{display}; family {family}; params {}{active}; architecture {architecture}; selected quant {}; need {}; fit {fit}; release {release}; license {}; open weight {}; context {}; KV bytes/token {kv}; benchmark {benchmark}; capabilities {}; backends {}; sources {}; quantizations {}",
359 single_line(&model.params)?,
360 single_line(&quant.name)?,
361 gib(required),
362 single_line(&model.license)?,
363 if model.open_weight { "yes" } else { "no" },
364 model.context_length,
365 omitted(&capabilities),
366 omitted(&supported),
367 sources(model)?,
368 omitted(&quantizations)
369 );
370 let canonical = if actionable(&model.id) {
371 model.id.as_str()
372 } else {
373 ""
374 };
375 let search = format!(
376 "{canonical} {family} {} {architecture} {fit} {}",
377 capabilities.join(" "),
378 release.chars().take(4).collect::<String>()
379 )
380 .to_lowercase();
381 rows.push(CatalogRow {
382 display,
383 summary: format!(
384 "{} | {} | {fit} | {release}",
385 single_line(&quant.name)?,
386 gib(required)
387 ),
388 evidence,
389 search,
390 });
391 }
392 let (kind, usable) = memory_capacity(hardware);
393 let gpus = hardware
394 .gpu
395 .iter()
396 .map(|gpu| Ok(format!("{} {}", label(&gpu.vendor)?, gib(gpu.vram_bytes))))
397 .collect::<io::Result<Vec<_>>>()?;
398 let machine = format!(
399 "{}/{}; RAM {} total / {} free; {} usable {kind}; disk {} free; GPUs {}",
400 label(&hardware.platform)?,
401 label(&hardware.arch)?,
402 gib(hardware.total_ram_bytes),
403 gib(hardware.free_ram_bytes),
404 gib(usable),
405 gib(hardware.free_disk_bytes),
406 omitted(&gpus)
407 );
408 let refresh = match &options.refresh {
409 None => "Not requested".into(),
410 Some(refresh) => format!(
411 "Dry-run diff: added {}; updated {}; removed {}; skipped {}; capped {}",
412 omitted(&lines(&refresh.added)?),
413 omitted(&lines(&refresh.updated)?),
414 omitted(&lines(&refresh.removed)?),
415 omitted(&lines(&refresh.skipped)?),
416 omitted(&lines(&refresh.capped)?)
417 ),
418 };
419 Ok(CatalogPresentation {
420 machine,
421 filter: if options.all { "all" } else { "fits" },
422 total: catalog.models.len(),
423 rows,
424 refresh,
425 })
426}
427
428impl CatalogPresentation {
429 pub fn visual_rows(&self) -> impl ExactSizeIterator<Item = (&str, &str, &str, &str)> {
430 self.rows.iter().map(|row| {
431 (
432 row.display.as_str(),
433 row.summary.as_str(),
434 row.search.as_str(),
435 row.evidence.as_str(),
436 )
437 })
438 }
439
440 pub fn visual_overview(&self) -> Vec<String> {
441 vec![
442 self.machine.clone(),
443 format!(
444 "Catalog: {}; {} of {} models",
445 self.filter,
446 self.rows.len(),
447 self.total
448 ),
449 format!("Refresh: {}", self.refresh),
450 ]
451 }
452}
453
454fn bounded(document: &str) -> String {
455 let mut output = String::new();
456 for line in document.split_inclusive('\n') {
457 if output.len() + line.len() > MAX_CATALOG_FRAME_BYTES - NOTICE.len() {
458 output.push_str(NOTICE);
459 break;
460 }
461 output.push_str(line);
462 }
463 output
464}
465
466fn row(row: &CatalogRow, index: usize) -> String {
467 format!("{}. {}", index + 1, row.evidence)
468}
469
470pub fn catalog_screen(catalog: &CatalogPresentation) -> String {
471 let rows = catalog
472 .rows
473 .iter()
474 .take(ROW_LIMIT)
475 .enumerate()
476 .map(|(index, entry)| row(entry, index))
477 .collect::<Vec<_>>()
478 .join("\n");
479 let rows = if rows.is_empty() {
480 format!(
481 "Empty: {}",
482 if catalog.total == 0 {
483 "catalog-empty"
484 } else {
485 "no-models-fit"
486 }
487 )
488 } else {
489 rows
490 };
491 let more = if catalog.rows.len() > ROW_LIMIT {
492 format!(
493 "\nShowing first {ROW_LIMIT} of {}; use /text to refine.",
494 catalog.rows.len()
495 )
496 } else {
497 String::new()
498 };
499 bounded(&format!(
500 "rigspark / Catalog / Accessible\n1. Machine\n{}\n2. Catalog ({}; {}/{})\n{rows}{more}\n3. Refresh\n{}\n4. Controls\n{HELP}",
501 catalog.machine,
502 catalog.filter,
503 catalog.rows.len(),
504 catalog.total,
505 catalog.refresh
506 ))
507}
508
509fn filtered<'catalog>(
510 catalog: &'catalog CatalogPresentation,
511 query: &str,
512) -> Vec<&'catalog CatalogRow> {
513 let needle = query.to_lowercase();
514 catalog
515 .rows
516 .iter()
517 .filter(|row| row.search.contains(&needle))
518 .collect()
519}
520
521pub async fn run_catalog<W: Write>(
522 catalog: &CatalogPresentation,
523 input: &mut Receiver<io::Result<String>>,
524 output: &mut W,
525 cancel: &CancellationToken,
526) -> io::Result<()> {
527 if cancel.is_cancelled() {
528 return Err(io::Error::new(
529 io::ErrorKind::Interrupted,
530 "interactive input cancelled",
531 ));
532 }
533 output.write_all(catalog_screen(catalog).as_bytes())?;
534 output.flush()?;
535 let mut query = String::new();
536 loop {
537 let raw = tokio::select! {
538 biased;
539 _ = cancel.cancelled() => return Err(io::Error::new(io::ErrorKind::Interrupted, "interactive input cancelled")),
540 answer = input.recv() => match answer { Some(answer) => answer?, None => return Ok(()) },
541 };
542 if raw.len() > MAX_CATALOG_INPUT_BYTES {
543 return Err(invalid("answer exceeds 256 bytes"));
544 }
545 let safe = single_line(&raw)?;
546 let command = safe.trim();
547 let document = if command == "q" {
548 return Ok(());
549 } else if command == "?" {
550 HELP.into()
551 } else if let Some(search) = command.strip_prefix('/') {
552 query = search.trim().into();
553 let matches = filtered(catalog, &query);
554 let rows = matches
555 .iter()
556 .take(ROW_LIMIT)
557 .enumerate()
558 .map(|(index, entry)| row(entry, index))
559 .collect::<Vec<_>>()
560 .join("\n");
561 let more = if matches.len() > ROW_LIMIT {
562 format!(
563 "\nShowing first {ROW_LIMIT} of {}; refine search for more.",
564 matches.len()
565 )
566 } else {
567 String::new()
568 };
569 format!(
570 "Filter: {}\n{}{more}\n",
571 if query.is_empty() { "off" } else { &query },
572 if rows.is_empty() { "No results" } else { &rows }
573 )
574 } else if (1..=3).contains(&command.len())
575 && !command.starts_with('0')
576 && command.bytes().all(|byte| byte.is_ascii_digit())
577 {
578 let index = command.parse::<usize>().map_err(io::Error::other)? - 1;
579 match filtered(catalog, &query).get(index) {
580 Some(entry) => format!("Details: {}\n{}\n", entry.display, row(entry, index)),
581 None => "No such result.\n".into(),
582 }
583 } else {
584 "Unknown command. Enter ? for help.\n".into()
585 };
586 output.write_all(bounded(&document).as_bytes())?;
587 output.flush()?;
588 }
589}