RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
import { ExpandableSearchInput } from '@/components/expandable-search-input';
import { SelectWithSearch } from '@/components/originui/select-with-search';
import { SkeletonCard } from '@/components/skeleton-card';
import { CompilationTemplateKind } from '@/constants/compilation';
import { useFetchDocumentClaims } from '@/hooks/use-document-request';
import { memo, useCallback, useEffect, useState } from 'react';
import { useTranslation } from 'react-i18next';
import {
type ClickableNode,
RepresentationRenderer,
} from '@/components/structure-graph/representation-renderer';
import type {
ClaimsPanelState,
EvidencePanelState,
} from './components/claim-list';
import { RepresentationSelect } from './components/representation-select';
import { useGraphEntitySearch } from './hooks/use-graph-entity-search';
export type {
ClaimsPanelState,
EvidencePanelState,
} from './components/claim-list';
interface RepresentationProps {
onNodeClick?: (node: ClickableNode) => void;
// The claims / evidence panels belong to the artifact page's middle column,
// not inside this tree view. The selection still lives here (it is driven by
// node clicks), but the resolved content is published upward and the page
// decides where to render it.
onClaimsPanelChange?: (panel: ClaimsPanelState | null) => void;
onEvidencePanelChange?: (panel: EvidencePanelState | null) => void;
}
function Representation({
onNodeClick,
onClaimsPanelChange,
onEvidencePanelChange,
}: RepresentationProps) {
const { t } = useTranslation();
const [claimsLeaf, setClaimsLeaf] = useState<ClickableNode | null>(null);
const [evidenceDetail, setEvidenceDetail] = useState<ClickableNode | null>(
null,
);
const {
data,
loading,
templates,
selectedTemplateId,
selectedTemplate,
isGraphKind,
entityOptions,
searchKeyword,
graphSelectValue,
highlightNodeId,
handleSelectEntity,
handleNoMatchEnter,
handleSearchKeywordChange,
handleTemplateChange,
handleNodeClick,
} = useGraphEntitySearch(onNodeClick);
// Tree leaves carry a claim-count badge: clicking one opens its claims in the
// artifact page's middle column, in addition to the usual chunk navigation.
// Branch clicks close the panel — they are pure structure and their
// descendants own the claims. The panels themselves are rendered by the page
// (as a resizable column), so only the resolved content is published upward.
const { data: claimsData, loading: claimsLoading } = useFetchDocumentClaims(
claimsLeaf?.source_chunk_ids,
selectedTemplateId,
);
const handleCloseClaims = useCallback(() => setClaimsLeaf(null), []);
const handleCloseEvidence = useCallback(() => setEvidenceDetail(null), []);
// The claims / evidence panels only make sense for compilation templates
// that actually produce claim rows. Right now that's page_index (titles
// + claim/fact/conclusion entities with gate-verified evidence) and tree
// (RAPTOR leaf clusters with harvested claims). Other templates
// (knowledge_graph, mind_map, timeline, wiki, session_graph,
// session_essence, empty) emit no claim rows at all, so opening the
// panel for them would only ever show the empty state.
const supportsClaims =
selectedTemplate?.kind === CompilationTemplateKind.PageIndex ||
selectedTemplate?.kind === CompilationTemplateKind.Tree;
// Wait for the fetch to settle before committing to either panel. While it
// is in flight, publish the claims panel in its loading state so the middle
// column is stable and honest — publishing the node-detail panel during the
// load made it flash first and then be overwritten by the claims panel (or,
// for a node without claims, it just stayed there looking unexplained). The
// page stacks both panels in one slot, so the choice is exclusive — and it
// can only be made once the claim count is known.
const claimsSettled = Boolean(claimsLeaf) && !claimsLoading;
const hasClaims = claimsSettled && (claimsData?.claims?.length ?? 0) > 0;
useEffect(() => {
if (!supportsClaims) {
onClaimsPanelChange?.(null);
return;
}
if (claimsLeaf && !claimsSettled) {
onClaimsPanelChange?.({
clusterName: claimsLeaf.name,
claims: [],
total: 0,
loading: true,
onClose: handleCloseClaims,
});
return () => onClaimsPanelChange?.(null);
}
// No claims and no node detail: keep the claims panel open with its empty
// state when the click actually addressed chunks (a real leaf), so the
// column answers "why nothing" instead of silently closing. Branch nodes
// without source_chunk_ids close it -- they are pure structure.
const showEmptyClaims =
claimsSettled &&
!hasClaims &&
!evidenceDetail &&
Boolean(claimsLeaf?.source_chunk_ids?.length);
onClaimsPanelChange?.(
claimsLeaf && (hasClaims || showEmptyClaims)
? {
clusterName: claimsLeaf.name,
claims: claimsData?.claims ?? [],
total: claimsData?.total ?? 0,
loading: claimsLoading,
onClose: handleCloseClaims,
}
: null,
);
// Clear on unmount too: switching the left view back to the document
// preview unmounts the tree, and the page must drop the column with it.
return () => onClaimsPanelChange?.(null);
}, [
claimsLeaf,
claimsData,
claimsLoading,
claimsSettled,
evidenceDetail,
hasClaims,
handleCloseClaims,
onClaimsPanelChange,
supportsClaims,
]);
useEffect(() => {
if (!supportsClaims) {
onEvidencePanelChange?.(null);
return;
}
onEvidencePanelChange?.(
claimsSettled && !hasClaims && evidenceDetail
? {
nodeName: evidenceDetail.name,
description: evidenceDetail.description,
evidence: evidenceDetail.evidence ?? [],
onClose: handleCloseEvidence,
}
: null,
);
return () => onEvidencePanelChange?.(null);
}, [
claimsSettled,
evidenceDetail,
handleCloseEvidence,
hasClaims,
onEvidencePanelChange,
supportsClaims,
]);
const handleNodeClickWithClaims = useCallback(
(node: ClickableNode) => {
// Skip the claims / evidence panel state for templates that have no
// claim rows: setting the leaf would fire a guaranteed-empty fetch.
// Chunk-list filtering still runs through ``handleNodeClick`` below.
if (supportsClaims) {
// Any node can own claims — a page_index heading covers the chunks of its
// whole section, so the claims belonging to it are the ones sourced from
// those chunks. Nothing here keys off ``badge``: the structure compiler
// never writes ``claim_count``, so gating on it kept the panel shut for
// every node. Whether the panel actually opens is decided by the fetch
// below, once we know the node has claims.
setClaimsLeaf(node);
// The node-detail panel is ONLY for nodes carrying gate-verified quotes
// (page_index fact/conclusion rows). A description alone would make
// every tree node fall back to it when no claims exist -- an
// unexplained block of compiled summary text in the claims slot.
setEvidenceDetail(node.evidence?.length ? node : null);
}
handleNodeClick(node);
},
[handleNodeClick, supportsClaims],
);
return (
<section className="p-5 rounded-2xl h-full flex flex-col">
<div className="flex items-center gap-2">
<RepresentationSelect
templates={templates}
value={selectedTemplateId}
onChange={handleTemplateChange}
/>
<div className="min-w-0">
{isGraphKind ? (
<SelectWithSearch
options={entityOptions}
value={graphSelectValue}
onChange={handleSelectEntity}
placeholder={t('knowledgeCompilation.searchEntity')}
allowClear
onNoMatchEnter={handleNoMatchEnter}
disableAutoSelectOnEnter
/>
) : (
<ExpandableSearchInput
value={searchKeyword}
onChange={handleSearchKeywordChange}
placeholder={t('common.search')}
/>
)}
</div>
</div>
{loading && !data && <SkeletonCard className="mt-6" />}
{!(loading && !data) && templates.length === 0 && (
<div className="mt-6 text-text-secondary">
{t('knowledgeCompilation.representationEmpty')}
</div>
)}
{!(loading && !data) && templates.length > 0 && (
<RepresentationRenderer
template={selectedTemplate}
onNodeClick={handleNodeClickWithClaims}
highlightNodeId={highlightNodeId}
totalEntities={data?.total_entities}
returnedEntities={data?.returned_entities}
/>
)}
</section>
);
}
export default memo(Representation);
export type { ClickableNode };