1use crate::{
2 acquire::{Acquisition, HfTransport},
3 adapters::{BackendAdapter, BackendError, BackendKind, RuntimeAdapter, ServeRequest},
4 command::{CommandRunner, NativeCommandRunner},
5 http::{HttpError, NativeTransport, Request, Response, Transport},
6 identity::{NativeProcessProbe, ProcessIdentity},
7 lifecycle::{Activation, Lifecycle, Registry},
8 ollama_installed::{InstalledModels, LocalVerifier, verify_catalog_manifest},
9 process_control::{
10 NativeProcessControl, ProcessControl, listener, resolve_binary, resolve_bitnet_server,
11 same_process,
12 },
13 pull::{PullRequest, PullService},
14 special_adapters::{LmStudioAdapter, MlxAdapter},
15 state::{Config, ServerState, StateStore},
16};
17use rigspark_core::{
18 catalog::{Catalog, CatalogModel, resolve},
19 reports::strip_control,
20 sizing::{Hardware, SizingRequest, evaluate},
21};
22use serde_json::{Value, json};
23use std::{path::PathBuf, time::Duration};
24use tokio_util::sync::CancellationToken;
25
26pub mod events;
27use events::{
28 LifecycleObserver, LifecycleScope, LifecycleStage, LifecycleWarning, ObservedAdapter,
29 download_progress, observe, warning,
30};
31
32pub struct LifecycleOptions {
33 pub command: String,
34 pub model: Option<String>,
35 pub backend: Option<String>,
36 pub port: Option<u16>,
37 pub context: Option<u32>,
38 pub installed: bool,
39 pub bypass: bool,
40 pub cache: crate::cache::CacheFlags,
41}
42impl LifecycleOptions {
43 pub fn validate(&self) -> Result<(), BackendError> {
44 if !self.cache.is_empty() {
45 if !["up", "switch"].contains(&self.command.as_str()) {
46 return Err(BackendError(format!(
47 "{} does not accept cache options",
48 self.command
49 )));
50 }
51 if self.installed {
52 return Err(BackendError(
53 "cache options apply only to a runtime rigspark starts; --installed attaches to a running Ollama".into(),
54 ));
55 }
56 if let Some(profile) = self.cache.over(None) {
57 profile
58 .validate()
59 .map_err(|error| BackendError(error.to_string()))?;
60 }
61 }
62 if !["up", "switch", "down", "doctor"].contains(&self.command.as_str())
63 || self.port == Some(0)
64 || self
65 .context
66 .is_some_and(|value| !(1..=10000000).contains(&value))
67 || self
68 .backend
69 .as_ref()
70 .is_some_and(|value| !rigspark_core::catalog::BACKENDS.contains(&value.as_str()))
71 {
72 return Err(BackendError("invalid lifecycle options".into()));
73 }
74 if self.command == "down" || self.command == "doctor" {
75 if (self.command == "doctor" && self.model.is_some())
76 || self.backend.is_some()
77 || self.port.is_some()
78 || self.context.is_some()
79 || self.installed
80 || self.bypass
81 {
82 return Err(BackendError(format!(
83 "{} does not accept selection options",
84 self.command
85 )));
86 }
87 } else if self.model.is_none() {
88 return Err(BackendError("model is required".into()));
89 }
90 if let Some(query) = self.model.as_deref() {
91 if query.trim().is_empty() || query.len() > 8192 || query.chars().any(char::is_control)
92 {
93 return Err(BackendError("invalid model reference".into()));
94 }
95 if self.installed {
96 crate::adapters::model_id(query)?;
97 }
98 }
99 if self.installed
100 && (!self.bypass
101 || self
102 .backend
103 .as_ref()
104 .is_some_and(|backend| backend != "ollama"))
105 {
106 return Err(BackendError(
107 "installed models require --bypass and Ollama".into(),
108 ));
109 }
110 Ok(())
111 }
112}
113struct CheckedHttp<'runtime> {
114 inner: &'runtime dyn Transport,
115 probe: &'runtime NativeProcessProbe,
116 expected: ProcessIdentity,
117}
118#[async_trait::async_trait]
119impl Transport for CheckedHttp<'_> {
120 async fn send(&self, request: Request) -> Result<Response, HttpError> {
121 let observed = listener(self.probe, request.url.as_str(), &CancellationToken::new())
122 .await
123 .map_err(|_| HttpError::Invalid)?;
124 if !same_process(&observed.identity, &self.expected) {
125 return Err(HttpError::Invalid);
126 }
127 self.inner.send(request).await
128 }
129}
130struct ContextActivation<'runtime> {
131 source: String,
132 context: Option<u32>,
133 installed: bool,
134 expected_manifest: Option<String>,
135 expected_sha: Option<String>,
136 expected_bytes: Option<u64>,
137 projectors: Vec<rigspark_core::sizing::ProjectorArtifact>,
138 root: PathBuf,
139 http: &'runtime NativeTransport,
140 probe: &'runtime NativeProcessProbe,
141 observer: Option<&'runtime LifecycleObserver>,
142}
143#[async_trait::async_trait]
144impl Activation for ContextActivation<'_> {
145 async fn finalize(
146 &self,
147 handle: &ServerState,
148 cancel: &CancellationToken,
149 ) -> Result<ServerState, BackendError> {
150 let observed = listener(self.probe, &handle.endpoint, cancel).await?;
151 if handle.pid != Some(observed.identity.pid)
152 || handle.process_executable.as_deref() != Some(&observed.identity.executable)
153 || handle.process_started_at.as_deref() != Some(&observed.identity.started)
154 {
155 return Err(BackendError(
156 "Ollama listener changed before activation".into(),
157 ));
158 }
159 let http = CheckedHttp {
160 inner: self.http,
161 probe: self.probe,
162 expected: observed.identity,
163 };
164 let verifier = LocalVerifier {
165 root: self.root.clone(),
166 };
167 let support = InstalledModels::new(&http, &verifier);
168 let model = support
169 .inspect(&handle.endpoint, &self.source, cancel)
170 .await
171 .map_err(|error| BackendError(error.to_string()))?;
172 if let Some(expected) = &self.expected_manifest {
173 let digests = crate::ollama_installed::manifest_digests(&self.root, &self.source)
175 .map_err(|error| BackendError(error.to_string()))?;
176 if digests.first() != Some(expected) || !digests.contains(&model.digest) {
177 return Err(BackendError("installed source changed; retry".into()));
178 }
179 }
180 observe(
181 self.observer,
182 LifecycleScope::Runtime,
183 LifecycleStage::Verification,
184 async {
185 verify_catalog_manifest(
186 &self.root,
187 &model.id,
188 &model.digest,
189 self.expected_sha.as_deref(),
190 self.expected_bytes,
191 &self.projectors,
192 cancel,
193 )
194 .await
195 .map_err(|error| BackendError(error.to_string()))
196 },
197 )
198 .await?;
199 let runtime = observe(
200 self.observer,
201 LifecycleScope::Runtime,
202 LifecycleStage::Activation,
203 async {
204 support
205 .activate(&handle.endpoint, &model, self.context, cancel)
206 .await
207 .map_err(|error| BackendError(error.to_string()))
208 },
209 )
210 .await?;
211 let final_model = support
212 .inspect(&handle.endpoint, &self.source, cancel)
213 .await
214 .map_err(|error| BackendError(error.to_string()))?;
215 if final_model.digest != model.digest {
216 return Err(BackendError(
217 "installed source changed before commit".into(),
218 ));
219 }
220 let mut active = handle.clone();
221 active.runtime_model_id = Some(runtime);
222 active.context = self.context;
223 if self.installed {
224 active.integrity = Some("local-manifest".into());
225 active.local_manifest_digest = Some(model.digest);
226 }
227 Ok(active)
228 }
229}
230fn compatible(model: &CatalogModel, backend: &str) -> bool {
231 model.supports_backend(backend)
232}
233fn backend_known(backend: &str) -> bool {
234 rigspark_core::catalog::BACKENDS.contains(&backend)
235}
236fn backend_index(backend: &str) -> usize {
238 match backend {
239 "llamacpp" => 1,
240 "mlx" => 2,
241 "lmstudio" => 3,
242 "bitnet" => 4,
243 _ => 0,
244 }
245}
246pub fn check_attach_override(
248 command: &str,
249 active: &str,
250 flag: Option<&str>,
251 env: Option<&str>,
252) -> Result<(), BackendError> {
253 if let Some(backend) = flag
254 && backend != active
255 {
256 return Err(BackendError(format!(
257 "{command} cannot change the active backend from {active} to {backend}; use up --backend {backend}"
258 )));
259 }
260 if let Some(backend) = env.map(str::trim).filter(|value| !value.is_empty())
261 && backend != active
262 {
263 return Err(BackendError(format!(
264 "RIGSPARK_BACKEND={} conflicts with the active {active} server; unset it or use up",
265 strip_control(backend)
266 )));
267 }
268 Ok(())
269}
270pub fn preferred_backend(
272 flag: Option<&str>,
273 env: Option<&str>,
274 user: Option<&str>,
275) -> Option<String> {
276 flag.or(env.filter(|value| !value.trim().is_empty()))
277 .or(user)
278 .map(str::to_owned)
279}
280pub fn auto_backend_order(model: &CatalogModel, hardware: &Hardware) -> Vec<&'static str> {
283 let apple = hardware.platform == rigspark_core::sizing::Platform::Darwin
284 && hardware.arch == rigspark_core::sizing::CpuArch::Arm64;
285 let order: &[&str] = if apple {
286 &["mlx", "ollama", "llamacpp", "bitnet"]
287 } else {
288 &["ollama", "llamacpp", "bitnet"]
289 };
290 order
291 .iter()
292 .copied()
293 .filter(|name| compatible(model, name))
294 .collect()
295}
296pub fn check_backend(
297 model: &CatalogModel,
298 backend: &str,
299 hardware: &Hardware,
300 installed: bool,
301) -> Result<(), BackendError> {
302 if !rigspark_core::catalog::BACKENDS.contains(&backend) {
303 return Err(BackendError("invalid backend selection".into()));
304 }
305 validate_backend_platform(backend, hardware.platform.clone(), hardware.arch.clone())?;
306 if backend == "lmstudio" && model.source.gguf.is_none() && model.source.mlx.is_some() {
307 validate_backend_platform("mlx", hardware.platform.clone(), hardware.arch.clone())?;
308 }
309 if !installed || !compatible(model, backend) {
310 return Err(BackendError(
311 "backend is unavailable or model source is unsupported".into(),
312 ));
313 }
314 Ok(())
315}
316#[derive(Debug, Clone, Copy)]
317pub struct PlanOptions {
318 pub simple_switch: bool,
319 pub bypass: bool,
320 pub context: Option<u32>,
321 pub kv_cache: Option<rigspark_core::sizing::KvCacheType>,
323}
324#[derive(Debug)]
325pub struct QuantPlan {
326 pub quant: rigspark_core::sizing::Quantization,
327 pub estimated_fit: bool,
328}
329pub fn plan_quantization(
331 model: &CatalogModel,
332 explicit: Option<&rigspark_core::sizing::Quantization>,
333 backend: &str,
334 hardware: &Hardware,
335 options: PlanOptions,
336) -> Result<QuantPlan, BackendError> {
337 if options.simple_switch && backend != "ollama" {
338 return Err(BackendError(
339 "single-model and delegated runtimes require up to replace models".into(),
340 ));
341 }
342 if backend == "bitnet" {
343 if !model.supports_backend("bitnet") {
344 return Err(BackendError("BitNet requires an I2_S GGUF artifact".into()));
345 }
346 if options.context.is_some_and(|context| {
347 context == 0 || f64::from(context) > model.context_length.min(4096.0)
348 }) {
349 return Err(BackendError(
350 "BitNet context exceeds the model's supported range".into(),
351 ));
352 }
353 }
354 if options.context.is_some() && !["ollama", "llamacpp", "bitnet"].contains(&backend) {
355 return Err(BackendError(
356 "explicit runtime context currently requires Ollama or llama.cpp".into(),
357 ));
358 }
359 let mut sizing = match options.kv_cache {
360 Some(kind) => model
361 .with_kv_cache(kind)
362 .map_err(|error| BackendError(error.to_string()))?
363 .sizing(),
364 None => model.sizing(),
365 };
366 if let Some(quant) = explicit {
367 sizing.quantizations = vec![quant.clone()];
368 }
369 let fit = evaluate(&SizingRequest {
370 model: sizing,
371 hardware: hardware.clone(),
372 context: options.context.map(f64::from),
373 })
374 .map_err(|error| BackendError(error.to_string()))?;
375 if !options.simple_switch
376 && explicit.is_none()
377 && backend != "lmstudio"
378 && fit.fit.reason == Some("disk-bound")
379 {
380 return Err(BackendError("insufficient disk space".into()));
381 }
382 let quant = if options.simple_switch {
383 explicit.or_else(|| model.quantizations.first()).cloned()
384 } else {
385 explicit.cloned().or(fit.fit.quant.clone()).or_else(|| {
386 if options.bypass {
387 model
388 .quantizations
389 .iter()
390 .min_by(|left, right| left.disk_bytes.total_cmp(&right.disk_bytes))
391 .cloned()
392 } else {
393 None
394 }
395 })
396 }
397 .ok_or_else(|| {
398 BackendError("model does not fit; use --bypass to override estimated fit".into())
399 })?;
400 if !options.simple_switch
401 && backend != "lmstudio"
402 && quant.disk_bytes > hardware.free_disk_bytes
403 {
404 return Err(BackendError("insufficient disk space".into()));
405 }
406 if !options.simple_switch
407 && !fit.fit.fits
408 && !options.bypass
409 && (options.context.is_some() || explicit.is_none())
410 {
411 return Err(BackendError(
412 "model does not fit requested context; use --bypass".into(),
413 ));
414 }
415 Ok(QuantPlan {
416 quant,
417 estimated_fit: !options.simple_switch && !fit.fit.fits,
418 })
419}
420#[derive(Debug)]
422pub struct SpeculationPlan<'catalog> {
423 pub profile: Option<crate::cache::CacheProfile>,
424 pub drafter: Option<&'catalog CatalogModel>,
425 pub implicit: bool,
427}
428pub fn plan_speculation<'catalog>(
430 catalog: &'catalog Catalog,
431 model: &CatalogModel,
432 backend: &str,
433 requested: Option<crate::cache::CacheProfile>,
434 flag_given: bool,
435) -> Result<SpeculationPlan<'catalog>, BackendError> {
436 use crate::cache::Speculative;
437 let mut profile = requested.unwrap_or_default();
438 let drafter = catalog.drafter_of(model).filter(|_| backend == "llamacpp");
439 if !flag_given && matches!(profile.speculative, Speculative::Off | Speculative::Draft) {
441 profile.speculative = if drafter.is_some() {
442 Speculative::Auto
443 } else {
444 Speculative::Off
445 };
446 }
447 let implicit = !flag_given && profile.speculative == Speculative::Auto;
448 let drafter = match profile.speculative {
449 Speculative::Auto => {
450 profile.speculative = if drafter.is_some() {
451 Speculative::Draft
452 } else {
453 Speculative::Off
454 };
455 drafter
456 }
457 Speculative::Draft => Some(drafter.ok_or_else(|| {
458 BackendError(if backend == "llamacpp" {
459 "this model has no catalog drafter; try --speculative ngram".into()
460 } else {
461 "draft speculative decoding requires --backend llamacpp".into()
462 })
463 })?),
464 Speculative::Off | Speculative::Ngram => None,
465 };
466 Ok(SpeculationPlan {
467 profile: crate::cache::effective(Some(&profile)),
468 drafter,
469 implicit,
470 })
471}
472pub fn drafter_reserve(hardware: &Hardware, drafter: &CatalogModel) -> Hardware {
474 let memory = drafter
475 .quantizations
476 .iter()
477 .map(|quant| quant.min_ram_bytes)
478 .fold(0.0, f64::max);
479 let disk = drafter
480 .quantizations
481 .iter()
482 .map(|quant| quant.disk_bytes * 1.5)
483 .fold(0.0, f64::max);
484 let mut reduced = hardware.clone();
485 reduced.total_ram_bytes = (reduced.total_ram_bytes - memory).max(0.0);
486 reduced.free_ram_bytes = (reduced.free_ram_bytes - memory).max(0.0);
487 reduced.free_disk_bytes = (reduced.free_disk_bytes - disk).max(0.0);
488 for gpu in &mut reduced.gpu {
489 gpu.vram_bytes = (gpu.vram_bytes - memory).max(0.0);
490 }
491 reduced
492}
493pub fn slot_sizing_model(
496 model: &CatalogModel,
497 profile: Option<&crate::cache::CacheProfile>,
498 backend: &str,
499 context: Option<u32>,
500 bypass: bool,
501) -> Result<CatalogModel, BackendError> {
502 let slots = profile.and_then(|profile| profile.parallel).unwrap_or(1);
503 let mut sized = model.clone();
504 if backend != "ollama" || slots <= 1 {
505 return Ok(sized);
506 }
507 if context.is_none() {
508 return Err(BackendError(
509 "Ollama sizes every slot at the full context; pass --context with --parallel".into(),
510 ));
511 }
512 match model.kv_bytes_per_token {
513 Some(rate) => sized.kv_bytes_per_token = Some(rate * f64::from(slots)),
514 None if bypass => {}
515 None => {
516 return Err(BackendError(
517 "KV geometry for this model is unknown, so memory for parallel slots cannot be sized; use --bypass to accept that".into(),
518 ));
519 }
520 }
521 Ok(sized)
522}
523fn catalog_pull_request(
524 model: &CatalogModel,
525 quant: &rigspark_core::sizing::Quantization,
526 backend: &str,
527) -> Result<PullRequest, BackendError> {
528 Ok(PullRequest {
529 backend: backend.into(),
530 model_id: if backend == "ollama" {
531 model
532 .source
533 .ollama
534 .clone()
535 .ok_or_else(|| BackendError("missing Ollama source".into()))?
536 } else {
537 model.id.clone()
538 },
539 expected_bytes: quant.disk_bytes as u64,
540 expected_sha256: quant.sha256.clone(),
541 projectors: quant.projectors.clone(),
542 gguf: model.source.gguf.clone(),
543 mlx: model.source.mlx.clone(),
544 })
545}
546pub fn validate_backend_platform(
547 backend: &str,
548 platform: rigspark_core::sizing::Platform,
549 arch: rigspark_core::sizing::CpuArch,
550) -> Result<(), BackendError> {
551 if backend == "mlx"
552 && !(platform == rigspark_core::sizing::Platform::Darwin
553 && arch == rigspark_core::sizing::CpuArch::Arm64)
554 {
555 return Err(BackendError(
556 "MLX requires Apple Silicon (darwin/arm64)".into(),
557 ));
558 }
559 Ok(())
560}
561pub(crate) fn studio_trust(home: &std::path::Path) -> Vec<PathBuf> {
562 let paths = if cfg!(target_os = "macos") {
563 vec![
564 PathBuf::from("/Applications/LM Studio.app/Contents/MacOS/LM Studio"),
565 home.join("Applications/LM Studio.app/Contents/MacOS/LM Studio"),
566 ]
567 } else if cfg!(windows) {
568 let mut paths = vec![
569 PathBuf::from("C:\\Program Files\\LM Studio\\LM Studio.exe"),
570 PathBuf::from("C:\\Program Files\\LM Studio\\llmster.exe"),
571 ];
572 if let Some(local) = std::env::var_os("LOCALAPPDATA") {
573 paths.extend([
574 PathBuf::from(&local).join("Programs/LM Studio/LM Studio.exe"),
575 PathBuf::from(local).join("Programs/LM Studio/llmster.exe"),
576 ]);
577 }
578 paths
579 } else {
580 vec![
581 PathBuf::from("/usr/bin/llmster"),
582 PathBuf::from("/usr/local/bin/llmster"),
583 PathBuf::from("/opt/lm-studio/bin/llmster"),
584 ]
585 };
586 paths
587 .into_iter()
588 .map(|path| path.canonicalize().unwrap_or(path))
589 .collect()
590}
591pub async fn run_native(
592 options: &LifecycleOptions,
593 catalog: &Catalog,
594 hardware: Option<&Hardware>,
595 cancel: &CancellationToken,
596) -> Result<(Value, String), BackendError> {
597 run_native_observed(options, catalog, hardware, cancel, None).await
598}
599pub async fn run_native_observed(
600 options: &LifecycleOptions,
601 catalog: &Catalog,
602 hardware: Option<&Hardware>,
603 cancel: &CancellationToken,
604 observer: Option<&LifecycleObserver>,
605) -> Result<(Value, String), BackendError> {
606 let config = Config::load().map_err(|error| BackendError(error.to_string()))?;
607 run_native_with_config_observed(options, catalog, hardware, cancel, config, observer).await
608}
609pub async fn forget_attached_with_config(
611 config: Config,
612 cancel: &CancellationToken,
613) -> Result<(Value, String), BackendError> {
614 let store = StateStore::new(config);
615 let registry = Registry::new(Vec::new());
616 let lifecycle = Lifecycle {
617 store: &store,
618 registry: ®istry,
619 probe: &NativeProcessProbe,
620 };
621 Ok(match lifecycle.forget_attached(cancel).await? {
622 None => (
623 json!({"type":"no-active"}),
624 "No active server to forget.\n".into(),
625 ),
626 Some(active) => (
627 json!({"type":"forgotten","modelId":active.model_id,"endpoint":active.endpoint}),
628 format!(
629 "Forgot {} ({}); no process was signalled.\n",
630 strip_control(&active.model_id),
631 active.endpoint
632 ),
633 ),
634 })
635}
636pub async fn run_native_with_config(
637 options: &LifecycleOptions,
638 catalog: &Catalog,
639 hardware: Option<&Hardware>,
640 cancel: &CancellationToken,
641 config: Config,
642) -> Result<(Value, String), BackendError> {
643 run_native_with_config_observed(options, catalog, hardware, cancel, config, None).await
644}
645pub async fn run_native_with_config_observed(
646 options: &LifecycleOptions,
647 catalog: &Catalog,
648 hardware: Option<&Hardware>,
649 cancel: &CancellationToken,
650 config: Config,
651 observer: Option<&LifecycleObserver>,
652) -> Result<(Value, String), BackendError> {
653 options.validate()?;
654 let observer = observer.filter(|_| options.command != "doctor");
655 let store = StateStore::new(config.clone());
656 let prior = store
657 .read()
658 .map_err(|error| BackendError(error.to_string()))?;
659 if options.command == "switch" {
660 let active = prior
661 .active
662 .as_ref()
663 .ok_or_else(|| BackendError("no active server to switch; run up first".into()))?;
664 check_attach_override(
665 "switch",
666 &active.backend,
667 options.backend.as_deref(),
668 std::env::var("RIGSPARK_BACKEND").ok().as_deref(),
669 )?;
670 if options.context.is_none()
671 && !options.bypass
672 && let Some(port) = options.port
673 && port != active.port
674 {
675 return Err(BackendError(format!(
676 "switch without --context or --bypass cannot change the active port; use up --port {port}"
677 )));
678 }
679 }
680 if options.command == "down"
681 && let Some(active) = &prior.active
682 {
683 check_attach_override(
684 "down",
685 &active.backend,
686 None,
687 std::env::var("RIGSPARK_BACKEND").ok().as_deref(),
688 )?;
689 }
690 let home = std::env::var_os("HOME")
691 .or_else(|| std::env::var_os("USERPROFILE"))
692 .map(PathBuf::from)
693 .ok_or_else(|| BackendError("home unavailable".into()))?;
694 let bitnet_path = resolve_bitnet_server();
695 if ["down", "doctor"].contains(&options.command.as_str())
696 && prior
697 .active
698 .as_ref()
699 .is_some_and(|active| active.backend == "bitnet")
700 {
701 bitnet_path
702 .as_ref()
703 .map_err(|error| BackendError(error.clone()))?;
704 }
705 let mut paths = ["ollama", "llama-server", "python3", "lms"]
706 .map(|name| resolve_binary(name).ok())
707 .to_vec();
708 paths.push(bitnet_path.as_ref().ok().cloned());
709 let binary = |index: usize| {
710 paths[index]
711 .clone()
712 .unwrap_or_else(|| config.home.join(".unavailable").join(index.to_string()))
713 };
714 let http = NativeTransport::new().map_err(|error| BackendError(error.to_string()))?;
715 let probe = NativeProcessProbe;
716 let control = NativeProcessControl;
717 let commands = NativeCommandRunner;
718 let ollama_root = std::env::var_os("OLLAMA_MODELS")
719 .map(PathBuf::from)
720 .unwrap_or_else(|| home.join(".ollama/models"));
721 let ollama = RuntimeAdapter::new(BackendKind::Ollama, binary(0), &http, &probe, &control)
722 .with_ollama_models(ollama_root.clone())?;
723 let llama = RuntimeAdapter::new(BackendKind::LlamaCpp, binary(1), &http, &probe, &control);
724 let bitnet = RuntimeAdapter::new(BackendKind::BitNet, binary(4), &http, &probe, &control);
725 let mlx = MlxAdapter {
726 binary: binary(2),
727 http: &http,
728 probe: &probe,
729 control: &control,
730 commands: &commands,
731 token: None,
732 };
733 let studio = LmStudioAdapter {
734 binary: binary(3),
735 trusted_executables: studio_trust(&home),
736 http: &http,
737 probe: &probe,
738 commands: &commands,
739 token: std::env::var("LM_API_TOKEN").ok(),
740 };
741 let acquisition_daemon =
742 ObservedAdapter::new(&ollama, observer, LifecycleScope::AcquisitionDaemon);
743 let ollama = ObservedAdapter::new(&ollama, observer, LifecycleScope::Runtime);
744 let llama = ObservedAdapter::new(&llama, observer, LifecycleScope::Runtime);
745 let mlx = ObservedAdapter::new(&mlx, observer, LifecycleScope::Runtime);
746 let studio = ObservedAdapter::new(&studio, observer, LifecycleScope::Runtime);
747 let bitnet = ObservedAdapter::new(&bitnet, observer, LifecycleScope::Runtime);
748 let registry = Registry::new(vec![&ollama, &llama, &mlx, &studio, &bitnet]);
749 let lifecycle = Lifecycle {
750 store: &store,
751 registry: ®istry,
752 probe: &probe,
753 };
754 if options.command == "doctor" {
755 let Some(active) = prior.active else {
756 return Ok((
757 json!({"name":"state","status":"ok","detail":"no active server recorded"}),
758 String::new(),
759 ));
760 };
761 let model = catalog
762 .models
763 .iter()
764 .find(|model| model.id == active.model_id);
765 let path = if active.backend == "mlx" {
766 let source = model
767 .and_then(|model| model.source.mlx.as_ref())
768 .ok_or_else(|| BackendError("active MLX source unavailable".into()))?;
769 let (owner, name) = source
770 .repo
771 .split_once('/')
772 .ok_or_else(|| BackendError("invalid source".into()))?;
773 Some(
774 config
775 .home
776 .join("cache/mlx")
777 .join(owner)
778 .join(format!("{name}@{}", source.revision)),
779 )
780 } else if ["llamacpp", "bitnet"].contains(&active.backend.as_str()) {
781 let source = model
782 .and_then(|model| model.source.gguf.as_ref())
783 .ok_or_else(|| BackendError("active GGUF source unavailable".into()))?;
784 let (owner, name) = source
785 .repo
786 .split_once('/')
787 .ok_or_else(|| BackendError("invalid source".into()))?;
788 Some(
789 config
790 .home
791 .join("cache")
792 .join(&active.backend)
793 .join(owner)
794 .join(format!("{name}@{}", source.revision))
795 .join(&source.file),
796 )
797 } else {
798 active.model_path.as_ref().map(PathBuf::from)
799 };
800 let request = ServeRequest {
801 draft_model_path: None,
802 model_id: active.model_id.clone(),
803 endpoint: active.endpoint.clone(),
804 model_path: path,
805 context: None,
806 cache: None,
807 };
808 lifecycle.health(&active, &request, cancel).await?;
809 return Ok((
810 json!({"name":"state","status":"ok","detail":format!("serving {} at {}",strip_control(&active.model_id),active.endpoint)}),
811 String::new(),
812 ));
813 }
814 if options.command == "down" {
815 let stopped = lifecycle
816 .down_with_target(cancel, || {
817 options
818 .model
819 .as_deref()
820 .map(|query| {
821 resolve(catalog, query)
822 .map(|resolved| resolved.model.id.clone())
823 .map_err(|error| BackendError(error.message))
824 })
825 .transpose()
826 })
827 .await?;
828 let Some(active) = stopped else {
829 return Ok((
830 json!({"type":"no-active"}),
831 "No active server to stop.\n".into(),
832 ));
833 };
834 return Ok((
835 json!({"type":if active.owned_by_us{"stopped"}else{"detached"},"modelId":active.model_id,"endpoint":active.endpoint}),
836 if active.owned_by_us {
837 format!(
838 "Stopped {} ({}).\n",
839 strip_control(&active.model_id),
840 active.endpoint
841 )
842 } else {
843 format!(
844 "Detached from {} ({}); it was not started by rigspark and is still running.\n",
845 strip_control(&active.model_id),
846 active.endpoint
847 )
848 },
849 ));
850 }
851 let query = options
852 .model
853 .as_deref()
854 .ok_or_else(|| BackendError("model required".into()))?;
855 let installed_fallback = options.bypass
856 && resolve(catalog, query).is_err_and(|error| error.code == "MODEL_RESOLUTION_ERROR");
857 if options.installed || installed_fallback {
858 warning(observer, LifecycleWarning::InstalledBypass);
859 if options
860 .backend
861 .as_ref()
862 .is_some_and(|backend| backend != "ollama")
863 {
864 return Err(BackendError(
865 "installed model bypass requires Ollama".into(),
866 ));
867 }
868 let port = options
869 .port
870 .or_else(|| {
871 prior
872 .active
873 .as_ref()
874 .filter(|active| active.backend == "ollama")
875 .map(|active| active.port)
876 })
877 .unwrap_or(11434);
878 let endpoint = format!("http://127.0.0.1:{port}");
879 let reviewed = lifecycle.review(query, cancel).await?;
880 if !control.occupied(&endpoint).await? {
881 return Err(BackendError(
882 "installed activation requires an existing Ollama daemon".into(),
883 ));
884 }
885 let observed = listener(&probe, &endpoint, cancel).await?;
886 if !ollama.trusts(&observed.identity) {
887 return Err(BackendError("untrusted Ollama daemon".into()));
888 }
889 let checked = CheckedHttp {
890 inner: &http,
891 probe: &probe,
892 expected: observed.identity,
893 };
894 let verifier = LocalVerifier {
895 root: ollama_root.clone(),
896 };
897 let support = InstalledModels::new(&checked, &verifier);
898 let model = support
899 .inspect(&endpoint, query, cancel)
900 .await
901 .map_err(|error| BackendError(error.to_string()))?;
902 let catalog_quant = catalog
903 .models
904 .iter()
905 .find(|entry| entry.source.ollama.as_deref() == Some(model.id.as_str()))
906 .and_then(|entry| {
907 entry
908 .quantizations
909 .iter()
910 .find(|quant| Some(&quant.name) == model.quant.as_ref())
911 .or_else(|| entry.quantizations.first())
912 });
913 let activation = ContextActivation {
914 source: model.id.clone(),
915 context: options.context,
916 installed: true,
917 expected_manifest: Some(model.digest),
918 expected_sha: catalog_quant.and_then(|quant| quant.sha256.clone()),
919 expected_bytes: catalog_quant.map(|quant| quant.disk_bytes as u64),
920 projectors: catalog_quant
921 .map(|quant| quant.projectors.clone())
922 .unwrap_or_default(),
923 root: ollama_root,
924 http: &http,
925 probe: &probe,
926 observer,
927 };
928 let request = ServeRequest {
929 draft_model_path: None,
930 model_id: model.id,
931 endpoint,
932 model_path: None,
933 context: options.context,
934 cache: options.cache.over(None),
935 };
936 let active = lifecycle
937 .attach_installed(&request, &reviewed, cancel, &activation)
938 .await?;
939 return Ok(up_output(&active, "local-manifest"));
940 }
941 let resolved = resolve(catalog, query).map_err(|error| BackendError(error.message))?;
942 let model = resolved.model;
943 let prior_cache = prior.active.as_ref().and_then(|active| active.cache);
945 let cache_kept = options.command == "switch"
946 && crate::cache::requested(options.cache, true, prior_cache, None) == prior_cache;
947 if options.command == "switch"
948 && prior
949 .active
950 .as_ref()
951 .is_some_and(|active| active.model_id == model.id)
952 && options.context.is_none()
953 && !options.bypass
954 && cache_kept
955 {
956 let active = prior
957 .active
958 .as_ref()
959 .ok_or_else(|| BackendError("no active model".into()))?;
960 return Ok((
961 json!({"type":"already-active","modelId":model.id,"endpoint":active.endpoint}),
962 format!("{} is already active.\n", model.id),
963 ));
964 }
965 let hardware =
966 hardware.ok_or_else(|| BackendError("hardware required for model selection".into()))?;
967 let simple_switch = options.command == "switch"
968 && options.context.is_none()
969 && !options.bypass
970 && cache_kept
971 && prior
972 .active
973 .as_ref()
974 .is_none_or(|active| active.backend != "bitnet");
975 let env_backend = std::env::var("RIGSPARK_BACKEND").ok();
976 let user = config
977 .user_config()
978 .map_err(|error| BackendError(error.to_string()))?;
979 let requested = crate::cache::requested(
980 options.cache,
981 options.command == "switch",
982 prior_cache,
983 user.cache,
984 );
985 let user_backend = user.default_backend;
986 let configured = preferred_backend(
987 options.backend.as_deref(),
988 env_backend.as_deref(),
989 user_backend.as_deref(),
990 );
991 let backend = if options.command == "switch" {
992 prior
993 .active
994 .as_ref()
995 .ok_or_else(|| BackendError("no active model".into()))?
996 .backend
997 .clone()
998 } else if let Some(backend) = configured {
999 backend
1000 } else {
1001 let mut selected = None;
1002 for name in auto_backend_order(model, hardware) {
1003 if name == "bitnet" {
1004 bitnet_path
1005 .as_ref()
1006 .map_err(|error| BackendError(error.clone()))?;
1007 }
1008 let index = backend_index(name);
1009 if paths[index].is_some() {
1010 let args = if name == "mlx" {
1011 vec![
1012 "-I".into(),
1013 "-c".into(),
1014 "import importlib.metadata; print(importlib.metadata.version('mlx-lm'))"
1015 .into(),
1016 ]
1017 } else {
1018 vec!["--version".into()]
1019 };
1020 if let Ok(version) = commands
1021 .run(&binary(index), &args, cancel, Duration::from_secs(5))
1022 .await
1023 && (name != "mlx" || version.trim() == "0.31.3")
1024 {
1025 selected = Some(name.to_owned());
1026 break;
1027 }
1028 }
1029 }
1030 selected.ok_or_else(|| BackendError("no installed backend supports this model".into()))?
1031 };
1032 if backend == "bitnet" {
1033 bitnet_path
1034 .as_ref()
1035 .map_err(|error| BackendError(error.clone()))?;
1036 }
1037 check_backend(
1038 model,
1039 &backend,
1040 hardware,
1041 backend_known(&backend) && paths[backend_index(&backend)].is_some(),
1042 )?;
1043 let index = backend_index(&backend);
1044 let speculation = plan_speculation(
1045 catalog,
1046 model,
1047 &backend,
1048 requested,
1049 options.cache.speculative.is_some(),
1050 )?;
1051 let mut requested = speculation.profile;
1052 let mut drafter = speculation.drafter;
1053 crate::cache::launch_delta(requested.as_ref(), &backend, true)
1054 .map_err(|error| BackendError(error.to_string()))?;
1055 let sized = slot_sizing_model(
1056 model,
1057 requested.as_ref(),
1058 &backend,
1059 options.context,
1060 options.bypass,
1061 )?;
1062 let plan_options = |requested: Option<crate::cache::CacheProfile>| PlanOptions {
1063 simple_switch,
1064 bypass: options.bypass,
1065 context: options.context,
1066 kv_cache: requested
1067 .filter(|profile| profile.kv_k == profile.kv_v)
1068 .map(|profile| profile.kv_k),
1069 };
1070 let reserved = drafter.map(|drafter| drafter_reserve(hardware, drafter));
1071 let plan = match plan_quantization(
1072 &sized,
1073 resolved.quant,
1074 &backend,
1075 reserved.as_ref().unwrap_or(hardware),
1076 plan_options(requested),
1077 ) {
1078 Err(_) if speculation.implicit => {
1079 warning(observer, LifecycleWarning::DrafterSkipped);
1080 drafter = None;
1081 requested = crate::cache::effective(
1082 requested
1083 .map(|profile| crate::cache::CacheProfile {
1084 speculative: crate::cache::Speculative::Off,
1085 ..profile
1086 })
1087 .as_ref(),
1088 );
1089 plan_quantization(
1090 &sized,
1091 resolved.quant,
1092 &backend,
1093 hardware,
1094 plan_options(requested),
1095 )?
1096 }
1097 result => result?,
1098 };
1099 let quant = plan.quant;
1100 let reviewed = lifecycle.review(&model.id, cancel).await?;
1101 let pull_request = catalog_pull_request(model, &quant, &backend)?;
1102 if plan.estimated_fit {
1103 warning(observer, LifecycleWarning::EstimatedFit);
1104 }
1105 let diagnostics = observer.and_then(|observer| observer.diagnostics.clone());
1106 let acquisition = Acquisition::new(config.home.join("cache"))?.with_progress(
1107 move |completed, total, file| {
1108 download_progress(diagnostics.as_ref(), completed, total, file)
1109 },
1110 );
1111 let download = HfTransport::new()?;
1112 let studio_root = home.join(".lmstudio/models");
1113 let pulls = PullService {
1114 acquisition: &acquisition,
1115 download: &download,
1116 commands: &commands,
1117 ollama_models: &ollama_root,
1118 studio_models: &studio_root,
1119 };
1120 let port = options
1121 .port
1122 .or_else(|| {
1123 if options.command == "switch" {
1124 prior.active.as_ref().map(|active| active.port)
1125 } else {
1126 None
1127 }
1128 })
1129 .unwrap_or(match backend.as_str() {
1130 "ollama" => 11434,
1131 "lmstudio" => 1234,
1132 _ => 8080,
1133 });
1134 let endpoint = format!("http://127.0.0.1:{port}");
1135 let pull_binary = binary(index);
1136 let pull = pulls.pull_at_observed(&pull_request, &pull_binary, &endpoint, cancel, observer);
1137 let prepared = if backend == "ollama" {
1138 crate::pull::with_ollama_daemon(&acquisition_daemon, &endpoint, cancel, pull).await?
1139 } else {
1140 pull.await?
1141 };
1142 if !prepared.digest_verified {
1143 warning(observer, LifecycleWarning::SizeOnly);
1144 }
1145 let draft_model_path = match drafter {
1146 Some(drafter) => {
1147 let quant = drafter
1148 .quantizations
1149 .first()
1150 .ok_or_else(|| BackendError("drafter has no quantization".into()))?;
1151 let drafted = pulls
1152 .pull_at_observed(
1153 &catalog_pull_request(drafter, quant, &backend)?,
1154 &pull_binary,
1155 &endpoint,
1156 cancel,
1157 observer,
1158 )
1159 .await?;
1160 if !drafted.digest_verified {
1161 return Err(BackendError(
1162 "refusing an unverified speculative drafter".into(),
1163 ));
1164 }
1165 Some(
1166 drafted
1167 .model_path
1168 .ok_or_else(|| BackendError("drafter path unavailable".into()))?,
1169 )
1170 }
1171 None => None,
1172 };
1173 if simple_switch {
1174 let active = lifecycle
1175 .switch_pointer(&model.id, &reviewed, cancel)
1176 .await?;
1177 return Ok((
1178 json!({"type":"switched","modelId":active.model_id,"endpoint":active.endpoint}),
1179 format!("Switched to {} ({}).\n", active.model_id, active.endpoint),
1180 ));
1181 }
1182 let request = ServeRequest {
1183 draft_model_path,
1184 model_id: model.id.clone(),
1185 endpoint,
1186 model_path: prepared.model_path,
1187 context: if backend == "bitnet" {
1188 Some(
1189 options
1190 .context
1191 .unwrap_or(model.context_length.min(4096.0) as u32),
1192 )
1193 } else {
1194 options.context
1195 },
1196 cache: requested,
1197 };
1198 let active = if options.context.is_some() && backend == "ollama" {
1199 let activation = ContextActivation {
1200 source: pull_request.model_id,
1201 context: options.context,
1202 installed: false,
1203 expected_manifest: prepared.local_manifest_digest,
1204 expected_sha: quant.sha256.clone(),
1205 expected_bytes: Some(quant.disk_bytes as u64),
1206 projectors: quant.projectors.clone(),
1207 root: ollama_root,
1208 http: &http,
1209 probe: &probe,
1210 observer,
1211 };
1212 lifecycle
1213 .replace_with(&backend, &request, &reviewed, cancel, &activation)
1214 .await?
1215 } else {
1216 lifecycle
1217 .replace(&backend, &request, &reviewed, cancel)
1218 .await?
1219 };
1220 if active.backend == "ollama"
1224 && model
1225 .capabilities
1226 .iter()
1227 .any(|capability| capability != "embedding")
1228 {
1229 let tag = active
1230 .runtime_model_id
1231 .clone()
1232 .or_else(|| model.source.ollama.clone())
1233 .unwrap_or_else(|| active.model_id.clone());
1234 crate::ollama_inference::preload(&http, &active.endpoint, &tag, cancel)
1235 .await
1236 .map_err(|reason| {
1237 BackendError(format!(
1238 "{} started but Ollama cannot load it: {reason}. Update Ollama, or start it with another runtime.",
1239 strip_control(&model.id)
1240 ))
1241 })?;
1242 }
1243 Ok(up_output(
1244 &active,
1245 if prepared.digest_verified {
1246 "verified"
1247 } else {
1248 "size-only"
1249 },
1250 ))
1251}
1252fn up_output(active: &ServerState, integrity: &str) -> (Value, String) {
1253 let mut report = json!({"modelId":active.model_id,"backend":active.backend,"endpoint":active.endpoint,"ownership":if active.owned_by_us{"owned"}else{"attached"},"integrity":integrity});
1254 let mut text = format!(
1255 "{} ready at {}\n",
1256 strip_control(&active.model_id),
1257 active.endpoint
1258 );
1259 if let Some(runtime) = &active.runtime_model_id {
1260 text.push_str(&format!("Runtime model: {}", strip_control(runtime)));
1261 if let Some(context) = active.context {
1262 text.push_str(&format!(" (context {context})"));
1263 }
1264 text.push('\n');
1265 }
1266 if let Some(cache) = &active.cache {
1267 report["cache"] = json!(cache);
1268 text.push_str(&format!("Cache: {}\n", cache.summary()));
1269 }
1270 (report, text)
1271}
1272
1273pub async fn installed_inventory(
1274 hardware: &Hardware,
1275 model: Option<&str>,
1276 port: u16,
1277 context: Option<u32>,
1278 fits_only: bool,
1279 cancel: &CancellationToken,
1280) -> Result<(Value, String, u8), BackendError> {
1281 if port == 0 || context.is_some_and(|context| !(1..=10000000).contains(&context)) {
1282 return Err(BackendError("invalid installed comparison options".into()));
1283 }
1284 let binary = resolve_binary("ollama")?;
1285 let endpoint = format!("http://127.0.0.1:{port}");
1286 let http = NativeTransport::new().map_err(|error| BackendError(error.to_string()))?;
1287 let probe = NativeProcessProbe;
1288 let before = listener(&probe, &endpoint, cancel).await?;
1289 if binary.to_str() != Some(before.identity.executable.as_str()) {
1290 return Err(BackendError(
1291 "untrusted installed inventory listener".into(),
1292 ));
1293 }
1294 let checked = CheckedHttp {
1295 inner: &http,
1296 probe: &probe,
1297 expected: before.identity.clone(),
1298 };
1299 let root = std::env::var_os("OLLAMA_MODELS")
1300 .map(PathBuf::from)
1301 .unwrap_or_else(|| {
1302 std::env::var_os("HOME")
1303 .or_else(|| std::env::var_os("USERPROFILE"))
1304 .map(PathBuf::from)
1305 .unwrap_or_default()
1306 .join(".ollama/models")
1307 });
1308 let verifier = LocalVerifier { root };
1309 let support = InstalledModels::new(&checked, &verifier);
1310 let models = if let Some(model) = model {
1311 vec![
1312 support
1313 .inspect(&endpoint, model, cancel)
1314 .await
1315 .map_err(|error| BackendError(error.to_string()))?,
1316 ]
1317 } else {
1318 let mut models = Vec::new();
1319 for entry in support
1320 .list(&endpoint, cancel)
1321 .await
1322 .map_err(|error| BackendError(error.to_string()))?
1323 {
1324 models.push(
1325 support
1326 .inspect(&endpoint, &entry.id, cancel)
1327 .await
1328 .map_err(|error| BackendError(error.to_string()))?,
1329 );
1330 }
1331 models
1332 };
1333 let mut results = Vec::new();
1334 let mut lines = Vec::new();
1335 for entry in models {
1336 let sized = crate::ollama_installed::size_installed(&entry, hardware, context)
1337 .map_err(|error| BackendError(error.to_string()))?;
1338 if fits_only && sized["fit"] != "yes" {
1339 continue;
1340 }
1341 lines.push(format!(
1342 "{}: context {}; estimated {} fit {}; weights {:.2} GiB ({}); throughput unknown",
1343 strip_control(&entry.id),
1344 context
1345 .map(|value| value.to_string())
1346 .unwrap_or_else(|| "default".into()),
1347 sized["memoryKind"].as_str().unwrap_or("ram"),
1348 sized["fit"].as_str().unwrap_or("unknown"),
1349 entry.size_bytes as f64 / 1073741824.0,
1350 if sized["weightsFit"] == true {
1351 "fit"
1352 } else {
1353 "over budget"
1354 }
1355 ));
1356 results.push(sized);
1357 }
1358 let after = listener(&probe, &endpoint, cancel).await?;
1359 if !same_process(&before.identity, &after.identity) {
1360 return Err(BackendError("inventory listener changed".into()));
1361 }
1362 let exit =
1363 u8::from(model.is_some() && results.first().is_some_and(|result| result["fit"] == "no"));
1364 Ok((
1365 json!({"source":"local-runtime-metadata","models":results}),
1366 format!(
1367 "{}\n",
1368 if lines.is_empty() {
1369 "No installed models match.".into()
1370 } else {
1371 lines.join("\n")
1372 }
1373 ),
1374 exit,
1375 ))
1376}
1377
1378#[cfg(test)]
1379mod acquisition_contract_tests {
1380 use super::*;
1381
1382 #[test]
1383 fn catalog_pull_preserves_quant_digest_size_and_runtime_model_id() {
1384 let mut catalog = Catalog::parse(rigspark_core::MODELS_JSON).unwrap();
1385 let model = catalog
1386 .models
1387 .iter_mut()
1388 .find(|model| model.source.ollama.is_some())
1389 .unwrap();
1390 model.quantizations[0].sha256 = Some("b".repeat(64));
1391 model.quantizations[0].disk_bytes = 5_000_000_000.0;
1392 let id = model.id.clone();
1393 let quant_query = format!("{id}-{}", model.quantizations[0].name);
1394 for query in [&id, &quant_query] {
1395 let resolved = resolve(&catalog, query).unwrap();
1396 let quant = resolved.quant.unwrap_or(&resolved.model.quantizations[0]);
1397 let request = catalog_pull_request(resolved.model, quant, "ollama").unwrap();
1398 assert_eq!(request.expected_sha256, Some("b".repeat(64)));
1399 assert_eq!(request.expected_bytes, 5_000_000_000);
1400 assert_eq!(Some(request.model_id), resolved.model.source.ollama);
1401 }
1402 let model = &mut catalog.models[0];
1403 model.source.ollama = None;
1404 assert!(catalog_pull_request(model, &model.quantizations[0], "ollama").is_err());
1405 }
1406
1407 #[test]
1408 fn success_lines_strip_controls_and_report_integrity_and_ownership() {
1409 let active = ServerState {
1410 backend: "ollama".into(),
1411 model_id: "evil\u{1b}[31m\nid".into(),
1412 endpoint: "http://127.0.0.1:11434".into(),
1413 port: 11434,
1414 owned_by_us: true,
1415 pid: Some(7),
1416 runtime_model_id: Some("variant\u{7}".into()),
1417 context: Some(65_536),
1418 integrity: None,
1419 local_manifest_digest: None,
1420 model_path: None,
1421 process_executable: None,
1422 process_started_at: None,
1423 auth_token: None,
1424 cache: None,
1425 };
1426 let (report, text) = up_output(&active, "size-only");
1427 assert_eq!(
1428 (report["ownership"].as_str(), report["integrity"].as_str()),
1429 (Some("owned"), Some("size-only"))
1430 );
1431 assert!(
1432 !text
1433 .chars()
1434 .any(|character| character.is_control() && character != '\n'),
1435 "{text:?}"
1436 );
1437 assert_eq!(text.lines().count(), 2, "{text:?}");
1438 assert!(text.ends_with("(context 65536)\n"));
1439 }
1440}