OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
import type {
TaskFailureComponent,
TaskFailurePhase,
TaskFileEntry,
} from "@/app/api/queries/useGetTasksQuery";
import { formatProviderErrorMessage } from "@/lib/chat-stream-errors";
export const FILE_ERROR_MAX_LINE_LENGTH = 80;
/**
* Centralized detection for cancelled files.
*
* Checks failure_phase first (structured data), then falls back to error message strings.
* This ensures consistent detection across whole-task cancellation ("Task cancelled by user"),
* file-level cancellation ("File cancelled by user"), and API-provided phase markers.
*/
export function isFileCancelled(
fileInfo: Pick<TaskFileEntry, "failure_phase" | "error">,
): boolean {
// 1. Check structured failure_phase first (most reliable)
if (fileInfo.failure_phase === "cancelled") {
return true;
}
// 2. Fall back to error message detection for legacy cases
const error = fileInfo.error?.toLowerCase() || "";
return (
error.includes("file cancelled by user") ||
error.includes("task cancelled by user") ||
error.includes("file processing task cancelled")
);
}
export type TaskErrorComponentCause =
| "OpenSearch"
| "Docling"
| "Langflow"
| "OpenRAG";
export type TaskPipelineStepId =
| "parsing"
| "chunking"
| "embedding"
| "indexing"
| "file_validation"
| "cancelled"
| "unknown";
export interface IngestionPipelineStep {
id: TaskPipelineStepId;
label: string;
status: "completed" | "failed";
}
export interface TaskFileIngestionFailureAnalysis {
resolvedError: string;
failedStep: TaskPipelineStepId;
pipelineSteps: IngestionPipelineStep[];
rowStatusLabel: string;
failureSummary: string;
componentCause?: TaskErrorComponentCause;
componentTags: string[];
summaryLine: string;
}
const PIPELINE_STEP_ORDER: TaskPipelineStepId[] = [
"parsing",
"chunking",
"embedding",
"indexing",
];
const PIPELINE_STEP_LABELS: Record<TaskPipelineStepId, string> = {
parsing: "Parsing",
chunking: "Chunking",
embedding: "Embedding",
indexing: "Indexing",
file_validation: "File validation",
cancelled: "Cancelled",
unknown: "Ingestion",
};
const COMPONENT_LABELS: Record<TaskFailureComponent, TaskErrorComponentCause> =
{
docling: "Docling",
openrag: "OpenRAG",
langflow: "Langflow",
opensearch: "OpenSearch",
};
function truncateLine(
text: string,
maxLength = FILE_ERROR_MAX_LINE_LENGTH,
): string {
if (text.length <= maxLength) {
return text;
}
return `${text.slice(0, maxLength - 1).trimEnd()}…`;
}
export function formatApiComponent(
component?: TaskFailureComponent,
): TaskErrorComponentCause | undefined {
if (!component) {
return undefined;
}
return COMPONENT_LABELS[component];
}
export function normalizeFailurePhase(
phase?: string,
): TaskPipelineStepId | undefined {
if (!phase) {
return undefined;
}
if (phase in PIPELINE_STEP_LABELS) {
return phase as TaskPipelineStepId;
}
return undefined;
}
export function buildRowStatusLabel(failedStep: TaskPipelineStepId): string {
if (failedStep === "cancelled") {
return "Cancelled";
}
if (failedStep === "file_validation") {
return "File validation issue";
}
if (failedStep === "unknown") {
return "Failed";
}
return `${PIPELINE_STEP_LABELS[failedStep]} issue`;
}
function buildFailureSummary(failedStep: TaskPipelineStepId): string {
if (failedStep === "cancelled") {
return "Cancelled";
}
return `Failed at ${PIPELINE_STEP_LABELS[failedStep].toLowerCase()}`;
}
function buildPipelineStepsFromFailurePhase(
failurePhase: TaskPipelineStepId,
): IngestionPipelineStep[] {
if (
failurePhase === "file_validation" ||
failurePhase === "cancelled" ||
failurePhase === "unknown"
) {
return [
{
id: failurePhase,
label: PIPELINE_STEP_LABELS[failurePhase],
status: "failed",
},
];
}
const failedIndex = PIPELINE_STEP_ORDER.indexOf(failurePhase);
if (failedIndex < 0) {
return [
{ id: "unknown", label: PIPELINE_STEP_LABELS.unknown, status: "failed" },
];
}
return PIPELINE_STEP_ORDER.slice(0, failedIndex + 1).map((id, index) => ({
id,
label: PIPELINE_STEP_LABELS[id],
status: index < failedIndex ? "completed" : "failed",
}));
}
export function resolveTaskFileError(
fileInfo: TaskFileEntry,
taskError?: string,
): string {
if (
fileInfo.result &&
typeof fileInfo.result === "object" &&
"warning" in fileInfo.result &&
typeof fileInfo.result.warning === "string" &&
fileInfo.result.warning.trim()
) {
return formatProviderErrorMessage(fileInfo.result.warning.trim());
}
if (typeof fileInfo.user_facing_message === "string") {
const message = fileInfo.user_facing_message.trim();
if (message) {
return formatProviderErrorMessage(message);
}
}
if (typeof fileInfo.error === "string" && fileInfo.error.trim()) {
return formatProviderErrorMessage(fileInfo.error.trim());
}
if (typeof taskError === "string" && taskError.trim()) {
return formatProviderErrorMessage(taskError.trim());
}
return "Unknown error";
}
/** Best available user-facing reason for a failed ingestion task toast. */
export function getTaskFailureToastDescription(task: {
error?: string | null;
failed_files?: number;
files?: Record<string, TaskFileEntry> | null;
}): string {
const files = Object.values(task.files ?? {});
for (const fileInfo of files) {
if (fileInfo.status !== "failed" && fileInfo.status !== "error") {
continue;
}
const message = resolveTaskFileError(fileInfo, task.error ?? undefined);
if (message && message !== "Unknown error") {
return message;
}
}
if (typeof task.error === "string" && task.error.trim()) {
return task.error.trim();
}
const failedCount =
task.failed_files ??
files.filter((file) => file.status === "failed" || file.status === "error")
.length;
if (failedCount > 0) {
return `${failedCount} file${failedCount !== 1 ? "s" : ""} failed`;
}
return "Unknown error";
}
export function analyzeTaskFileIngestionFailure(
fileInfo: TaskFileEntry,
taskError?: string,
): TaskFileIngestionFailureAnalysis {
const resolvedError = resolveTaskFileError(fileInfo, taskError);
// Use centralized cancellation detection
const isCancelled = isFileCancelled(fileInfo);
const failedStep = isCancelled
? "cancelled"
: (normalizeFailurePhase(fileInfo.failure_phase) ?? "unknown");
const pipelineSteps = buildPipelineStepsFromFailurePhase(failedStep);
const componentCause = formatApiComponent(fileInfo.component);
const componentTags = componentCause ? [componentCause] : [];
return {
resolvedError,
failedStep,
pipelineSteps,
rowStatusLabel: buildRowStatusLabel(failedStep),
failureSummary: buildFailureSummary(failedStep),
componentCause,
componentTags,
summaryLine: truncateLine(resolvedError),
};
}