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}
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}