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.

42.1 KB
Raw Blame
/**
 * Fetch helpers and React Query hooks for the "Local models" section.
 *
 * Endpoints: `dodaios/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 {
  keepPreviousData,
  type QueryClient,
  useMutation,
  useQuery,
  useQueryClient,
} from "@tanstack/react-query";
import { useEffect, useMemo } from "react";

import {
  clearOverviewSnapshot,
  readOverviewSnapshot,
  writeOverviewSnapshot,
} from "../lib/localModelsSnapshot";
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 five writable slots (voice = the managed voice server's own brain). */
export type LocalModelRole = "chat" | "voice" | "tools_screen" | "deep" | "embedding";
/** Every role row the backend renders, read-only ones included. */
export type LocalModelRoleId = LocalModelRole | "ack" | "polish";

export interface RunningModelRow {
  name: string;
  size_bytes: number;
  size_vram_bytes: number;
  expires_at: string;
  context_length: number | null;
  digest: string;
  /** The download this entry's weights belong to (an alias folded back). */
  base_tag?: string;
  /** "model" | "tune_profile" | "voice_profile". */
  kind?: string;
}

export interface LocalModelRow {
  name: string;
  /**
   * Readable parts from the backend's `ollama_names.describe`: the model
   * line ("Qwen 3.5"), the line with its size ("Qwen 3.5 4B"), the size
   * ("4B"), the quantisation ("Q4_K_M"), the source namespace of an import
   * ("hf.co/unsloth") and the tag's variant markers ("it-qat").
   */
  display_name?: string;
  display_label?: string;
  params_label?: string;
  quant_label?: string;
  source?: string;
  variant?: 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[];
  /** The download or one of its aliases sits in memory; `loaded_as` names which. */
  loaded: boolean;
  loaded_as?: string;
  size_vram_bytes: number;
  /** What /api/ps reports as the loaded size (weights + context). */
  loaded_size_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
// ---------------------------------------------------------------------------

/** The backend's ONE verdict on a model doing a job (`ollama_roles.FITS`). */
export type RoleFit = "fits" | "slow" | "unfit" | "unknown";

/** One installed download judged for one job — the picker's row. */
export interface RoleChoice {
  tag: string;
  fit: RoleFit | string;
  /** Short clause saying why; "" when it fits. */
  reason: string;
}

/** A shortlist entry that would do the job here and is not on disk. */
export interface RoleDownload {
  tag: string;
  label: string;
  size_gb: number;
  /** "comfortable" | "tight" | "unknown" — the shortlist's own verdict. */
  fit: string;
  note: string;
}

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;
  /** "card" | "row" | "footnote" — where the section shows the role. */
  layout?: "card" | "row" | "footnote" | string;
  /** Configured tag; "" = the plugin discovers one. */
  current: string;
  /** `current` is on the server right now. */
  installed: boolean;
  /**
   * The verdict on `current`: a RoleFit, "absent" when configured but not on
   * the server, "" when nothing is set.
   */
  current_fit?: RoleFit | "absent" | "" | string;
  current_reason?: string;
  required: string[];
  recommended_capabilities: string[];
  /** Installed tags that can do the job (fits or slow). */
  qualifying: string[];
  /** Every installed download with its verdict, inventory order. */
  choices?: RoleChoice[];
  /** Shortlist downloads that would do the job on this machine. */
  downloads?: RoleDownload[];
  /**
   * The pick for this machine: the best qualifying INSTALLED download, or
   * the shortlist's download when nothing installed qualifies; "" when
   * neither has one.
   */
  recommended: string;
  /** One backend sentence saying why `recommended` is the pick; "" when none. */
  recommended_reason?: string;
  writable: boolean;
  advanced: boolean;
  /** Sentence when the slot is served by something other than Ollama. */
  note: string;
  /** The voice brain's effective context on this machine (voice role only). */
  context_tokens?: number | null;
  /** "automatic" (sized from memory) | "manual" (set in Tune) | "". */
  context_source?: "" | "automatic" | "manual";
  /**
   * The size class this job prefers, in GB (the voice brain stays under 6 so
   * a call answers within a breath); null/absent when the job has none.
   */
  max_size_gb?: number | null;
  /** The smallest native context that can do the job; null = no floor. */
  min_context_tokens?: number | null;
}

export interface IdleReleaseResponse {
  /** Minutes of voice idleness before the local stack frees memory; 0 = never. */
  minutes: number;
}

/** One distinct download across the roles, with what it costs loaded. */
export interface ResidentItem {
  tag: string;
  display_label: string;
  roles: LocalModelRole[];
  weights_gb: number;
  context_gb: number;
  context_tokens: number | null;
  loaded: boolean;
}

/** What graphics memory holds when every job is loaded at once. */
export interface ResidentPayload {
  items: ResidentItem[];
  /** Kept free beside the voice brain for local speech in/out. */
  reserve_gb: number;
  total_gb: number;
  accelerator_gb: number;
  over: boolean;
}

export interface RolesResponse {
  provider: string;
  server: string;
  roles: RoleRow[];
  resident?: ResidentPayload;
  error: string | null;
}

/** Mirror of `AutostartResponse` (`GET/PUT …/runtime/autostart`). */
export interface AutostartResponse {
  /** `[brain.providers.ollama].autostart` — start the server with Jarvis. */
  enabled: boolean;
  /** Something in this install runs on the local server right now. */
  in_use: boolean;
  /** One backend sentence: what the boot task would do and why. */
  reason: string;
}

/** One step of `POST …/verify`; `ok: null` = not run (role unset / server down). */
export interface VerifyStep {
  id: "server" | "chat" | "voice" | "tools_screen" | "embedding" | string;
  ok: boolean | null;
  model: string;
  detail: string;
  ms: number;
}

/** Mirror of `VerifyResponse` (`POST …/verify`). */
export interface VerifyResponse {
  ok: boolean;
  status: "ok" | "needs_setup" | "error" | string;
  reason: string;
  steps: VerifyStep[];
}

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;
  /** Spawned by this install and not answering yet — shown as "Starting". */
  starting: 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[];
}

// ---------------------------------------------------------------------------
// Wire types — overview (one round-trip for the whole Simple page)
// ---------------------------------------------------------------------------

/**
 * Mirror of `OverviewResponse` in `dodaios/ui/web/local_models_routes.py`
 * (`GET …/local-models/overview`). A Python parity test reads these six
 * field names — keep them verbatim.
 */
export interface OverviewResponse {
  server: ServerResponse;
  roles: RolesResponse;
  inventory: InventoryResponse;
  recommended: CatalogRecommendedResponse;
  /** "live" = built for this request; "cache" = a stored snapshot, refresh underway. */
  source: "live" | "cache";
  /** Epoch seconds the payload was built. */
  fetched_at: number;
}

// ---------------------------------------------------------------------------
// Fetch helpers
// ---------------------------------------------------------------------------

/** A non-2xx answer, with the status kept so callers can branch on it. */
export class HttpError extends Error {
  readonly status: number;
  constructor(status: number, message: string) {
    super(message);
    this.name = "HttpError";
    this.status = status;
  }
}

/** 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 HttpError(
        res.status,
        (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 getIdleRelease(
  providerId: string,
): Promise<IdleReleaseResponse> {
  return request(`${base(providerId)}/runtime/idle-release`);
}

export async function setIdleRelease(
  providerId: string,
  minutes: number,
): Promise<IdleReleaseResponse> {
  return request(
    `${base(providerId)}/runtime/idle-release`,
    {
      method: "PUT",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ minutes }),
    },
    WRITE_TIMEOUT_MS,
  );
}

export async function getAutostart(
  providerId: string,
): Promise<AutostartResponse> {
  return request(`${base(providerId)}/runtime/autostart`);
}

export async function setAutostart(
  providerId: string,
  enabled: boolean,
): Promise<AutostartResponse> {
  return request(
    `${base(providerId)}/runtime/autostart`,
    json("PUT", { enabled }),
    WRITE_TIMEOUT_MS,
  );
}

/** Three real round trips: the server, a chat answer, an embedding. */
const VERIFY_TIMEOUT_MS = 120_000;

export async function verifySetup(providerId: string): Promise<VerifyResponse> {
  return request(
    `${base(providerId)}/verify`,
    { method: "POST" },
    VERIFY_TIMEOUT_MS,
  );
}

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}`);
}

// overview

/**
 * The whole Simple page in one round-trip. A backend that predates the route
 * (a CLI-only install that lags the UI bundle) answers 404: then the four
 * legacy reads are composed here so the page still paints — that fallback is
 * permanent, not a migration shim.
 */
export async function getOverview(
  providerId: string,
  fresh = false,
): Promise<OverviewResponse> {
  try {
    return await request<OverviewResponse>(
      `${base(providerId)}/overview${fresh ? "?fresh=1" : ""}`,
    );
  } catch (err) {
    if (!(err instanceof HttpError) || err.status !== 404) throw err;
  }
  const [server, roles, inventory, recommended] = await Promise.all([
    getServer(providerId),
    getRoles(providerId),
    getInventory(providerId),
    getCatalogRecommended(providerId),
  ]);
  return {
    server,
    roles,
    inventory,
    recommended,
    source: "live",
    fetched_at: Math.floor(Date.now() / 1000),
  };
}

// ---------------------------------------------------------------------------
// Query keys
// ---------------------------------------------------------------------------

export const localModelsKeys = {
  all: ["local-models"] as const,
  overview: (p: string) => ["local-models", p, "overview"] 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,
  idleRelease: (p: string) => ["local-models", p, "idle-release"] as const,
  autostart: (p: string) => ["local-models", p, "autostart"] 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
// ---------------------------------------------------------------------------

/**
 * How long an unused section query stays in memory. A tab switch inside the
 * section, or leaving and coming back within half an hour, must reopen warm
 * instead of re-sweeping the server.
 */
export const SECTION_GC_MS = 30 * 60_000;

/** Options for the overview query — shared by `useOverview` and the idle prefetch. */
export function overviewQueryOptions(providerId: string) {
  return {
    queryKey: localModelsKeys.overview(providerId),
    queryFn: () => getOverview(providerId),
    staleTime: 5_000,
    gcTime: SECTION_GC_MS,
  };
}

/**
 * The Simple page's data, painted first from the on-disk snapshot and
 * refreshed at once. While the snapshot is on screen and the refresh runs,
 * `data.source === "cache"` and `isFetching` is true — the panel shows
 * "Checking…". Every fresh payload is written back to the snapshot and
 * seeds the legacy per-section queries so Catalogue / Models / Tune open warm.
 */
export function useOverview(providerId: string | undefined, enabled = true) {
  const qc = useQueryClient();
  const id = providerId ?? "";
  const snapshot = useMemo(
    () => (providerId ? readOverviewSnapshot(providerId) : null),
    [providerId],
  );
  const query = useQuery({
    ...overviewQueryOptions(id),
    enabled: enabled && !!providerId,
    initialData: snapshot ?? undefined,
    initialDataUpdatedAt: snapshot ? snapshot.fetched_at * 1000 : undefined,
    placeholderData: keepPreviousData,
    refetchInterval: 15_000,
  });

  const data = query.data;
  useEffect(() => {
    if (!providerId || !data) return;
    const updatedAt = data.fetched_at * 1000;
    qc.setQueryData(localModelsKeys.server(providerId), data.server, {
      updatedAt,
    });
    qc.setQueryData(localModelsKeys.roles(providerId), data.roles, {
      updatedAt,
    });
    qc.setQueryData(localModelsKeys.inventory(providerId), data.inventory, {
      updatedAt,
    });
    qc.setQueryData(
      localModelsKeys.recommended(providerId),
      data.recommended,
      { updatedAt },
    );
    // The snapshot we painted from is already on disk.
    if (data !== snapshot && data.source === "live")
      writeOverviewSnapshot(providerId, data);
  }, [data, providerId, qc, snapshot]);

  return query;
}

/** 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,
    gcTime: SECTION_GC_MS,
  });
}

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,
    gcTime: SECTION_GC_MS,
  });
}

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,
    gcTime: SECTION_GC_MS,
  });
}

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,
    gcTime: SECTION_GC_MS,
  });
}

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,
    gcTime: SECTION_GC_MS,
  });
}

/** 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,
    gcTime: SECTION_GC_MS,
    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,
    gcTime: SECTION_GC_MS,
  });
}

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,
    gcTime: SECTION_GC_MS,
  });
}

export function useHfEnabled(providerId: string | undefined) {
  return useQuery({
    queryKey: localModelsKeys.hfEnabled(providerId ?? ""),
    queryFn: () => getHfEnabled(providerId as string),
    enabled: !!providerId,
    staleTime: 60_000,
    gcTime: SECTION_GC_MS,
  });
}

/** 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,
    gcTime: SECTION_GC_MS,
    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,
    gcTime: SECTION_GC_MS,
  });
}

export function useServer(providerId: string | undefined, enabled = true) {
  return useQuery({
    queryKey: localModelsKeys.server(providerId ?? ""),
    queryFn: () => getServer(providerId as string),
    enabled: enabled && !!providerId,
    // A boot is over in seconds, so the "Starting" dot polls every second
    // while it lasts; a settled server goes back to the slow beat. Fifteen
    // seconds of a stale "Starting" reads as a hang (BUG-204).
    refetchInterval: (query) =>
      (query.state.data as ServerResponse | undefined)?.starting ? 1_000 : 15_000,
    staleTime: 5_000,
    gcTime: SECTION_GC_MS,
  });
}

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,
    gcTime: SECTION_GC_MS,
  });
}

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,
    gcTime: SECTION_GC_MS,
  });
}

// ---------------------------------------------------------------------------
// Mutation hooks — each one invalidates what its write changes
// ---------------------------------------------------------------------------

/** Invalidate every query of the section for one provider. */
/**
 * Refetch the overview LIVE after a change this section made itself.
 *
 * A plain invalidation would re-read `GET …/overview`, which answers the
 * disk snapshot first (`source: "cache"`) and refreshes in the background —
 * so the row the user just changed would sit on its old value until the
 * next poll. `?fresh=1` skips the cache; the answer replaces the cached
 * payload under the same key, so every panel repaints from it.
 */
export async function refetchOverviewFresh(
  qc: QueryClient,
  providerId: string,
): Promise<OverviewResponse | undefined> {
  const queryKey = localModelsKeys.overview(providerId);
  try {
    // A poll may be in flight with the cache-first answer; `fetchQuery`
    // would join it instead of running the fresh read and the stale payload
    // would land AFTER the write. Cancel it first, then read live.
    await qc.cancelQueries({ queryKey });
    return await qc.fetchQuery({
      queryKey,
      queryFn: () => getOverview(providerId, true),
      staleTime: 0,
    });
  } catch (err) {
    // The write already landed; a failed re-read only delays the repaint
    // until the next poll, so it is logged rather than surfaced.
    console.warn("[local-models] fresh overview failed", err);
    return undefined;
  }
}

/** "qwen3.5" and "qwen3.5:latest" are the same download. */
export function canonicalModelName(name: string): string {
  return name.endsWith(":latest") ? name.slice(0, -":latest".length) : name;
}

/**
 * The overview as it will read once `role` is on `model` — the optimistic
 * shape a pick shows while the write and the fresh read are underway.
 */
export function withRolePick(
  overview: OverviewResponse,
  role: LocalModelRole,
  model: string,
): OverviewResponse {
  const installed =
    model !== "" &&
    overview.inventory.models.some(
      (m) => canonicalModelName(m.name) === canonicalModelName(model),
    );
  return {
    ...overview,
    roles: {
      ...overview.roles,
      roles: overview.roles.roles.map((r) =>
        r.id === role ? { ...r, current: model, installed } : r,
      ),
    },
  };
}

export function useInvalidateLocalModels(providerId: string | undefined) {
  const qc = useQueryClient();
  return () => {
    const id = providerId ?? "";
    void refetchOverviewFresh(qc, id);
    return qc.invalidateQueries({
      queryKey: ["local-models", id],
      // The overview is being fetched fresh above; refetching it again
      // here would race that answer with a cache-first one.
      predicate: (q) =>
        !(q.queryKey.length === 3 && q.queryKey[2] === "overview"),
    });
  };
}

/**
 * Throw away everything the section has cached and read it again from the
 * server — the "Refresh" button behind the section header.
 *
 * `useInvalidateLocalModels` refetches, but it cannot help against the one
 * state a user actually gets stuck in: a painted snapshot taken while the
 * server was silent. That snapshot is `initialData`, so it survives a
 * refetch failure and keeps a wiped-looking machine on screen. Clearing it
 * first makes the button mean what it says (BUG-188).
 */
export function useReloadLocalModels(providerId: string | undefined) {
  const qc = useQueryClient();
  return async () => {
    const id = providerId ?? "";
    if (!id) return;
    clearOverviewSnapshot(id);
    await qc.cancelQueries({ queryKey: ["local-models", id] });
    qc.removeQueries({ queryKey: ["local-models", id] });
    await refetchOverviewFresh(qc, id);
  };
}

export function useSetRole(providerId: string | undefined) {
  const qc = useQueryClient();
  const id = providerId ?? "";
  const overviewKey = localModelsKeys.overview(id);
  return useMutation({
    mutationFn: ({ role, model }: { role: LocalModelRole; model: string }) =>
      setRole(providerId as string, role, model),
    // The picker is a controlled input bound to the overview. Without this
    // it snapped back to the OLD model the instant a pick was made and
    // stayed there until the fresh read landed (one to three seconds on a
    // live build) — which reads as "my pick was thrown away". The cache
    // shows the pick at once; a refused write rolls it back.
    onMutate: async ({ role, model }) => {
      await qc.cancelQueries({ queryKey: overviewKey });
      const previous = qc.getQueryData<OverviewResponse>(overviewKey);
      if (previous)
        qc.setQueryData(overviewKey, withRolePick(previous, role, model));
      return { previous };
    },
    onError: (_err, _vars, context) => {
      if (context?.previous) qc.setQueryData(overviewKey, context.previous);
    },
    onSettled: () => {
      void qc.invalidateQueries({ queryKey: localModelsKeys.roles(id) });
      void qc.invalidateQueries({ queryKey: localModelsKeys.inventory(id) });
      void refetchOverviewFresh(qc, id);
    },
  });
}

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 ?? ""),
      });
      void qc.invalidateQueries({
        queryKey: localModelsKeys.overview(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 ?? ""),
      });
      void qc.invalidateQueries({
        queryKey: localModelsKeys.overview(providerId ?? ""),
      });
    },
  });
}

export function useIdleRelease(providerId: string | undefined) {
  return useQuery({
    queryKey: localModelsKeys.idleRelease(providerId ?? ""),
    queryFn: () => getIdleRelease(providerId as string),
    enabled: !!providerId,
    gcTime: SECTION_GC_MS,
  });
}

export function useSetIdleRelease(providerId: string | undefined) {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: (minutes: number) => setIdleRelease(providerId as string, minutes),
    onSuccess: () => {
      void qc.invalidateQueries({
        queryKey: localModelsKeys.idleRelease(providerId ?? ""),
      });
    },
  });
}

export function useAutostart(providerId: string | undefined) {
  return useQuery({
    queryKey: localModelsKeys.autostart(providerId ?? ""),
    queryFn: () => getAutostart(providerId as string),
    enabled: !!providerId,
    gcTime: SECTION_GC_MS,
  });
}

export function useSetAutostart(providerId: string | undefined) {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: (enabled: boolean) =>
      setAutostart(providerId as string, enabled),
    onSuccess: (data) => {
      qc.setQueryData(localModelsKeys.autostart(providerId ?? ""), data);
    },
  });
}

/** The on-demand proof; the sidebar badge follows the health record it writes. */
export function useVerifySetup(providerId: string | undefined) {
  return useMutation({
    mutationFn: () => verifySetup(providerId as string),
  });
}

export function useTestServer(providerId: string | undefined) {
  return useMutation({
    mutationFn: (baseUrl: string) => testServer(providerId as string, baseUrl),
  });
}