Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(local-models): the routes and the hook behind the section

rubenluetke10-beepb3a596d87d8d
diff --git a/jarvis/ui/web/frontend/src/hooks/useLocalModels.test.ts b/jarvis/ui/web/frontend/src/hooks/useLocalModels.test.ts
new file mode 100644
index 0000000000..34ea66039b
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/hooks/useLocalModels.test.ts
@@ -0,0 +1,112 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+ deleteModel,
+ getModelOptions,
+ hfPullName,
+ localModelsKeys,
+ searchCatalog,
+ setRole,
+} from "./useLocalModels";
+
+function stubFetch(body: unknown, ok = true, status = 200) {
+ const fetchMock = vi.fn(async (_url: string, _init?: RequestInit) => ({
+ ok,
+ status,
+ json: async () => body,
+ }));
+ vi.stubGlobal("fetch", fetchMock);
+ return fetchMock;
+}
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+});
+
+describe("useLocalModels fetch helpers", () => {
+ it("keeps the slashes of a Hugging Face model name in the path", async () => {
+ const fetchMock = stubFetch({
+ model: "hf.co/u/r:Q4_K_M",
+ options: {},
+ configured: false,
+ });
+ await getModelOptions("ollama", "hf.co/u/r:Q4_K_M");
+ const url = String(fetchMock.mock.calls[0][0]);
+ expect(url).toBe(
+ "/api/providers/ollama/local-models/models/hf.co/u/r%3AQ4_K_M/options",
+ );
+ });
+
+ it("sends the role body as JSON to PUT roles/{role}", async () => {
+ const fetchMock = stubFetch({
+ ok: true,
+ role: "chat",
+ model: "x",
+ config_key: "",
+ message: "",
+ });
+ await setRole("ollama", "chat", "qwen3.5:4b");
+ const [url, init] = fetchMock.mock.calls[0] as unknown as [
+ string,
+ RequestInit,
+ ];
+ expect(url).toBe("/api/providers/ollama/local-models/roles/chat");
+ expect(init.method).toBe("PUT");
+ expect(JSON.parse(String(init.body))).toEqual({ model: "qwen3.5:4b" });
+ });
+
+ it("forwards sort and capability only when set", async () => {
+ const fetchMock = stubFetch({
+ query: "",
+ sort: "popular",
+ capability: null,
+ models: [],
+ error: null,
+ });
+ await searchCatalog("ollama");
+ await searchCatalog("ollama", {
+ q: "qwen",
+ sort: "newest",
+ capability: "tools",
+ });
+ expect(String(fetchMock.mock.calls[0][0])).toBe(
+ "/api/providers/ollama/local-models/catalog",
+ );
+ expect(String(fetchMock.mock.calls[1][0])).toBe(
+ "/api/providers/ollama/local-models/catalog?q=qwen&sort=newest&capability=tools",
+ );
+ });
+
+ it("surfaces the backend sentence of a refused delete", async () => {
+ stubFetch({ detail: "qwen3.5:4b is still the pick for chat." }, false, 409);
+ await expect(deleteModel("ollama", "qwen3.5:4b")).rejects.toThrow(
+ "still the pick",
+ );
+ });
+
+ it("builds the hf.co pull name the backend uses", () => {
+ expect(hfPullName("unsloth", "Qwen3.8-27B-GGUF", "Q4_K_M")).toBe(
+ "hf.co/unsloth/Qwen3.8-27B-GGUF:Q4_K_M",
+ );
+ expect(hfPullName("unsloth", "Qwen3.8-27B-GGUF")).toBe(
+ "hf.co/unsloth/Qwen3.8-27B-GGUF",
+ );
+ });
+
+ it("scopes every query key under local-models and the provider", () => {
+ expect(localModelsKeys.roles("ollama")).toEqual([
+ "local-models",
+ "ollama",
+ "roles",
+ ]);
+ expect(localModelsKeys.catalog("ollama", { q: "a" })).toEqual([
+ "local-models",
+ "ollama",
+ "catalog",
+ "a",
+ "popular",
+ "",
+ 50,
+ ]);
+ });
+});
diff --git a/jarvis/ui/web/frontend/src/hooks/useLocalModels.ts b/jarvis/ui/web/frontend/src/hooks/useLocalModels.ts
new file mode 100644
index 0000000000..7c84b87329
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/hooks/useLocalModels.ts
@@ -0,0 +1,942 @@
+/**
+ * Fetch helpers and React Query hooks for the "Local models" section.
+ *
+ * Endpoints: `jarvis/ui/web/local_models_routes.py`, all under
+ * `/api/providers/{id}/local-models/...` and gated on a pull-capable card
+ * (Ollama today). The interfaces below are the TS half of the AP-4 contract —
+ * they mirror the Pydantic response models one to one.
+ *
+ * The pull helpers (`startModelPull`, `modelPullStatus`) stay in
+ * `useProviders.ts` and are re-exported here so a panel imports one module.
+ */
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+import type { OllamaModelOptions } from "../lib/ollamaModelOptions";
+import type {
+ LibraryModel,
+ LibraryTag,
+ ModelPullProgress,
+ PullableModels,
+} from "./useProviders";
+
+export { startModelPull, modelPullStatus } from "./useProviders";
+export type {
+ LibraryModel,
+ LibraryTag,
+ ModelPullProgress,
+ PullableModels,
+} from "./useProviders";
+export type { OllamaModelOptions } from "../lib/ollamaModelOptions";
+
+// ---------------------------------------------------------------------------
+// Wire types — inventory
+// ---------------------------------------------------------------------------
+
+/** The four writable slots. */
+export type LocalModelRole = "chat" | "tools_screen" | "deep" | "embedding";
+/** Every role row the backend renders, read-only ones included. */
+export type LocalModelRoleId = LocalModelRole | "voice" | "ack" | "polish";
+
+export interface RunningModelRow {
+ name: string;
+ size_bytes: number;
+ size_vram_bytes: number;
+ expires_at: string;
+ context_length: number | null;
+ digest: string;
+}
+
+export interface LocalModelRow {
+ name: string;
+ size_bytes: number;
+ digest: string;
+ modified_at: string;
+ family: string;
+ parameter_size: string;
+ quantization_level: string;
+ /** Native window from the manifest; null when unknown. */
+ context_length: number | null;
+ /** "completion" | "vision" | "tools" | "thinking" | "embedding" | "audio" | "insert". */
+ capabilities: string[];
+ license: string;
+ /** False when /api/show failed for this row — "unknown", not "none". */
+ probed: boolean;
+ used_by: LocalModelRole[];
+ loaded: boolean;
+ size_vram_bytes: number;
+ expires_at: string;
+ running_context_length: number | null;
+}
+
+export interface LocalModelDetail extends LocalModelRow {
+ parameters: string;
+ template: string;
+}
+
+export interface InventoryResponse {
+ provider: string;
+ server: string;
+ models: LocalModelRow[];
+ running: RunningModelRow[];
+ disk_bytes: number;
+ loaded_vram_bytes: number;
+ /** Sentence when the server did not answer; show it instead of "nothing installed". */
+ error: string | null;
+}
+
+export interface UnloadResponse {
+ ok: boolean;
+ model: string;
+ message: string;
+}
+
+export interface DeleteResponse {
+ ok: boolean;
+ model: string;
+ message: string;
+ reassigned: LocalModelRole[];
+ reassigned_to: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Wire types — roles
+// ---------------------------------------------------------------------------
+
+export interface RoleRow {
+ id: LocalModelRoleId;
+ /** i18n key, e.g. "local_models.role_chat". */
+ label_key: string;
+ /** Dotted config path for the footnote. */
+ config_key: string;
+ /** Configured tag; "" = the plugin discovers one. */
+ current: string;
+ /** `current` is on the server right now. */
+ installed: boolean;
+ required: string[];
+ recommended_capabilities: string[];
+ /** Installed tags declaring every required capability. */
+ qualifying: string[];
+ /** The shortlist's pick for this machine; "" when it has none. */
+ recommended: string;
+ writable: boolean;
+ advanced: boolean;
+ /** Sentence when the slot is served by something other than Ollama. */
+ note: string;
+}
+
+export interface RolesResponse {
+ provider: string;
+ server: string;
+ roles: RoleRow[];
+ error: string | null;
+}
+
+export interface RoleSetBody {
+ /** "" = back to discovery (brain roles only). */
+ model: string;
+}
+
+export interface RoleSetResponse {
+ ok: boolean;
+ role: string;
+ model: string;
+ config_key: string;
+ message: string;
+}
+
+// ---------------------------------------------------------------------------
+// Wire types — options
+// ---------------------------------------------------------------------------
+
+export interface ModelOptionsResponse {
+ model: string;
+ /** Only the knobs that are set. */
+ options: OllamaModelOptions;
+ configured: boolean;
+ /** The derived alias the brain streams through; null when none is needed. */
+ profile_alias: string | null;
+}
+
+export interface SuggestedOptionsResponse {
+ model: string;
+ options: OllamaModelOptions;
+ /** One plain sentence per knob, plus one for the memory budget. */
+ reasons: string[];
+ size_gb: number;
+ native_context: number | null;
+ accelerator_gb: number;
+ /** "nvidia-smi" | "apple-unified" | "none" ... */
+ accelerator_source: string;
+ ram_gb: number | null;
+}
+
+// ---------------------------------------------------------------------------
+// Wire types — catalogue
+// ---------------------------------------------------------------------------
+
+export type CatalogSort = "popular" | "newest";
+export type CatalogCapability = "tools" | "vision" | "embedding" | "thinking";
+
+export interface CatalogSearchResponse {
+ query: string;
+ sort: CatalogSort;
+ capability: CatalogCapability | null;
+ models: LibraryModel[];
+ error: string | null;
+}
+
+/** One tag with the catalogue's two new columns. */
+export interface CatalogTag extends LibraryTag {
+ /** From the tag name ("q8_0", "bf16", "iq2_xs"); "" for a default tag. */
+ quantization: string;
+}
+
+export interface CatalogTagsResponse {
+ model: string;
+ tags: CatalogTag[];
+ error: string | null;
+}
+
+export interface CatalogRecommendedModel {
+ id: string;
+ label: string;
+ size_gb: number;
+ purpose: string;
+ role: "chat" | "vision" | "coder" | "embedding";
+ tools: boolean;
+ vision: boolean;
+ installed: boolean;
+ fit: "comfortable" | "tight" | "unknown" | string;
+ fit_note: string;
+ recommended: boolean;
+ /** The roles this row is the pick for on this machine. */
+ recommended_for: Array<"chat" | "vision" | "coder" | "embedding">;
+}
+
+export interface CatalogRecommendedResponse extends Omit<
+ PullableModels,
+ "models"
+> {
+ /** ISO date the maintainer last reviewed the shortlist. */
+ curated_reviewed_on: string;
+ models: CatalogRecommendedModel[];
+}
+
+// ---------------------------------------------------------------------------
+// Wire types — Hugging Face
+// ---------------------------------------------------------------------------
+
+export type HfSort = "downloads" | "lastModified" | "trendingScore";
+
+export interface HfRepo {
+ id: string;
+ author: string;
+ downloads: number;
+ likes: number;
+ /** ISO 8601; "" when unknown. */
+ last_modified: string;
+ architecture: string;
+ total_params: number | null;
+ context_length: number | null;
+}
+
+export interface HfFile {
+ filename: string;
+ /** "Q4_K_M" ...; null = pull the repository default. */
+ quant: string | null;
+ size_gb: number | null;
+ fit: "comfortable" | "tight" | "unknown";
+ fit_note: string;
+}
+
+export interface HfSearchResponse {
+ repos: HfRepo[];
+ error: string | null;
+}
+
+export interface HfFilesResponse {
+ files: HfFile[];
+ error: string | null;
+}
+
+export interface HfPullBody {
+ user: string;
+ repo: string;
+ quant?: string | null;
+}
+
+export interface HfEnabledResponse {
+ enabled: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Wire types — server
+// ---------------------------------------------------------------------------
+
+export type HostKind = "local" | "remote";
+
+export interface ServerResponse {
+ installed: boolean;
+ binary: string;
+ running: boolean;
+ version: string;
+ detail: string;
+ base_url: string;
+ /** Hide Install / Start / Stop / log when "remote". */
+ host_kind: HostKind;
+ models_dir: string;
+ running_models: RunningModelRow[];
+ disk_bytes: number;
+ loaded_vram_bytes: number;
+ error: string | null;
+}
+
+export interface ServerActionResponse {
+ ok: boolean;
+ message: string;
+}
+
+export interface ServerProbeResponse {
+ ok: boolean;
+ version: string;
+ latency_ms: number;
+ detail: string;
+}
+
+export interface ServerLogResponse {
+ lines: string[];
+}
+
+export type EnvGuideOs = "windows" | "macos" | "linux";
+
+export interface EnvGuideRow {
+ key: string;
+ purpose: string;
+ /** The copyable line. */
+ command: string;
+ restart: string;
+}
+
+export interface EnvGuideResponse {
+ os: EnvGuideOs;
+ rows: EnvGuideRow[];
+}
+
+// ---------------------------------------------------------------------------
+// Fetch helpers
+// ---------------------------------------------------------------------------
+
+/** Long enough for a cold /api/show sweep over a big inventory or a registry read. */
+const READ_TIMEOUT_MS = 20_000;
+/** Config writes and server actions answer within a few seconds or not at all. */
+const WRITE_TIMEOUT_MS = 15_000;
+
+function base(providerId: string): string {
+ return `/api/providers/${encodeURIComponent(providerId)}/local-models`;
+}
+
+/** Model names may carry ":" and "/" (hf.co/user/repo:Q4_K_M); keep the slashes. */
+function modelPath(name: string): string {
+ return name.split("/").map(encodeURIComponent).join("/");
+}
+
+async function request<T>(
+ url: string,
+ init: RequestInit = {},
+ timeoutMs = READ_TIMEOUT_MS,
+): Promise<T> {
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
+ try {
+ const res = await fetch(url, { ...init, signal: controller.signal });
+ const body = await res.json().catch(() => ({}));
+ if (!res.ok) {
+ throw new Error(
+ (body as { detail?: string }).detail ?? `HTTP ${res.status}`,
+ );
+ }
+ return body as T;
+ } finally {
+ clearTimeout(timer);
+ }
+}
+
+function json(method: "POST" | "PUT", payload: unknown): RequestInit {
+ return {
+ method,
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(payload),
+ };
+}
+
+// inventory
+
+export async function getInventory(
+ providerId: string,
+): Promise<InventoryResponse> {
+ return request(`${base(providerId)}/inventory`);
+}
+
+export async function getInventoryModel(
+ providerId: string,
+ name: string,
+): Promise<LocalModelDetail> {
+ return request(`${base(providerId)}/inventory/${modelPath(name)}`);
+}
+
+export async function unloadModel(
+ providerId: string,
+ name: string,
+): Promise<UnloadResponse> {
+ return request(
+ `${base(providerId)}/inventory/${modelPath(name)}/unload`,
+ { method: "POST" },
+ WRITE_TIMEOUT_MS,
+ );
+}
+
+export async function deleteModel(
+ providerId: string,
+ name: string,
+ reassign?: string,
+): Promise<DeleteResponse> {
+ const qs = reassign ? `?reassign=${encodeURIComponent(reassign)}` : "";
+ return request(
+ `${base(providerId)}/inventory/${modelPath(name)}${qs}`,
+ { method: "DELETE" },
+ WRITE_TIMEOUT_MS,
+ );
+}
+
+// roles
+
+export async function getRoles(providerId: string): Promise<RolesResponse> {
+ return request(`${base(providerId)}/roles`);
+}
+
+export async function setRole(
+ providerId: string,
+ role: LocalModelRole,
+ model: string,
+): Promise<RoleSetResponse> {
+ const body: RoleSetBody = { model };
+ return request(
+ `${base(providerId)}/roles/${encodeURIComponent(role)}`,
+ json("PUT", body),
+ WRITE_TIMEOUT_MS,
+ );
+}
+
+// options
+
+export async function getModelOptions(
+ providerId: string,
+ name: string,
+): Promise<ModelOptionsResponse> {
+ return request(`${base(providerId)}/models/${modelPath(name)}/options`);
+}
+
+/** REPLACE semantics: send the whole set; an empty object clears the profile. */
+export async function saveModelOptions(
+ providerId: string,
+ name: string,
+ options: OllamaModelOptions,
+): Promise<ModelOptionsResponse> {
+ return request(
+ `${base(providerId)}/models/${modelPath(name)}/options`,
+ json("PUT", options),
+ WRITE_TIMEOUT_MS,
+ );
+}
+
+export async function resetModelOptions(
+ providerId: string,
+ name: string,
+): Promise<ModelOptionsResponse> {
+ return request(
+ `${base(providerId)}/models/${modelPath(name)}/options`,
+ { method: "DELETE" },
+ WRITE_TIMEOUT_MS,
+ );
+}
+
+export async function getSuggestedOptions(
+ providerId: string,
+ name: string,
+): Promise<SuggestedOptionsResponse> {
+ return request(
+ `${base(providerId)}/models/${modelPath(name)}/suggested-options`,
+ );
+}
+
+// catalogue
+
+export interface CatalogQuery {
+ q?: string;
+ sort?: CatalogSort;
+ capability?: CatalogCapability | null;
+ limit?: number;
+}
+
+export async function searchCatalog(
+ providerId: string,
+ query: CatalogQuery = {},
+): Promise<CatalogSearchResponse> {
+ const params = new URLSearchParams();
+ if (query.q) params.set("q", query.q);
+ if (query.sort) params.set("sort", query.sort);
+ if (query.capability) params.set("capability", query.capability);
+ if (query.limit) params.set("limit", String(query.limit));
+ const qs = params.toString();
+ return request(`${base(providerId)}/catalog${qs ? `?${qs}` : ""}`);
+}
+
+export async function getCatalogTags(
+ providerId: string,
+ name: string,
+): Promise<CatalogTagsResponse> {
+ return request(`${base(providerId)}/catalog/${modelPath(name)}/tags`);
+}
+
+export async function getCatalogRecommended(
+ providerId: string,
+): Promise<CatalogRecommendedResponse> {
+ return request(`${base(providerId)}/catalog/recommended`);
+}
+
+// Hugging Face
+
+export async function getHfEnabled(
+ providerId: string,
+): Promise<HfEnabledResponse> {
+ return request(`${base(providerId)}/hf/enabled`);
+}
+
+export async function setHfEnabled(
+ providerId: string,
+ enabled: boolean,
+): Promise<HfEnabledResponse> {
+ return request(
+ `${base(providerId)}/hf/enabled`,
+ json("PUT", { enabled }),
+ WRITE_TIMEOUT_MS,
+ );
+}
+
+export async function searchHf(
+ providerId: string,
+ q: string,
+ sort: HfSort = "downloads",
+ limit = 30,
+): Promise<HfSearchResponse> {
+ const params = new URLSearchParams({ q, sort, limit: String(limit) });
+ return request(`${base(providerId)}/hf/search?${params.toString()}`);
+}
+
+export async function getHfFiles(
+ providerId: string,
+ user: string,
+ repo: string,
+): Promise<HfFilesResponse> {
+ return request(
+ `${base(providerId)}/hf/${encodeURIComponent(user)}/${encodeURIComponent(repo)}/files`,
+ );
+}
+
+/** Starts `ollama pull hf.co/<user>/<repo>[:<quant>]`; poll with `modelPullStatus`. */
+export async function startHfPull(
+ providerId: string,
+ body: HfPullBody,
+): Promise<ModelPullProgress> {
+ return request(
+ `${base(providerId)}/hf/pull`,
+ json("POST", body),
+ WRITE_TIMEOUT_MS,
+ );
+}
+
+/** The pull name the backend builds, for the status poll. */
+export function hfPullName(
+ user: string,
+ repo: string,
+ quant?: string | null,
+): string {
+ return quant ? `hf.co/${user}/${repo}:${quant}` : `hf.co/${user}/${repo}`;
+}
+
+// server
+
+export async function getServer(providerId: string): Promise<ServerResponse> {
+ return request(`${base(providerId)}/server`);
+}
+
+export async function stopServer(
+ providerId: string,
+): Promise<ServerActionResponse> {
+ return request(
+ `${base(providerId)}/server/stop`,
+ { method: "POST" },
+ WRITE_TIMEOUT_MS,
+ );
+}
+
+export async function testServer(
+ providerId: string,
+ baseUrl: string,
+): Promise<ServerProbeResponse> {
+ return request(
+ `${base(providerId)}/server/test`,
+ json("POST", { base_url: baseUrl }),
+ WRITE_TIMEOUT_MS,
+ );
+}
+
+export async function getServerLog(
+ providerId: string,
+ lines = 40,
+): Promise<ServerLogResponse> {
+ return request(`${base(providerId)}/server/log?lines=${lines}`);
+}
+
+export async function getEnvGuide(
+ providerId: string,
+ os?: EnvGuideOs,
+): Promise<EnvGuideResponse> {
+ const qs = os ? `?os=${os}` : "";
+ return request(`${base(providerId)}/server/env-guide${qs}`);
+}
+
+// ---------------------------------------------------------------------------
+// Query keys
+// ---------------------------------------------------------------------------
+
+export const localModelsKeys = {
+ all: ["local-models"] as const,
+ inventory: (p: string) => ["local-models", p, "inventory"] as const,
+ model: (p: string, name: string) =>
+ ["local-models", p, "inventory", name] as const,
+ roles: (p: string) => ["local-models", p, "roles"] as const,
+ options: (p: string, name: string) =>
+ ["local-models", p, "options", name] as const,
+ suggested: (p: string, name: string) =>
+ ["local-models", p, "suggested-options", name] as const,
+ catalog: (p: string, q: CatalogQuery) =>
+ [
+ "local-models",
+ p,
+ "catalog",
+ q.q ?? "",
+ q.sort ?? "popular",
+ q.capability ?? "",
+ q.limit ?? 50,
+ ] as const,
+ catalogTags: (p: string, name: string) =>
+ ["local-models", p, "catalog", "tags", name] as const,
+ recommended: (p: string) =>
+ ["local-models", p, "catalog", "recommended"] as const,
+ hfEnabled: (p: string) => ["local-models", p, "hf", "enabled"] as const,
+ hfSearch: (p: string, q: string, sort: HfSort) =>
+ ["local-models", p, "hf", "search", q, sort] as const,
+ hfFiles: (p: string, user: string, repo: string) =>
+ ["local-models", p, "hf", "files", user, repo] as const,
+ server: (p: string) => ["local-models", p, "server"] as const,
+ serverLog: (p: string, lines: number) =>
+ ["local-models", p, "server", "log", lines] as const,
+ envGuide: (p: string, os: EnvGuideOs | "") =>
+ ["local-models", p, "server", "env-guide", os] as const,
+};
+
+// ---------------------------------------------------------------------------
+// Query hooks
+// ---------------------------------------------------------------------------
+
+/** Every download with facts, loaded state and the roles using it. Polls slowly. */
+export function useInventory(providerId: string | undefined, enabled = true) {
+ return useQuery({
+ queryKey: localModelsKeys.inventory(providerId ?? ""),
+ queryFn: () => getInventory(providerId as string),
+ enabled: enabled && !!providerId,
+ refetchInterval: 15_000,
+ staleTime: 5_000,
+ });
+}
+
+export function useInventoryModel(
+ providerId: string | undefined,
+ name: string | undefined,
+) {
+ return useQuery({
+ queryKey: localModelsKeys.model(providerId ?? "", name ?? ""),
+ queryFn: () => getInventoryModel(providerId as string, name as string),
+ enabled: !!providerId && !!name,
+ staleTime: 30_000,
+ });
+}
+
+export function useRoles(providerId: string | undefined, enabled = true) {
+ return useQuery({
+ queryKey: localModelsKeys.roles(providerId ?? ""),
+ queryFn: () => getRoles(providerId as string),
+ enabled: enabled && !!providerId,
+ staleTime: 10_000,
+ });
+}
+
+export function useModelOptions(
+ providerId: string | undefined,
+ name: string | undefined,
+) {
+ return useQuery({
+ queryKey: localModelsKeys.options(providerId ?? "", name ?? ""),
+ queryFn: () => getModelOptions(providerId as string, name as string),
+ enabled: !!providerId && !!name,
+ staleTime: 30_000,
+ });
+}
+
+export function useSuggestedOptions(
+ providerId: string | undefined,
+ name: string | undefined,
+) {
+ return useQuery({
+ queryKey: localModelsKeys.suggested(providerId ?? "", name ?? ""),
+ queryFn: () => getSuggestedOptions(providerId as string, name as string),
+ enabled: !!providerId && !!name,
+ staleTime: 5 * 60_000,
+ });
+}
+
+/** Browse-by-default: fetches on mount; the backend caches the page for 10 minutes. */
+export function useCatalog(
+ providerId: string | undefined,
+ query: CatalogQuery = {},
+ enabled = true,
+) {
+ return useQuery({
+ queryKey: localModelsKeys.catalog(providerId ?? "", query),
+ queryFn: () => searchCatalog(providerId as string, query),
+ enabled: enabled && !!providerId,
+ staleTime: 10 * 60_000,
+ placeholderData: (prev) => prev,
+ });
+}
+
+export function useCatalogTags(
+ providerId: string | undefined,
+ name: string | undefined,
+) {
+ return useQuery({
+ queryKey: localModelsKeys.catalogTags(providerId ?? "", name ?? ""),
+ queryFn: () => getCatalogTags(providerId as string, name as string),
+ enabled: !!providerId && !!name,
+ staleTime: 10 * 60_000,
+ });
+}
+
+export function useCatalogRecommended(
+ providerId: string | undefined,
+ enabled = true,
+) {
+ return useQuery({
+ queryKey: localModelsKeys.recommended(providerId ?? ""),
+ queryFn: () => getCatalogRecommended(providerId as string),
+ enabled: enabled && !!providerId,
+ staleTime: 60_000,
+ });
+}
+
+export function useHfEnabled(providerId: string | undefined) {
+ return useQuery({
+ queryKey: localModelsKeys.hfEnabled(providerId ?? ""),
+ queryFn: () => getHfEnabled(providerId as string),
+ enabled: !!providerId,
+ staleTime: 60_000,
+ });
+}
+
+/** Only runs while the switch is on AND a query is typed — no idle HF traffic. */
+export function useHfSearch(
+ providerId: string | undefined,
+ q: string,
+ sort: HfSort = "downloads",
+ enabled = true,
+) {
+ return useQuery({
+ queryKey: localModelsKeys.hfSearch(providerId ?? "", q, sort),
+ queryFn: () => searchHf(providerId as string, q, sort),
+ enabled: enabled && !!providerId && q.trim().length > 0,
+ staleTime: 10 * 60_000,
+ placeholderData: (prev) => prev,
+ });
+}
+
+export function useHfFiles(
+ providerId: string | undefined,
+ user: string | undefined,
+ repo: string | undefined,
+) {
+ return useQuery({
+ queryKey: localModelsKeys.hfFiles(providerId ?? "", user ?? "", repo ?? ""),
+ queryFn: () =>
+ getHfFiles(providerId as string, user as string, repo as string),
+ enabled: !!providerId && !!user && !!repo,
+ staleTime: 10 * 60_000,
+ });
+}
+
+export function useServer(providerId: string | undefined, enabled = true) {
+ return useQuery({
+ queryKey: localModelsKeys.server(providerId ?? ""),
+ queryFn: () => getServer(providerId as string),
+ enabled: enabled && !!providerId,
+ refetchInterval: 15_000,
+ staleTime: 5_000,
+ });
+}
+
+export function useServerLog(
+ providerId: string | undefined,
+ lines = 40,
+ enabled = true,
+) {
+ return useQuery({
+ queryKey: localModelsKeys.serverLog(providerId ?? "", lines),
+ queryFn: () => getServerLog(providerId as string, lines),
+ enabled: enabled && !!providerId,
+ refetchInterval: 10_000,
+ });
+}
+
+export function useEnvGuide(providerId: string | undefined, os?: EnvGuideOs) {
+ return useQuery({
+ queryKey: localModelsKeys.envGuide(providerId ?? "", os ?? ""),
+ queryFn: () => getEnvGuide(providerId as string, os),
+ enabled: !!providerId,
+ staleTime: Infinity,
+ });
+}
+
+// ---------------------------------------------------------------------------
+// Mutation hooks — each one invalidates what its write changes
+// ---------------------------------------------------------------------------
+
+/** Invalidate every query of the section for one provider. */
+export function useInvalidateLocalModels(providerId: string | undefined) {
+ const qc = useQueryClient();
+ return () =>
+ qc.invalidateQueries({ queryKey: ["local-models", providerId ?? ""] });
+}
+
+export function useSetRole(providerId: string | undefined) {
+ const qc = useQueryClient();
+ return useMutation({
+ mutationFn: ({ role, model }: { role: LocalModelRole; model: string }) =>
+ setRole(providerId as string, role, model),
+ onSuccess: () => {
+ void qc.invalidateQueries({
+ queryKey: localModelsKeys.roles(providerId ?? ""),
+ });
+ void qc.invalidateQueries({
+ queryKey: localModelsKeys.inventory(providerId ?? ""),
+ });
+ },
+ });
+}
+
+export function useSaveModelOptions(providerId: string | undefined) {
+ const qc = useQueryClient();
+ return useMutation({
+ mutationFn: ({
+ name,
+ options,
+ }: {
+ name: string;
+ options: OllamaModelOptions;
+ }) => saveModelOptions(providerId as string, name, options),
+ onSuccess: (_data, { name }) => {
+ void qc.invalidateQueries({
+ queryKey: localModelsKeys.options(providerId ?? "", name),
+ });
+ },
+ });
+}
+
+export function useResetModelOptions(providerId: string | undefined) {
+ const qc = useQueryClient();
+ return useMutation({
+ mutationFn: (name: string) => resetModelOptions(providerId as string, name),
+ onSuccess: (_data, name) => {
+ void qc.invalidateQueries({
+ queryKey: localModelsKeys.options(providerId ?? "", name),
+ });
+ },
+ });
+}
+
+export function useUnloadModel(providerId: string | undefined) {
+ const qc = useQueryClient();
+ return useMutation({
+ mutationFn: (name: string) => unloadModel(providerId as string, name),
+ onSuccess: () => {
+ void qc.invalidateQueries({
+ queryKey: localModelsKeys.inventory(providerId ?? ""),
+ });
+ void qc.invalidateQueries({
+ queryKey: localModelsKeys.server(providerId ?? ""),
+ });
+ },
+ });
+}
+
+export function useDeleteModel(providerId: string | undefined) {
+ const qc = useQueryClient();
+ return useMutation({
+ mutationFn: ({ name, reassign }: { name: string; reassign?: string }) =>
+ deleteModel(providerId as string, name, reassign),
+ onSuccess: () => {
+ void qc.invalidateQueries({
+ queryKey: ["local-models", providerId ?? ""],
+ });
+ },
+ });
+}
+
+export function useSetHfEnabled(providerId: string | undefined) {
+ const qc = useQueryClient();
+ return useMutation({
+ mutationFn: (enabled: boolean) =>
+ setHfEnabled(providerId as string, enabled),
+ onSuccess: () => {
+ void qc.invalidateQueries({
+ queryKey: localModelsKeys.hfEnabled(providerId ?? ""),
+ });
+ },
+ });
+}
+
+export function useStartHfPull(providerId: string | undefined) {
+ return useMutation({
+ mutationFn: (body: HfPullBody) => startHfPull(providerId as string, body),
+ });
+}
+
+export function useStopServer(providerId: string | undefined) {
+ const qc = useQueryClient();
+ return useMutation({
+ mutationFn: () => stopServer(providerId as string),
+ onSuccess: () => {
+ void qc.invalidateQueries({
+ queryKey: localModelsKeys.server(providerId ?? ""),
+ });
+ void qc.invalidateQueries({
+ queryKey: localModelsKeys.inventory(providerId ?? ""),
+ });
+ },
+ });
+}
+
+export function useTestServer(providerId: string | undefined) {
+ return useMutation({
+ mutationFn: (baseUrl: string) => testServer(providerId as string, baseUrl),
+ });
+}
diff --git a/jarvis/ui/web/local_models_routes.py b/jarvis/ui/web/local_models_routes.py
index 6aef248781..5c8e5740e7 100644
--- a/jarvis/ui/web/local_models_routes.py
+++ b/jarvis/ui/web/local_models_routes.py
@@ -1,4 +1,9 @@
-"""REST surface of the "Local models" section: inventory, unload, delete.
+"""REST surface of the "Local models" section.
+
+Inventory, unload and delete; the four roles; per-model options and the
+suggestion for this machine; the public catalogue; Hugging Face GGUF
+browsing (off until switched on); and the server itself (status, stop,
+probe, log, environment guide).
Everything the section shows about what is INSTALLED on the pull-capable
local server (Ollama today) lives here, separate from ``provider_routes.py``
@@ -27,6 +32,13 @@ from fastapi import APIRouter, HTTPException, Query, Request
from pydantic import BaseModel, Field
from jarvis.brain import ollama_inventory as inventory
+from jarvis.brain import (
+ ollama_library,
+ ollama_profiles,
+ ollama_pull,
+ ollama_roles,
+ ollama_runtime,
+)
from jarvis.brain.ollama_inventory import (
OllamaModelInfo,
OllamaModelNotFound,
@@ -34,6 +46,8 @@ from jarvis.brain.ollama_inventory import (
OllamaServerError,
same_model,
)
+from jarvis.core import config as cfg_mod
+from jarvis.core.config import OLLAMA_MODEL_OPTION_KEYS, OllamaModelOptions
from jarvis.ui.web.provider_routes import _require_pull_capable, _resolve_cfg
log = logging.getLogger(__name__)
@@ -372,3 +386,528 @@ def _reassign_roles(cfg: Any, roles: list[str], target: str) -> list[str]:
status_code=500, detail=f"Could not rewrite the roles to {target}: {exc}"
) from exc
return done
+
+
+# ═════════════════════════════════════════════════════════════════════════
+# Roles
+# ═════════════════════════════════════════════════════════════════════════
+
+
+class RoleRow(BaseModel):
+ id: str
+ label_key: str
+ config_key: str
+ #: Configured tag; ``""`` = the plugin discovers one.
+ current: str
+ #: ``current`` is on the server right now.
+ installed: bool
+ required: list[str]
+ recommended_capabilities: list[str]
+ #: Installed tags declaring every required capability.
+ qualifying: list[str]
+ #: The shortlist's pick for this machine (``""`` when it has none).
+ recommended: str
+ writable: bool
+ advanced: bool
+ #: One sentence when the slot is served by something other than Ollama.
+ note: str = ""
+
+
+class RolesResponse(BaseModel):
+ provider: str
+ server: str
+ roles: list[RoleRow]
+ error: str | None = None
+
+
+class RoleSetBody(BaseModel):
+ #: ``""`` = back to discovery (brain roles only).
+ model: str = Field(default="", max_length=200)
+
+
+class RoleSetResponse(BaseModel):
+ ok: bool
+ role: str
+ model: str
+ config_key: str
+ message: str
+
+
+def _role_row(state: ollama_roles.RoleState) -> RoleRow:
+ spec = state.spec
+ return RoleRow(
+ id=spec.id,
+ label_key=spec.label_key,
+ config_key=spec.config_key,
+ current=state.current,
+ installed=state.installed,
+ required=list(spec.required),
+ recommended_capabilities=list(spec.recommended),
+ qualifying=list(state.qualifying),
+ recommended=state.recommended,
+ writable=spec.writable,
+ advanced=spec.advanced,
+ note=state.note,
+ )
+
+
[email protected]("/roles", response_model=RolesResponse)
+async def get_roles(provider_id: str, request: Request) -> RolesResponse:
+ """Every model slot with its pick, what qualifies, and the recommendation."""
+ _require_pull_capable(provider_id)
+ root = _server_root()
+ states, error = await ollama_roles.list_roles(root, _resolve_cfg(request))
+ return RolesResponse(
+ provider=provider_id, server=root, roles=[_role_row(s) for s in states], error=error
+ )
+
+
[email protected]("/roles/{role}", response_model=RoleSetResponse)
+async def set_role(
+ provider_id: str, role: str, body: RoleSetBody, request: Request
+) -> RoleSetResponse:
+ """Assign ``model`` to a role through the config writers; ``""`` = discovery."""
+ _require_pull_capable(provider_id)
+ cfg = _resolve_cfg(request)
+ try:
+ written = ollama_roles.set_role(role, body.model, cfg=cfg)
+ except ValueError as exc:
+ status = 404 if "Unknown role" in str(exc) else 422
+ raise HTTPException(status_code=status, detail=str(exc)) from exc
+ except Exception as exc: # noqa: BLE001 — a failed TOML write is a 500 with the reason
+ log.warning("local-models: role %s -> %s failed: %s", role, body.model, exc)
+ raise HTTPException(status_code=500, detail=f"Could not save the role: {exc}") from exc
+ tag = written["model"]
+ message = (
+ f"{role} now uses {tag}."
+ if tag
+ else f"{role} is back to discovery: Jarvis picks the smallest capable download."
+ )
+ return RoleSetResponse(
+ ok=True, role=role, model=tag, config_key=written["config_key"], message=message
+ )
+
+
+# ═════════════════════════════════════════════════════════════════════════
+# Per-model options
+# ═════════════════════════════════════════════════════════════════════════
+
+
+class OllamaModelOptionsBody(BaseModel):
+ """The PUT body — one field per :data:`OLLAMA_MODEL_OPTION_KEYS`, in order.
+
+ ``tests/unit/core/test_ollama_model_options_parity.py`` pins the field
+ list against the tuple. Values are clamped by the writer, never rejected.
+ """
+
+ num_ctx: int | None = None
+ num_gpu: int | None = None
+ num_thread: int | None = None
+ num_predict: int | None = None
+ temperature: float | None = None
+ top_p: float | None = None
+ top_k: int | None = None
+ min_p: float | None = None
+ repeat_penalty: float | None = None
+ seed: int | None = None
+ stop: list[str] | str | None = None
+ keep_alive: str | int | None = None
+ think: bool | str | None = None
+
+
+assert tuple(OllamaModelOptionsBody.model_fields) == OLLAMA_MODEL_OPTION_KEYS
+
+
+class ModelOptionsResponse(BaseModel):
+ model: str
+ #: Only the knobs that are set.
+ options: dict[str, Any]
+ #: True when ``[brain.providers.ollama.models."<tag>"]`` exists.
+ configured: bool
+ #: The derived alias the brain streams through when a bakeable knob is
+ #: set; ``null`` when the options ride the request alone.
+ profile_alias: str | None = None
+
+
+class SuggestedOptionsResponse(BaseModel):
+ model: str
+ options: dict[str, Any]
+ #: One plain sentence per knob (and one for the memory budget).
+ reasons: list[str]
+ size_gb: float
+ native_context: int | None
+ accelerator_gb: float
+ accelerator_source: str
+ ram_gb: float | None
+
+
+def _options_for(cfg: Any, name: str) -> tuple[str | None, OllamaModelOptions | None]:
+ """``(stored key, options)`` for ``name`` (``:latest`` tolerant)."""
+ provider = _ollama_provider_cfg(cfg)
+ models = getattr(provider, "models", None) or {}
+ if not isinstance(models, dict):
+ return None, None
+ for key, value in models.items():
+ if same_model(str(key), name) and isinstance(value, OllamaModelOptions):
+ return str(key), value
+ return None, None
+
+
+def _options_response(name: str, opts: OllamaModelOptions | None) -> ModelOptionsResponse:
+ if opts is None:
+ return ModelOptionsResponse(model=name, options={}, configured=False)
+ compact = opts.model_dump(exclude_none=True)
+ alias = ollama_profiles.profile_name(name, opts) if ollama_profiles.has_bakeable(opts) else None
+ return ModelOptionsResponse(model=name, options=compact, configured=True, profile_alias=alias)
+
+
[email protected]("/models/{name:path}/options", response_model=ModelOptionsResponse)
+async def get_model_options(provider_id: str, name: str, request: Request) -> ModelOptionsResponse:
+ """The per-model profile as configured (empty when none)."""
+ _require_pull_capable(provider_id)
+ _key, opts = _options_for(_resolve_cfg(request), name)
+ return _options_response(name, opts)
+
+
[email protected]("/models/{name:path}/options", response_model=ModelOptionsResponse)
+async def put_model_options(
+ provider_id: str, name: str, body: OllamaModelOptionsBody, request: Request
+) -> ModelOptionsResponse:
+ """Replace the profile of ``name`` with ``body`` (whole set; nothing set = clear)."""
+ _require_pull_capable(provider_id)
+ tag = name.strip()
+ if not tag:
+ raise HTTPException(status_code=422, detail="A model name is needed.")
+ raw = {k: v for k, v in body.model_dump().items() if v is not None}
+ from jarvis.core import config_writer
+
+ try:
+ written = config_writer.set_ollama_model_options(tag, raw)
+ except ValueError as exc:
+ raise HTTPException(status_code=422, detail=str(exc)) from exc
+ except Exception as exc: # noqa: BLE001 — a failed TOML write is a 500 with the reason
+ log.warning("local-models: options for %s failed: %s", tag, exc)
+ raise HTTPException(status_code=500, detail=f"Could not save the options: {exc}") from exc
+ cfg = _resolve_cfg(request)
+ provider = _ollama_provider_cfg(cfg)
+ opts = OllamaModelOptions.model_validate(written) if written else None
+ if provider is not None and isinstance(getattr(provider, "models", None), dict):
+ stored_key, _old = _options_for(cfg, tag)
+ if stored_key is not None:
+ provider.models.pop(stored_key, None)
+ if opts is not None:
+ provider.models[tag] = opts
+ return _options_response(tag, opts)
+
+
[email protected]("/models/{name:path}/options", response_model=ModelOptionsResponse)
+async def delete_model_options(
+ provider_id: str, name: str, request: Request
+) -> ModelOptionsResponse:
+ """Reset: drop the profile so Ollama's defaults apply again."""
+ _require_pull_capable(provider_id)
+ from jarvis.core import config_writer
+
+ try:
+ config_writer.clear_ollama_model_options(name)
+ except Exception as exc: # noqa: BLE001 — a failed TOML write is a 500 with the reason
+ log.warning("local-models: clearing options for %s failed: %s", name, exc)
+ raise HTTPException(status_code=500, detail=f"Could not reset the options: {exc}") from exc
+ cfg = _resolve_cfg(request)
+ stored_key, _old = _options_for(cfg, name)
+ provider = _ollama_provider_cfg(cfg)
+ if stored_key is not None and provider is not None:
+ provider.models.pop(stored_key, None)
+ return _options_response(name, None)
+
+
[email protected]("/models/{name:path}/suggested-options", response_model=SuggestedOptionsResponse)
+async def get_suggested_options(provider_id: str, name: str) -> SuggestedOptionsResponse:
+ """An advisory profile for ``name`` on THIS machine, with one reason per knob."""
+ _require_pull_capable(provider_id)
+ root = _server_root()
+ try:
+ info = await inventory.get_model(root, name)
+ except OllamaServerError as exc:
+ raise _http_error(exc) from exc
+ accel, source = ollama_pull.accelerator_gb()
+ ram = ollama_pull.total_memory_gb()
+ size_gb = round(info.size_bytes / (1024**3), 2)
+ opts, reasons = ollama_profiles.suggest_options(
+ size_gb=size_gb,
+ native_context=info.context_length,
+ accelerator_gb=accel,
+ source=source,
+ ram_gb=ram,
+ )
+ return SuggestedOptionsResponse(
+ model=info.name,
+ options=opts.model_dump(exclude_none=True),
+ reasons=reasons,
+ size_gb=size_gb,
+ native_context=info.context_length,
+ accelerator_gb=round(accel, 1),
+ accelerator_source=source,
+ ram_gb=ram,
+ )
+
+
+# ═════════════════════════════════════════════════════════════════════════
+# Catalogue
+# ═════════════════════════════════════════════════════════════════════════
+
+
[email protected]("/catalog")
+async def get_catalog(
+ provider_id: str,
+ q: str = Query(default="", max_length=120),
+ sort: str = Query(default="popular", description="popular | newest"),
+ capability: str | None = Query(
+ default=None, description="tools | vision | embedding | thinking"
+ ),
+ limit: int = Query(default=50, ge=1, le=50),
+) -> dict[str, Any]:
+ """Browse ollama.com; ``error`` is a normal outcome offline, never a 5xx."""
+ _require_pull_capable(provider_id)
+ return await ollama_library.search_library(q, sort=sort, capability=capability, limit=limit)
+
+
[email protected]("/catalog/recommended")
+async def get_catalog_recommended(provider_id: str) -> dict[str, Any]:
+ """The curated shortlist ranked for this machine, with its review date."""
+ _require_pull_capable(provider_id)
+ return await ollama_pull.recommendations()
+
+
[email protected]("/catalog/{name:path}/tags")
+async def get_catalog_tags(provider_id: str, name: str) -> dict[str, Any]:
+ """Every tag of one library model with size, quantization, context and fit."""
+ _require_pull_capable(provider_id)
+ return await ollama_library.library_tags(name)
+
+
+# ═════════════════════════════════════════════════════════════════════════
+# Hugging Face (off until switched on)
+# ═════════════════════════════════════════════════════════════════════════
+
+
+class HfEnabledBody(BaseModel):
+ enabled: bool
+
+
+class HfEnabledResponse(BaseModel):
+ enabled: bool
+
+
+class HfPullBody(BaseModel):
+ user: str = Field(max_length=96)
+ repo: str = Field(max_length=96)
+ quant: str | None = Field(default=None, max_length=96)
+
+
+_HF_OFF = (
+ "Hugging Face browsing is switched off. Turn it on under Local models → "
+ "Hugging Face; until then Jarvis makes no request to huggingface.co."
+)
+
+
+def _require_hf(request: Request) -> None:
+ if not cfg_mod.ollama_hf_enabled(_resolve_cfg(request)):
+ raise HTTPException(status_code=404, detail=_HF_OFF)
+
+
[email protected]("/hf/enabled", response_model=HfEnabledResponse)
+async def get_hf_enabled(provider_id: str, request: Request) -> HfEnabledResponse:
+ _require_pull_capable(provider_id)
+ return HfEnabledResponse(enabled=cfg_mod.ollama_hf_enabled(_resolve_cfg(request)))
+
+
[email protected]("/hf/enabled", response_model=HfEnabledResponse)
+async def put_hf_enabled(
+ provider_id: str, body: HfEnabledBody, request: Request
+) -> HfEnabledResponse:
+ """Switch Hugging Face browsing on or off (``[brain.providers.ollama].hf_enabled``)."""
+ _require_pull_capable(provider_id)
+ from jarvis.core import config_writer
+
+ try:
+ config_writer.set_ollama_hf_enabled(body.enabled)
+ except Exception as exc: # noqa: BLE001 — a failed TOML write is a 500 with the reason
+ log.warning("local-models: hf_enabled=%s failed: %s", body.enabled, exc)
+ raise HTTPException(status_code=500, detail=f"Could not save the switch: {exc}") from exc
+ provider = _ollama_provider_cfg(_resolve_cfg(request))
+ if provider is not None:
+ provider.hf_enabled = body.enabled
+ return HfEnabledResponse(enabled=body.enabled)
+
+
[email protected]("/hf/search")
+async def get_hf_search(
+ provider_id: str,
+ request: Request,
+ q: str = Query(default="", max_length=120),
+ sort: str = Query(default="downloads", description="downloads | lastModified | trendingScore"),
+ limit: int = Query(default=30, ge=1, le=100),
+) -> dict[str, Any]:
+ """GGUF repositories on Hugging Face; ``error`` is a sentence, never a 5xx."""
+ _require_pull_capable(provider_id)
+ _require_hf(request)
+ from jarvis.brain import hf_gguf # lazy: only an install that switched HF on imports it
+
+ return await hf_gguf.search(q, sort=sort, limit=limit)
+
+
[email protected]("/hf/{user}/{repo}/files")
+async def get_hf_files(provider_id: str, user: str, repo: str, request: Request) -> dict[str, Any]:
+ """The ``.gguf`` files of one repository with quantization, size and fit."""
+ _require_pull_capable(provider_id)
+ _require_hf(request)
+ from jarvis.brain import hf_gguf
+
+ return await hf_gguf.files(user, repo)
+
+
[email protected]("/hf/pull")
+async def post_hf_pull(provider_id: str, body: HfPullBody, request: Request) -> dict[str, Any]:
+ """Start pulling ``hf.co/<user>/<repo>[:<quant>]`` through the normal pull path."""
+ _require_pull_capable(provider_id)
+ _require_hf(request)
+ from jarvis.brain import hf_gguf
+
+ try:
+ name = hf_gguf.pull_name(body.user, body.repo, body.quant)
+ except ValueError as exc:
+ raise HTTPException(status_code=400, detail=str(exc)) from exc
+ return await ollama_pull.start_pull(name)
+
+
+# ═════════════════════════════════════════════════════════════════════════
+# Server
+# ═════════════════════════════════════════════════════════════════════════
+
+
+class ServerResponse(BaseModel):
+ installed: bool
+ binary: str
+ running: bool
+ version: str
+ detail: str
+ base_url: str
+ host_kind: str
+ models_dir: str
+ running_models: list[RunningModelRow] = Field(default_factory=list)
+ disk_bytes: int = 0
+ loaded_vram_bytes: int = 0
+ #: Sentence when the inventory could not be read while the probe ran.
+ error: str | None = None
+
+
+class ServerActionResponse(BaseModel):
+ ok: bool
+ message: str
+
+
+class ServerTestBody(BaseModel):
+ base_url: str = Field(max_length=300)
+
+
+class ServerProbeResponse(BaseModel):
+ ok: bool
+ version: str
+ latency_ms: int
+ detail: str
+
+
+class ServerLogResponse(BaseModel):
+ lines: list[str]
+
+
+class EnvGuideRow(BaseModel):
+ key: str
+ purpose: str
+ command: str
+ restart: str
+
+
+class EnvGuideResponse(BaseModel):
+ os: str
+ rows: list[EnvGuideRow]
+
+
[email protected]("/server", response_model=ServerResponse)
+async def get_server(provider_id: str) -> ServerResponse:
+ """Runtime picture plus what is loaded and how much disk the downloads take."""
+ _require_pull_capable(provider_id)
+ status = ollama_runtime.runtime_status()
+ root = str(status.get("base_url") or _server_root())
+ running: list[RunningModelRow] = []
+ disk = 0
+ error: str | None = None
+ if status.get("running"):
+ try:
+ disk = await inventory.disk_usage(root)
+ except OllamaServerError as exc:
+ log.info("local-models: disk usage unavailable at %s: %s", root, exc)
+ error = str(exc)
+ running = [RunningModelRow(**asdict(r)) for r in (await _running_by_name(root)).values()]
+ return ServerResponse(
+ installed=bool(status.get("installed")),
+ binary=str(status.get("binary") or ""),
+ running=bool(status.get("running")),
+ version=str(status.get("version") or ""),
+ detail=str(status.get("detail") or ""),
+ base_url=root,
+ host_kind=str(status.get("host_kind") or "local"),
+ models_dir=str(status.get("models_dir") or ""),
+ running_models=running,
+ disk_bytes=disk,
+ loaded_vram_bytes=sum(r.size_vram_bytes for r in running),
+ error=error,
+ )
+
+
+ "/server/stop",
+ response_model=ServerActionResponse,
+ openapi_extra={"x-jarvis-dangerous": True},
+)
+async def post_server_stop(provider_id: str) -> ServerActionResponse:
+ """Stop the Ollama Jarvis itself started — never one started elsewhere."""
+ _require_pull_capable(provider_id)
+ ok, message = ollama_runtime.stop_server()
+ return ServerActionResponse(ok=ok, message=message)
+
+
[email protected]("/server/test", response_model=ServerProbeResponse)
+async def post_server_test(provider_id: str, body: ServerTestBody) -> ServerProbeResponse:
+ """Probe a host before saving it: version and latency, or the reason it failed."""
+ _require_pull_capable(provider_id)
+ probe = await ollama_runtime.probe_host(body.base_url)
+ return ServerProbeResponse(
+ ok=bool(probe.get("ok")),
+ version=str(probe.get("version") or ""),
+ latency_ms=int(str(probe.get("latency_ms") or 0)),
+ detail=str(probe.get("detail") or ""),
+ )
+
+
[email protected]("/server/log", response_model=ServerLogResponse)
+async def get_server_log(
+ provider_id: str, lines: int = Query(default=40, ge=1, le=500)
+) -> ServerLogResponse:
+ """The last lines of the server log Jarvis writes when it starts Ollama."""
+ _require_pull_capable(provider_id)
+ return ServerLogResponse(lines=ollama_runtime.tail_log(lines))
+
+
[email protected]("/server/env-guide", response_model=EnvGuideResponse)
+async def get_server_env_guide(
+ provider_id: str,
+ os: str = Query(default="", description="windows | macos | linux; empty = this OS"),
+) -> EnvGuideResponse:
+ """Copyable per-OS commands for the server's environment variables."""
+ _require_pull_capable(provider_id)
+ rows = ollama_runtime.env_guide(os or None)
+ return EnvGuideResponse(
+ os=ollama_runtime._normalize_os(os or None), rows=[EnvGuideRow(**row) for row in rows]
+ )
diff --git a/tests/unit/ui/web/test_local_models_routes.py b/tests/unit/ui/web/test_local_models_routes.py
index 612332344c..fe928f5821 100644
--- a/tests/unit/ui/web/test_local_models_routes.py
+++ b/tests/unit/ui/web/test_local_models_routes.py
@@ -1,4 +1,7 @@
-"""Local-models routes: inventory, unload, delete — through the fake server.
+"""Local-models routes through the fake server and monkeypatched modules.
+
+Inventory, unload, delete; roles; per-model options and the suggestion;
+catalogue; Hugging Face (off by default); server status and actions.
Pins: the routes exist only on pull-capable cards, the inventory pairs the
downloads with what is loaded and marks which role uses which model, an
@@ -14,10 +17,10 @@ import httpx
import pytest
from fastapi.testclient import TestClient
-from jarvis.brain import ollama_inventory
+from jarvis.brain import ollama_inventory, ollama_library, ollama_pull, ollama_runtime
from jarvis.core import config_writer
from jarvis.core.bus import EventBus
-from jarvis.core.config import BrainProviderConfig, JarvisConfig
+from jarvis.core.config import BrainProviderConfig, JarvisConfig, OllamaModelOptions
from jarvis.ui.web import local_models_routes
from jarvis.ui.web.server import WebServer
from tests.fakes.fake_ollama_server import FakeOllamaServer
@@ -212,3 +215,371 @@ def test_destructive_routes_carry_the_danger_flag() -> None:
}
assert f"{BASE.replace('ollama', '{provider_id}')}/inventory/{{name:path}}/unload" in flagged
assert f"{BASE.replace('ollama', '{provider_id}')}/inventory/{{name:path}}" in flagged
+
+
+# ═════════════════════════════════════════════════════════════════════════
+# Roles
+# ═════════════════════════════════════════════════════════════════════════
+
+
+def shortlist(monkeypatch: pytest.MonkeyPatch) -> list[dict]:
+ rows = [
+ {
+ "id": "qwen3.8:27b",
+ "role": "chat",
+ "vision": True,
+ "size_gb": 18.0,
+ "installed": False,
+ "recommended": True,
+ "recommended_for": ["chat", "vision"],
+ },
+ {
+ "id": "ornith:9b",
+ "role": "coder",
+ "vision": False,
+ "size_gb": 5.6,
+ "installed": False,
+ "recommended": True,
+ "recommended_for": ["coder"],
+ },
+ ]
+
+ async def _recommendations() -> dict:
+ return {"models": rows, "curated_reviewed_on": "2026-08-24", "roles": ["chat"]}
+
+ monkeypatch.setattr(ollama_pull, "recommendations", _recommendations)
+ return rows
+
+
+def test_roles_list_every_slot_with_pick_qualifying_and_recommendation(
+ server: WebServer, fake, shortlist
+) -> None:
+ with TestClient(server.app) as client:
+ resp = client.get(f"{BASE}/roles")
+ assert resp.status_code == 200, resp.text
+ body = resp.json()
+ assert body["error"] is None
+ roles = {r["id"]: r for r in body["roles"]}
+ assert list(roles) == ["chat", "tools_screen", "deep", "embedding", "voice", "ack", "polish"]
+ assert roles["chat"]["current"] == "qwen3.5:4b"
+ assert roles["chat"]["installed"] is True
+ assert roles["chat"]["recommended"] == "qwen3.8:27b"
+ assert roles["chat"]["qualifying"] == ["qwen3.5:4b", "gemma4:12b-it-qat"]
+ assert roles["tools_screen"]["required"] == ["tools", "vision"]
+ assert roles["tools_screen"]["qualifying"] == ["qwen3.5:4b"]
+ assert roles["deep"]["recommended"] == "ornith:9b"
+ assert roles["embedding"]["qualifying"] == ["qwen3-embedding:4b"]
+ assert roles["voice"]["writable"] is False and roles["voice"]["advanced"] is True
+ assert roles["chat"]["label_key"] == "local_models.role_chat"
+
+
+def test_roles_keep_rendering_when_the_server_is_offline(server, fake, shortlist) -> None:
+ fake.offline = True
+ with TestClient(server.app) as client:
+ body = client.get(f"{BASE}/roles").json()
+ assert "did not answer" in body["error"]
+ assert len(body["roles"]) == 7
+ assert body["roles"][0]["qualifying"] == []
+
+
+def test_put_role_writes_through_the_config_writer(server, fake, writes) -> None:
+ with TestClient(server.app) as client:
+ resp = client.put(f"{BASE}/roles/tools_screen", json={"model": "qwen3.5:4b"})
+ back = client.put(f"{BASE}/roles/deep", json={"model": ""})
+ assert resp.status_code == 200, resp.text
+ assert resp.json()["config_key"] == "brain.providers.ollama.tool_model"
+ assert "qwen3.5:4b" in resp.json()["message"]
+ assert "discovery" in back.json()["message"]
+ assert writes == [
+ ("brain", "ollama", {"tool_model": "qwen3.5:4b", "cu_model": "qwen3.5:4b"}),
+ ("brain", "ollama", {"deep_model": ""}),
+ ]
+ provider = server.app.state.config.brain.providers["ollama"]
+ assert provider.tool_model == "qwen3.5:4b"
+ assert provider.deep_model == ""
+
+
+def test_put_role_refuses_read_only_and_unknown_roles(server, fake, writes) -> None:
+ with TestClient(server.app) as client:
+ ro = client.put(f"{BASE}/roles/voice", json={"model": "x"})
+ unknown = client.put(f"{BASE}/roles/nope", json={"model": "x"})
+ empty_embedding = client.put(f"{BASE}/roles/embedding", json={"model": ""})
+ assert ro.status_code == 422
+ assert unknown.status_code == 404
+ assert empty_embedding.status_code == 422
+ assert writes == []
+
+
+# ═════════════════════════════════════════════════════════════════════════
+# Options
+# ═════════════════════════════════════════════════════════════════════════
+
+
+def option_writes(monkeypatch: pytest.MonkeyPatch) -> list[tuple]:
+ """Stand-in for the TOML writer: clamps like the real one, records the call."""
+ calls: list[tuple] = []
+
+ def _set(model: str, options: dict, **_kw) -> dict:
+ calls.append(("set", model, options))
+ return OllamaModelOptions(**options).model_dump(exclude_none=True)
+
+ def _clear(model: str, **_kw) -> bool:
+ calls.append(("clear", model))
+ return True
+
+ monkeypatch.setattr(config_writer, "set_ollama_model_options", _set)
+ monkeypatch.setattr(config_writer, "clear_ollama_model_options", _clear)
+ return calls
+
+
+def test_options_round_trip_through_the_writer_and_the_live_config(
+ server, fake, option_writes
+) -> None:
+ with TestClient(server.app) as client:
+ before = client.get(f"{BASE}/models/qwen3.5:4b/options").json()
+ put = client.put(
+ f"{BASE}/models/qwen3.5:4b/options",
+ json={"num_ctx": 16384, "keep_alive": "30m", "think": False, "stop": "###"},
+ )
+ after = client.get(f"{BASE}/models/qwen3.5:4b/options").json()
+ reset = client.delete(f"{BASE}/models/qwen3.5:4b/options").json()
+ gone = client.get(f"{BASE}/models/qwen3.5:4b/options").json()
+ assert before == {
+ "model": "qwen3.5:4b",
+ "options": {},
+ "configured": False,
+ "profile_alias": None,
+ }
+ assert put.status_code == 200, put.text
+ body = put.json()
+ assert body["configured"] is True
+ assert body["options"] == {
+ "num_ctx": 16384,
+ "stop": ["###"],
+ "keep_alive": "30m",
+ "think": False,
+ }
+ assert body["profile_alias"].startswith("qwen3.5-4b-jarvis-")
+ assert after == body
+ assert reset["configured"] is False
+ assert gone["options"] == {}
+ assert option_writes == [
+ (
+ "set",
+ "qwen3.5:4b",
+ {"num_ctx": 16384, "stop": "###", "keep_alive": "30m", "think": False},
+ ),
+ ("clear", "qwen3.5:4b"),
+ ]
+ assert "qwen3.5:4b" not in server.app.state.config.brain.providers["ollama"].models
+
+
+def test_options_without_a_bakeable_knob_have_no_alias(server, fake, option_writes) -> None:
+ with TestClient(server.app) as client:
+ body = client.put(f"{BASE}/models/qwen3.5:4b/options", json={"temperature": 0.2}).json()
+ assert body["profile_alias"] is None
+ assert body["options"] == {"temperature": 0.2}
+
+
+def test_suggested_options_are_judged_against_this_machine(server, fake, monkeypatch) -> None:
+ monkeypatch.setattr(ollama_pull, "accelerator_gb", lambda: (16.0, "nvidia-smi"))
+ monkeypatch.setattr(ollama_pull, "total_memory_gb", lambda: 32.0)
+ with TestClient(server.app) as client:
+ resp = client.get(f"{BASE}/models/qwen3.5:4b/suggested-options")
+ missing = client.get(f"{BASE}/models/ghost:7b/suggested-options")
+ assert resp.status_code == 200, resp.text
+ body = resp.json()
+ assert body["accelerator_gb"] == 16.0
+ assert body["accelerator_source"] == "nvidia-smi"
+ assert body["ram_gb"] == 32.0
+ assert body["native_context"] == 262_144
+ assert body["options"]["num_gpu"] == -1
+ assert body["options"]["num_ctx"] >= 4096
+ assert any("num_ctx" in r for r in body["reasons"])
+ assert missing.status_code == 404
+
+
+# ═════════════════════════════════════════════════════════════════════════
+# Catalogue
+# ═════════════════════════════════════════════════════════════════════════
+
+
+def test_catalog_forwards_sort_and_capability(server, fake, monkeypatch) -> None:
+ seen: dict = {}
+
+ async def _search(query: str, **kw) -> dict:
+ seen.update({"query": query, **kw})
+ return {
+ "query": query,
+ "sort": kw["sort"],
+ "capability": kw["capability"],
+ "models": [],
+ "error": None,
+ }
+
+ async def _tags(model: str) -> dict:
+ return {"model": model, "tags": [{"tag": "4b", "quantization": ""}], "error": None}
+
+ monkeypatch.setattr(ollama_library, "search_library", _search)
+ monkeypatch.setattr(ollama_library, "library_tags", _tags)
+ with TestClient(server.app) as client:
+ resp = client.get(
+ f"{BASE}/catalog", params={"q": "qwen", "sort": "newest", "capability": "tools"}
+ )
+ tags = client.get(f"{BASE}/catalog/huihui_ai/qwen3-abliterated/tags")
+ assert resp.status_code == 200
+ assert seen == {"query": "qwen", "sort": "newest", "capability": "tools", "limit": 50}
+ assert tags.json()["model"] == "huihui_ai/qwen3-abliterated"
+
+
+def test_catalog_recommended_carries_the_review_date(server, fake, shortlist) -> None:
+ with TestClient(server.app) as client:
+ body = client.get(f"{BASE}/catalog/recommended").json()
+ assert body["curated_reviewed_on"] == "2026-08-24"
+ assert body["models"][0]["recommended_for"] == ["chat", "vision"]
+
+
+# ═════════════════════════════════════════════════════════════════════════
+# Hugging Face
+# ═════════════════════════════════════════════════════════════════════════
+
+
+def test_hf_routes_answer_404_with_a_sentence_while_switched_off(server, fake) -> None:
+ with TestClient(server.app) as client:
+ enabled = client.get(f"{BASE}/hf/enabled").json()
+ search = client.get(f"{BASE}/hf/search", params={"q": "qwen"})
+ files = client.get(f"{BASE}/hf/unsloth/Qwen3.8-27B-GGUF/files")
+ pull = client.post(f"{BASE}/hf/pull", json={"user": "unsloth", "repo": "x"})
+ assert enabled == {"enabled": False}
+ for resp in (search, files, pull):
+ assert resp.status_code == 404
+ assert "switched off" in resp.json()["detail"]
+
+
+def test_hf_switch_persists_and_opens_the_routes(server, fake, monkeypatch) -> None:
+ from jarvis.brain import hf_gguf
+
+ flags: list[bool] = []
+ pulls: list[str] = []
+ monkeypatch.setattr(config_writer, "set_ollama_hf_enabled", lambda v, **_kw: flags.append(v))
+
+ async def _search(q: str, *, sort: str = "downloads", limit: int = 30) -> dict:
+ return {"repos": [{"id": f"{q}/{sort}/{limit}"}], "error": None}
+
+ async def _files(user: str, repo: str) -> dict:
+ return {"files": [{"filename": f"{user}-{repo}.gguf", "quant": "Q4_K_M"}], "error": None}
+
+ async def _start_pull(model: str) -> dict:
+ pulls.append(model)
+ return {"state": "running", "model": model, "message": "Starting"}
+
+ monkeypatch.setattr(hf_gguf, "search", _search)
+ monkeypatch.setattr(hf_gguf, "files", _files)
+ monkeypatch.setattr(ollama_pull, "start_pull", _start_pull)
+ with TestClient(server.app) as client:
+ on = client.put(f"{BASE}/hf/enabled", json={"enabled": True})
+ search = client.get(
+ f"{BASE}/hf/search", params={"q": "qwen", "sort": "lastModified", "limit": 5}
+ )
+ files = client.get(f"{BASE}/hf/unsloth/Qwen3.8-27B-GGUF/files")
+ pull = client.post(
+ f"{BASE}/hf/pull",
+ json={"user": "unsloth", "repo": "Qwen3.8-27B-GGUF", "quant": "Q4_K_M"},
+ )
+ bad = client.post(f"{BASE}/hf/pull", json={"user": "../etc", "repo": "x"})
+ assert on.json() == {"enabled": True}
+ assert flags == [True]
+ assert server.app.state.config.brain.providers["ollama"].hf_enabled is True
+ assert search.json()["repos"] == [{"id": "qwen/lastModified/5"}]
+ assert files.json()["files"][0]["filename"] == "unsloth-Qwen3.8-27B-GGUF.gguf"
+ assert pull.json()["state"] == "running"
+ assert pulls == ["hf.co/unsloth/Qwen3.8-27B-GGUF:Q4_K_M"]
+ assert bad.status_code == 400
+
+
+# ═════════════════════════════════════════════════════════════════════════
+# Server
+# ═════════════════════════════════════════════════════════════════════════
+
+
+def _status(running: bool) -> dict:
+ return {
+ "installed": True,
+ "binary": "/usr/local/bin/ollama",
+ "running": running,
+ "version": "0.32.15" if running else "",
+ "detail": "Ollama is running (version 0.32.15)."
+ if running
+ else "Ollama is installed but not running.",
+ "base_url": ROOT,
+ "host_kind": "local",
+ "models_dir": "/home/me/.ollama/models",
+ }
+
+
+def test_server_status_pairs_the_runtime_with_what_is_loaded(server, fake, monkeypatch) -> None:
+ monkeypatch.setattr(ollama_runtime, "runtime_status", lambda: _status(True))
+ fake.load("qwen3.5:4b", size_vram=3_000_000_000)
+ with TestClient(server.app) as client:
+ body = client.get(f"{BASE}/server").json()
+ assert body["running"] is True
+ assert body["version"] == "0.32.15"
+ assert body["host_kind"] == "local"
+ assert body["models_dir"].endswith("models")
+ assert [r["name"] for r in body["running_models"]] == ["qwen3.5:4b"]
+ assert body["loaded_vram_bytes"] == 3_000_000_000
+ assert body["disk_bytes"] == 3_400_000_000 + 7_200_000_000 + 2_500_000_000
+ assert body["error"] is None
+
+
+def test_server_status_skips_the_inventory_when_stopped(server, fake, monkeypatch) -> None:
+ monkeypatch.setattr(ollama_runtime, "runtime_status", lambda: _status(False))
+ with TestClient(server.app) as client:
+ body = client.get(f"{BASE}/server").json()
+ assert body["running"] is False
+ assert body["running_models"] == []
+ assert body["disk_bytes"] == 0
+ assert fake.calls == []
+
+
+def test_server_stop_test_log_and_env_guide(server, fake, monkeypatch) -> None:
+ monkeypatch.setattr(
+ ollama_runtime, "stop_server", lambda: (False, "This Ollama was not started by Jarvis.")
+ )
+ monkeypatch.setattr(
+ ollama_runtime, "tail_log", lambda lines=40: [f"line {i}" for i in range(lines)]
+ )
+
+ async def _probe(base_url: str, **_kw) -> dict:
+ return {
+ "ok": True,
+ "version": "0.32.15",
+ "latency_ms": 12,
+ "detail": f"Ollama answered at {base_url}.",
+ }
+
+ monkeypatch.setattr(ollama_runtime, "probe_host", _probe)
+ with TestClient(server.app) as client:
+ stop = client.post(f"{BASE}/server/stop").json()
+ probe = client.post(f"{BASE}/server/test", json={"base_url": "gpu-box:11434"}).json()
+ log_ = client.get(f"{BASE}/server/log", params={"lines": 3}).json()
+ guide = client.get(f"{BASE}/server/env-guide", params={"os": "macos"}).json()
+ own = client.get(f"{BASE}/server/env-guide").json()
+ assert stop == {"ok": False, "message": "This Ollama was not started by Jarvis."}
+ assert probe["ok"] is True and probe["latency_ms"] == 12 and "gpu-box" in probe["detail"]
+ assert log_["lines"] == ["line 0", "line 1", "line 2"]
+ assert guide["os"] == "macos"
+ assert [r["key"] for r in guide["rows"]][:2] == ["OLLAMA_HOST", "OLLAMA_MODELS"]
+ assert all(r["command"].startswith("launchctl setenv") for r in guide["rows"])
+ assert own["os"] in {"windows", "macos", "linux"}
+
+
+def test_server_stop_carries_the_danger_flag() -> None:
+ flagged = {
+ route.path
+ for route in local_models_routes.router.routes
+ if (getattr(route, "openapi_extra", None) or {}).get("x-jarvis-dangerous")
+ }
+ assert f"{BASE.replace('ollama', '{provider_id}')}/server/stop" in flagged