Enterprise agent platform for building, deploying, and operating AI teammates.
export interface KnowledgeBaseErrorToastCopy {
genericTitle: string
nameUnavailableTitle: string
nameUnavailableDescription: string
embeddingTitle: string
embeddingDescription: string
rollbackTitle: string
rollbackDescription: string
}
/**
* Whether a 409 from this request is allowed to tell the user to pick another
* name.
*
* This states the **conclusion**, not the premise, because no single premise
* survives every call site: the rename dialog has a name field yet its 409 also
* covers storage collisions and lock contention, so "did the user type a name"
* cannot be answered usefully there.
*
* Pass `true` only where a 409 has exactly one possible cause -- the name just
* entered is taken. Everywhere else pass `false` and the backend's own message
* is shown, which stays accurate whichever cause actually fired. `false` is
* always the safe answer.
*/
export interface KnowledgeBaseErrorSource {
/**
* HTTP status of the failed response, or ``undefined`` when the failure did
* not come from one. Required rather than optional so a call site that checks
* ``response.ok`` cannot forget to pass ``response.status`` with it.
*/
status: number | undefined
adviseRename: boolean
}
export interface KnowledgeBaseErrorToastContent {
title: string
description?: string
}
export interface KnowledgeBaseIngestionResultLike {
collection?: string
document_count?: number
chunks_count?: number
status: string
message: string
failed_step?: string
file_name?: string
doc_id?: string
chunk_count?: number
embedding_count?: number
vector_count?: number
documents_processed?: number
chunks_created?: number
parses_completed?: number
embeddings_created?: number
error?: string
}
export interface NormalizeKnowledgeBaseIngestionResultOptions {
collection: string
fileName?: string
}
export function normalizeKnowledgeBaseIngestionResult(
result: KnowledgeBaseIngestionResultLike,
options: NormalizeKnowledgeBaseIngestionResultOptions
): Required<
Pick<
KnowledgeBaseIngestionResultLike,
| "collection"
| "document_count"
| "chunks_count"
| "status"
| "message"
| "parses_completed"
| "file_name"
| "vector_count"
>
> &
Pick<
KnowledgeBaseIngestionResultLike,
| "failed_step"
| "doc_id"
| "embedding_count"
| "embeddings_created"
| "error"
> {
const fileName = result.file_name ?? options.fileName
const documentCount = result.document_count
?? result.documents_processed
?? (result.doc_id ? 1 : 0)
const chunkCount = result.chunks_count
?? result.chunks_created
?? result.chunk_count
?? 0
const parseCount = result.parses_completed ?? (result.doc_id ? 1 : 0)
const vectorCount = result.vector_count
?? result.embeddings_created
?? result.embedding_count
?? 0
return {
collection: result.collection ?? options.collection,
document_count: documentCount,
chunks_count: chunkCount,
status: result.status,
message: result.message,
failed_step: result.failed_step,
file_name: fileName ?? options.collection,
parses_completed: parseCount,
doc_id: result.doc_id,
embedding_count: result.embedding_count,
vector_count: vectorCount,
embeddings_created: result.embeddings_created,
error: result.error ?? (result.status === "success" ? undefined : result.message),
}
}
function normalizeMessage(message: string): string {
return message.replace(/\s+/g, " ").trim()
}
function truncateDescription(message: string, maxLength = 180): string {
const normalized = normalizeMessage(message)
if (normalized.length <= maxLength) {
return normalized
}
return `${normalized.slice(0, maxLength - 1).trimEnd()}…`
}
function extractOriginalIngestionError(message: string): string | null {
const marker = "Original ingestion error:"
const startIndex = message.indexOf(marker)
if (startIndex === -1) {
return null
}
const rawOriginal = message.slice(startIndex + marker.length).trim()
const backupIndex = rawOriginal.indexOf("; backup restore also failed:")
const original = backupIndex >= 0
? rawOriginal.slice(0, backupIndex).trim()
: rawOriginal
return original || null
}
function isEmbeddingConfigurationError(message: string): boolean {
const normalized = message.toLowerCase()
return (
normalized.includes("no embedding model available") ||
(
normalized.includes("not found in hub") &&
normalized.includes("environment configuration available for embedding")
) ||
(
normalized.includes("no environment configuration") &&
normalized.includes("embedding")
)
)
}
function isRollbackFailure(message: string): boolean {
return (
message.startsWith("Failed to fully roll back ingest") ||
message.startsWith("Failed to fully roll back cloud ingest")
)
}
export function getKnowledgeBaseErrorToastContent(
message: string,
copy: KnowledgeBaseErrorToastCopy,
source: KnowledgeBaseErrorSource
): KnowledgeBaseErrorToastContent {
const normalized = normalizeMessage(message)
const originalError = extractOriginalIngestionError(normalized)
const rootCause = originalError ?? normalized
// Classifying on the status keeps this independent of the backend's English
// wording. A 409 without that advice falls through to the backend's own message:
// inventing one sentence for every conflict cause would misstate most of them.
if (source.status === 409 && source.adviseRename) {
return {
title: copy.nameUnavailableTitle,
description: copy.nameUnavailableDescription,
}
}
if (isEmbeddingConfigurationError(rootCause)) {
return {
title: copy.embeddingTitle,
description: isRollbackFailure(normalized)
? `${copy.embeddingDescription} ${copy.rollbackDescription}`
: copy.embeddingDescription,
}
}
if (isRollbackFailure(normalized)) {
return {
title: copy.rollbackTitle,
description: truncateDescription(rootCause),
}
}
return {
title: copy.genericTitle,
description: truncateDescription(normalized),
}
}
export function buildKnowledgeBaseErrorResult(
collection: string,
message: string,
failedStep?: string,
fileName?: string
): KnowledgeBaseIngestionResultLike {
return {
collection,
document_count: 0,
chunks_count: 0,
status: "error",
message,
failed_step: failedStep,
file_name: fileName,
}
}