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