@nextsparkjs/plugin-langchain 0.1.0-beta.1

package/presets/templates/sector7/ai-observability/[traceId]/page.tsx

@@ -0,0 +1,91 @@
+'use client'
+
+/**
+ * AI Observability Trace Detail Page Preset
+ *
+ * Shows detailed view of a specific trace with its spans.
+ * Configurable basePath allows use at any URL (e.g., /superadmin/ai-observability/{traceId})
+ */
+
+import { useRouter } from 'next/navigation'
+import { useTraceDetail } from '@/plugins/langchain/hooks/observability/useTraceDetail'
+import { TraceDetail } from '@/plugins/langchain/components/observability/TraceDetail'
+
+interface TraceDetailPagePresetProps {
+  traceId: string
+  enabled?: boolean
+  /** Base path for navigation (e.g., '/superadmin/ai-observability') */
+  basePath?: string
+}
+
+export function TraceDetailPagePreset({
+  traceId,
+  enabled = true,
+  basePath = '/superadmin/ai-observability'
+}: TraceDetailPagePresetProps) {
+  const router = useRouter()
+  const { data, isLoading, isError } = useTraceDetail(traceId)
+
+  const handleBack = () => {
+    router.push(basePath)
+  }
+
+  const handleSelectChildTrace = (childTraceId: string) => {
+    router.push(`${basePath}/${childTraceId}`)
+  }
+
+  const handleSelectParentTrace = (parentTraceId: string) => {
+    router.push(`${basePath}/${parentTraceId}`)
+  }
+
+  if (!enabled) {
+    return (
+      <div className="container py-6">
+        <p className="text-muted-foreground">Observability is disabled.</p>
+      </div>
+    )
+  }
+
+  if (isLoading) {
+    return (
+      <div className="container py-6">
+        <div className="text-center py-12">
+          <p className="text-muted-foreground">Loading trace...</p>
+        </div>
+      </div>
+    )
+  }
+
+  if (isError || !data) {
+    return (
+      <div className="container py-6">
+        <div className="text-center py-12">
+          <p className="text-destructive">Failed to load trace</p>
+          <button
+            onClick={handleBack}
+            className="mt-4 text-primary hover:underline"
+          >
+            Back to traces
+          </button>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="container py-6">
+      <TraceDetail
+        trace={data.trace}
+        spans={data.spans}
+        childTraces={data.childTraces}
+        childSpansMap={data.childSpansMap}
+        parentTrace={data.parentTrace}
+        onBack={handleBack}
+        onSelectChildTrace={handleSelectChildTrace}
+        onSelectParentTrace={handleSelectParentTrace}
+      />
+    </div>
+  )
+}
+
+export default TraceDetailPagePreset

package/presets/templates/sector7/ai-observability/page.tsx

@@ -0,0 +1,54 @@
+'use client'
+
+/**
+ * AI Observability Dashboard Page Preset
+ *
+ * Client component preset for the observability dashboard.
+ * The theme template should define its own metadata since this is a client component.
+ *
+ * Usage in theme template:
+ * ```tsx
+ * // In your theme, import the langchain config from lib/langchain/langchain.config
+ * // import { AIObservabilityPagePreset } from '@/plugins/langchain/presets/templates/sector7/ai-observability/page'
+ *
+ * export const metadata = {
+ *   title: 'AI Observability',
+ *   description: 'Monitor LangChain agent invocations and traces',
+ * }
+ *
+ * export default function AIObservabilityPage() {
+ *   // Pass observability.enabled prop from your theme's langchain config
+ *   return <AIObservabilityPagePreset enabled={true} />
+ * }
+ * ```
+ */
+
+import { ObservabilityDashboard } from '@/plugins/langchain/components/observability/ObservabilityDashboard'
+import { DisabledMessage } from '@/plugins/langchain/components/observability/DisabledMessage'
+
+interface AIObservabilityPagePresetProps {
+  enabled?: boolean
+  /** Base path for trace detail navigation (e.g., '/superadmin/ai-observability') */
+  basePath?: string
+}
+
+export function AIObservabilityPagePreset({
+  enabled = true,
+  basePath = '/superadmin/ai-observability'
+}: AIObservabilityPagePresetProps) {
+  if (!enabled) {
+    return (
+      <div className="container py-6">
+        <DisabledMessage />
+      </div>
+    )
+  }
+
+  return (
+    <div className="container py-6">
+      <ObservabilityDashboard basePath={basePath} />
+    </div>
+  )
+}
+
+export default AIObservabilityPagePreset

package/types/langchain.types.ts

@@ -0,0 +1,274 @@
+import { z } from 'zod'
+import { BaseMessage } from '@langchain/core/messages'
+import type { GuardrailsConfig } from '../lib/guardrails'
+import type { ObservabilityConfig } from './observability.types'
+
+/**
+ * Configuration for creating an agent
+ */
+export interface AgentConfig {
+    sessionId: string
+    systemPrompt?: string
+    tools?: ToolDefinition<z.ZodObject<z.ZodRawShape>>[]
+}
+
+/**
+ * Response from an agent chat invocation
+ */
+export interface AgentResponse {
+    content: string
+    sessionId: string
+}
+
+/**
+ * Chat message structure for UI
+ */
+export interface ChatMessage {
+    id: string
+    role: 'user' | 'assistant'
+    content: string
+    timestamp: number
+}
+
+/**
+ * Tool definition for creating LangChain tools
+ */
+export interface ToolDefinition<T extends z.ZodObject<z.ZodRawShape>> {
+    name: string
+    description: string
+    schema: T
+    func: (input: z.infer<T>) => Promise<string>
+}
+
+/**
+ * Tool call result
+ */
+export interface ToolCall {
+    toolName: string
+    input: Record<string, unknown>
+    output: unknown
+}
+
+/**
+ * Supported LLM providers
+ */
+export type LLMProvider = 'openai' | 'anthropic' | 'ollama'
+
+/**
+ * Model configuration for creating LLM instances
+ * Can be used to override default provider settings
+ */
+export interface ModelConfig {
+    /** LLM provider to use */
+    provider: LLMProvider
+    /** Model name (e.g., 'gpt-4o-mini', 'claude-3-5-sonnet-20241022', 'llama3.2:3b') */
+    model: string
+    /** Temperature for response generation (0-1) */
+    temperature?: number
+    /** Maximum tokens in response */
+    maxTokens?: number
+    /** Provider-specific options */
+    options?: {
+        /** API key override (uses env var if not provided) */
+        apiKey?: string
+        /** Base URL override (for Ollama or custom endpoints) */
+        baseUrl?: string
+    }
+}
+
+/**
+ * Session configuration options for memory customization
+ */
+export interface SessionConfig {
+    /** Maximum number of messages to keep in conversation (sliding window) */
+    maxMessages?: number
+    /** TTL in hours. null = no expiration (default) */
+    ttlHours?: number | null
+}
+
+/**
+ * Context passed to agents, tools, and memory operations
+ * Required: userId + teamId for multi-tenancy
+ * Flexible: Themes can add any additional properties for prompt injection
+ */
+export interface AgentContext {
+    /** User identifier (required for RLS) */
+    userId: string
+    /** Team identifier (required for RLS) */
+    teamId: string
+    /** Flexible: Theme defines any additional context */
+    [key: string]: unknown
+}
+
+/**
+ * Complete agent configuration
+ * Centralizes all settings for an agent in one place
+ */
+export interface AgentDefinition {
+    /** LLM provider */
+    provider: LLMProvider
+    /** Model name */
+    model?: string
+    /** Temperature (0-1) */
+    temperature?: number
+    /** Factory function to create tools with runtime context */
+    createTools?: (context: AgentContext) => ToolDefinition<z.ZodObject<z.ZodRawShape>>[]
+    /** System prompt - either filename (e.g., 'task-assistant') or inline string */
+    systemPrompt?: string
+    /** Description of what this agent does (for documentation) */
+    description?: string
+    /** Memory customization per agent (TTL, maxMessages) */
+    sessionConfig?: SessionConfig
+    /** Guardrails configuration for security and safety */
+    guardrails?: GuardrailsConfig
+    /**
+     * Enrich base context with runtime data for prompt templates
+     * Called before creating agent to inject business data into prompts
+     * @param baseContext - Base context with userId + teamId
+     * @returns Enhanced context with additional data for Handlebars templates
+     */
+    enrichContext?: (baseContext: AgentContext) => Promise<AgentContext>
+}
+
+/**
+ * Theme-level LangChain configuration
+ * Allows themes to specify different models for different agents
+ */
+export interface ThemeLangChainConfig {
+    /** Default provider when not specified per-agent */
+    defaultProvider: LLMProvider
+    /** Default model when not specified per-agent */
+    defaultModel?: string
+    /** Default temperature when not specified per-agent */
+    defaultTemperature?: number
+    /** Per-agent complete configuration */
+    agents?: Record<string, AgentDefinition>
+    /** Model pricing per 1M tokens (USD) */
+    pricing?: Record<string, { input: number; output: number }>
+    /** Default guardrails for all agents */
+    defaultGuardrails?: GuardrailsConfig
+    /** Observability configuration */
+    observability?: ObservabilityConfig
+}
+
+/**
+ * Provider configuration (legacy, kept for backwards compatibility)
+ * @deprecated Use ModelConfig instead
+ */
+export interface ProviderConfig {
+    type: LLMProvider
+    baseUrl?: string
+    model: string
+}
+
+/**
+ * Session data stored in memory
+ */
+export interface SessionData {
+    messages: BaseMessage[]
+    lastUpdated: number
+}
+
+// ============================================
+// CONVERSATION / SESSION TYPES
+// ============================================
+
+/**
+ * Conversation limits
+ */
+export const CONVERSATION_LIMITS = {
+    MAX_CONVERSATIONS: 50,
+    MAX_MESSAGES_PER_CONVERSATION: 50,
+} as const
+
+/**
+ * Conversation/Session information for API responses
+ */
+export interface ConversationInfo {
+    /** Unique session identifier: {userId}-{timestamp} */
+    sessionId: string
+    /** User-defined name or auto-generated from first message */
+    name: string | null
+    /** Number of messages in conversation */
+    messageCount: number
+    /** First user message (truncated to 100 chars) for display */
+    firstMessage: string | null
+    /** Whether conversation is pinned */
+    isPinned: boolean
+    /** ISO timestamp of creation */
+    createdAt: string
+    /** ISO timestamp of last update */
+    updatedAt: string
+}
+
+/**
+ * Request to create a new conversation
+ */
+export interface CreateConversationRequest {
+    /** Optional name for the conversation */
+    name?: string
+}
+
+/**
+ * Request to update an existing conversation
+ */
+export interface UpdateConversationRequest {
+    /** Session ID to update */
+    sessionId: string
+    /** New name (optional) */
+    name?: string
+    /** New pin status (optional) */
+    isPinned?: boolean
+}
+
+/**
+ * Response for listing conversations
+ */
+export interface ListConversationsResponse {
+    success: true
+    data: {
+        sessions: ConversationInfo[]
+        count: number
+        maxAllowed: number
+    }
+}
+
+/**
+ * Response for creating a conversation
+ */
+export interface CreateConversationResponse {
+    success: true
+    data: {
+        sessionId: string
+        name: string | null
+        createdAt: string
+    }
+}
+
+/**
+ * Response for getting conversation with messages
+ */
+export interface GetConversationResponse {
+    success: true
+    data: ConversationInfo & {
+        messages: ChatMessage[]
+    }
+}
+
+/**
+ * Error response when limit is reached
+ */
+export interface ConversationLimitError {
+    success: false
+    error: 'CONVERSATION_LIMIT_REACHED'
+    message: string
+    data: {
+        currentCount: number
+        maxAllowed: number
+        oldestSession: {
+            sessionId: string
+            name: string | null
+            updatedAt: string
+        } | null
+    }
+}

package/types/observability.types.ts

@@ -0,0 +1,270 @@
+/**
+ * LangChain Observability Types
+ *
+ * Type definitions for trace and span tracking in LangChain agents.
+ */
+
+/**
+ * Trace status
+ */
+export type TraceStatus = 'running' | 'success' | 'error'
+
+/**
+ * Span type
+ */
+export type SpanType = 'llm' | 'tool' | 'chain' | 'retriever'
+
+/**
+ * Full trace record with all observability data
+ */
+export interface Trace {
+  /** Unique trace identifier */
+  traceId: string
+  /** User who triggered the invocation */
+  userId: string
+  /** Team context */
+  teamId: string
+  /** Optional session identifier */
+  sessionId?: string
+  /** Name of the agent */
+  agentName: string
+  /** Type/category of agent */
+  agentType?: string
+  /** Parent trace ID for nested calls */
+  parentId?: string
+  /** Agent input (truncated) */
+  input: string
+  /** Agent output (truncated) */
+  output?: string
+  /** Trace status */
+  status: TraceStatus
+  /** Error message if failed */
+  error?: string
+  /** Error type/category */
+  errorType?: string
+  /** Error stack trace */
+  errorStack?: string
+  /** Trace start timestamp */
+  startedAt: string
+  /** Trace end timestamp */
+  endedAt?: string
+  /** Total duration in milliseconds */
+  durationMs?: number
+  /** Total input tokens */
+  inputTokens: number
+  /** Total output tokens */
+  outputTokens: number
+  /** Total tokens (input + output) */
+  totalTokens: number
+  /** Total cost in USD */
+  totalCost: number
+  /** Number of LLM calls */
+  llmCalls: number
+  /** Number of tool calls */
+  toolCalls: number
+  /** Additional metadata */
+  metadata?: Record<string, unknown>
+  /** Tags for filtering */
+  tags?: string[]
+  /** Record creation timestamp */
+  createdAt: string
+}
+
+/**
+ * Individual operation (span) within a trace
+ */
+export interface Span {
+  /** Unique span identifier */
+  spanId: string
+  /** Parent trace identifier */
+  traceId: string
+  /** Parent span ID for nested operations */
+  parentSpanId?: string
+  /** Span name/description */
+  name: string
+  /** Span type */
+  type: SpanType
+  /** LLM provider (openai, anthropic, etc) */
+  provider?: string
+  /** LLM model name */
+  model?: string
+  /** Input tokens (LLM spans) */
+  inputTokens?: number
+  /** Output tokens (LLM spans) */
+  outputTokens?: number
+  /** Tool name (tool spans) */
+  toolName?: string
+  /** Tool input data (tool spans) */
+  toolInput?: unknown
+  /** Tool output data (tool spans) */
+  toolOutput?: unknown
+  /** Generic span input */
+  input?: unknown
+  /** Generic span output */
+  output?: unknown
+  /** Span status */
+  status: TraceStatus
+  /** Error message if failed */
+  error?: string
+  /** Span start timestamp */
+  startedAt: string
+  /** Span end timestamp */
+  endedAt?: string
+  /** Span duration in milliseconds */
+  durationMs?: number
+  /** Nesting depth in span tree */
+  depth: number
+  /** Record creation timestamp */
+  createdAt: string
+}
+
+/**
+ * Observability configuration
+ */
+export interface ObservabilityConfig {
+  /** Whether observability is enabled */
+  enabled: boolean
+  /** Data retention settings */
+  retention: {
+    /** Days to keep trace data */
+    traces: number
+  }
+  /** Sampling configuration */
+  sampling: {
+    /** Sample rate (0.0-1.0) */
+    rate: number
+    /** Always trace errors regardless of sample rate */
+    alwaysTraceErrors: boolean
+  }
+  /** PII and content processing */
+  pii: {
+    /** Mask inputs for PII */
+    maskInputs: boolean
+    /** Mask outputs for PII */
+    maskOutputs: boolean
+    /** Truncate content at this length */
+    truncateAt: number
+  }
+}
+
+/**
+ * Runtime trace context
+ */
+export interface TraceContext {
+  /** Trace identifier */
+  traceId: string
+  /** User ID */
+  userId: string
+  /** Team ID */
+  teamId: string
+  /** Optional session ID */
+  sessionId?: string
+  /** Agent name */
+  agentName: string
+}
+
+/**
+ * Runtime span context
+ */
+export interface SpanContext {
+  /** Span identifier */
+  spanId: string
+  /** Parent trace ID */
+  traceId: string
+  /** Parent span ID (if nested) */
+  parentSpanId?: string
+  /** Span name */
+  name: string
+  /** Span type */
+  type: SpanType
+  /** Nesting depth */
+  depth: number
+  /** Start timestamp */
+  startedAt: Date
+}
+
+/**
+ * Options for starting a trace
+ */
+export interface StartTraceOptions {
+  /** Agent type/category */
+  agentType?: string
+  /** Parent trace ID for nested calls */
+  parentId?: string
+  /** Session ID */
+  sessionId?: string
+  /** Initial metadata */
+  metadata?: Record<string, unknown>
+  /** Initial tags */
+  tags?: string[]
+}
+
+/**
+ * Options for ending a trace
+ */
+export interface EndTraceOptions {
+  /** Output content */
+  output?: string
+  /** Error if trace failed */
+  error?: Error | string
+  /** Token usage */
+  tokens?: {
+    input: number
+    output: number
+    total: number
+  }
+  /** Cost in USD */
+  cost?: number
+  /** LLM call count */
+  llmCalls?: number
+  /** Tool call count */
+  toolCalls?: number
+  /** Additional metadata */
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Options for starting a span
+ */
+export interface StartSpanOptions {
+  /** Span name */
+  name: string
+  /** Span type */
+  type: SpanType
+  /** Parent span ID (if nested) */
+  parentSpanId?: string
+  /** Nesting depth */
+  depth?: number
+  /** LLM provider */
+  provider?: string
+  /** LLM model */
+  model?: string
+  /** Tool name */
+  toolName?: string
+  /** Span input */
+  input?: unknown
+}
+
+/**
+ * Options for ending a span
+ */
+export interface EndSpanOptions {
+  /** Span output */
+  output?: unknown
+  /** Error if span failed */
+  error?: Error | string
+  /** Token usage (LLM spans) */
+  tokens?: {
+    input: number
+    output: number
+  }
+  /** Tool input (tool spans) */
+  toolInput?: unknown
+  /** Tool output (tool spans) */
+  toolOutput?: unknown
+}
+
+/**
+ * Content type for processing
+ */
+export type ContentType = 'input' | 'output'