Skip to main content

rigspark_cli/
accessible_catalog.rs

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}