Managed

pub const RuntimePaths = struct

Resolved cache and config directory paths for the current platform.

pub fn deinit(self: *RuntimePaths, allocator: std.mem.Allocator) void

pub const ModelFit = struct

VRAM budget check result for a single catalog model.

pub const ActiveSelection = struct

The currently active managed model as persisted in the config directory.

pub fn deinit(self: *ActiveSelection, allocator: std.mem.Allocator) void

pub const CachedGpuProfile = struct

Cached GPU capability profile used to avoid re-probing the device on every run.

pub fn deinit(self: *CachedGpuProfile, allocator: std.mem.Allocator) void

pub const InstalledManifest = struct

On-disk manifest written alongside an installed GGUF model file.

`sha256` is optional: hand-rolled manifests for symlinked local files (e.g. `download_url:"local"`) frequently omit it because the user can't or won't precompute the digest of an existing GGUF. Treat it as a hint, not a required field — the catalog's `sha256` is the source of truth when a checksum needs to be enforced.

pub fn deinit(self: *InstalledManifest, allocator: std.mem.Allocator) void

pub const RemoveInstalledModelResult = struct

Outcome of a model removal: which artifacts were actually deleted.

pub const DownloadObserver = struct

Callback hooks for observing model download lifecycle events.

pub fn runtimePaths(allocator: std.mem.Allocator) !RuntimePaths

Returns the resolved cache and config root directories for the current platform.

pub fn resolveInstalledModelPath(model_id: []const u8, allocator: std.mem.Allocator) ![]u8

Returns the absolute path to the installed GGUF file for the given model id.

pub fn resolveManifestPath(model_id: []const u8, allocator: std.mem.Allocator) ![]u8

Returns the absolute path to the manifest JSON for the given model id.

pub fn resolveActiveConfigPath(allocator: std.mem.Allocator) ![]u8

Returns the absolute path to the active-model config file.

pub fn resolveGpuProfileCachePath(device_index: u32, allocator: std.mem.Allocator) ![]u8

Returns the absolute path to the cached GPU profile JSON for the given device index.

pub fn isInstalled(model_id: []const u8, allocator: std.mem.Allocator) bool

Returns true if the model GGUF file exists in the local cache.

pub fn readActiveSelection(allocator: std.mem.Allocator) !?ActiveSelection

Reads the persisted active-model selection, or returns null if none is set.

pub fn writeActiveSelection(model_id: []const u8, allocator: std.mem.Allocator) !void

Persists the given model id as the active selection with the current timestamp.

pub fn clearActiveSelection(allocator: std.mem.Allocator) !bool

Removes the active-model config file.

Returns true if a file was deleted.

pub fn clearActiveSelectionIfMatches(model_id: []const u8, allocator: std.mem.Allocator) !bool

Clears the active selection only if it currently points to the given model id.

pub fn readCachedGpuProfile(device_index: u32, allocator: std.mem.Allocator) !?CachedGpuProfile

Reads the cached GPU profile for the given device, or returns null if not cached.

pub fn writeCachedGpuProfile( device_index: u32, profile: []const u8, device_name: []const u8, vram_budget_bytes: u64, allocator: std.mem.Allocator, ) !void

Persists a GPU capability profile to disk for the given device index.

Overwrites any existing cache file for that device.

pub fn describeFit(entry: catalog.CatalogEntry, vram_budget_bytes: u64, allocator: std.mem.Allocator) !ModelFit

Returns a VRAM fit assessment for a catalog model against the given budget.

If the model is installed, the on-disk manifest is consulted first (most accurate); if the manifest lacks VRAM fields, the installed GGUF is inspected directly and the manifest is updated. For models that are not yet installed, catalog static estimates are used and `ModelFit.exact` is false.

pub fn verifyActiveSelectionFits(model_id: []const u8, vram_budget_bytes: u64, allocator: std.mem.Allocator) !ModelFit

Verifies that the named model is installed and fits in the given VRAM budget.

Returns `error.UnknownManagedModel` if `model_id` is not in the catalog, or `error.ModelNotInstalled` if the GGUF file is absent from the local cache.

pub fn removeInstalledModel(model_id: []const u8, allocator: std.mem.Allocator) !RemoveInstalledModelResult

Deletes an installed model's GGUF, manifest, and (if empty) its directory.

pub fn pullModel(entry: catalog.CatalogEntry, allocator: std.mem.Allocator, writer: anytype) !void

Downloads and installs a model from the catalog, verifying its sha256 checksum.

pub fn pullModelWithObserver( entry: catalog.CatalogEntry, allocator: std.mem.Allocator, writer: anytype, observer: ?*const DownloadObserver, ) !void

Downloads and installs a model, reporting progress via an optional observer.

If the model is already installed and its sha256 matches the catalog, the function returns immediately without re-downloading. A `.partial` staging file is used so an interrupted download does not corrupt the cache.

pub fn bytesToGiB(bytes: u64) f64

Converts a byte count to gibibytes (GiB) as a floating-point value.