Skip to content

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

11.9 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 { DynamicFormRef } from '@/components/dynamic-form';
import message from '@/components/ui/message';
import { IModelInfo } from '@/interfaces/request/llm';
import { useTranslation } from 'react-i18next';
import { LIST_MODEL_PROVIDERS } from '../provider-schema/constants';
import {
  forwardRef,
  useCallback,
  useEffect,
  useImperativeHandle,
  useMemo,
  useRef,
  useState,
} from 'react';
import { useFetchInstanceNameSet, useHideWhenInstanceExists } from '../hooks';
import { getProviderConfig } from '../provider-schema/field-config';
import { BedrockInstanceCard } from './bedrock-instance-card';
import { GPUStackInstanceCard } from './gpustack-instance-card';
import { DraftModeCard } from './components/draft-mode-card';
import { InstanceNameSection } from './components/instance-name-section';
import { SavedModeCard } from './components/saved-mode-card';
import {
  useDeleteInstance,
  useFormFields,
  useFormResetOnDetailsLoad,
  useInstanceSave,
  useInstanceSaveState,
  useLazyInstanceDetails,
  useProviderBaseUrlOptions,
  useProviderInitialValues,
  useVerifyProvider,
} from './hooks';
import {
  ProviderInstanceCardProps,
  ProviderInstanceCardRef,
} from './interface';

/**
 * One inline provider-instance card. The provider name + doc-link arrow
 * live in the parent page's sticky `ProviderHeaderBar`; this card only
 * shows the **instance**-level details (name, fields, verify, models).
 *
 * Two visual modes driven by `isDraft`:
 *  1. **Draft** (`isDraft`): the instance name lives in a dedicated
 *     input section at the top of the body, and the form fields are
 *     always editable (no fieldset lock). Its header Save button
 *     persists the new instance.
 *  2. **Saved** (`!isDraft`): the form-field section collapses into a
 *     single collapsible row showing the name as plain text with a
 *     hover-only key/lock icon. The form fields live inside the
 *     collapsible content and can be collapsed/expanded.
 *
 * Saving is per card: the header Save button validates and persists
 * only the instance it belongs to.
 */
const GenericProviderInstanceCard = forwardRef<
  ProviderInstanceCardRef,
  ProviderInstanceCardProps
>(function GenericProviderInstanceCard(
  {
    providerName,
    instance,
    isDraft = false,
    onDelete,
    onSaved,
    defaultOpen = false,
  },
  ref,
) {
  // Drafts always start open (the user just added them and needs to
  // fill the fields); saved cards default to collapsed unless the
  // parent flagged this card as the one to expand initially (typically
  // the first instance in the list).
  const [open, setOpen] = useState(isDraft || defaultOpen);
  // Drafts start with an empty name - the user types it themselves.
  const [draftName, setDraftName] = useState('');
  // For saved cards: the instance name as shown in the UI. Initialized
  // from the persisted name and updated when the user double-clicks the
  // name to rename it. Persisted via the card's Save button.
  const [editedInstanceName, setEditedInstanceName] = useState(
    instance.instance_name,
  );
  const formRef = useRef<DynamicFormRef>(null);
  // Mirror of the per-instance model list - written by ModelsSection
  // via `setModelInfo`, read by the payload builder.
  const { t } = useTranslation();
  const modelInfoRef = useRef<IModelInfo[]>([]);
  const modelsLoadedRef = useRef(false);

  // Provider-specific config: carries `verifyTransform` / `submitTransform`
  // for providers whose form field names don't map directly onto
  // `api_key` / `base_url` (e.g. OpenDataLoader's nested
  // `opendataloader_apiserver` / `opendataloader_api_key`). When present
  // the transforms take precedence over the generic field mapping inside
  // `useVerifyProvider` and `useInstanceSaveState.buildPayload`.
  const providerConfig = useMemo(
    () => getProviderConfig(providerName),
    [providerName],
  );

  useEffect(() => {
    if (isDraft) {
      setDraftName('');
    }
  }, [providerName, isDraft]);

  // Reset the edited name when the persisted instance changes (e.g.
  // after a successful rename + refetch, or when switching providers).
  useEffect(() => {
    if (!isDraft) {
      setEditedInstanceName(instance.instance_name);
    }
  }, [instance.instance_name, isDraft]);

  // ── Data fetching ────────────────────────────────────────────────
  const { instanceNameSet } = useFetchInstanceNameSet(
    isDraft ? providerName : '',
  );
  const hideWhenInstanceExists = useHideWhenInstanceExists(instanceNameSet);
  const { baseUrlOptions, urlHint } = useProviderBaseUrlOptions(providerName);
  const { instanceDetails } = useLazyInstanceDetails(
    providerName,
    instance.id,
    isDraft,
    open,
  );

  // ── Form initial values + fields ────────────────────────────────
  const initialValues = useProviderInitialValues(
    providerName,
    instance,
    instanceDetails,
    isDraft,
    baseUrlOptions,
    providerConfig.echoTransform,
  );
  const { formFields, formDefaultValues } = useFormFields(
    providerName,
    isDraft,
    initialValues,
    baseUrlOptions,
    hideWhenInstanceExists,
    urlHint,
  );
  useFormResetOnDetailsLoad(
    formRef,
    formDefaultValues,
    instanceDetails,
    isDraft,
  );

  // ── Action handlers ─────────────────────────────────────────────
  const handleVerify = useVerifyProvider(
    providerName,
    formRef,
    providerConfig.verifyTransform,
    modelInfoRef,
    isDraft ? undefined : instance.id,
    isDraft ? undefined : { ...instance, ...(instanceDetails ?? {}) },
  );
  const handleDelete = useDeleteInstance(
    providerName,
    instance.instance_name,
    isDraft,
    onDelete,
  );

  // ── Save state (payload builder + dirty tracking) ───────────────
  const { getSavePayload, markSaved, markModelsEdited } = useInstanceSaveState({
    formRef,
    providerName,
    instanceName: instance.instance_name,
    editedInstanceName,
    instanceId: instance.id,
    isDraft,
    draftName,
    instanceDetails,
    initialValues,
    baselineValues: formDefaultValues,
    modelInfoRef,
    submitTransform: providerConfig.submitTransform,
  });

  // Form validation shared by the header Save button and the
  // imperative ref API.
  const validate = useCallback(async () => {
    // Drafts need a non-empty instance name (the DynamicForm does
    // not include the instance_name field, so `trigger()` won't
    // catch it). For both drafts and saved cards, run the form's
    // own validation so errors surface in the UI.
    if (isDraft && !draftName.trim()) return false;
    if (!isDraft && instanceDetails && !modelsLoadedRef.current) {
      message.error(t('setting.selectModelBeforeSave'));
      return false;
    }
    // List-model providers (list picker) require at least one selected model.
    if (
      LIST_MODEL_PROVIDERS.has(providerName) &&
      modelInfoRef.current.length === 0
    ) {
      message.error(t('setting.selectModelBeforeVerify'));
      return false;
    }
    const isValid = await formRef.current?.trigger();
    return !!isValid;
  }, [isDraft, draftName, instanceDetails, providerName, t]);

  // The card header owns the Save button: each instance is persisted
  // independently, straight from its own card.
  const { save: handleSave, saving } = useInstanceSave({
    isDraft,
    getSavePayload,
    validate,
    markSaved,
    existingNames: instanceNameSet,
    onSaved,
  });

  // Expose the imperative save API for tests and embedders that drive
  // the card from outside.
  useImperativeHandle(
    ref,
    () => ({
      validate,
      getSavePayload,
      markSaved,
    }),
    [validate, getSavePayload, markSaved],
  );

  return (
    <div
      className="mb-5 pb-5"
      data-testid={`instance-card-${instance.instance_name || 'draft'}`}
    >
      {isDraft ? (
        <DraftModeCard
          formFields={formFields}
          formDefaultValues={formDefaultValues}
          formRef={formRef}
          handleVerify={handleVerify}
          handleDelete={handleDelete}
          handleSave={handleSave}
          saving={saving}
          handleInstanceModelsEdited={markModelsEdited}
          providerName={providerName}
          instanceName={instance.instance_name}
          instance={instance}
          modelInfoRef={modelInfoRef}
          draftName={draftName}
          setDraftName={setDraftName}
          verifyTransform={providerConfig.verifyTransform}
        />
      ) : (
        <SavedModeCard
          formFields={formFields}
          formDefaultValues={formDefaultValues}
          formRef={formRef}
          handleVerify={handleVerify}
          handleDelete={handleDelete}
          handleSave={handleSave}
          saving={saving}
          handleInstanceModelsEdited={markModelsEdited}
          providerName={providerName}
          instanceName={instance.instance_name}
          editedInstanceName={editedInstanceName}
          onRename={setEditedInstanceName}
          instance={{ ...instance, ...(instanceDetails ?? {}) }}
          instanceDetailsLoaded={Boolean(instanceDetails)}
          modelInfoRef={modelInfoRef}
          onInstanceModelsStatusChange={(ready) => {
            modelsLoadedRef.current = ready;
          }}
          draftName={draftName}
          open={open}
          setOpen={setOpen}
          verifyTransform={providerConfig.verifyTransform}
        />
      )}
    </div>
  );
});

/**
 * One inline provider-instance card. The provider name + doc-link arrow
 * live in the parent page's sticky `ProviderHeaderBar`; this card only
 * shows the **instance**-level details (name, fields, verify, models).
 *
 * Two visual modes driven by `isDraft`:
 *  1. **Draft** (`isDraft`): the instance name lives in a dedicated
 *     input section at the top of the body, and the form fields are
 *     always editable (no fieldset lock). Its header Save button
 *     persists the new instance.
 *  2. **Saved** (`!isDraft`): the form-field section collapses into a
 *     single collapsible row showing the name as plain text with a
 *     hover-only key/lock icon. The form fields live inside the
 *     collapsible content and can be collapsed/expanded.
 *
 * Saving is per card: the header Save button validates and persists
 * only the instance it belongs to.
 */
export const ProviderInstanceCard = forwardRef<
  ProviderInstanceCardRef,
  ProviderInstanceCardProps
>(function ProviderInstanceCard(props, ref) {
  // AWS Bedrock has provider-specific fields (auth_mode, region, AK/SK,
  // role ARN, model name, max_tokens) that don't fit the generic
  // DynamicForm path. Render its own inline card instead.
  //
  // Dispatch BEFORE any hooks so each branch component has a stable
  // hook-call order (Rules of Hooks).
  if (props.providerName === 'Bedrock') {
    return <BedrockInstanceCard {...props} ref={ref} />;
  }
  if (props.providerName === 'GPUStack') {
    return <GPUStackInstanceCard {...props} ref={ref} />;
  }
  return <GenericProviderInstanceCard {...props} ref={ref} />;
});

// Re-export the name section for callers that need to embed it
// (e.g. parent pages with custom layouts).
export { InstanceNameSection };

export default ProviderInstanceCard;