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