@nextsparkjs/plugin-langchain 0.1.0-beta.1

package/components/observability/ConversationFlow.tsx

@@ -0,0 +1,271 @@
+'use client'
+
+/**
+ * ConversationFlow Component
+ *
+ * Displays a human-readable view of the agent execution flow,
+ * showing tool calls, their inputs/outputs, and LLM responses
+ * in a chronological conversation format.
+ */
+
+import { useMemo } from 'react'
+import { useTranslations } from 'next-intl'
+import { Card, CardContent, CardHeader, CardTitle } from '@nextsparkjs/core/components/ui/card'
+import { Badge } from '@nextsparkjs/core/components/ui/badge'
+import type { Span, Trace } from '../../types/observability.types'
+import { CollapsibleJson } from './CollapsibleJson'
+
+interface ConversationFlowProps {
+  trace: Trace
+  spans: Span[]
+}
+
+interface FlowStep {
+  id: string
+  type: 'user' | 'llm' | 'tool_call' | 'tool_result' | 'assistant'
+  timestamp: string
+  content: string
+  rawData?: unknown  // For JSON data (tool inputs/outputs)
+  metadata?: {
+    model?: string
+    provider?: string
+    toolName?: string
+    duration?: number
+    tokens?: { input?: number; output?: number }
+  }
+  status?: 'success' | 'error' | 'running'
+}
+
+function formatJson(data: unknown): string {
+  if (!data) return ''
+  if (typeof data === 'string') {
+    try {
+      const parsed = JSON.parse(data)
+      return JSON.stringify(parsed, null, 2)
+    } catch {
+      return data
+    }
+  }
+  return JSON.stringify(data, null, 2)
+}
+
+function truncateContent(content: string, maxLength = 500): string {
+  if (content.length <= maxLength) return content
+  return content.slice(0, maxLength) + '...'
+}
+
+export function ConversationFlow({ trace, spans }: ConversationFlowProps) {
+  const t = useTranslations('observability')
+
+  // Transform spans into a chronological flow
+  const flowSteps = useMemo(() => {
+    const steps: FlowStep[] = []
+
+    // 1. User message (from trace input)
+    steps.push({
+      id: 'user-input',
+      type: 'user',
+      timestamp: trace.startedAt,
+      content: trace.input,
+    })
+
+    // 2. Process spans in order
+    const sortedSpans = [...spans].sort(
+      (a, b) => new Date(a.startedAt).getTime() - new Date(b.startedAt).getTime()
+    )
+
+    for (const span of sortedSpans) {
+      if (span.type === 'llm') {
+        // LLM call
+        steps.push({
+          id: `llm-${span.spanId}`,
+          type: 'llm',
+          timestamp: span.startedAt,
+          content: span.model || span.name,
+          metadata: {
+            model: span.model,
+            provider: span.provider,
+            duration: span.durationMs,
+            tokens: {
+              input: span.inputTokens,
+              output: span.outputTokens,
+            },
+          },
+          status: span.status,
+        })
+      } else if (span.type === 'tool') {
+        // Tool call with input
+        const toolInput = span.toolInput || span.input
+        if (toolInput) {
+          steps.push({
+            id: `tool-call-${span.spanId}`,
+            type: 'tool_call',
+            timestamp: span.startedAt,
+            content: formatJson(toolInput),
+            rawData: toolInput,
+            metadata: {
+              toolName: span.toolName || span.name.replace('Tool: ', ''),
+              duration: span.durationMs,
+            },
+            status: span.status,
+          })
+        }
+
+        // Tool result
+        const toolOutput = span.toolOutput || span.output
+        if (toolOutput) {
+          steps.push({
+            id: `tool-result-${span.spanId}`,
+            type: 'tool_result',
+            timestamp: span.endedAt || span.startedAt,
+            content: formatJson(toolOutput),
+            rawData: toolOutput,
+            metadata: {
+              toolName: span.toolName || span.name.replace('Tool: ', ''),
+            },
+            status: span.status,
+          })
+        }
+      }
+    }
+
+    // 3. Final assistant response (from trace output)
+    if (trace.output) {
+      steps.push({
+        id: 'assistant-output',
+        type: 'assistant',
+        timestamp: trace.endedAt || trace.startedAt,
+        content: trace.output,
+      })
+    }
+
+    return steps
+  }, [trace, spans])
+
+  const getStepLabel = (step: FlowStep) => {
+    switch (step.type) {
+      case 'user':
+        return t('flow.userMessage')
+      case 'llm':
+        return step.metadata?.provider
+          ? `${step.metadata.provider} / ${step.metadata?.model || 'unknown'}`
+          : `LLM: ${step.metadata?.model || 'unknown'}`
+      case 'tool_call':
+        return `${t('flow.toolCall')}: ${step.metadata?.toolName}`
+      case 'tool_result':
+        return `${t('flow.toolResult')}: ${step.metadata?.toolName}`
+      case 'assistant':
+        return t('flow.assistantResponse')
+      default:
+        return step.type
+    }
+  }
+
+  const getStepStyles = (type: FlowStep['type']) => {
+    // Use semantic theme colors with subtle differentiation
+    switch (type) {
+      case 'user':
+        return 'bg-muted/50 border-border'
+      case 'llm':
+        return 'bg-muted/30 border-border'
+      case 'tool_call':
+        return 'bg-card border-border'
+      case 'tool_result':
+        return 'bg-card border-border'
+      case 'assistant':
+        return 'bg-muted/50 border-border'
+      default:
+        return 'bg-muted border-border'
+    }
+  }
+
+  const getStepTypeLabel = (type: FlowStep['type']) => {
+    const labels: Record<FlowStep['type'], string> = {
+      user: 'USER',
+      llm: 'LLM',
+      tool_call: 'CALL',
+      tool_result: 'RESULT',
+      assistant: 'ASSISTANT',
+    }
+    return labels[type] || type
+  }
+
+  const formatTime = (timestamp: string) => {
+    try {
+      return new Date(timestamp).toLocaleTimeString()
+    } catch {
+      return ''
+    }
+  }
+
+  return (
+    <Card data-cy="conversation-flow">
+      <CardHeader>
+        <CardTitle>{t('flow.title')}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <div className="space-y-3">
+          {flowSteps.map((step, index) => (
+            <div
+              key={step.id}
+              className={`relative rounded-lg border p-4 ${getStepStyles(step.type)}`}
+              data-cy={`flow-step-${step.type}`}
+            >
+              {/* Connection line */}
+              {index < flowSteps.length - 1 && (
+                <div className="absolute left-6 top-full h-3 w-0.5 bg-border" />
+              )}
+
+              {/* Header */}
+              <div className="flex items-center justify-between mb-2">
+                <div className="flex items-center gap-2">
+                  <span className="text-[10px] font-mono uppercase tracking-wider text-muted-foreground bg-muted px-1.5 py-0.5 rounded">
+                    {getStepTypeLabel(step.type)}
+                  </span>
+                  <span className="font-medium text-sm">{getStepLabel(step)}</span>
+                  {step.status === 'error' && (
+                    <Badge variant="destructive" className="text-xs">
+                      Error
+                    </Badge>
+                  )}
+                </div>
+                <div className="flex items-center gap-3 text-xs text-muted-foreground">
+                  {step.metadata?.duration && (
+                    <span>{step.metadata.duration}ms</span>
+                  )}
+                  {step.metadata?.tokens?.input !== undefined && (
+                    <span>
+                      {step.metadata.tokens.input}/{step.metadata.tokens.output} tokens
+                    </span>
+                  )}
+                  <span>{formatTime(step.timestamp)}</span>
+                </div>
+              </div>
+
+              {/* Content */}
+              <div className="mt-2">
+                {step.type === 'user' || step.type === 'assistant' ? (
+                  <p className="text-sm whitespace-pre-wrap">{step.content}</p>
+                ) : step.type === 'llm' ? (
+                  <p className="text-sm text-muted-foreground">{step.content}</p>
+                ) : step.rawData ? (
+                  <CollapsibleJson data={step.rawData} maxPreviewLength={150} />
+                ) : (
+                  <pre className="text-xs bg-muted p-3 rounded overflow-x-auto whitespace-pre-wrap font-mono">
+                    {truncateContent(step.content, 1000)}
+                  </pre>
+                )}
+              </div>
+            </div>
+          ))}
+
+          {flowSteps.length === 0 && (
+            <p className="text-center text-muted-foreground py-8">
+              {t('flow.noSteps')}
+            </p>
+          )}
+        </div>
+      </CardContent>
+    </Card>
+  )
+}

package/components/observability/DisabledMessage.tsx

@@ -0,0 +1,21 @@
+'use client'
+
+import { useTranslations } from 'next-intl'
+import { Card, CardContent, CardHeader, CardTitle } from '@nextsparkjs/core/components/ui/card'
+
+export function DisabledMessage() {
+  const t = useTranslations('observability')
+
+  return (
+    <div className="flex items-center justify-center min-h-[400px]" data-cy="observability-disabled">
+      <Card className="max-w-md">
+        <CardHeader>
+          <CardTitle className="text-center">{t('title')}</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <p className="text-center text-muted-foreground">{t('disabled')}</p>
+        </CardContent>
+      </Card>
+    </div>
+  )
+}

package/components/observability/FiltersPanel.tsx

@@ -0,0 +1,82 @@
+'use client'
+
+import { useTranslations } from 'next-intl'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@nextsparkjs/core/components/ui/select'
+import { Input } from '@nextsparkjs/core/components/ui/input'
+
+interface FiltersPanelProps {
+  status: string
+  agent: string
+  search: string
+  onStatusChange: (status: string) => void
+  onAgentChange: (agent: string) => void
+  onSearchChange: (search: string) => void
+  availableAgents?: string[]
+  className?: string
+}
+
+export function FiltersPanel({
+  status,
+  agent,
+  search,
+  onStatusChange,
+  onAgentChange,
+  onSearchChange,
+  availableAgents = [],
+  className = '',
+}: FiltersPanelProps) {
+  const t = useTranslations('observability')
+
+  return (
+    <div className={`flex items-center gap-4 ${className}`} data-cy="filters-panel">
+      <div className="w-[200px]">
+        <Select value={status} onValueChange={onStatusChange}>
+          <SelectTrigger data-cy="filter-status">
+            <SelectValue placeholder={t('filters.status')} />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="all">{t('filters.allStatus')}</SelectItem>
+            <SelectItem value="success">{t('status.success')}</SelectItem>
+            <SelectItem value="error">{t('status.error')}</SelectItem>
+            <SelectItem value="running">{t('status.running')}</SelectItem>
+          </SelectContent>
+        </Select>
+      </div>
+
+      {availableAgents.length > 0 && (
+        <div className="w-[200px]">
+          <Select value={agent} onValueChange={onAgentChange}>
+            <SelectTrigger data-cy="filter-agent">
+              <SelectValue placeholder={t('filters.agent')} />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="all">{t('filters.allAgents')}</SelectItem>
+              {availableAgents.map((agentName) => (
+                <SelectItem key={agentName} value={agentName}>
+                  {agentName}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+      )}
+
+      <div className="flex-1">
+        <Input
+          type="text"
+          placeholder={t('filters.searchPlaceholder')}
+          value={search}
+          onChange={(e) => onSearchChange(e.target.value)}
+          data-cy="filter-search"
+          className="max-w-md"
+        />
+      </div>
+    </div>
+  )
+}

package/components/observability/ObservabilityDashboard.tsx

@@ -0,0 +1,230 @@
+'use client'
+
+import { useState, useMemo, useCallback, useEffect } from 'react'
+import { useRouter } from 'next/navigation'
+import { useTranslations } from 'next-intl'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@nextsparkjs/core/components/ui/select'
+import { Button } from '@nextsparkjs/core/components/ui/button'
+import { RefreshCcw } from 'lucide-react'
+import { useTraces } from '../../hooks/observability/useTraces'
+import { TracesTable } from './TracesTable'
+import { FiltersPanel } from './FiltersPanel'
+import type { Trace } from '../../types/observability.types'
+
+interface ObservabilityDashboardProps {
+  /** Base path for trace detail navigation (e.g., '/superadmin/ai-observability') */
+  basePath?: string
+}
+
+export function ObservabilityDashboard({ basePath = '/superadmin/ai-observability' }: ObservabilityDashboardProps) {
+  const t = useTranslations('observability')
+  const router = useRouter()
+  const [period, setPeriod] = useState('24h')
+  const [statusFilter, setStatusFilter] = useState('all')
+  const [agentFilter, setAgentFilter] = useState('all')
+  const [searchFilter, setSearchFilter] = useState('')
+  const [allTraces, setAllTraces] = useState<Trace[]>([])
+  const [cursor, setCursor] = useState<string | undefined>(undefined)
+  const [isLoadingMore, setIsLoadingMore] = useState(false)
+  const [isReloading, setIsReloading] = useState(false)
+  const [refreshKey, setRefreshKey] = useState(0)
+
+  // Calculate date range based on period (refreshKey forces recalculation)
+  const dateRange = useMemo(() => {
+    const now = new Date()
+    const periods: Record<string, number> = {
+      '1h': 1,
+      '24h': 24,
+      '7d': 24 * 7,
+      '30d': 24 * 30,
+    }
+
+    const hoursAgo = periods[period] || 24
+    const from = new Date(now.getTime() - hoursAgo * 60 * 60 * 1000)
+
+    return {
+      from: from.toISOString(),
+      to: now.toISOString(),
+    }
+  }, [period, refreshKey])
+
+  // Reset pagination when filters change
+  const resetPagination = useCallback(() => {
+    setAllTraces([])
+    setCursor(undefined)
+  }, [])
+
+  // Fetch traces with filters
+  const tracesQuery = useTraces({
+    status: statusFilter === 'all' ? undefined : statusFilter,
+    agent: agentFilter === 'all' ? undefined : agentFilter,
+    from: dateRange.from,
+    to: dateRange.to,
+    limit: 50,
+    cursor,
+  })
+
+  // Update allTraces when data changes
+  useEffect(() => {
+    if (tracesQuery.data?.traces) {
+      if (cursor) {
+        // Append to existing traces (load more)
+        setAllTraces((prev) => [...prev, ...tracesQuery.data.traces])
+      } else if (isReloading) {
+        // Reload: prepend new traces without duplicates
+        setAllTraces((prev) => {
+          const existingIds = new Set(prev.map((t) => t.traceId))
+          const newTraces = tracesQuery.data.traces.filter(
+            (t) => !existingIds.has(t.traceId)
+          )
+          return [...newTraces, ...prev]
+        })
+        setIsReloading(false)
+      } else {
+        // Replace traces (new filter/period)
+        setAllTraces(tracesQuery.data.traces)
+      }
+      setIsLoadingMore(false)
+    }
+  }, [tracesQuery.data, cursor, isReloading])
+
+  // Extract unique agent names for filter
+  const availableAgents = useMemo(() => {
+    if (allTraces.length === 0) return []
+    const agents = new Set(allTraces.map((t) => t.agentName))
+    return Array.from(agents).sort()
+  }, [allTraces])
+
+  // Filter traces by search
+  const filteredTraces = useMemo(() => {
+    if (allTraces.length === 0) return []
+    if (!searchFilter) return allTraces
+
+    const lowerSearch = searchFilter.toLowerCase()
+    return allTraces.filter(
+      (trace) =>
+        trace.traceId.toLowerCase().includes(lowerSearch) ||
+        trace.agentName.toLowerCase().includes(lowerSearch) ||
+        trace.input.toLowerCase().includes(lowerSearch)
+    )
+  }, [allTraces, searchFilter])
+
+  // Handle load more
+  const handleLoadMore = useCallback(() => {
+    if (tracesQuery.data?.nextCursor) {
+      setIsLoadingMore(true)
+      setCursor(tracesQuery.data.nextCursor)
+    }
+  }, [tracesQuery.data?.nextCursor])
+
+  // Handle trace selection - navigate to detail page
+  const handleSelectTrace = useCallback((traceId: string) => {
+    router.push(`${basePath}/${traceId}`)
+  }, [router, basePath])
+
+  // Handle filter changes - reset pagination
+  const handleStatusChange = useCallback((value: string) => {
+    setStatusFilter(value)
+    resetPagination()
+  }, [resetPagination])
+
+  const handleAgentChange = useCallback((value: string) => {
+    setAgentFilter(value)
+    resetPagination()
+  }, [resetPagination])
+
+  const handlePeriodChange = useCallback((value: string) => {
+    setPeriod(value)
+    resetPagination()
+  }, [resetPagination])
+
+  // Handle reload - fetch new traces and prepend them
+  const handleReload = useCallback(() => {
+    setIsReloading(true)
+    setRefreshKey((k) => k + 1)
+  }, [])
+
+  return (
+    <div className="space-y-6" data-cy="observability-dashboard">
+      <div className="flex items-center justify-between">
+        <div>
+          <h1 className="text-3xl font-bold">{t('title')}</h1>
+          <p className="text-muted-foreground mt-1">{t('description')}</p>
+        </div>
+
+        <div className="flex items-center gap-2">
+          <Button
+            variant="outline"
+            size="icon"
+            onClick={handleReload}
+            disabled={tracesQuery.isFetching}
+            data-cy="reload-traces"
+            title={t('reload')}
+          >
+            <RefreshCcw className={`h-4 w-4 ${tracesQuery.isFetching ? 'animate-spin' : ''}`} />
+          </Button>
+          <div className="w-[150px]">
+            <Select value={period} onValueChange={handlePeriodChange}>
+              <SelectTrigger data-cy="period-selector">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="1h">{t('period.1h')}</SelectItem>
+                <SelectItem value="24h">{t('period.24h')}</SelectItem>
+                <SelectItem value="7d">{t('period.7d')}</SelectItem>
+                <SelectItem value="30d">{t('period.30d')}</SelectItem>
+              </SelectContent>
+            </Select>
+          </div>
+        </div>
+      </div>
+
+      <FiltersPanel
+        status={statusFilter}
+        agent={agentFilter}
+        search={searchFilter}
+        onStatusChange={handleStatusChange}
+        onAgentChange={handleAgentChange}
+        onSearchChange={setSearchFilter}
+        availableAgents={availableAgents}
+      />
+
+      {tracesQuery.isLoading && (
+        <div className="text-center py-12" data-cy="loading">
+          <p className="text-muted-foreground">{t('loading')}</p>
+        </div>
+      )}
+
+      {tracesQuery.isError && (
+        <div className="text-center py-12" data-cy="error">
+          <p className="text-destructive">{t('error')}</p>
+        </div>
+      )}
+
+      {(tracesQuery.data || allTraces.length > 0) && (
+        <>
+          <TracesTable traces={filteredTraces} onSelect={handleSelectTrace} />
+
+          {tracesQuery.data?.hasMore && (
+            <div className="flex justify-center">
+              <Button
+                variant="outline"
+                onClick={handleLoadMore}
+                disabled={isLoadingMore}
+                data-cy="load-more"
+              >
+                {isLoadingMore ? t('loadingMore') : t('loadMore')}
+              </Button>
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  )
+}