Skip to content

LLM inference in C/C++

C++ ggml
25.8 KB
Raw Blame
import { PATH_SEPARATOR, SETTINGS_KEYS } from '$lib/constants';
import {
	BYTE,
	BYTE_LABEL,
	DAYS_AGO_LABEL,
	DAYS_PER_MONTH,
	DAYS_PER_WEEK,
	DAYS_PER_YEAR,
	GIGA_LABEL,
	GIGABYTE,
	GIGABYTE_LABEL,
	HF_API_MODELS_URL,
	HF_AVATARS_URL,
	HF_BASE_MODEL_TAG_REGEX,
	HF_BASE_URL,
	HF_CACHE_DIR_SEPARATOR,
	HF_CACHE_PATH_REGEX,
	HF_DECISION_MODEL_TAG,
	HF_DECISION_PIPELINE_TAG,
	HF_DEFAULT_LIMIT,
	HF_FIRST_SHARD,
	HF_FRONTMATTER_REGEX,
	HF_FULL_DETAIL_PARAM,
	HF_GATED_TAG,
	HF_GGUF_FILTER,
	HF_GGUF_TAG,
	HF_HTTP_NOT_FOUND,
	HF_HTTP_SERVER_ERROR_MIN,
	HF_LICENSE_TAG_PREFIX,
	HF_LINK_HEADER,
	HF_LINK_NEXT_REGEX,
	HF_MAIN_BRANCH,
	HF_MAX_LIMIT,
	HF_MODEL_LIST_EXPAND,
	HF_PARAM_COUNT_REGEX,
	HF_QUANT_PRECISION_REGEX,
	HF_RAW_PATH,
	HF_README_FILENAME,
	HF_RECURSIVE_TREE_PARAM,
	HF_RETRY_ATTEMPTS,
	HF_RETRY_DELAY_MS,
	HF_SAFETENSORS_TAG,
	HF_SHARD_PAD_WIDTH,
	HF_SHARD_REGEX,
	HF_SHARED_DRAFT_TOKEN,
	HF_SIZE_STRING_REGEX,
	HF_SIZE_SUFFIX_BYTES,
	HF_TASK_TAGS,
	HF_TREE_MAX_PAGES,
	HF_TREE_PATH,
	HF_UD_QUANT_PREFIX,
	HF_UD_QUANT_PREFIX_REGEX,
	KILO_LABEL,
	KILOBYTE,
	KILOBYTE_LABEL,
	MEGA_LABEL,
	MEGABYTE,
	MEGABYTE_LABEL,
	MODELS_DISCOVER_CATALOG_URL,
	MONTHS_AGO_LABEL,
	MS_PER_DAY,
	TODAY_LABEL,
	WEEKS_AGO_LABEL,
	YEARS_AGO_LABEL,
	YESTERDAY_LABEL
} from '$lib/constants';
import { MODEL_ID, type ModelSidecar } from '$lib/constants';
import { HfEntryType, HfModelSort, SidecarForm } from '$lib/enums';
import { settingsStore } from '$lib/stores/settings/index.svelte';
import type {
	HfCatalogEntry,
	HfModelDetailInfo,
	HfModelInfo,
	HfModelSearchParams,
	HfModelSibling
} from '$lib/types/huggingface';
import { sidecarFromFileToken } from '$lib/utils';
import { SvelteMap } from 'svelte/reactivity';

/** Fetch failure carrying the HTTP status, so retry logic tests the code instead of the message. */
class HfHttpStatusError extends Error {
	status: number;

	constructor(status: number, statusText: string) {
		super(`API request failed: ${status} ${statusText}`);

		this.status = status;
	}
}

export class HuggingFaceService {
	private static readonly BASE_URL = HF_API_MODELS_URL;

	// Cached base model lookups keyed by repo id, so repeated selector opens
	// never re-hit the HF API for the same repo.
	private static baseModelCache = new Map<string, { org: string; name: string } | null>();

	private static baseModelPending = new Map<
		string,
		Promise<{ org: string; name: string } | null>
	>();

	// Model details fetched this session, keyed by repo id: the Hub rate limits
	// aggressively, so each repo costs at most one request per load. Failures stay
	// uncached so the next mount can retry.
	private static detailsCache = new SvelteMap<string, HfModelDetailInfo | null>();

	private static detailsPending = new Map<string, Promise<HfModelDetailInfo | null>>();

	/**
	 * Map of quant token to its average bit-depth in bits-per-weight (bpw).
	 */
	private static readonly QUANT_BIT_DEPTH: Record<string, number> = {
		BF16: 16,
		F16: 16,
		IQ1_M: 1,
		IQ1_S: 1,
		IQ1_XS: 1,
		IQ1_XXS: 1,
		IQ2_M: 2,
		IQ2_S: 2,
		IQ2_XS: 2,
		IQ2_XXS: 2,
		IQ3_M: 3,
		IQ3_S: 3,
		IQ3_XS: 3,
		IQ3_XXS: 3,
		Q2_K: 2,
		Q2_K_M: 2,
		Q2_K_S: 2,
		Q3_K: 3,
		Q3_K_L: 3,
		Q3_K_M: 3,
		Q3_K_S: 3,
		Q4_0: 4,
		Q4_1: 4,
		Q4_K: 4,
		Q4_K_M: 4,
		Q4_K_S: 4,
		Q5_0: 5,
		Q5_1: 5,
		Q5_K: 5,
		Q5_K_M: 5,
		Q5_K_S: 5,
		Q6_K: 6,
		Q8_0: 8
	};

	// File trees already fetched, keyed by repo id: the discover view asks for the same
	// repo from several places.
	private static treeCache = new Map<string, HfModelSibling[]>();

	private static treePending = new Map<string, Promise<HfModelSibling[]>>();

	/** Details already fetched, for a caller that cannot await (a table sorting its rows). */
	static cachedDetails(modelId: string): HfModelDetailInfo | null | undefined {
		// llama.cpp model ids carry the quant tag after a colon
		const [hfRepoId] = modelId.split(MODEL_ID.QUANTIZATION_SEPARATOR);

		return HuggingFaceService.detailsCache.get(hfRepoId);
	}

	// GGUF Model Browsing

	/**
	 * Collapse split GGUF shard sets (`-00001-of-00015.gguf`, ...) to their first
	 * shard, summing every shard's size so the kept entry reflects the whole
	 * quant. Downloads are tag-based (`repo:quant`), so the first shard is
	 * enough to represent the set.
	 */
	static collapseGgufShards(siblings: HfModelSibling[]): HfModelSibling[] {
		const sizeByPath = new Map(siblings.map((f) => [f.path, f.size ?? 0]));
		const result: HfModelSibling[] = [];

		for (const file of siblings) {
			const match = HF_SHARD_REGEX.exec(file.path);

			if (!match) {
				result.push(file);

				continue;
			}

			if (Number(match[1]) !== HF_FIRST_SHARD) continue;

			const total = Number(match[2]);
			const stem = file.path.slice(0, file.path.length - match[0].length);

			let size = 0;

			for (let i = HF_FIRST_SHARD; i <= total; i++) {
				const shard = HuggingFaceService.shardPath(stem, i, total);

				size += sizeByPath.get(shard) ?? 0;
			}

			result.push({ ...file, size });
		}

		return result;
	}

	/**
	 * Extract the GGUF quantization token (e.g. `Q4_K_M`) and any sidecar type
	 * (`mtp`, `dflash`, `mmproj`, ...) from a `.gguf` filename.
	 *
	 * `sidecarForm` records which side of the filename the sidecar token sat on
	 * so callers can render badges differently. `quant` and `sidecar` are `null`
	 * when absent; returns `null` for non-GGUF filenames.
	 */
	static extractQuantMeta(filename: string): {
		quant: string | null;
		/** Draft-head-only variant borrowing embed/output weights from the target model. */
		shared: boolean;
		sidecar: ModelSidecar | null;
		sidecarForm: SidecarForm | null;
	} | null {
		if (!MODEL_ID.WEIGHT_EXTENSION_REGEX.test(filename)) return null;

		// HF repos may nest sidecars in a folder (e.g. `MTP/mtp-Model-Q4_0.gguf`);
		// parse the file name only, the folder adds no quant information.
		let source = (filename.split(PATH_SEPARATOR).pop() ?? filename).replace(
			MODEL_ID.WEIGHT_EXTENSION_REGEX,
			''
		);
		let sidecar: ModelSidecar | null = null;
		let sidecarForm: SidecarForm | null = null;

		// A file named just the sidecar token (`imatrix.gguf`) is the sidecar
		// itself: no name or quant segments to parse.
		const bareSidecar = sidecarFromFileToken(source.toLowerCase());

		if (bareSidecar) {
			return { quant: null, shared: false, sidecar: bareSidecar, sidecarForm: SidecarForm.PREFIX };
		}

		const prefixMatch = source.match(MODEL_ID.SIDECAR_PREFIX_REGEX);

		if (prefixMatch) {
			sidecar = sidecarFromFileToken(prefixMatch[1].toLowerCase());
			sidecarForm = SidecarForm.PREFIX;
			source = prefixMatch[2];
		} else {
			const suffixMatch = source.match(MODEL_ID.SIDECAR_SUFFIX_REGEX);

			if (suffixMatch) {
				// Take the suffix sidecar even when the head carries no quant:
				// embedded drafts end in one (`Hy3-IQ1_M-mtp`), standalone sidecar
				// files do not (`Model-mtp-draft`, `Model-imatrix`).
				sidecar = sidecarFromFileToken(suffixMatch[2].toLowerCase());
				sidecarForm = SidecarForm.SUFFIX;
				source = suffixMatch[1];
			} else {
				const infixMatch = source.match(MODEL_ID.SIDECAR_INFIX_REGEX);

				if (infixMatch) {
					sidecar = sidecarFromFileToken(infixMatch[2].toLowerCase());
					sidecarForm = SidecarForm.INFIX;
					source = `${infixMatch[1]}-${infixMatch[3]}`;
				}
			}
		}

		// Scan dash-separated segments left-to-right for the first quant match.
		// - For sidecars like `mtp-Q4_0-180MB.gguf` the quant is `Q4_0`.
		// - For embedded MTP like `Hy3-IQ1_M-mtp.gguf` we have `Hy3-IQ1_M` and `IQ1_M` matches.
		// - For main files like `Llama-3-8B-Q4_K_M.gguf` we land on the trailing quant.
		const segments = source.split(MODEL_ID.SEGMENT_SEPARATOR);
		const quantIdx = segments.findIndex((seg) => MODEL_ID.QUANTIZATION_SEGMENT_REGEX.test(seg));
		// Unsloth ships draft heads in two layouts: `shared-` files borrow the
		// embedding/output weights from the target model, others are self-contained.
		const shared = segments.some((seg) => seg.toLowerCase() === HF_SHARED_DRAFT_TOKEN);

		let quant = quantIdx >= 0 ? segments[quantIdx].toUpperCase() : null;

		// Recombine a `UD-` (Unsloth Dynamic) prefix, e.g. `...-UD-Q4_K_XL.gguf`.
		// The prefix must be the whole previous segment, matching the server's
		// `UD-<quant>` custom-quant convention (e.g. not `-mtp-Q4_K_M`).
		const udPrefixIdx = quantIdx - 1;

		if (quant && quantIdx > 0 && segments[udPrefixIdx].toUpperCase() === HF_UD_QUANT_PREFIX) {
			quant = `${HF_UD_QUANT_PREFIX}-${quant}`;
		}

		return { quant, shared, sidecar, sidecarForm };
	}

	static filterByExtension(siblings: HfModelSibling[], ext: string): HfModelSibling[] {
		return siblings
			.filter((f) => f.path.toLowerCase().endsWith(ext.toLowerCase()) && (f.size ?? 0) > 0)
			.sort((a, b) => (b.size ?? 0) - (a.size ?? 0));
	}

	static formatDownloads(downloads: number): string {
		if (downloads >= GIGABYTE) {
			return `${(downloads / GIGABYTE).toFixed(1)}${GIGA_LABEL}`;
		}

		if (downloads >= MEGABYTE) {
			return `${(downloads / MEGABYTE).toFixed(1)}${MEGA_LABEL}`;
		}

		if (downloads >= KILOBYTE) {
			return `${(downloads / KILOBYTE).toFixed(1)}${KILO_LABEL}`;
		}

		return downloads.toString();
	}

	static formatFileSize(bytes: number): string {
		if (bytes >= GIGABYTE) {
			return `${(bytes / GIGABYTE).toFixed(1)} ${GIGABYTE_LABEL}`;
		}

		if (bytes >= MEGABYTE) {
			return `${(bytes / MEGABYTE).toFixed(1)} ${MEGABYTE_LABEL}`;
		}

		if (bytes >= KILOBYTE) {
			return `${(bytes / KILOBYTE).toFixed(1)} ${KILOBYTE_LABEL}`;
		}

		return `${bytes} ${BYTE_LABEL}`;
	}

	static formatLikes(likes: number): string {
		if (likes >= KILOBYTE) {
			return `${(likes / KILOBYTE).toFixed(1)}${KILO_LABEL}`;
		}

		return likes.toString();
	}

	static formatRelativeTime(timestamp: string): string {
		const date = new Date(timestamp);
		const now = new Date();
		const diffMs = now.getTime() - date.getTime();
		// timestamps can lie in the future (clock skew); clamp so they read as today
		const diffDays = Math.max(0, Math.floor(diffMs / MS_PER_DAY));

		if (diffDays === 0) return TODAY_LABEL;

		if (diffDays === 1) return YESTERDAY_LABEL;

		if (diffDays < DAYS_PER_WEEK) return `${diffDays} ${DAYS_AGO_LABEL}`;

		if (diffDays < DAYS_PER_MONTH) {
			return `${Math.floor(diffDays / DAYS_PER_WEEK)} ${WEEKS_AGO_LABEL}`;
		}

		if (diffDays < DAYS_PER_YEAR) {
			return `${Math.floor(diffDays / DAYS_PER_MONTH)} ${MONTHS_AGO_LABEL}`;
		}

		return `${Math.floor(diffDays / DAYS_PER_YEAR)} ${YEARS_AGO_LABEL}`;
	}

	// Model Details & Files

	/**
	 * Format a min-max size range with one shared unit, e.g. `19.0-28.6 GB`.
	 */
	static formatSizeRange(min: number, max: number): string {
		const unit =
			max >= GIGABYTE
				? GIGABYTE_LABEL
				: max >= MEGABYTE
					? MEGABYTE_LABEL
					: max >= KILOBYTE
						? KILOBYTE_LABEL
						: BYTE_LABEL;
		const div =
			unit === GIGABYTE_LABEL
				? GIGABYTE
				: unit === MEGABYTE_LABEL
					? MEGABYTE
					: unit === KILOBYTE_LABEL
						? KILOBYTE
						: BYTE;
		const fmt = (n: number) => (div === BYTE ? `${n}` : `${(n / div).toFixed(1)}`);

		return `${fmt(min)}-${fmt(max)} ${unit}`;
	}

	/**
	 * Avatar URL for an author (org or user). 404s when the author does not
	 * exist, so callers should provide a fallback.
	 */
	static getAvatarUrl(author: string): string {
		// OpenRouter-style model ids prefix the provider with a tilde
		// (`~openai/gpt-...`); the avatars endpoint only resolves bare names
		return `${HF_AVATARS_URL}${PATH_SEPARATOR}${author.replace(/^~/, '')}`;
	}

	/**
	 * Resolve the original (non-GGUF) base model `{ org, name }` for a GGUF repo
	 * from its HF card (`cardData.base_model`). Returns null when the card has no
	 * base model. A resolved repo is cached for the session.
	 */
	static getBaseModel(repoId: string): Promise<{ org: string; name: string } | null> {
		if (!HuggingFaceService.isEnabled()) return Promise.resolve(null);

		// all quants of one repo share the cached lookup, so key it by the repo id
		const [hfRepoId] = repoId.split(MODEL_ID.QUANTIZATION_SEPARATOR);
		const cached = this.baseModelCache.get(hfRepoId);

		if (cached !== undefined) return Promise.resolve(cached);

		const pending = this.baseModelPending.get(hfRepoId);

		if (pending) return pending;

		const promise = (async () => {
			const details = await this.getDetails(hfRepoId);
			const base = this.getBaseModels(details)[0];

			if (!base) return null;

			const [org, ...rest] = base.split(PATH_SEPARATOR);

			return { name: rest.join(PATH_SEPARATOR), org };
		})();

		this.baseModelPending.set(hfRepoId, promise);

		promise
			// a repo with no base model stays uncached: the details behind it are cached
			// already, so a retry costs nothing and a failed lookup can try again
			.then((result) => {
				if (result) this.baseModelCache.set(hfRepoId, result);
			})
			.finally(() => this.baseModelPending.delete(hfRepoId));

		return promise;
	}

	/**
	 * Extract the original (non-GGUF) base model ids for a repo, from
	 * `cardData.base_model` (string or list) and the `base_model:` tags.
	 */
	static getBaseModels(model: HfModelDetailInfo | null): string[] {
		if (!model) return [];

		const cardBase = model.cardData?.base_model;
		const fromCard: string[] = Array.isArray(cardBase) ? cardBase : cardBase ? [cardBase] : [];
		const fromTags = (model.tags ?? [])
			.map((t) => HF_BASE_MODEL_TAG_REGEX.exec(t)?.[1])
			.filter((v): v is string => Boolean(v));

		return Array.from(new Set([...fromCard, ...fromTags]));
	}

	/**
	 * Look up the average bit-depth for a known GGUF quantization.
	 * Returns `null` for unrecognized tokens.
	 */
	static getBitDepth(quant: string): number | null {
		const base = quant.replace(HF_UD_QUANT_PREFIX_REGEX, '');
		const direct = HuggingFaceService.QUANT_BIT_DEPTH[base];

		if (direct !== undefined) return direct;

		// Fall back to the leading precision digits for variants missing from the
		// map, e.g. `Q4_K_XL` -> 4, `IQ2_XXS` -> 2, `TQ1_0` -> 1, `BF16` -> 16.
		const match = HF_QUANT_PRECISION_REGEX.exec(base);

		return match ? parseInt(match[1], 10) : null;
	}

	static async getByTask(
		pipelineTag: string,
		params: Omit<HfModelSearchParams, 'pipeline_tag'> = {}
	): Promise<HfModelInfo[]> {
		return this.search({
			...params,
			pipeline_tag: pipelineTag
		});
	}

	static async getCatalog(): Promise<HfCatalogEntry[]> {
		if (!HuggingFaceService.isEnabled()) return [];

		const response = await fetch(MODELS_DISCOVER_CATALOG_URL);

		if (!response.ok) throw new Error(`Failed to fetch catalog: ${response.status}`);

		const entries = (await response.json()) as HfCatalogEntry[];

		return entries.filter((entry) => !entry.decision);
	}

	static getDetails(modelId: string): Promise<HfModelDetailInfo | null> {
		if (!HuggingFaceService.isEnabled()) return Promise.resolve(null);

		const cached = HuggingFaceService.detailsCache.get(modelId);

		if (cached !== undefined) return Promise.resolve(cached);

		const pending = HuggingFaceService.detailsPending.get(modelId);

		if (pending) return pending;

		const promise = (async () => {
			// Do not encode the modelId, it contains slashes for author/name.
			// `full=true` includes cardData (description, base_model) and safetensors.
			const url = `${HF_API_MODELS_URL}${PATH_SEPARATOR}${modelId}?${HF_FULL_DETAIL_PARAM}`;

			try {
				const response = await fetch(url);

				// a missing model is a definitive answer, cache it
				if (response.status === HF_HTTP_NOT_FOUND) {
					HuggingFaceService.detailsCache.set(modelId, null);

					return null;
				}

				if (!response.ok) throw new Error(`Failed to fetch model details: ${response.status}`);

				// the hub answers with a list of provider entries for one repo; the gguf and
				// card data sit on the entry that carries them
				const payload = (await response.json()) as HfModelDetailInfo | HfModelDetailInfo[];
				const entries = Array.isArray(payload) ? payload : [payload];
				const data = entries.find((entry) => entry?.gguf ?? entry?.cardData) ?? entries[0];

				if (!data) return null;

				HuggingFaceService.detailsCache.set(modelId, data);

				return data;
			} catch (error) {
				// not cached: a rate limited or failed fetch retries on the next mount
				// instead of hiding the model for the session
				console.error(`Error fetching details for ${modelId}:`, error);

				return null;
			} finally {
				HuggingFaceService.detailsPending.delete(modelId);
			}
		})();

		HuggingFaceService.detailsPending.set(modelId, promise);

		return promise;
	}

	static getModelUrl(modelId: string): string {
		return `${HF_BASE_URL}${PATH_SEPARATOR}${modelId}`;
	}

	// Utility Methods

	static async getMostLiked(limit: number = HF_DEFAULT_LIMIT): Promise<HfModelInfo[]> {
		return this.search({ limit, sort: HfModelSort.LIKES });
	}

	static async getNew(limit: number = HF_DEFAULT_LIMIT): Promise<HfModelInfo[]> {
		return this.search({ limit, sort: HfModelSort.CREATED_AT });
	}

	static async getPopular(limit: number = HF_DEFAULT_LIMIT): Promise<HfModelInfo[]> {
		return this.search({ limit, sort: HfModelSort.DOWNLOADS });
	}

	/**
	 * Fetch the raw README.md for a repo, with the YAML frontmatter stripped.
	 */
	static async getReadme(modelId: string): Promise<string | null> {
		if (!HuggingFaceService.isEnabled()) return null;

		// Do not encode the modelId, it contains slashes for author/name
		const url = `${HF_BASE_URL}${PATH_SEPARATOR}${modelId}${PATH_SEPARATOR}${HF_RAW_PATH}${PATH_SEPARATOR}${HF_MAIN_BRANCH}${PATH_SEPARATOR}${HF_README_FILENAME}`;

		try {
			const response = await fetch(url);

			if (response.status === HF_HTTP_NOT_FOUND) return null;

			if (!response.ok) throw new Error(`Failed to fetch README: ${response.status}`);

			return HuggingFaceService.stripFrontmatter(await response.text());
		} catch (error) {
			console.error(`Error fetching README for ${modelId}:`, error);

			return null;
		}
	}

	static getTree(modelId: string): Promise<HfModelSibling[]> {
		if (!HuggingFaceService.isEnabled()) return Promise.resolve([]);

		const cached = HuggingFaceService.treeCache.get(modelId);

		if (cached) return Promise.resolve(cached);

		const pending = HuggingFaceService.treePending.get(modelId);

		if (pending) return pending;

		const promise = (async () => {
			const files: HfModelSibling[] = [];
			const firstUrl =
				`${HF_API_MODELS_URL}${PATH_SEPARATOR}${modelId}${PATH_SEPARATOR}${HF_TREE_PATH}` +
				`${PATH_SEPARATOR}${HF_MAIN_BRANCH}?${HF_RECURSIVE_TREE_PARAM}`;

			let url: string | null = firstUrl;

			for (let page = 0; url && page < HF_TREE_MAX_PAGES; page++) {
				const response: Response = await fetch(url);

				if (!response.ok)
					throw new Error(`Failed to fetch tree for ${modelId}: ${response.status}`);

				const data = (await response.json()) as HfModelSibling[];

				files.push(...data.filter((f) => f.type !== HfEntryType.DIRECTORY));

				url = HuggingFaceService.parseNextPageUrl(response.headers.get(HF_LINK_HEADER));
			}

			HuggingFaceService.treeCache.set(modelId, files);

			return files;
		})()
			.catch((error: unknown) => {
				// not cached: a rate limited or failed fetch should retry on the
				// next mount; an empty tree makes the store fall back to the
				// catalog's advertised sizes
				console.error(`Error fetching tree for ${modelId}:`, error);

				return [] as HfModelSibling[];
			})
			.finally(() => HuggingFaceService.treePending.delete(modelId));

		HuggingFaceService.treePending.set(modelId, promise);

		return promise;
	}

	static async getTrending(limit: number = HF_DEFAULT_LIMIT): Promise<HfModelInfo[]> {
		return this.search({ limit, sort: HfModelSort.TRENDING_SCORE });
	}

	/**
	 * True for decision models: they answer with calibrated probabilities instead
	 * of generated text, so llama-ui cannot use them and they stay out of every
	 * list the Hub data layer returns.
	 */
	static isDecisionModel(model: Pick<HfModelInfo, 'pipeline_tag' | 'tags'>): boolean {
		return (
			model.tags.includes(HF_DECISION_MODEL_TAG) || model.pipeline_tag === HF_DECISION_PIPELINE_TAG
		);
	}

	/**
	 * True when the UI may read from the Hugging Face Hub API: model display data
	 * (avatars, context length, chat template) and the Discover Models view. With
	 * it off, callers only see what the server's /v1/models reports and the org
	 * avatars stay hidden.
	 */
	static isEnabled(): boolean {
		return settingsStore.config[SETTINGS_KEYS.USE_HUGGING_FACE_HUB] ?? false;
	}

	/**
	 * Parameter count a repo reports: a GGUF repo spells it out in its metadata,
	 * a transformers repo reports it in its SafeTensors index.
	 */
	static parameterCount(details?: HfModelDetailInfo | null): number | null {
		return details?.gguf?.total ?? details?.safetensors?.total ?? null;
	}

	/**
	 * Parse a local HF cache file path
	 * (`.../models--<org>--<name>/snapshots/<sha>/<file>`) into its repo id and
	 * repo-relative file path. Returns null when the path is not an HF cache path.
	 */
	static parseCachePath(path: string): { repo: string; file: string } | null {
		// the paths come from the server's CLI args, which use native separators
		const match = HF_CACHE_PATH_REGEX.exec(path.replace(/\\/g, PATH_SEPARATOR));

		if (!match) return null;

		const parts = match[1].split(HF_CACHE_DIR_SEPARATOR);

		if (parts.length < 2) return null;

		return {
			file: match[2],
			repo: `${parts[0]}${PATH_SEPARATOR}${parts.slice(1).join(HF_CACHE_DIR_SEPARATOR)}`
		};
	}

	/**
	 * Best-effort parameter count parsed from a model id/name, e.g. `27B` from
	 * `Qwen3.8-27B-GGUF` or `300M` from `embeddinggemma-300M-GGUF`. Returns null
	 * when no size token is present.
	 */
	static parseParamCount(name: string): string | null {
		const match = HF_PARAM_COUNT_REGEX.exec(name);

		if (!match) return null;

		return `${match[1]}${match[2].toUpperCase()}`;
	}

	/**
	 * Parse a human size string (`177GB`, `1.2 TB`, `500MB`) to bytes. Returns
	 * null when it carries no number or no known suffix, so callers can fall
	 * back to another source instead of showing a wrong size.
	 */
	static parseSizeBytes(size: string): number | null {
		const match = HF_SIZE_STRING_REGEX.exec(size);

		if (!match) return null;

		const value = parseFloat(match[1]);
		const multiplier = HF_SIZE_SUFFIX_BYTES[match[2].toLowerCase()];

		if (!Number.isFinite(value) || multiplier === undefined) return null;

		return value * multiplier;
	}

	static parseTags(tags: string[]): {
		license: string | null;
		isGated: boolean;
		isGguf: boolean;
		isSafetensors: boolean;
		tasks: string[];
	} {
		const license =
			tags
				.find((tag) => tag.startsWith(HF_LICENSE_TAG_PREFIX))
				?.replace(HF_LICENSE_TAG_PREFIX, '') || null;
		const isGated = tags.includes(HF_GATED_TAG);
		const isGguf = tags.includes(HF_GGUF_TAG);
		const isSafetensors = tags.includes(HF_SAFETENSORS_TAG);
		const tasks = tags.filter((tag) => HF_TASK_TAGS.includes(tag));

		return { isGated, isGguf, isSafetensors, license, tasks };
	}

	/**
	 * Search GGUF models with various filters and options.
	 *
	 * Always expands the fields the discover rows render (chat template, context
	 * length, siblings, ...) so a search result carries the same badges as a
	 * catalog entry; caller-provided `expand` entries are merged in.
	 */
	static async search(params: HfModelSearchParams = {}): Promise<HfModelInfo[]> {
		if (!HuggingFaceService.isEnabled()) return [];

		const { expand, limit = HF_DEFAULT_LIMIT, ...restParams } = params;
		const url = this.buildUrl({
			...restParams,
			expand: [...new Set([...HF_MODEL_LIST_EXPAND, ...(expand ?? [])])],
			filter: HF_GGUF_FILTER,
			limit: Math.min(limit, HF_MAX_LIMIT)
		});
		const models = await this.fetchWithRetry(url);

		return models.filter((model) => !HuggingFaceService.isDecisionModel(model));
	}

	static async searchByQuery(
		query: string,
		params: Omit<HfModelSearchParams, 'search'> = {}
	): Promise<HfModelInfo[]> {
		return this.search({
			...params,
			search: query
		});
	}

	private static buildUrl(params: HfModelSearchParams): string {
		const url = new URL(this.BASE_URL);

		Object.entries(params).forEach(([key, value]) => {
			if (value !== undefined && value !== null && value !== '') {
				if (Array.isArray(value)) {
					value.forEach((v) => url.searchParams.append(key, v));
				} else {
					url.searchParams.set(key, String(value));
				}
			}
		});

		return url.toString();
	}

	private static delay(ms: number): Promise<void> {
		return new Promise((resolve) => setTimeout(resolve, ms));
	}

	private static async fetchWithRetry(url: string, attempt: number = 1): Promise<HfModelInfo[]> {
		try {
			const response = await fetch(url);

			if (!response.ok) {
				if (response.status === HF_HTTP_NOT_FOUND) {
					return [];
				}

				if (response.status >= HF_HTTP_SERVER_ERROR_MIN && attempt < HF_RETRY_ATTEMPTS) {
					await this.delay(HF_RETRY_DELAY_MS * attempt);

					return this.fetchWithRetry(url, attempt + 1);
				}

				throw new HfHttpStatusError(response.status, response.statusText);
			}

			const data = await response.json();

			if (Array.isArray(data)) {
				return data as HfModelInfo[];
			}

			if (data && Array.isArray(data.data)) {
				return data.data as HfModelInfo[];
			}

			throw new Error('Unexpected API response format');
		} catch (error) {
			const transient =
				error instanceof TypeError ||
				(error instanceof HfHttpStatusError && error.status >= HF_HTTP_SERVER_ERROR_MIN);

			if (transient && attempt < HF_RETRY_ATTEMPTS) {
				await this.delay(HF_RETRY_DELAY_MS * attempt);

				return this.fetchWithRetry(url, attempt + 1);
			}

			throw error;
		}
	}

	// Internal Methods

	/** Extract the `rel="next"` URL from an RFC 5988 `Link` header, if present. */
	private static parseNextPageUrl(linkHeader: string | null): string | null {
		if (!linkHeader) return null;

		const match = HF_LINK_NEXT_REGEX.exec(linkHeader);

		return match ? match[1] : null;
	}

	/** Full path of one shard in a split-shard GGUF set. */
	private static shardPath(stem: string, index: number, total: number): string {
		const pad = (n: number) => String(n).padStart(HF_SHARD_PAD_WIDTH, '0');

		return `${stem}-${pad(index)}-of-${pad(total)}.gguf`;
	}

	/** Strip a leading YAML frontmatter block (--- ... ---) from a markdown document. */
	private static stripFrontmatter(text: string): string {
		const match = text.match(HF_FRONTMATTER_REGEX);

		return match ? text.slice(match[0].length) : text;
	}
}