Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
/** Whether GET /knowledge/:id/spans returned a real trace (not legacy placeholder-only). */
export function knowledgeSpansPayloadHasTrace(
data: { trace?: { span_id?: string }; current_attempt?: number } | null | undefined,
): boolean {
if (!data?.trace) return false
return !!(data.trace.span_id || (data.current_attempt ?? 0) > 0)
}
export interface KnowledgeTraceNode {
span_id?: string
parent_span_id?: string
name: string
kind: string
status: string
started_at?: string | null
finished_at?: string | null
duration_ms?: number
error_code?: string
error_message?: string
input?: unknown
output?: unknown
metadata?: unknown
children?: KnowledgeTraceNode[]
}
export interface PostprocessTaskSummary {
running: number
failed: number
completed: number
other: number
total: number
}
const graphChunkName = /^postprocess\.graph\.chunk\[(\d+)\]$/
function timestamp(value?: string | null): number | null {
if (!value) return null
const parsed = Date.parse(value)
return Number.isNaN(parsed) ? null : parsed
}
function nodeEnd(node: KnowledgeTraceNode): number | null {
const finished = timestamp(node.finished_at)
if (finished !== null) return finished
const started = timestamp(node.started_at)
if (started !== null && typeof node.duration_ms === 'number' && node.duration_ms >= 0) {
return started + node.duration_ms
}
return null
}
/**
* The persisted postprocess stage ends after enqueue, while its workers can
* continue for minutes. Return the elapsed wall-clock window through the
* latest asynchronous descendant for the stage's inclusive display duration.
* Keep duration_ms untouched so enqueue time remains available in details.
*/
export function postprocessElapsedMs(stage: KnowledgeTraceNode, now: number): number | null {
if (stage.name !== 'postprocess') return null
const start = timestamp(stage.started_at)
if (start === null || !stage.children?.length) return null
let latest = nodeEnd(stage) ?? start
let hasTimedChild = false
const visit = (node: KnowledgeTraceNode) => {
const childStart = timestamp(node.started_at)
const end = node.status === 'running' || node.status === 'pending'
? now
: nodeEnd(node)
if (end !== null && (childStart !== null || node.status === 'pending')) {
latest = Math.max(latest, end)
hasTimedChild = true
}
node.children?.forEach(visit)
}
stage.children.forEach(visit)
return hasTimedChild ? Math.max(0, latest - start) : null
}
function aggregateStatus(nodes: KnowledgeTraceNode[]): string {
if (nodes.some(node => node.status === 'running' || node.status === 'pending')) return 'running'
if (nodes.some(node => node.status === 'failed')) return 'failed'
if (nodes.every(node => node.status === 'skipped')) return 'skipped'
if (nodes.some(node => node.status === 'cancelled')) return 'cancelled'
return 'done'
}
/**
* Groups persisted postprocess.graph.chunk[i] spans into one derived graph
* node. The derived duration is wall-clock time from the first graph worker
* start to the final graph worker finish; children retain per-chunk detail.
*/
export function groupPostprocessGraphSpans(
stage: KnowledgeTraceNode,
): KnowledgeTraceNode {
const children = stage.children || []
const graphChildren = children.filter(child => graphChunkName.test(child.name))
if (graphChildren.length === 0) return stage
const starts = graphChildren
.map(child => timestamp(child.started_at))
.filter((value): value is number => value !== null)
const ends = graphChildren
.map(nodeEnd)
.filter((value): value is number => value !== null)
const status = aggregateStatus(graphChildren)
const start = starts.length > 0 ? Math.min(...starts) : null
const terminal = status !== 'running'
const end = terminal && ends.length > 0 ? Math.max(...ends) : null
const counts = graphChildren.reduce<Record<string, number>>((result, child) => {
result[child.status] = (result[child.status] || 0) + 1
return result
}, {})
const group: KnowledgeTraceNode = {
span_id: `virtual:postprocess.graph:${stage.span_id || 'stage'}`,
parent_span_id: stage.span_id,
name: 'postprocess.graph',
kind: 'group',
status,
started_at: start === null ? null : new Date(start).toISOString(),
finished_at: end === null ? null : new Date(end).toISOString(),
duration_ms: start !== null && end !== null ? Math.max(0, end - start) : undefined,
input: { chunk_count: graphChildren.length },
output: { chunk_count: graphChildren.length, status_counts: counts },
children: graphChildren,
}
let inserted = false
const groupedChildren: KnowledgeTraceNode[] = []
for (const child of children) {
if (graphChunkName.test(child.name)) {
if (!inserted) {
groupedChildren.push(group)
inserted = true
}
continue
}
groupedChildren.push(child)
}
return { ...stage, children: groupedChildren }
}
/**
* Counts leaf postprocess spans so the UI can distinguish the five main
* pipeline stages from asynchronous enrichment work.
*/
export function summarizePostprocessTasks(
trace?: KnowledgeTraceNode,
): PostprocessTaskSummary {
const summary: PostprocessTaskSummary = {
running: 0,
failed: 0,
completed: 0,
other: 0,
total: 0,
}
if (!trace) return summary
const postprocess = trace.name === 'postprocess'
? trace
: (trace.children || []).find(child => child.name === 'postprocess')
if (!postprocess) return summary
const countLeaves = (node: KnowledgeTraceNode) => {
const children = node.children || []
if (children.length > 0) {
children.forEach(countLeaves)
return
}
summary.total++
switch (node.status) {
case 'running':
case 'pending':
case 'processing':
case 'finalizing':
summary.running++
break
case 'failed':
summary.failed++
break
case 'done':
case 'completed':
summary.completed++
break
default:
summary.other++
}
}
;(postprocess.children || []).forEach(countLeaves)
return summary
}