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