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.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.pyindex 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-capablelocal server (Ollama today) lives here, separate from ``provider_routes.py``@@ -27,6 +32,13 @@ from fastapi import APIRouter, HTTPException, Query, Requestfrom pydantic import BaseModel, Fieldfrom 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, OllamaModelOptionsfrom jarvis.ui.web.provider_routes import _require_pull_capable, _resolve_cfglog = 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 excreturn 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.pyindex 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 thedownloads with what is loaded and marks which role uses which model, an@@ -14,10 +17,10 @@ import httpximport pytestfrom fastapi.testclient import TestClient-from jarvis.brain import ollama_inventory+from jarvis.brain import ollama_inventory, ollama_library, ollama_pull, ollama_runtimefrom jarvis.core import config_writerfrom jarvis.core.bus import EventBus-from jarvis.core.config import BrainProviderConfig, JarvisConfig+from jarvis.core.config import BrainProviderConfig, JarvisConfig, OllamaModelOptionsfrom jarvis.ui.web import local_models_routesfrom jarvis.ui.web.server import WebServerfrom 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 flaggedassert 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