Skip to main content

rigspark_cli/
accessible_installed.rs

1use crate::accessible_text::{identifier, single_line};
2use serde::Deserialize;
3use serde_json::Value;
4use std::io::{self, Write};
5use tokio::sync::mpsc::Receiver;
6use tokio_util::sync::CancellationToken;
7
8pub const MAX_ROWS: usize = 20;
9pub const MAX_ITEMS: usize = 1_000;
10pub const MAX_TEXT_BYTES: usize = 1024 * 1024;
11pub const MAX_INPUT_BYTES: usize = 4096;
12pub const MAX_DOCUMENT_BYTES: usize = 64 * 1024;
13const MAX_TOTAL_TEXT_BYTES: usize = 4 * MAX_TEXT_BYTES;
14const MAX_NODES: usize = 100_000;
15
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub enum InstalledCommand {
18    Recommend,
19    CanRun,
20}
21
22#[derive(Debug, Clone, Copy, PartialEq, Eq)]
23pub enum InstalledOutcome {
24    Exited,
25    Cancelled,
26}
27
28#[derive(Debug)]
29pub struct InstalledView {
30    command: InstalledCommand,
31    source: String,
32    rows: Vec<Row>,
33}
34
35#[derive(Debug)]
36struct Row {
37    id: String,
38    search: String,
39    fit: String,
40    details: String,
41}
42
43#[derive(Deserialize)]
44#[serde(rename_all = "lowercase")]
45enum Fit {
46    Yes,
47    No,
48    Unknown,
49}
50
51impl Fit {
52    fn label(&self) -> &'static str {
53        match self {
54            Self::Yes => "yes",
55            Self::No => "no",
56            Self::Unknown => "unknown",
57        }
58    }
59}
60
61#[derive(Deserialize)]
62#[serde(rename_all = "lowercase")]
63enum MemoryKind {
64    Ram,
65    Vram,
66}
67
68#[derive(Deserialize)]
69struct Report<'report> {
70    source: Option<&'report str>,
71    #[serde(borrow)]
72    models: Vec<Model<'report>>,
73}
74
75#[derive(Deserialize)]
76#[serde(rename_all = "camelCase")]
77struct Model<'report> {
78    id: &'report str,
79    digest: Option<&'report str>,
80    size_bytes: Option<u64>,
81    quant: Option<&'report str>,
82    context_length: Option<u32>,
83    kv_bytes_per_token: Option<u64>,
84    #[serde(borrow)]
85    capabilities: Option<Vec<&'report str>>,
86    context: Option<u32>,
87    fit: Option<Fit>,
88    weights_fit: Option<bool>,
89    required_bytes: Option<f64>,
90    usable_bytes: Option<f64>,
91    memory_kind: Option<MemoryKind>,
92    evidence: Option<&'report str>,
93    throughput: Option<&'report str>,
94}
95
96fn invalid(message: &str) -> io::Error {
97    io::Error::new(io::ErrorKind::InvalidInput, message)
98}
99
100fn check_bounds(
101    value: &Value,
102    depth: usize,
103    nodes: &mut usize,
104    bytes: &mut usize,
105) -> io::Result<()> {
106    *nodes += 1;
107    if depth > 16 || *nodes > MAX_NODES {
108        return Err(invalid("installed report structure limit exceeded"));
109    }
110    let mut check_text = |text: &str| -> io::Result<()> {
111        if text.len() > MAX_TEXT_BYTES {
112            return Err(invalid("installed report text limit exceeded"));
113        }
114        *bytes += text.len();
115        if *bytes > MAX_TOTAL_TEXT_BYTES {
116            return Err(invalid("installed report total text limit exceeded"));
117        }
118        Ok(())
119    };
120    match value {
121        Value::String(text) => check_text(text)?,
122        Value::Array(values) => {
123            if values.len() > MAX_ITEMS {
124                return Err(invalid("installed report collection limit exceeded"));
125            }
126            for value in values {
127                check_bounds(value, depth + 1, nodes, bytes)?;
128            }
129        }
130        Value::Object(values) => {
131            if values.len() > MAX_ITEMS {
132                return Err(invalid("installed report collection limit exceeded"));
133            }
134            for key in values.keys() {
135                check_text(key)?;
136            }
137            for value in values.values() {
138                check_bounds(value, depth + 1, nodes, bytes)?;
139            }
140        }
141        _ => {}
142    }
143    Ok(())
144}
145
146fn number(value: Option<impl ToString>, unit: &str) -> String {
147    value.map_or_else(
148        || "unknown".into(),
149        |value| format!("{}{unit}", value.to_string()),
150    )
151}
152
153fn safe(value: Option<&str>) -> io::Result<String> {
154    single_line(value.filter(|value| !value.is_empty()).unwrap_or("unknown"))
155}
156
157fn build_row(model: Model<'_>) -> io::Result<Row> {
158    if model.id.trim().is_empty()
159        || model
160            .context
161            .is_some_and(|context| !(1..=10_000_000).contains(&context))
162        || [model.required_bytes, model.usable_bytes]
163            .into_iter()
164            .flatten()
165            .any(|value| !value.is_finite() || value < 0.0)
166    {
167        return Err(invalid("invalid installed model evidence"));
168    }
169    let id = identifier(model.id)?;
170    let fit = model.fit.as_ref().map_or("unknown", Fit::label).to_owned();
171    let capabilities = model.capabilities.unwrap_or_default();
172    let mut capability_text = capabilities
173        .iter()
174        .take(MAX_ROWS)
175        .map(|value| single_line(value))
176        .collect::<io::Result<Vec<_>>>()?
177        .join(", ");
178    if capability_text.is_empty() {
179        capability_text = "unknown".into();
180    }
181    if capabilities.len() > MAX_ROWS {
182        capability_text.push_str(&format!(
183            "; +{} more capabilities",
184            capabilities.len() - MAX_ROWS
185        ));
186    }
187    let quant = safe(model.quant)?;
188    let context = model.context.map_or_else(
189        || "unknown (no explicit token count reported)".into(),
190        |context| format!("{context} tokens"),
191    );
192    let details = format!(
193        "Details: {id}\nFit: {fit}\nWeights: {}; fit {}\nRequired memory: {}\nUsable memory: {}\nMemory kind: {}\nContext: {context}\nModel context limit: {}\nKV cache: {}\nQuantization: {quant}\nCapabilities: {capability_text}\nDigest (reported, not verified): {}\nEvidence: {}\nThroughput: {}\n",
194        number(model.size_bytes, " bytes"),
195        model
196            .weights_fit
197            .map_or("unknown", |fits| if fits { "yes" } else { "no" }),
198        number(model.required_bytes, " bytes"),
199        number(model.usable_bytes, " bytes"),
200        match model.memory_kind {
201            Some(MemoryKind::Ram) => "ram",
202            Some(MemoryKind::Vram) => "vram",
203            None => "unknown",
204        },
205        number(model.context_length, " tokens"),
206        number(model.kv_bytes_per_token, " bytes/token"),
207        safe(model.digest)?,
208        safe(model.evidence)?,
209        safe(model.throughput)?,
210    );
211    let search = format!(
212        "{} {id} {quant} {fit} {capability_text}",
213        single_line(model.id)?
214    )
215    .to_lowercase();
216    Ok(Row {
217        id,
218        search,
219        fit,
220        details,
221    })
222}
223
224pub fn build_installed(report: &Value, command: InstalledCommand) -> io::Result<InstalledView> {
225    check_bounds(report, 0, &mut 0, &mut 0)?;
226    let report =
227        Report::deserialize(report).map_err(|_| invalid("invalid installed inventory report"))?;
228    if command == InstalledCommand::CanRun && report.models.len() > 1 {
229        return Err(invalid(
230            "can-run installed report must contain at most one model",
231        ));
232    }
233    Ok(InstalledView {
234        command,
235        source: safe(report.source)?,
236        rows: report
237            .models
238            .into_iter()
239            .map(build_row)
240            .collect::<io::Result<_>>()?,
241    })
242}
243
244fn bounded_document(text: String) -> String {
245    const NOTICE: &str = "[output bounded; refine search]\n";
246    let mut output = String::new();
247    for line in text.split_inclusive('\n') {
248        if output.len() + line.len() > MAX_DOCUMENT_BYTES - NOTICE.len() {
249            output.push_str(NOTICE);
250            return output;
251        }
252        output.push_str(line);
253    }
254    output
255}
256
257impl InstalledView {
258    pub(crate) fn command(&self) -> InstalledCommand {
259        self.command
260    }
261
262    pub(crate) fn visual_overview(&self) -> Vec<String> {
263        let mut lines = vec![
264            format!("Source: {}", self.source),
265            "Installed metadata only; digests reported, not verified".into(),
266        ];
267        if self.rows.is_empty() {
268            lines.push("No results: No installed models match.".into());
269        }
270        lines
271    }
272
273    pub(crate) fn visual_rows(&self) -> impl ExactSizeIterator<Item = (&str, &str, &str, &str)> {
274        self.rows.iter().map(|row| {
275            (
276                row.id.as_str(),
277                row.fit.as_str(),
278                row.search.as_str(),
279                row.details.as_str(),
280            )
281        })
282    }
283
284    fn help(&self) -> &'static str {
285        match self.command {
286            InstalledCommand::Recommend => {
287                "Commands: /text search; number details; ? help; q quit\n"
288            }
289            InstalledCommand::CanRun => "Commands: ? help; q quit\n",
290        }
291    }
292
293    fn filtered<'view>(&'view self, query: &str) -> Vec<&'view Row> {
294        let query = query.to_lowercase();
295        self.rows
296            .iter()
297            .filter(|row| row.search.contains(&query))
298            .collect()
299    }
300
301    fn list(&self, query: &str) -> String {
302        let rows = self.filtered(query);
303        let mut output = String::new();
304        if rows.is_empty() {
305            output.push_str("No results\n");
306        }
307        for (index, row) in rows.iter().take(MAX_ROWS).enumerate() {
308            output.push_str(&format!("{}. {}; fit {}\n", index + 1, row.id, row.fit));
309        }
310        if rows.len() > MAX_ROWS {
311            output.push_str(&format!(
312                "Showing first {MAX_ROWS} of {}; use /text to refine.\n",
313                rows.len()
314            ));
315        }
316        output
317    }
318
319    pub fn format(&self) -> String {
320        let title = match self.command {
321            InstalledCommand::Recommend => "Recommend",
322            InstalledCommand::CanRun => "Can Run",
323        };
324        let mut output = format!(
325            "rigspark / {title} / Installed / Accessible\nSource: {}\n",
326            self.source
327        );
328        if self.rows.is_empty() {
329            output.push_str("No installed models match.\n");
330        } else {
331            match self.command {
332                InstalledCommand::Recommend => output.push_str(&self.list("")),
333                InstalledCommand::CanRun => output.push_str(&self.rows[0].details),
334            }
335        }
336        output.push_str(self.help());
337        bounded_document(output)
338    }
339
340    fn response(&self, line: &str, query: &mut String) -> String {
341        if line == "?" {
342            return self.help().into();
343        }
344        if self.command == InstalledCommand::Recommend {
345            if let Some(filter) = line.strip_prefix('/') {
346                *query = filter.trim().into();
347                return bounded_document(format!(
348                    "Filter: {}\n{}",
349                    if query.is_empty() {
350                        "off"
351                    } else {
352                        query.as_str()
353                    },
354                    self.list(query)
355                ));
356            }
357            if !line.is_empty()
358                && line.len() <= 4
359                && !line.starts_with('0')
360                && line.bytes().all(|byte| byte.is_ascii_digit())
361            {
362                let index = line.parse::<usize>().unwrap_or(0);
363                return if (1..=MAX_ROWS).contains(&index) {
364                    self.filtered(query).get(index - 1).map_or_else(
365                        || "No such result.\n".into(),
366                        |row| bounded_document(row.details.clone()),
367                    )
368                } else {
369                    "No such result.\n".into()
370                };
371            }
372        }
373        "Unknown command. Enter ? for help.\n".into()
374    }
375}
376
377fn write_frame(output: &mut impl Write, frame: &str) -> io::Result<()> {
378    output.write_all(frame.as_bytes())?;
379    output.flush()
380}
381
382pub async fn run_installed(
383    view: &InstalledView,
384    input: &mut Receiver<io::Result<String>>,
385    output: &mut impl Write,
386    cancellation: &CancellationToken,
387) -> io::Result<InstalledOutcome> {
388    if cancellation.is_cancelled() {
389        return Ok(InstalledOutcome::Cancelled);
390    }
391    write_frame(output, &view.format())?;
392    let mut query = String::new();
393    loop {
394        let raw = tokio::select! {
395            biased;
396            () = cancellation.cancelled() => return Ok(InstalledOutcome::Cancelled),
397            line = input.recv() => match line {
398                Some(line) => line?,
399                None => return Ok(InstalledOutcome::Exited),
400            }
401        };
402        if raw.len() > MAX_INPUT_BYTES {
403            return Err(invalid("installed command input limit exceeded"));
404        }
405        let line = single_line(raw.trim())?;
406        if line == "q" {
407            return Ok(InstalledOutcome::Exited);
408        }
409        write_frame(output, &view.response(&line, &mut query))?;
410        tokio::task::yield_now().await;
411    }
412}