Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

42.4 KB
Raw Blame
/*
 *  Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

import { LLMFactory } from '@/constants/llm';
import { useQueryClient } from '@tanstack/react-query';
import {
  LlmKeys,
  useAddInstanceModel,
  useDeleteInstanceModels,
  useListProviderModels,
  usePatchInstanceModel,
  useUpdateProviderInstance,
  useVerifyProviderConnection,
} from '@/hooks/use-llm-request';
import { IInstanceModel, IProviderInstance } from '@/interfaces/database/llm';
import { IModelInfo, IProviderModelItem } from '@/interfaces/request/llm';
import llmService from '@/services/llm-service';
import { modelNameKey } from '@/utils/llm-util';
import { hasProviderCredentialInput } from '../../provider-schema/field-config/utils';
import { getProviderConfig } from '../../provider-schema/field-config/get-provider-config';
import {
  applySavedCredentialEdits,
  buildApiKeyValue,
  SAVED_CREDENTIAL_MASK,
} from '../hooks';
import {
  Dispatch,
  SetStateAction,
  useCallback,
  useEffect,
  useMemo,
  useRef,
  useState,
} from 'react';
import { sortModelTypes } from '../available-models';
import { useCustomModelFields } from '../use-custom-model-fields';
import { ModelsSectionProps, VerifyStatus } from './interface';
import {
  SavedProviderConfigFieldSet,
  SavedProviderConfigFields,
  hasUnsavedProviderCredential,
} from '../saved-provider-config';

// ---------------------------------------------------------------------------
// Constants
// ---------------------------------------------------------------------------

/** Feature keys that mark a model as supporting tool/function calls. */
const TOOL_FEATURE_KEYS = ['is_tools', 'tool_call', 'tools', 'function_call'];

/** Sentinel instance name used by draft (unsaved) provider cards. */
export const DRAFT_INSTANCE_SENTINEL = '__draft__';

/**
 * Providers whose model listing is meaningful only when an api-key exists
 * (typed into the draft form or returned with the saved instance details).
 * Opening their cards without a key would fire a list request the upstream
 * rejects, so — like VolcEngine — the auto-fetch waits for the key.
 */
export const API_KEY_GATED_LIST_PROVIDERS: string[] = [
  LLMFactory.SystemOne,
  LLMFactory.RAGcon,
  LLMFactory.VolcEngine,
  LLMFactory.DaoXE,
  LLMFactory.RadeonCloud,
  LLMFactory.DemonRoute,
];

// ---------------------------------------------------------------------------
// Pure helpers (no React state, easy to test)
// ---------------------------------------------------------------------------

/** True when `features` contains any of {@link TOOL_FEATURE_KEYS}. */
export const hasToolFeature = (
  features: string[] | null | undefined,
): boolean =>
  Array.isArray(features) &&
  features.some((f) => TOOL_FEATURE_KEYS.includes(f));

/**
 * Normalize the assorted shapes returned by the backend for a model's
 * `model_types` into a plain `string[]`.
 *  - already an array → as-is
 *  - a single string   → wrapped
 *  - nullish / other   → []
 */
export const normalizeModelTypes = (raw: unknown): string[] =>
  Array.isArray(raw) ? raw : raw ? [raw as string] : [];

/**
 * Build an `IModelInfo[]` (the shape the PUT
 * `/providers/{name}/instances/{name}` endpoint expects) from a list of
 * provider model items. `features` is forwarded via `extra` so the backend
 * can persist per-model flags such as `is_tools`.
 */
export const buildModelInfo = (
  items: IProviderModelItem[],
  // New (draft) instances default every model to tool-calling enabled;
  // an explicit per-model `extra.is_tools` below still overrides it.
  defaultToolsEnabled = false,
): IModelInfo[] =>
  items.map((m) => ({
    model_name: m.name,
    model_type: m.model_types ?? [],
    max_tokens: m.max_tokens ?? 0,
    extra: {
      is_tools: defaultToolsEnabled || hasToolFeature(m.features),
      ...(m.extra ?? {}),
    },
  }));

/** Resolved credentials for catalog / verify / batch calls.
 *  `baseUrl` is `undefined` when the provider's form has no `base_url`
 *  field (e.g. VolcEngine, Google Cloud) so the auto-fetch gate can
 *  distinguish "no base_url field" from "base_url field exists but is
 *  empty". */
export type ResolvedCreds = {
  apiKey: string | object;
  apiKeyConfig?: Record<string, unknown>;
  baseUrl: string | undefined;
  region?: string;
  hasStoredCredentials?: boolean;
  credentialChanged?: boolean;
};

function isVisibleSavedConfigField(
  providerName: string,
  field: { name: string; shouldRender?: string | ((values: any) => boolean) },
  values: Record<string, any>,
  hasSavedInstance: boolean,
): boolean {
  const shouldRender = field.shouldRender;
  if (!shouldRender) return true;
  if (typeof shouldRender === 'function') return shouldRender(values);
  if (shouldRender === 'hideWhenInstanceExists') return !hasSavedInstance;
  if (shouldRender === 'showGroupId') {
    return providerName.toLowerCase() === LLMFactory.MiniMax.toLowerCase();
  }
  return true;
}

// ---------------------------------------------------------------------------
// 1. useResolveCreds — resolve api_key / base_url from host form or instance
// ---------------------------------------------------------------------------

export function useResolveCreds(
  providerName: string,
  instance: IProviderInstance | undefined,
  getFormValues: ModelsSectionProps['getFormValues'],
) {
  // Prefer the live values from the host card's form (so the user can
  // verify with an api_key they have just typed but not yet saved); fall
  // back to the persisted instance fields when no form getter is wired up.
  const resolveCreds = useCallback((): ResolvedCreds => {
    const fv = getFormValues?.() ?? {};
    const credentialStatus = instance?.credential_status ?? {};
    const savedConfig = instance?.api_key_config ?? {};
    const providerFields = getProviderConfig(providerName).fields;
    const visibleConfigFields = new Set(
      providerFields
        .filter(
          (field) =>
            SavedProviderConfigFieldSet.has(field.name) &&
            isVisibleSavedConfigField(
              providerName,
              field,
              fv,
              Boolean(instance?.id),
            ),
        )
        .map((field) => field.name),
    );
    const apiKeyConfig: Record<string, unknown> = {};
    for (const field of SavedProviderConfigFields) {
      if (!visibleConfigFields.has(field)) continue;
      if (!Object.prototype.hasOwnProperty.call(fv, field)) continue;
      const value = fv[field];
      if (value === SAVED_CREDENTIAL_MASK) continue;
      if (value === '' || value === undefined || value === null) {
        const savedValue = savedConfig[field];
        if (
          savedValue !== undefined &&
          savedValue !== null &&
          savedValue !== ''
        ) {
          apiKeyConfig[field] = null;
        }
        continue;
      }
      apiKeyConfig[field] = value;
    }
    if (providerName === LLMFactory.Bedrock) {
      let bedrockConfig: unknown = buildApiKeyValue(fv, credentialStatus);
      if (
        bedrockConfig &&
        typeof bedrockConfig === 'object' &&
        'api_key' in bedrockConfig
      ) {
        bedrockConfig = (bedrockConfig as Record<string, unknown>).api_key;
      }
      if (bedrockConfig && typeof bedrockConfig === 'object') {
        for (const field of ['auth_mode', 'aws_role_arn', 'bedrock_region']) {
          const value = (bedrockConfig as Record<string, unknown>)[field];
          if (value === undefined || value === SAVED_CREDENTIAL_MASK) continue;
          const savedValue = savedConfig[field];
          if (value === '' || value === null) {
            if (
              savedValue !== undefined &&
              savedValue !== null &&
              savedValue !== ''
            ) {
              apiKeyConfig[field] = null;
            }
            continue;
          }
          apiKeyConfig[field] = value;
        }
      }
    }
    return {
      apiKey: (buildApiKeyValue(fv, credentialStatus) as string | object) ?? '',
      apiKeyConfig,
      baseUrl: (fv.base_url as string) ?? instance?.base_url,
      region: (fv.region as string) ?? instance?.region,
      hasStoredCredentials: instance?.api_key_configured === true,
      credentialChanged: Object.entries(credentialStatus).some(
        ([field, configured]) =>
          configured &&
          !SavedProviderConfigFieldSet.has(field) &&
          fv[field] !== undefined &&
          fv[field] !== SAVED_CREDENTIAL_MASK,
      ),
    };
  }, [getFormValues, instance, providerName]);

  return { resolveCreds };
}

// ---------------------------------------------------------------------------
// 2. useModelsCatalog — upstream provider catalog fetch + auto-fetch
// ---------------------------------------------------------------------------

interface UseModelsCatalogArgs {
  providerName: string;
  instanceName: string;
  hideActions: boolean;
  resolveCreds: () => ResolvedCreds;
  instanceModels: IInstanceModel[] | undefined;
  instance?: IProviderInstance;

  apiKeyValue: ResolvedCreds['apiKey'];

  baseUrlValue: string | undefined;

  regionValue?: ResolvedCreds['region'];

  instanceDetailsLoaded?: boolean;

  /**
   * Invoked with the freshly fetched items after every successful catalog
   * fetch (mount auto-fetch and manual "List models" clicks). Used by
   * draft cards to auto-merge new models while skipping names the user
   * has already removed.
   */
  onCatalogFetched?: (items: IProviderModelItem[]) => void;
}

export function useModelsCatalog({
  providerName,
  instanceName,
  hideActions,
  resolveCreds,
  instanceModels,
  instance,
  apiKeyValue,
  baseUrlValue,
  regionValue,
  instanceDetailsLoaded,
  onCatalogFetched,
}: UseModelsCatalogArgs) {
  const { listProviderModels } = useListProviderModels();
  const [catalog, setCatalog] = useState<IProviderModelItem[]>([]);
  const [catalogOverrides, setCatalogOverrides] = useState<
    Record<string, IProviderModelItem>
  >({});
  const catalogOverridesRef = useRef(catalogOverrides);
  const [manualListLoading, setManualListLoading] = useState(false);
  const [hasFetched, setHasFetched] = useState(false);
  const onCatalogFetchedRef = useRef(onCatalogFetched);
  onCatalogFetchedRef.current = onCatalogFetched;

  const applyCatalogOverrides = useCallback((items: IProviderModelItem[]) => {
    const overrides = catalogOverridesRef.current;
    const keys = new Set<string>();
    const merged = items.map((item) => {
      const key = modelNameKey(item.name);
      keys.add(key);
      const override = overrides[key];
      return override ? { ...item, ...override, name: item.name } : item;
    });
    Object.entries(overrides).forEach(([key, override]) => {
      if (!keys.has(key)) {
        merged.push(override);
      }
    });
    return merged;
  }, []);

  const updateCatalogModel = useCallback(
    (name: string, item: IProviderModelItem) => {
      const key = modelNameKey(name);
      setCatalogOverrides((prev) => {
        const next = {
          ...prev,
          [key]: { ...(prev[key] ?? {}), ...item, name },
        };
        catalogOverridesRef.current = next;
        return next;
      });
      setCatalog((prev) => {
        if (!prev.some((m) => modelNameKey(m.name) === key)) {
          return [...prev, { ...item, name }];
        }
        return prev.map((m) =>
          modelNameKey(m.name) === key ? { ...m, ...item, name } : m,
        );
      });
    },
    [],
  );

  const clearCatalogOverride = useCallback((name: string) => {
    const key = modelNameKey(name);
    setCatalogOverrides((prev) => {
      if (!prev[key]) return prev;
      const next = { ...prev };
      delete next[key];
      catalogOverridesRef.current = next;
      return next;
    });
  }, []);

  // Manual "List models" handler — hits the upstream catalog endpoint.
  // The result is merged into `catalog`; the displayed list then becomes
  // the union of catalog + instance models.
  const handleListModels = async () => {
    const {
      apiKey,
      apiKeyConfig,
      baseUrl,
      region,
      hasStoredCredentials,
      credentialChanged,
    } = resolveCreds();
    if (
      providerName === LLMFactory.VolcEngine &&
      !hasUnsavedProviderCredential(apiKey) &&
      !hasStoredCredentials
    ) {
      setHasFetched(true);
      return;
    }
    setManualListLoading(true);
    try {
      const useStoredCredentials =
        instanceName &&
        instanceName !== DRAFT_INSTANCE_SENTINEL &&
        !hasUnsavedProviderCredential(apiKey) &&
        !credentialChanged;
      const canOverrideSavedCredentials =
        useStoredCredentials && instance?.is_owner === true;
      const ret = await listProviderModels({
        provider_name: providerName,
        ...(!useStoredCredentials ? { api_key: apiKey as any } : {}),
        ...(canOverrideSavedCredentials &&
        apiKeyConfig &&
        Object.keys(apiKeyConfig).length > 0
          ? { api_key_config: apiKeyConfig }
          : {}),
        ...(!useStoredCredentials || canOverrideSavedCredentials
          ? { base_url: baseUrl, region }
          : {}),
        ...(useStoredCredentials ? { use_saved_credentials: true } : {}),
        ...(instanceName && instanceName !== DRAFT_INSTANCE_SENTINEL
          ? { instance_name: instanceName }
          : {}),
      });
      if (ret?.code === 0) {
        const merged = applyCatalogOverrides(
          (ret.data as IProviderModelItem[]) ?? [],
        );
        setCatalog(merged);
        onCatalogFetchedRef.current?.(merged);
      }
      setHasFetched(true);
    } catch {
      setHasFetched(true);
    } finally {
      setManualListLoading(false);
    }
  };

  // Auto-fetch the provider's available-models catalog when this section
  // mounts (effectively "when the card is expanded"). For VolcEngine and the
  // providers in API_KEY_GATED_LIST_PROVIDERS (SystemOne, RAGcon) we
  // wait until an api_key is available (typed in the draft form or loaded
  // from instance details). For providers whose form includes a
  // `base_url` field (e.g. Ollama, Xinference, LocalAI) we defer until a
  // non-empty URL is entered - their list-models endpoint needs the URL
  // to know which server to query. For every other provider we fetch on
  // mount regardless.
  //
  // The credential check is performed INSIDE the effect (not in the deps).
  // Saved instances wait for their details and form reset before this reads
  // current endpoint and region values.

  const hasAutoFetchedRef = useRef(false);
  useEffect(() => {
    if (hasAutoFetchedRef.current) return;
    if (hideActions) return;
    if (!providerName) return;
    if (
      providerName === LLMFactory.Bedrock &&
      instanceName === DRAFT_INSTANCE_SENTINEL
    )
      return;

    const creds = resolveCreds();
    const apiKeyConfig =
      typeof creds.apiKey === 'object' && creds.apiKey !== null
        ? (creds.apiKey as Record<string, unknown>)
        : undefined;
    const requiresApiKey =
      API_KEY_GATED_LIST_PROVIDERS.includes(providerName) ||
      (providerName === LLMFactory.Bedrock &&
        apiKeyConfig?.auth_mode === 'bedrock_api_key');
    const hasApiKey =
      hasProviderCredentialInput(creds.apiKey) ||
      (creds.hasStoredCredentials && !creds.credentialChanged);
    const waitingForInstanceDetails =
      instanceName !== DRAFT_INSTANCE_SENTINEL && !instanceDetailsLoaded;
    const hasBaseUrlField = creds.baseUrl !== undefined;
    const ready =
      !waitingForInstanceDetails &&
      (!requiresApiKey || hasApiKey) &&
      (!hasBaseUrlField || !!creds.baseUrl);
    if (!ready) return;
    const frame = requestAnimationFrame(() => {
      if (hasAutoFetchedRef.current) return;
      hasAutoFetchedRef.current = true;
      handleListModels();
    });
    return () => cancelAnimationFrame(frame);
    // oxlint-disable-next-line react/exhaustive-deps
  }, [
    providerName,
    instanceName,
    hideActions,
    apiKeyValue,
    baseUrlValue,
    regionValue,
    instanceDetailsLoaded,
  ]);

  // Mark `hasFetched` true once the per-instance query resolves — even if
  // it returned an empty array — so `hideIfEmpty` can safely take effect.
  useEffect(() => {
    if (instanceModels) {
      setHasFetched(true);
    }
  }, [instanceModels]);

  return {
    catalog,
    setCatalog,
    updateCatalogModel,
    clearCatalogOverride,
    manualListLoading,
    hasFetched,
    handleListModels,
  };
}

// ---------------------------------------------------------------------------
// 3. useModelsDerived — derived model list (instance ∪ catalog) + sync
// ---------------------------------------------------------------------------

interface UseModelsDerivedArgs {
  catalog: IProviderModelItem[];
  instanceModels: IInstanceModel[] | undefined;
  /** True while the saved instance model query is fetching. */
  instanceModelsLoading: boolean;
  /** True only when the saved instance model query completed successfully. */
  instanceModelsSucceeded: boolean;
  /**
   * Locally-added models for a draft (unsaved) instance. The hook uses
   * this list as the "instance models" source when `isDraftInstance` is
   * true, so per-model add/remove/batch on a draft updates the derived
   * list without a backend round-trip. The host's save handler then
   * flushes the latest snapshot through `model_info` on save.
   */
  draftModels: IProviderModelItem[];
  /**
   * True when this card represents a draft instance (no backend id yet).
   * Picks between `instanceModels` (saved) and `draftModels` (draft) as
   * the source for `instanceItems` / `isModelAdded`.
   */
  isDraftInstance: boolean;
  onInstanceModelsChange: ModelsSectionProps['onInstanceModelsChange'];
  onInstanceModelsEdited?: ModelsSectionProps['onInstanceModelsEdited'];
}

export function useModelsDerived({
  catalog,
  instanceModels,
  instanceModelsLoading,
  instanceModelsSucceeded,
  draftModels,
  isDraftInstance,
  onInstanceModelsChange,
  onInstanceModelsEdited,
}: UseModelsDerivedArgs) {
  const catalogFeatures = useMemo(() => {
    const map = new Map<string, string[]>();
    catalog.forEach((m) => {
      if (Array.isArray(m.features) && m.features.length > 0) {
        map.set(modelNameKey(m.name), m.features);
      }
    });
    return map;
  }, [catalog]);

  // For drafts the backend has no per-instance models yet, so the local
  // `draftModels` array stands in. For saved cards the backend list is
  // authoritative. The hook signature normalises both into the same
  // shape (`IProviderModelItem[]`) downstream.
  const sourceItems = useMemo(
    () => (isDraftInstance ? draftModels : ((instanceModels ?? []) as any[])),
    [isDraftInstance, draftModels, instanceModels],
  );

  const instanceItems: IProviderModelItem[] = useMemo(() => {
    // `im` is typed `any` because the backend may return either
    // `model_type` or `model_types`, and `features` is not on the
    // declared IInstanceModel interface.
    return sourceItems.map((im: any) => {
      const model_types = normalizeModelTypes(
        im.model_types ?? im.model_type ?? [],
      );
      const catalogFeats =
        catalogFeatures.get(modelNameKey(im.name)) ?? im.features ?? null;
      const features =
        im.is_tools && !hasToolFeature(catalogFeats)
          ? [...(catalogFeats ?? []), 'is_tools']
          : catalogFeats;
      return {
        name: im.name,
        max_tokens: im.max_tokens ?? 0,
        model_types,
        features,
        extra: im.extra,
      };
    });
  }, [sourceItems, catalogFeatures]);

  // Union of instance models + catalog, keyed by the normalized name (see
  // `modelNameKey`) — the catalog and an upstream listing can spell the same
  // model with different case, and both must collapse into one row. Instance
  // entries win on conflict so that editing an already-added model loads the
  // instance-specific values (e.g. a user-customised `max_tokens`) rather
  // than the upstream catalog defaults; catalog entries are only used to
  // fill in models that have not been added yet. Instance set is listed
  // first so already-added models stay at the top on the initial render.
  const models: IProviderModelItem[] = useMemo(() => {
    const byName = new Map<string, IProviderModelItem>();
    instanceItems.forEach((m) => byName.set(modelNameKey(m.name), m));
    catalog.forEach((m) => {
      const key = modelNameKey(m.name);
      if (!byName.has(key)) {
        byName.set(key, m);
      }
    });
    return Array.from(byName.values());
  }, [instanceItems, catalog]);

  // Mirror of `instanceItems` names - drives the +/- toggle on each row
  // and the batch-toggle button. For drafts this is the local "added"
  // set; for saved cards it tracks what the backend has persisted. Keyed
  // by normalized name so a row the catalog spells differently from the
  // saved model still reads as added.
  const addedSet = useMemo(
    () => new Set(sourceItems.map((m: any) => modelNameKey(m.name))),
    [sourceItems],
  );

  const isModelAdded = useCallback(
    (name: string) => addedSet.has(modelNameKey(name)),
    [addedSet],
  );

  // Keep the latest callbacks in refs so the effect below only fires
  // when `instanceItems` actually changes — not on every parent
  // re-render that passes a new arrow for the callbacks. The previous
  // deps included the callbacks directly, which made the effect re-run
  // with the same data on every render; that was harmless for the
  // idempotent model_info push, but the new "edited" callback updates
  // the host's last-saved baseline and must not absorb in-flight form
  // edits fired by an unrelated re-render.
  const onChangeRef = useRef(onInstanceModelsChange);
  const onEditedRef = useRef(onInstanceModelsEdited);
  useEffect(() => {
    onChangeRef.current = onInstanceModelsChange;
    onEditedRef.current = onInstanceModelsEdited;
  });

  // Push the latest per-instance model list up to the host so its
  // save payload can include `model_info`.
  useEffect(() => {
    onChangeRef.current?.(buildModelInfo(instanceItems, isDraftInstance));
  }, [instanceItems, isDraftInstance]);

  // Saved instance models come from the backend, both after the initial
  // query and after mutation-driven refetches. Once that authoritative
  // snapshot is ready, absorb it into the host's saved baseline so an
  // unchanged card does not look dirty solely because model_info loaded
  // after the instance details. Draft models remain local and must still
  // be included in the first save.
  useEffect(() => {
    if (!isDraftInstance && !instanceModelsLoading && instanceModelsSucceeded) {
      onEditedRef.current?.();
    }
  }, [
    instanceItems,
    instanceModelsLoading,
    instanceModelsSucceeded,
    isDraftInstance,
  ]);

  return { instanceItems, models, isModelAdded };
}

// ---------------------------------------------------------------------------
// 4. useModelsFilter — search box + tag filter
// ---------------------------------------------------------------------------

export function useModelsFilter(models: IProviderModelItem[]) {
  const [search, setSearch] = useState('');
  const [tag, setTag] = useState<string | null>(null);

  const filteredModels = useMemo(() => {
    const q = search.trim().toLowerCase();
    return models.filter((m) => {
      if (q && !m.name.toLowerCase().includes(q)) return false;
      if (tag && !m.model_types?.includes(tag)) return false;
      return true;
    });
  }, [models, search, tag]);

  const allTags = useMemo(() => {
    const tagsSet = new Set<string>();
    models.forEach((m) => m.model_types?.forEach((t) => tagsSet.add(t)));
    return sortModelTypes(Array.from(tagsSet));
  }, [models]);

  return { search, tag, setSearch, setTag, filteredModels, allTags };
}

// ---------------------------------------------------------------------------
// 5. useModelVerify — per-model verify state + handler
// ---------------------------------------------------------------------------

interface UseModelVerifyArgs {
  providerName: string;
  resolveCreds: () => ResolvedCreds;
  instanceModels: IInstanceModel[] | undefined;
  instance?: IProviderInstance;
  getFormValues?: () => Record<string, any>;
  verifyTransform?: ModelsSectionProps['verifyTransform'];
}

/**
 * Build the verify call arguments for a single model. Shared by
 * per-model `handleVerify` and batch `handleBatchVerify` so both paths
 * use identical credential resolution logic.
 */
function buildVerifyArgs(
  model: IProviderModelItem,
  providerName: string,
  resolveCreds: () => ResolvedCreds,
  instance: IProviderInstance | undefined,
  getFormValues: (() => Record<string, any>) | undefined,
  verifyTransform: UseModelVerifyArgs['verifyTransform'],
) {
  const modelInfo: IModelInfo[] = [
    {
      model_name: model.name,
      model_type: model.model_types ?? [],
      max_tokens: model.max_tokens ?? 0,
    },
  ];

  let apiKey: string | object;
  let baseUrl: string | undefined;
  let region: string | undefined;
  const formValues = getFormValues?.() ?? {};

  const credentialStatus = instance?.credential_status ?? {};
  const verifyValues = { ...formValues };
  for (const [field, configured] of Object.entries(credentialStatus)) {
    if (configured && verifyValues[field] === SAVED_CREDENTIAL_MASK) {
      verifyValues[field] = '';
    }
  }
  if (verifyTransform) {
    const transformed = verifyTransform(verifyValues);
    apiKey = applySavedCredentialEdits(
      transformed.apiKey,
      formValues,
      credentialStatus,
    ) as string | object;
    baseUrl = transformed.baseUrl;
    region = transformed.region;
  } else {
    const creds = resolveCreds();
    apiKey = creds.apiKey;
    baseUrl = creds.baseUrl;
  }

  const resolvedCreds = resolveCreds();
  const credentialChanged =
    resolvedCreds.credentialChanged === true ||
    Object.entries(credentialStatus).some(
      ([field, configured]) =>
        configured &&
        !SavedProviderConfigFieldSet.has(field) &&
        formValues[field] !== undefined &&
        formValues[field] !== SAVED_CREDENTIAL_MASK,
    );

  const useSavedCredentials =
    Boolean(instance?.id) &&
    !credentialChanged &&
    !hasUnsavedProviderCredential(apiKey);

  // `api_key` is typed `string` on the service signature, but
  // providers with a `verifyTransform` may legitimately produce an
  // object (e.g. PaddleOCR's nested config). The backend accepts
  // both shapes, so cast to `any` to match the existing card-level
  // verify path in `useVerifyProvider`.
  return {
    provider_name: providerName,
    ...(!useSavedCredentials ? { api_key: apiKey as any } : {}),
    ...(useSavedCredentials &&
    instance?.is_owner === true &&
    resolvedCreds.apiKeyConfig &&
    Object.keys(resolvedCreds.apiKeyConfig).length > 0
      ? { api_key_config: resolvedCreds.apiKeyConfig }
      : {}),
    ...(!useSavedCredentials || instance?.is_owner === true
      ? { base_url: baseUrl, region }
      : {}),
    model_info: modelInfo,
    ...(instance?.id ? { instance_id: instance.id } : {}),
    ...(useSavedCredentials ? { use_saved_credentials: true } : {}),
  };
}

export function useModelVerify({
  providerName,
  resolveCreds,
  instanceModels,
  instance,
  getFormValues,
  verifyTransform,
}: UseModelVerifyArgs) {
  const { verifyProviderConnection } = useVerifyProviderConnection();
  const [verify, setVerify] = useState<Record<string, VerifyStatus>>({});
  const [batchVerifying, setBatchVerifying] = useState(false);

  // Seed the per-model verify status from the backend's persisted `verify`
  // flag on each instance model.
  useEffect(() => {
    if (!instanceModels || instanceModels.length === 0) return;
    setVerify((prev) => {
      let changed = false;
      const next = { ...prev };
      for (const im of instanceModels) {
        if (im.name in next) continue;
        if (im.verify === 'success') {
          next[im.name] = 'success';
          changed = true;
        } else if (im.verify === 'fail') {
          next[im.name] = 'error';
          changed = true;
        }
      }
      return changed ? next : prev;
    });
  }, [instanceModels]);

  const handleVerify = async (model: IProviderModelItem) => {
    setVerify((prev) => ({ ...prev, [model.name]: 'loading' }));
    try {
      const ret = await verifyProviderConnection(
        buildVerifyArgs(
          model,
          providerName,
          resolveCreds,
          instance,
          getFormValues,
          verifyTransform,
        ),
      );
      setVerify((prev) => ({
        ...prev,
        [model.name]: ret.code === 0 ? 'success' : 'error',
      }));
    } catch {
      setVerify((prev) => ({ ...prev, [model.name]: 'error' }));
    }
  };

  // Batch verify: loop through the given models in chunks of 3 parallel
  // requests, suppressing the global error toast for each call. Per-model
  // verify status is updated on the same map used by `handleVerify`.
  const handleBatchVerify = async (models: IProviderModelItem[]) => {
    if (models.length === 0) return;
    setBatchVerifying(true);

    const CHUNK_SIZE = 3;
    for (let i = 0; i < models.length; i += CHUNK_SIZE) {
      const chunk = models.slice(i, i + CHUNK_SIZE);

      // Mark only the current chunk as loading; the remaining models
      // stay idle until their chunk is reached.
      const loadingMap: Record<string, VerifyStatus> = {};
      chunk.forEach((m) => {
        loadingMap[m.name] = 'loading';
      });
      setVerify((prev) => ({ ...prev, ...loadingMap }));

      const results = await Promise.allSettled(
        chunk.map(async (model) => {
          const args = buildVerifyArgs(
            model,
            providerName,
            resolveCreds,
            instance,
            getFormValues,
            verifyTransform,
          );
          // Pass `provider_name` at the top level so the URL function
          // can build `/providers/{provider_name}/connection`; the body
          // goes in `data`. `skipGlobalErrorNotification` suppresses the
          // global toast for each call during batch verify.
          const { data } = await llmService.verifyProviderConnection(
            {
              provider_name: providerName,
              data: args,
              skipGlobalErrorNotification: true,
            },
            true,
          );
          return { name: model.name, code: data?.code ?? -1 };
        }),
      );

      const statusUpdate: Record<string, VerifyStatus> = {};
      results.forEach((result, idx) => {
        const modelName = chunk[idx].name;
        statusUpdate[modelName] =
          result.status === 'fulfilled' && result.value.code === 0
            ? 'success'
            : 'error';
      });
      setVerify((prev) => ({ ...prev, ...statusUpdate }));
    }

    setBatchVerifying(false);
  };

  return { verify, handleVerify, batchVerifying, handleBatchVerify };
}

// ---------------------------------------------------------------------------
// 6. useModelMutations — add / remove / batch toggle / custom add
// ---------------------------------------------------------------------------

interface UseModelMutationsArgs {
  providerName: string;
  instanceName: string;
  isDraftInstance: boolean;
  hideActions: boolean;
  resolveCreds: () => ResolvedCreds;
  instance: IProviderInstance | undefined;
  instanceItems: IProviderModelItem[];
  filteredModels: IProviderModelItem[];
  isModelAdded: (name: string) => boolean;
  setCatalog: Dispatch<SetStateAction<IProviderModelItem[]>>;
  clearCatalogOverride: (name: string) => void;
  /**
   * Local mutators for the draft instance's model list. Required when
   * `isDraftInstance` is true so per-model add / remove / batch updates
   * stay local until the host saves the instance. Ignored for saved
   * cards (the backend mutations below fire as before).
   */
  addDraftModel?: (model: IProviderModelItem) => void;
  removeDraftModel?: (name: string) => void;
  setDraftModelsList?: (models: IProviderModelItem[]) => void;
}

export function useModelMutations({
  providerName,
  instanceName,
  isDraftInstance,
  hideActions,
  resolveCreds,
  instance,
  instanceItems,
  filteredModels,
  isModelAdded,
  setCatalog,
  clearCatalogOverride,
  addDraftModel,
  removeDraftModel,
  setDraftModelsList,
}: UseModelMutationsArgs) {
  const { addInstanceModel } = useAddInstanceModel();
  const { deleteInstanceModels } = useDeleteInstanceModels();
  const { updateProviderInstance, loading: batchLoading } =
    useUpdateProviderInstance();

  // True when every model currently shown in the filtered list is already
  // attached to the instance — drives the +/- toggle on the batch button.
  const allFilteredAdded = useMemo(
    () =>
      filteredModels.length > 0 &&
      filteredModels.every((m) => isModelAdded(m.name)),
    [filteredModels, isModelAdded],
  );

  const handleAddModel = async (model: IProviderModelItem) => {
    // Drafts have no backend instance yet — defer the call so the model
    // rides along with the instance save (model_info in the add body).
    if (isDraftInstance) {
      addDraftModel?.(model);
      clearCatalogOverride(model.name);
      return;
    }
    await addInstanceModel({
      provider_name: providerName,
      instance_name: instanceName,
      model_name: model.name,
      model_type: model.model_types ?? [],
      max_tokens: model.max_tokens ?? 0,
      extra: {
        is_tools: hasToolFeature(model.features),
        ...(model.extra ?? {}),
      },
    });
    clearCatalogOverride(model.name);
  };

  const handleRemoveModel = async (model: IProviderModelItem) => {
    if (isDraftInstance) {
      removeDraftModel?.(model.name);
      return;
    }
    await deleteInstanceModels({
      provider_name: providerName,
      instance_name: instanceName,
      model_name: [model.name],
    });
  };

  const handleAddCustom = async (item: IProviderModelItem) => {
    // Append the custom item to the local catalog so it shows up in the
    // unioned `models` list immediately. Server-side persistence happens
    // via `addInstanceModel` below (when there is a real instance).
    setCatalog((prev) =>
      prev.some((m) => modelNameKey(m.name) === modelNameKey(item.name))
        ? prev
        : [...prev, item],
    );
    if (hideActions || isDraftInstance) {
      // For drafts the catalog entry alone is not enough — we also need
      // to mark the model as added so it flows into the save payload's
      // `model_info`. Without this, custom models added on a draft
      // would render as "available" but not as "added", and would be
      // dropped on save.
      if (isDraftInstance) {
        addDraftModel?.(item);
        clearCatalogOverride(item.name);
      }
      return;
    }
    await addInstanceModel({
      provider_name: providerName,
      instance_name: instanceName,
      model_name: item.name,
      model_type: item.model_types ?? [],
      max_tokens: item.max_tokens ?? 0,
      extra: { is_tools: hasToolFeature(item.features), ...(item.extra ?? {}) },
    });
    clearCatalogOverride(item.name);
  };

  // Batch attach/detach the currently visible (filtered) models.
  //  - Saved card: PUT `/providers/{name}/instances/{name}` to replace
  //    `model_info` wholesale.
  //  - Draft: just rewrite the local draft list. The host save handler
  //    flushes the latest snapshot through the add-instance payload.
  const handleBatchToggleModels = async () => {
    if (filteredModels.length === 0) return;

    const byName = new Map<string, IProviderModelItem>();
    instanceItems.forEach((m) => byName.set(modelNameKey(m.name), m));

    let nextModels: IProviderModelItem[];
    if (allFilteredAdded) {
      const drop = new Set(filteredModels.map((m) => modelNameKey(m.name)));
      nextModels = Array.from(byName.values()).filter(
        (m) => !drop.has(modelNameKey(m.name)),
      );
    } else {
      filteredModels.forEach((m) => byName.set(modelNameKey(m.name), m));
      nextModels = Array.from(byName.values());
    }

    if (isDraftInstance) {
      setDraftModelsList?.(nextModels);
      filteredModels.forEach((m) => {
        if (!isModelAdded(m.name)) {
          clearCatalogOverride(m.name);
        }
      });
      return;
    }

    const { apiKey, baseUrl } = resolveCreds();
    await updateProviderInstance({
      provider_name: providerName,
      id: instance!.id,
      instance_name: instanceName,
      api_key: apiKey,
      base_url: baseUrl,
      region: instance?.region ?? 'default',
      model_info: buildModelInfo(nextModels, isDraftInstance),
    });
    filteredModels.forEach((m) => {
      if (!isModelAdded(m.name)) {
        clearCatalogOverride(m.name);
      }
    });
  };

  return {
    allFilteredAdded,
    handleAddModel,
    handleRemoveModel,
    handleAddCustom,
    handleBatchToggleModels,
    batchLoading,
  };
}

// ---------------------------------------------------------------------------
// 7. useModelEdit — edit dialog state + submit
// ---------------------------------------------------------------------------

interface UseModelEditArgs {
  providerName: string;
  instanceName: string;
  isModelAdded: (name: string) => boolean;
  isDraftInstance?: boolean;
  updateCatalogModel: (name: string, item: IProviderModelItem) => void;
  clearCatalogOverride: (name: string) => void;
  updateDraftModel?: (item: IProviderModelItem) => void;
}

export function useModelEdit({
  providerName,
  instanceName,
  isModelAdded,
  isDraftInstance,
  updateCatalogModel,
  clearCatalogOverride,
  updateDraftModel,
}: UseModelEditArgs) {
  const queryClient = useQueryClient();
  const customModelDialogFields = useCustomModelFields(providerName);
  const { patchInstanceModel, loading: editLoading } = usePatchInstanceModel();
  // Model currently being edited via AddCustomModelDialog (with `name`
  // pinned/disabled and the dialog initial values pre-populated from the
  // model's current config). `null` when the edit dialog is closed.
  const [editingModel, setEditingModel] = useState<IProviderModelItem | null>(
    null,
  );

  // Field schema for the edit dialog — identical to the add schema
  // except the `name` field is locked (model name is the row's primary
  // key and the API forbids renaming via this endpoint).
  const editModelDialogFields = useMemo(
    () =>
      customModelDialogFields.map((f) =>
        f.name === 'name' ? { ...f, disabled: true } : f,
      ),
    [customModelDialogFields],
  );

  // Whitelist of provider-specific feature keys derived from the
  // `features` switch-group options. Any option value that is not
  // `is_tools` is treated as provider-specific: on submit it is moved
  // from `features` to `extra` as a boolean; on echo it is converted
  // back from an `extra` boolean to a features array entry.
  const providerFeatureKeys = useMemo(() => {
    const featuresField = customModelDialogFields.find(
      (f) => f.name === 'features',
    );
    return (featuresField?.options ?? [])
      .filter((o) => o.value !== 'is_tools')
      .map((o) => o.value);
  }, [customModelDialogFields]);

  // Initial form values for the edit dialog, derived from the model's
  // persisted `extra` state. The `features` switch-group shows
  // enabled/disabled state, so it must be built from `extra` booleans
  // rather than from `editingModel.features` which merges in
  // catalog-supported features and would incorrectly pre-select
  // features the user has disabled.
  const editDefaultValues = useMemo(() => {
    if (!editingModel) return undefined;
    const extra = editingModel.extra ?? {};
    // Build the features array from `extra` booleans whose keys match
    // the standard feature (`is_tools`) or the provider-specific
    // whitelist. Only `true` values become selected switch-group entries.
    const featureKeySet = new Set<string>(['is_tools', ...providerFeatureKeys]);
    const features: string[] = [];
    const featureBooleans = new Set<string>();
    for (const [key, value] of Object.entries(extra)) {
      if (featureKeySet.has(key) && typeof value === 'boolean') {
        featureBooleans.add(key);
        if (value === true) {
          features.push(key);
        }
      }
    }
    // Remaining extra fields (non-feature: element-format selects, etc.).
    const remainingExtra = Object.fromEntries(
      Object.entries(extra).filter(([k]) => !featureBooleans.has(k)),
    );
    return {
      name: editingModel.name,
      model_types: editingModel.model_types ?? [],
      max_tokens: editingModel.max_tokens ?? 0,
      features,
      ...remainingExtra,
    };
  }, [editingModel, providerFeatureKeys]);

  // Persist edits to an existing model. For drafts the backend has no
  // instance yet, so we update the local `draftModels` list instead of
  // calling PATCH. For saved cards the cache changes only after the backend
  // accepts the edit; the PATCH hook then refetches the complete snapshot.
  const handleEditSubmit = async (item: IProviderModelItem) => {
    if (!editingModel) return;
    const targetName = editingModel.name;

    if (isDraftInstance && updateDraftModel && isModelAdded(targetName)) {
      updateDraftModel(item);
      setEditingModel(null);
      return;
    }

    if (!isModelAdded(targetName)) {
      updateCatalogModel(targetName, item);
      setEditingModel(null);
      return;
    }

    const data = await patchInstanceModel({
      provider_name: providerName,
      instance_name: instanceName,
      model_name: targetName,
      max_tokens: item.max_tokens ?? 0,
      model_type: item.model_types ?? [],
      extra: { is_tools: hasToolFeature(item.features), ...(item.extra ?? {}) },
    });
    if (data.code === 0) {
      queryClient.setQueryData<IInstanceModel[]>(
        LlmKeys.instanceModels(providerName, instanceName),
        (prev) => {
          if (!prev) return prev;
          const idx = prev.findIndex(
            (m) => modelNameKey(m.name) === modelNameKey(targetName),
          );
          if (idx === -1) return prev;
          const next = [...prev];
          const existing = next[idx];
          next[idx] = {
            ...existing,
            max_tokens: item.max_tokens ?? 0,
            model_type: item.model_types ?? [],
            is_tools: hasToolFeature(item.features),
            extra: {
              is_tools: hasToolFeature(item.features),
              ...(item.extra ?? {}),
            },
          };
          return next;
        },
      );
    }
    clearCatalogOverride(targetName);
    setEditingModel(null);
  };

  return {
    editingModel,
    setEditingModel,
    editModelDialogFields,
    editDefaultValues,
    handleEditSubmit,
    editLoading,
    customModelDialogFields,
    providerFeatureKeys,
  };
}