Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { useState, useEffect, useRef, useCallback, useMemo } from 'react';
import { useNavigate } from 'react-router';
import { Download, RefreshCw, Search, Plus, ExternalLink, Star, Play, AlertTriangle } from 'lucide-react';
import toast from '../ui/Toast';
import FormField from '../ui/FormField';
import BrailleSpinner from '../BrailleSpinner';
import { formatAgeDays, formatContextLength, formatCount, timeAgo, recommendedRamGb, formatDateNumeric } from '../../utils/formatters';
import { localLlmTargetKey } from '../../lib/localLlmTargetKey';
import { useConfirmDelete } from '../../hooks/useConfirmDelete';
import useDownloadPreflightConfirm from '../../hooks/useDownloadPreflightConfirm';
import useLocalLlmStatus from '../../hooks/useLocalLlmStatus';
import { getLocalLlmCatalog, getLocalLlmHuggingFaceSearch, installLocalLlmModel, deleteLocalLlmModel, upgradeLocalLlmBackend, controlOllamaService, installAudioModel, previewLocalLlmDownload } from '../../services/api';
import CapabilityBadges from '../models/CapabilityBadges.jsx';
import LocalLlmInstalledModels from './LocalLlmInstalledModels.jsx';
import DownloadPreflightConfirm from '../models/DownloadPreflightConfirm.jsx';
import { LOCAL_LLM_BACKENDS as BACKENDS, localLlmBackendLabel as labelFor } from '../../lib/localLlmBackends.js';
const btnClass = 'flex items-center gap-1.5 px-2 py-1 text-xs font-medium rounded transition-colors disabled:opacity-50';
const CATEGORY_LABELS = {
general: 'General purpose',
coding: 'Coding & agents',
security: 'Security specialists',
'security-uncensored': 'Security · Uncensored / abliterated',
reasoning: 'Reasoning & analysis',
vision: 'Image Analysis',
chat: 'Chat & voice',
writing: 'Fiction & writing',
audio: 'Audio & Music',
embedding: 'Text Embeddings',
lightweight: 'Small & Fast',
multilingual: 'Multilingual'
};
const CATEGORY_ORDER = ['general', 'coding', 'security', 'security-uncensored', 'writing', 'reasoning', 'vision', 'chat', 'lightweight', 'multilingual', 'embedding', 'audio'];
const categoryLabel = (id) => CATEGORY_LABELS[id] || id;
const primaryCategoryFor = (model) => model?.category || 'general';
const recommendationCategoriesFor = (model) => {
const categories = model?.recommendedFor;
return Array.isArray(categories) && categories.length ? categories : [primaryCategoryFor(model)];
};
const isRecommendedForCategory = (model, category) => recommendationCategoriesFor(model).includes(category);
// A model suited to AGENT / CoS tasks (coding agents, the Creative Director
// treatment/plan agents) needs BOTH native tool calling AND enough coding /
// instruction-following muscle to drive a multi-step loop. A chat-only
// tool-caller (e.g. a small function-calling voice brain) clears `tools` but
// isn't an agent workhorse, and a `code` model without `tools` narrates instead
// of acting — so we require both. Keyed off catalog capabilities (server truth),
// NOT a hard-coded model list, so new agentic models light up automatically.
const isAgentRecommendedModel = (capabilities) =>
Array.isArray(capabilities)
&& capabilities.includes('tools')
&& capabilities.includes('code');
// Server-computed per-quant fit verdict → badge styling + short label. Drives
// the RAM-fit hint on the quant picker so a too-large build reads as a warning.
const FIT_META = {
comfortable: { label: 'fits comfortably', cls: 'text-port-success' },
tight: { label: 'tight fit', cls: 'text-port-warning' },
'too-large': { label: 'exceeds RAM', cls: 'text-port-error' },
// Only ever produced by a MEASUREMENT — the size estimate cannot know that a
// backend refuses a model outright, and no amount of free RAM changes it.
incompatible: { label: 'backend refused it', cls: 'text-port-error' },
};
// The fit badge is a size ESTIMATE (weights + ~20% overhead vs. usable memory)
// until the model has actually been run here, at which point the measurement
// replaces it. The tooltip has to say which one the reader is looking at —
// "fits comfortably" from arithmetic and "fits comfortably" from a real run are
// very different claims — and it names the disagreement when there is one,
// because that is the most useful thing the measurement can say.
function fitTitle(source, entry) {
if (source !== 'measured') {
const stale = entry?.measuredFit && entry?.stale
? ` A previous measurement (${FIT_META[entry.measuredFit]?.label || entry.measuredFit}) was taken on a different machine state, so the estimate stands.`
: '';
return `Estimated fit on this machine — model weights + ~20% overhead vs. usable memory.${stale}`;
}
const measuredAt = entry?.assessedAt ? ` on ${formatDateNumeric(entry.assessedAt)}` : '';
const disagree = entry?.disagrees
? ` The size estimate said "${FIT_META[entry.estimatedFit]?.label || entry.estimatedFit}".`
: '';
return `Measured on this machine${measuredAt} — PortOS ran this model rather than estimating from its file size.${disagree}`;
}
// Model format badge — GGUF (llama.cpp, cross-backend) vs. MLX (Apple's native
// format, LM Studio on Apple Silicon only). Shown so the user knows what they're
// installing when both formats appear in the same result list.
const FORMAT_META = {
gguf: { label: 'GGUF', title: 'GGUF — llama.cpp format, runs on Ollama and LM Studio', cls: 'border-port-border text-gray-400' },
mlx: { label: 'MLX', title: "MLX — Apple's native format, installs via LM Studio on Apple Silicon", cls: 'border-port-accent/40 text-port-accent' },
};
// Find, install, compare and remove the model weights available to Ollama and
// LM Studio. Mounted only while the Model Library pill is selected, so the
// catalog is never queried for a reader who is looking at the runtimes.
export default function LocalLlmLibraryView() {
const navigate = useNavigate();
const [catalogSource, setCatalogSource] = useState('recommended');
const [catalog, setCatalog] = useState([]);
const [catalogLoading, setCatalogLoading] = useState(false);
const [catalogError, setCatalogError] = useState('');
// Total unified/system memory (GB) reported by the HF search, used to caption
// the RAM-aware quant defaults. null until the first Hugging Face search.
const [systemMemoryGb, setSystemMemoryGb] = useState(null);
// Per-result quant override: { [repoKey]: installId }. Empty → use each
// result's RAM-aware default (`m.id`). Cleared whenever the catalog reloads.
const [selectedVariants, setSelectedVariants] = useState({});
const [activeCategory, setActiveCategory] = useState('all');
const [query, setQuery] = useState('');
const [manualId, setManualId] = useState('');
// id of the installed model awaiting a delete confirmation (two-step inline
// confirm — deleting weights is an irreversible multi-GB rm -rf / DELETE).
const { isConfirming: isConfirmingDelete, requestDelete, cancelDelete, confirmDelete } = useConfirmDelete();
const [compareTargets, setCompareTargets] = useState([]);
const catalogRequestId = useRef(0);
const { confirm: downloadConfirm, request: requestWeightDownload, cancel: cancelDownloadConfirm, confirmRun: runDownloadConfirm } = useDownloadPreflightConfirm();
// The catalog reload the shared hook fires after an action (or a `complete`
// progress frame) depends on state this hook returns, so it is reached
// through a ref rather than a closure — that also keeps `runAction` stable
// across every keystroke in the search box.
const reloadCatalogRef = useRef(null);
const reloadCatalog = useCallback(() => reloadCatalogRef.current?.(), []);
const {
status, selected, setSelected, runAction, installBackend: installRuntimeBackend,
actionInProgress, busy, progressMsg, setProgressMsg,
} = useLocalLlmStatus({ onReload: reloadCatalog });
// `source` and `category` are required rather than defaulted from state: a
// state default would put them in the dep list, so `loadCatalog`'s identity
// would change on every category click and re-trigger the debounce effect —
// the exact refetch the effect below is written to avoid. Every call site
// passes both.
const loadCatalog = useCallback((backend, q, source, category) => {
const requestId = ++catalogRequestId.current;
setCatalogLoading(true);
setCatalogError('');
const request = source === 'huggingface'
? getLocalLlmHuggingFaceSearch(backend, q, category, 18)
: getLocalLlmCatalog(backend, q, { variants: true });
return request
.then((r) => {
if (requestId !== catalogRequestId.current) return;
setCatalog(r.models || []);
if (Number.isFinite(r.systemMemoryGb)) setSystemMemoryGb(r.systemMemoryGb);
// A fresh result set invalidates any per-card quant overrides.
setSelectedVariants({});
})
.catch((err) => {
if (requestId !== catalogRequestId.current) return;
setCatalog([]);
setCatalogError(source === 'huggingface' ? (err?.message || 'Hugging Face search failed') : '');
})
.finally(() => {
if (requestId === catalogRequestId.current) setCatalogLoading(false);
});
}, []);
// Debounce so typing in the search box doesn't fire a request per keystroke.
//
// `activeCategory` is a trigger for the Hugging Face source ONLY — the live
// search asks the Hub for that category's models, so switching tabs is a new
// query. The curated catalog sends just backend+q and filters by category on
// the client (see visibleCatalogGroups), so refetching on a tab click would
// re-request a byte-identical list AND re-run the server's ~36-repo variant
// enrichment. `catalogCategoryKey` is the category when it matters and a
// constant when it doesn't, which keeps the whole effect one code path.
const catalogCategoryKey = catalogSource === 'huggingface' ? activeCategory : 'client-filtered';
useEffect(() => {
const t = setTimeout(() => loadCatalog(selected, query, catalogSource, activeCategory), catalogSource === 'huggingface' ? 450 : 250);
return () => clearTimeout(t);
// `activeCategory` is intentionally absent: `catalogCategoryKey` IS it
// whenever the source consumes it, so the effect re-runs (with a fresh
// closure) exactly when the category matters. On the curated source the
// closure can hold a stale category, which is harmless because that branch
// of loadCatalog never reads the argument.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [selected, query, catalogSource, catalogCategoryKey, loadCatalog]);
useEffect(() => {
reloadCatalogRef.current = () => loadCatalog(selected, query, catalogSource, activeCategory);
});
const selectedData = status?.[selected];
const selectedOllamaStartupAction = selectedData?.service?.supported ? 'enable' : 'start';
const selectedOllamaStartupLabel = selectedData?.service?.supported ? 'Run at Startup' : 'Start Ollama';
const installedModels = selectedData?.models || [];
const catalogCategories = useMemo(() => {
const counts = new Map();
for (const model of catalog) {
for (const category of recommendationCategoriesFor(model)) {
counts.set(category, (counts.get(category) || 0) + 1);
}
}
// Hugging Face is searched per-category server-side, so a default GGUF query
// never surfaces audio results — expose the full category set as filter
// buttons (count shown only when known) so the user can navigate to
// categories like Audio & Music. Curated counts include every lane a model
// is recommended for; the unfiltered groups below still use one primary
// lane per model, so broad models never duplicate in All.
const ids = catalogSource === 'huggingface'
? CATEGORY_ORDER
: CATEGORY_ORDER.filter((id) => counts.has(id));
return ids.map((id) => ({ id, label: categoryLabel(id), count: counts.has(id) ? counts.get(id) : null }));
}, [catalog, catalogSource]);
const visibleCatalogGroups = useMemo(() => {
const filterCategory = catalogSource === 'huggingface' ? 'all' : activeCategory;
const categoryIds = filterCategory === 'all'
? CATEGORY_ORDER.filter((category) => catalog.some((model) => primaryCategoryFor(model) === category))
: [filterCategory];
return categoryIds
.map((category) => ({
category,
label: categoryLabel(category),
// A featured recommendation leads every relevant lane, including the
// broad All view, instead of being buried by the catalog's source order.
models: catalog
.filter((model) => (
filterCategory === 'all'
? primaryCategoryFor(model) === category
: isRecommendedForCategory(model, category)
))
.sort((a, b) => Number(Boolean(b.featured)) - Number(Boolean(a.featured)))
}))
.filter((group) => group.models.length > 0);
}, [activeCategory, catalog, catalogCategories, catalogSource]);
// Active auto-upgrade flow (Ollama outdated → 412 on pull). Stays set while we
// download / install / relaunch so the warning banner can show live status.
// `{ modelId, phase: 'upgrading' | 'retrying' | 'failed', error? }`.
const [upgradeFlow, setUpgradeFlow] = useState(null);
// LM Studio's REST fallback returns { pending: true } — the download was only
// queued, not finished — so don't claim "installed" in that case. Install is
// silent so an OLLAMA_OUTDATED failure can take over the UI with the upgrade
// banner instead of stacking a useless toast with the auto-upgrade flow.
const startInstall = (modelId, { force = false } = {}) => runAction(
`install-${modelId}`,
() => installLocalLlmModel(selected, modelId, { silent: true, force }),
(r) => r?.pending ? `${modelId} download started` : `${modelId} ${force ? 'redownloaded' : 'installed'}`,
{
onError: (err) => {
if (err?.code === 'OLLAMA_OUTDATED' && selected === 'ollama') {
// Don't wait for a click — just upgrade. The user already said "install
// this model"; needing a newer Ollama to do it is an implementation
// detail, not a separate decision.
upgradeOllamaAndRetry(modelId);
} else if (err?.code === 'SHARDED_GGUF') {
// Ollama can't pull a multi-part GGUF (#5245). The catalog disables
// Install for known-sharded quants, but a pull-by-name still lands here —
// explain the fix rather than echoing Ollama's raw 400.
toast.error('Ollama can’t install sharded (multi-part) GGUFs. Pick a smaller single-file quant, or install this build on LM Studio.');
} else {
// Any other failure: restore the default toast we suppressed.
toast.error(err?.message || 'Install failed');
}
},
clearConfirm: false
}
);
const install = (modelId, opts = {}) => requestWeightDownload({
title: opts.force ? 'Redownload local model' : 'Install local model',
preview: () => previewLocalLlmDownload({ kind: 'install', backend: selected, modelId }, { silent: true }),
run: () => startInstall(modelId, opts),
});
// Audio/music models don't run on Ollama/LM Studio — they install into the
// shared audio-model registry (server/services/audioModels.js) via the Music
// studio's streaming HF-download endpoint, so the Music studio picks them up.
// The download streams SSE frames; surface progress in the same banner as the
// socket-driven install progress; the promise owns terminal errors.
const installAudio = (model) => {
return runAction(
`install-${model.id}`,
async () => {
await installAudioModel(
{ engine: model.engine, repo: model.repository, name: model.name },
(ev) => {
if (ev?.type === 'stage') setProgressMsg(ev.stage || '');
else if (ev?.type === 'progress') setProgressMsg(`${ev.file || 'downloading'} — ${Math.round((ev.progress || 0) * 100)}%`);
},
);
},
`${model.name} installed — available in the Music studio`,
{ onError: (err) => toast.error(err?.message || 'Install failed'), clearConfirm: false },
).finally(() => setProgressMsg(''));
};
const remove = (modelId) => runAction(`delete-${modelId}`, () => deleteLocalLlmModel(selected, modelId), `${modelId} deleted`)
.then((result) => {
// Drop the just-deleted model from any pending comparison (runAction
// resolves undefined on failure, so only prune on a real success) — else
// openCompare ships a dead modelId the playground would error on.
if (!result) return;
const key = localLlmTargetKey({ backend: selected, modelId });
setCompareTargets((prev) => prev.filter((t) => localLlmTargetKey(t) !== key));
});
const toggleCompareTarget = (backend, modelId) => {
const key = localLlmTargetKey({ backend, modelId });
setCompareTargets((prev) => {
if (prev.some((t) => localLlmTargetKey(t) === key)) {
return prev.filter((t) => localLlmTargetKey(t) !== key);
}
if (prev.length >= 6) {
toast.error('Compare up to 6 models at once');
return prev;
}
return [...prev, { backend, modelId }];
});
};
const openCompare = () => {
const params = new URLSearchParams();
params.set('targets', JSON.stringify(compareTargets));
params.set('mode', 'compare');
navigate(`/local-llm/playground?${params.toString()}`);
};
// Upgrade Ollama in place (direct .app download on macOS; brew elsewhere) and
// retry the original model install once Ollama is back online. `upgradeFlow`
// drives the prominent warning banner so the user sees what's happening; the
// socket-driven `progressMsg` provides per-step detail inside the same banner.
const upgradeOllamaAndRetry = (modelId) => {
setUpgradeFlow({ modelId, phase: 'upgrading' });
runAction(
'upgrade-ollama',
() => upgradeLocalLlmBackend('ollama'),
(r) => r?.note ? `Ollama upgraded — ${r.note}` : 'Ollama upgraded'
).then((r) => {
if (r?.success && modelId) {
setUpgradeFlow({ modelId, phase: 'retrying' });
startInstall(modelId);
// install() either succeeds (its own success toast + status reload covers
// it) or re-enters the OLLAMA_OUTDATED branch above and resets the flow.
// Clear after a beat so the banner doesn't linger past the retry kickoff.
setTimeout(() => setUpgradeFlow((cur) => (cur?.phase === 'retrying' ? null : cur)), 1500);
} else if (!r?.success) {
setUpgradeFlow({ modelId, phase: 'failed', error: r?.error });
}
}).catch((err) => {
setUpgradeFlow({ modelId, phase: 'failed', error: err?.message });
});
};
return (
<section id="llm-management-panel-library" role="tabpanel" aria-labelledby="llm-library-heading" className="space-y-4">
{upgradeFlow && (
<div className="bg-port-warning/10 border-2 border-port-warning/60 rounded-lg p-4 space-y-2" role="alert">
<div className="flex items-start gap-3">
<AlertTriangle size={20} className="text-port-warning mt-0.5 shrink-0" />
<div className="flex-1 min-w-0 space-y-1">
<p className="text-sm font-semibold text-port-warning">
{upgradeFlow.phase === 'failed' ? 'Ollama upgrade failed' : 'Upgrading Ollama'}
</p>
<p className="text-xs text-gray-300">
{upgradeFlow.phase === 'upgrading' && `${upgradeFlow.modelId} needs a newer Ollama than the one installed. Downloading the latest Ollama and replacing the installed app — this can take a minute.`}
{upgradeFlow.phase === 'retrying' && `Ollama is up to date — retrying the ${upgradeFlow.modelId} download now.`}
{upgradeFlow.phase === 'failed' && (upgradeFlow.error || 'See the server logs for details.')}
</p>
{progressMsg && upgradeFlow.phase !== 'failed' && (
<p className="text-xs text-port-warning/90 flex items-center gap-2 pt-1">
<BrailleSpinner /> {progressMsg}
</p>
)}
{upgradeFlow.phase === 'failed' && (
<p className="text-xs text-gray-400 pt-1">
You can also upgrade manually from <a href="https://ollama.com/download" target="_blank" rel="noopener noreferrer" className="text-port-accent hover:underline inline-flex items-center gap-1">ollama.com/download <ExternalLink size={10} /></a>.
</p>
)}
</div>
{upgradeFlow.phase === 'failed' && (
<button onClick={() => setUpgradeFlow(null)} className="text-xs text-gray-400 hover:text-white transition-colors" aria-label="Dismiss">
Dismiss
</button>
)}
</div>
</div>
)}
{/* Models — backend picker + catalog/install + installed list */}
<div className="bg-port-card border border-port-border rounded-xl p-4 sm:p-6 space-y-4">
<div className="flex items-center justify-between gap-3 flex-wrap">
<h2 id="llm-library-heading" className="text-sm font-medium text-gray-300">Models</h2>
<div className="flex items-center gap-2 flex-wrap justify-end">
<div className="flex items-center gap-1.5">
{['recommended', 'huggingface'].map((source) => (
<button
key={source}
onClick={() => { setCatalogSource(source); setActiveCategory('all'); }}
className={`px-2.5 py-1 text-xs rounded transition-colors ${catalogSource === source ? 'bg-port-accent/20 text-port-accent' : 'bg-port-bg text-gray-400 hover:text-white'}`}
>
{source === 'recommended' ? 'Recommended' : 'Hugging Face'}
</button>
))}
</div>
<div className="flex items-center gap-1.5">
{BACKENDS.map((b) => (
<button
key={b.id}
onClick={() => { setSelected(b.id); setActiveCategory('all'); }}
className={`px-2.5 py-1 text-xs rounded transition-colors ${selected === b.id ? 'bg-port-accent/20 text-port-accent' : 'bg-port-bg text-gray-400 hover:text-white'}`}
>
{b.label}
</button>
))}
</div>
</div>
</div>
{selectedData && !selectedData.available && !selectedData.disabled && (
<div className="flex items-center gap-2 flex-wrap text-xs text-port-warning">
<span>
{selectedData.installed
? `${labelFor(selected)} isn't running — ${selected === 'ollama' ? 'use the controls to start it or keep it running at login.' : 'launch the app and enable the local server.'}`
: `${labelFor(selected)} isn't installed yet.`}
</span>
{!selectedData.installed && selectedData.canAutoInstall && (
<button
onClick={() => installRuntimeBackend(selected)}
disabled={busy}
className={`${btnClass} bg-port-accent/20 hover:bg-port-accent/30 text-port-accent`}
>
{actionInProgress === `runtime-install-${selected}` ? <BrailleSpinner /> : <Download size={12} />}
Install {labelFor(selected)}
</button>
)}
{!selectedData.installed && !selectedData.canAutoInstall && selectedData.downloadUrl && (
<a
href={selectedData.downloadUrl}
target="_blank"
rel="noopener noreferrer"
className={`${btnClass} bg-port-border hover:bg-port-border/70 text-white no-underline`}
>
<ExternalLink size={12} />
Download {labelFor(selected)}
</a>
)}
{selected === 'ollama' && selectedData.installed && selectedData.canControl && (
<button
onClick={() => runAction(
`ollama-service-${selectedOllamaStartupAction}-models`,
() => controlOllamaService(selectedOllamaStartupAction),
selectedOllamaStartupAction === 'enable' ? 'Ollama will run at login' : 'Ollama is running',
{ ollamaService: true }
)}
disabled={busy}
className={`${btnClass} bg-port-accent/20 hover:bg-port-accent/30 text-port-accent`}
>
{actionInProgress === `ollama-service-${selectedOllamaStartupAction}-models` ? <BrailleSpinner /> : <Play size={12} />}
{selectedOllamaStartupLabel}
</button>
)}
</div>
)}
{selectedData?.available && selectedData?.modelsError && (
<p role="status" className="text-xs text-port-warning">
Couldn't list {labelFor(selected)} models (showing what's available): {selectedData.modelsError}
</p>
)}
{/* Free-text install + search */}
<div className="flex flex-col sm:flex-row gap-2">
<div className="flex-1 flex items-center gap-2 bg-port-bg border border-port-border rounded-lg px-3 focus-within:border-port-accent">
<Search size={14} className="text-gray-500" />
<FormField label={`Search the ${labelFor(selected)} model catalog`} labelClassName="sr-only" className="flex-1">
<input
id="llm-catalog-search"
value={query}
onChange={(e) => setQuery(e.target.value)}
placeholder={catalogSource === 'huggingface' ? (activeCategory === 'audio' ? 'Search Hugging Face audio models…' : 'Search Hugging Face GGUF models…') : `Search the ${labelFor(selected)} catalog…`}
className="w-full flex-1 bg-transparent py-2 text-sm text-white placeholder-gray-600 focus:outline-none"
/>
</FormField>
</div>
<div className="flex items-center gap-2">
<FormField label={`Install a ${labelFor(selected)} model by id`} labelClassName="sr-only" className="flex-1 sm:w-56">
<input
id="llm-manual-install"
value={manualId}
onChange={(e) => setManualId(e.target.value)}
placeholder={selected === 'ollama' ? 'pull by name e.g. llama3.2' : 'publisher/Model-GGUF'}
className="w-full flex-1 sm:w-56 bg-port-bg border border-port-border rounded-lg px-3 py-2 text-sm text-white placeholder-gray-600 focus:outline-none focus:border-port-accent"
/>
</FormField>
<button
onClick={() => { const id = manualId.trim(); if (id) { install(id); setManualId(''); } }}
disabled={busy || !manualId.trim()}
className="flex items-center gap-1.5 px-3 py-2 bg-port-accent/20 hover:bg-port-accent/30 text-port-accent text-sm font-medium rounded-lg disabled:opacity-50"
>
<Plus size={14} /> Install
</button>
</div>
</div>
{catalogCategories.length > 0 && (
<div className="flex flex-wrap gap-1.5">
<button
onClick={() => setActiveCategory('all')}
className={`px-2.5 py-1 text-xs rounded transition-colors ${activeCategory === 'all' ? 'bg-port-accent/20 text-port-accent' : 'bg-port-bg text-gray-400 hover:text-white'}`}
>
All ({catalog.length})
</button>
{catalogCategories.map((category) => (
<button
key={category.id}
onClick={() => setActiveCategory(category.id)}
className={`px-2.5 py-1 text-xs rounded transition-colors ${activeCategory === category.id ? 'bg-port-accent/20 text-port-accent' : 'bg-port-bg text-gray-400 hover:text-white'}`}
>
{category.label}{category.count != null ? ` (${category.count})` : ''}
</button>
))}
</div>
)}
{catalogLoading && (
<div className="flex items-center gap-2 text-xs text-gray-400">
<BrailleSpinner />
{catalogSource === 'huggingface' ? 'Searching Hugging Face' : 'Loading recommendations'}
</div>
)}
{catalogError && (
<p role="status" className="text-xs text-port-warning">{catalogError}</p>
)}
{Number.isFinite(systemMemoryGb) && catalog.some((m) => Array.isArray(m.variants) && m.variants.length > 1) && (
<p className="text-[11px] text-gray-500">
This machine has {systemMemoryGb} GB of memory — the default quant is the highest-fidelity build that fits. Use the Quant menu on a result to choose a smaller or larger one.
</p>
)}
{/* Catalog cards */}
<div className="space-y-4">
{visibleCatalogGroups.map((group) => (
<div key={group.category} className="space-y-2">
{activeCategory === 'all' && (
<h3 className="text-xs font-medium text-gray-400">{group.label}</h3>
)}
<div className="grid grid-cols-1 md:grid-cols-2 gap-2">
{group.models.map((m) => {
const isHf = m.source === 'huggingface';
const isAudio = m.category === 'audio';
const repositoryUrl = m.repository ? `https://huggingface.co/${m.repository}` : null;
// Multi-quant repos let the user trade their RAM for fidelity.
// `chosenId` is the selected variant's install id (defaulting to
// the server's RAM-aware pick `m.id`); the card's size/RAM/fit
// reflect that choice.
const variants = (!isAudio && Array.isArray(m.variants)) ? m.variants : [];
const hasVariantPicker = variants.length > 1;
// The server marks the RAM-aware default with `recommended`, so it
// wins as the default selection. (For live HF results it equals
// `m.id`; for curated entries `m.id` is the stable catalog id, which
// may itself be a non-default variant — so `recommended` must take
// precedence over `m.id`, or the RAM-aware pick never applies.) Fall
// back to `m.id`-as-variant, then `m.id`, so the controlled <select>
// always has a matching option.
const idMatchesVariant = variants.some((v) => v.installId === m.id);
const recommendedId = variants.find((v) => v.recommended)?.installId;
// Only honor a saved selection if it still matches a current variant —
// variant install ids are backend-specific (`repo@Q…` vs `hf.co/repo:Q…`),
// so a selection made before a backend switch must not leak through as a
// stale id (which would null out chosenVariant and install the wrong id).
const savedSelection = selectedVariants[m.key];
const validSelection = variants.some((v) => v.installId === savedSelection) ? savedSelection : null;
const chosenId = validSelection || recommendedId || (idMatchesVariant ? m.id : null) || m.id;
const chosenVariant = variants.find((v) => v.installId === chosenId) || null;
// Installed state is per-quant (Ollama tracks each separately),
// so gate Install on the SELECTED variant, not the result default.
const chosenInstalled = chosenVariant ? chosenVariant.installed : m.installed;
// A sharded quant can't be pulled by the active backend (Ollama
// #5245) — disable Install with the server's reason rather than
// letting the user hit the raw 400. (The server only sets
// `unsupportedReason` when the variant is unsupported.)
const chosenUnsupported = chosenVariant?.unsupportedReason ?? null;
const size = chosenVariant?.size || m.size;
const sizeBytes = chosenVariant?.sizeBytes ?? m.sizeBytes;
// Curated entries fetched without `?variants=1` carry no
// variant list at all — the server puts a measured fit on the
// model itself there, so fall back to it rather than dropping
// the only evidence that exists.
const fitEntry = chosenVariant || m;
const fit = fitEntry?.fit;
const fitMeta = fit ? FIT_META[fit] : null;
const fitMeasured = fitEntry?.fitSource === 'measured';
const ram = recommendedRamGb(sizeBytes, size);
const ctxLabel = formatContextLength(m.contextLength);
const createdMs = new Date(m.createdAt).getTime();
const updatedMs = new Date(m.updatedAt).getTime();
return (
<div key={m.key || m.id} className={`flex flex-col sm:flex-row sm:items-start gap-2 sm:gap-3 rounded-lg p-3 ${m.featured ? 'bg-port-accent/5 border border-port-accent/60 ring-1 ring-port-accent/20' : 'bg-port-bg border border-port-border'}`}>
<div className="flex-1 min-w-0">
<div className="text-sm text-white break-words">
{m.name} <span className="text-xs text-gray-500">· {m.params}</span>
{m.featured && (
<span
title={m.featured.description || 'Flagship local recommendation'}
className="ml-1.5 align-middle inline-flex items-center gap-0.5 text-[10px] px-1.5 py-0.5 rounded border border-port-accent/60 bg-port-accent/15 text-port-accent"
>
<Star size={9} className="fill-current" /> {m.featured.label || 'Featured'}
</span>
)}
{FORMAT_META[m.format] && (
<span
title={FORMAT_META[m.format].title}
className={`ml-1.5 align-middle text-[10px] px-1 py-0.5 rounded border ${FORMAT_META[m.format].cls}`}
>
{FORMAT_META[m.format].label}
</span>
)}
{!m.reducedSafeguards && m.publisherReview !== 'unreviewed' && isAgentRecommendedModel(m.capabilities) && (
<span
title="Recommended for agent & CoS tasks — has native tool calling plus coding strength, so it can actually drive multi-step agent work (unlike chat-only or tool-less models)."
className="ml-1.5 align-middle inline-flex items-center gap-0.5 text-[10px] px-1 py-0.5 rounded border border-port-accent/50 text-port-accent"
>
<Star size={9} className="fill-current" /> Agents
</span>
)}
</div>
<div className="text-xs text-gray-500 break-all">{chosenId}</div>
<div className="text-xs text-gray-500 mt-0.5">{m.description}</div>
{m.featured?.description && (
<div className="text-xs text-port-accent mt-1">{m.featured.description}</div>
)}
{m.reducedSafeguards && (
<p className="flex items-start gap-1.5 text-xs text-port-warning mt-2" role="note">
<AlertTriangle size={15} className="shrink-0" aria-hidden="true" />
{m.warning || 'Uncensored / abliterated: run carefully in a sandbox without secrets or publishing tools.'}
</p>
)}
{m.publisherReview && (
<p className="text-[11px] text-gray-400 mt-1">
{m.publisherReview === 'reviewed-build' ? 'Publisher provenance checked' : m.publisherReview === 'established-publisher' ? 'Established publisher' : 'Publisher not reviewed — discovery result, not a recommendation'}
{' · Popularity is not a malware-free guarantee.'}
</p>
)}
{m.provenance && (
<p className="text-[11px] text-gray-400 mt-1">
Reviewed {m.provenance.checkedAt}: {formatCount(m.provenance.likes)} likes · {formatCount(m.provenance.downloads)} monthly downloads · {formatCount(m.provenance.followers)} publisher followers.{' '}
<a className="text-port-accent hover:underline" href={`https://huggingface.co/${m.provenance.repository}/tree/${m.provenance.revision}`} target="_blank" rel="noopener noreferrer">Reviewed revision</a>
{' · Installer uses the publisher’s current release; this is a dated review, not an immutable install pin.'}
</p>
)}
{m.note && <div className="text-[11px] text-port-warning/90 mt-0.5">{m.note}</div>}
{hasVariantPicker && (
<FormField label="Quant" labelClassName="text-[11px] text-gray-500" className="flex items-center gap-1.5 flex-wrap mt-1">
<select
id={`quant-${m.key}`}
value={chosenId}
onChange={(e) => setSelectedVariants((prev) => ({ ...prev, [m.key]: e.target.value }))}
disabled={busy}
className="text-[11px] bg-port-card border border-port-border rounded px-1.5 py-0.5 text-gray-300 max-w-[16rem]"
title="Pick a quantization — higher quants are larger but higher fidelity"
>
{variants.map((v) => (
<option key={v.installId} value={v.installId}>
{v.quant}{v.size ? ` · ${v.size}` : ''}{v.installed ? ' · installed' : ''}{v.recommended ? ' · recommended' : ''}{v.fit === 'too-large' ? ' · exceeds RAM' : ''}{v.fit === 'incompatible' ? ' · backend refused it' : ''}{v.fitSource === 'measured' ? ' · measured' : ''}{v.unsupported === 'sharded' ? ' · sharded (not on Ollama)' : ''}
</option>
))}
</select>
{fitMeta && (
<span className={`text-[11px] ${fitMeta.cls}`} title={fitTitle(fitEntry?.fitSource, fitEntry)}>
{fitMeta.label}{fitMeasured ? ' (measured)' : ''}
</span>
)}
</FormField>
)}
<div className="flex items-center gap-1.5 flex-wrap text-[11px] text-gray-600 mt-1">
<span className="text-gray-500">{categoryLabel(m.category)}</span>
<span>{size}</span>
{/* Single-variant cards (e.g. MLX) have no quant picker, so
surface the RAM-fit hint here instead of in the picker row. */}
{fitMeta && !hasVariantPicker && (
<span className={fitMeta.cls} title={fitTitle(fitEntry?.fitSource, fitEntry)}>
{fitMeta.label}{fitMeasured ? ' (measured)' : ''}
</span>
)}
{ctxLabel && (
<span title="Native context window (max tokens)">{ctxLabel}</span>
)}
{ram && (
<span title="Approx RAM/VRAM to run this model — weights + ~20% overhead">
~{ram} GB RAM
</span>
)}
{isHf && <span>{m.downloads?.toLocaleString?.() || 0} downloads</span>}
{isHf && Number.isFinite(createdMs) && (
<span
title={`Published ${formatDateNumeric(createdMs)}${Number.isFinite(updatedMs) ? ` · updated ${timeAgo(m.updatedAt)}` : ''}`}
>
published {formatAgeDays(m.createdAt)}
</span>
)}
{isHf && m.license && <span>{m.license}</span>}
<CapabilityBadges capabilities={m.capabilities} />
</div>
</div>
{/* Mobile: actions sit on their own row under the details so
the name/id column isn't squeezed into a narrow column.
Desktop keeps them stacked at the card's right edge. */}
<div className="flex flex-row sm:flex-col items-center sm:items-end gap-2 sm:gap-1 shrink-0 justify-end flex-wrap">
{chosenInstalled ? (
<>
<span className="text-xs px-2 py-1 text-port-success">Installed</span>
{!isAudio && (selected !== 'lmstudio' || /@/.test(chosenId || '')) && (
<button
onClick={() => install(chosenId, { force: true })}
disabled={busy}
title="Pull this build again. Updated GGUF files keep the same name, so an existing install will not refresh until you redownload."
className="px-2.5 py-1 text-xs bg-port-accent/20 hover:bg-port-accent/30 text-port-accent rounded disabled:opacity-50 disabled:cursor-not-allowed flex items-center gap-1"
>
{actionInProgress === `install-${chosenId}` ? <BrailleSpinner /> : <RefreshCw size={12} />}
Redownload
</button>
)}
</>
) : m.installable === false ? (
// Audio models with no PortOS runtime (or a fixed-checkpoint
// engine like ACE-Step) are discovery-only — "Visit" below.
null
) : (
<button
onClick={() => (isAudio ? installAudio(m) : install(chosenId))}
disabled={busy || !!chosenUnsupported}
title={chosenUnsupported || undefined}
className="px-2.5 py-1 text-xs bg-port-accent/20 hover:bg-port-accent/30 text-port-accent rounded disabled:opacity-50 disabled:cursor-not-allowed flex items-center gap-1"
>
{actionInProgress === `install-${chosenId}` ? <BrailleSpinner /> : <Download size={12} />}
Install
</button>
)}
{chosenUnsupported && !chosenInstalled && (
<span className="text-[11px] text-port-warning text-right max-w-[12rem] leading-snug" title={chosenUnsupported}>
Sharded — use LM Studio or a smaller quant
</span>
)}
{repositoryUrl && (
<a
href={repositoryUrl}
target="_blank"
rel="noopener noreferrer"
title={m.gated ? 'Open Hugging Face to accept repository terms' : 'Open the model page on Hugging Face'}
className="px-2.5 py-1 text-xs bg-port-border/60 hover:bg-port-border text-gray-300 rounded flex items-center gap-1"
>
<ExternalLink size={12} />
{m.gated ? 'Accept terms' : 'Visit'}
</a>
)}
</div>
</div>
);
})}
</div>
</div>
))}
{catalog.length === 0 && (
<p className="text-xs text-gray-500">No catalog matches{query ? ` for "${query}"` : ''}.</p>
)}
{catalog.length > 0 && visibleCatalogGroups.length === 0 && (
<p className="text-xs text-gray-500">No {categoryLabel(activeCategory)} matches{query ? ` for "${query}"` : ''}.</p>
)}
</div>
<LocalLlmInstalledModels
actionInProgress={actionInProgress}
backend={selected}
busy={busy}
cancelDelete={cancelDelete}
compareTargets={compareTargets}
confirmDelete={confirmDelete}
install={install}
isConfirmingDelete={isConfirmingDelete}
models={installedModels}
onCompare={openCompare}
onToggleCompare={toggleCompareTarget}
remove={remove}
requestDelete={requestDelete}
/>
</div>
<DownloadPreflightConfirm
open={Boolean(downloadConfirm)}
title={downloadConfirm?.title}
loading={Boolean(downloadConfirm?.loading)}
error={downloadConfirm?.error}
assessment={downloadConfirm?.assessment}
confirmLabel="Start download"
onCancel={cancelDownloadConfirm}
onConfirm={runDownloadConfirm}
/>
</section>
);
}