@nextsparkjs/plugin-langchain 0.1.0-beta.1

package/docs/index.md

@@ -0,0 +1,85 @@
+# LangChain Plugin Documentation
+
+Complete documentation for the LangChain Plugin - a comprehensive AI agent infrastructure for Next.js applications.
+
+---
+
+## Quick Links
+
+| I want to... | Go to... |
+|--------------|----------|
+| Understand what this plugin does | [Overview](./01-getting-started/01-overview.md) |
+| Install and configure the plugin | [Installation](./01-getting-started/02-installation.md) |
+| Set up the graph orchestrator | [Graph Orchestrator](./03-orchestration/01-graph-orchestrator.md) |
+| Monitor AI usage and costs | [Token Tracking](./04-advanced/02-token-tracking.md) |
+| Debug agent execution | [Observability](./04-advanced/01-observability.md) |
+
+---
+
+## Documentation Structure
+
+### 01 - Getting Started
+
+Essential guides for setting up and configuring the plugin.
+
+| Document | Description |
+|----------|-------------|
+| [01 - Overview](./01-getting-started/01-overview.md) | Introduction and core concepts |
+| [02 - Installation](./01-getting-started/02-installation.md) | Setup, migrations, and dependencies |
+| [03 - Configuration](./01-getting-started/03-configuration.md) | Theme-level agent configuration |
+
+### 02 - Core Concepts
+
+Deep dives into the fundamental building blocks.
+
+| Document | Description |
+|----------|-------------|
+| [01 - Architecture](./02-core-concepts/01-architecture.md) | Technical architecture and patterns |
+| [02 - Agents](./02-core-concepts/02-agents.md) | Creating and customizing agents |
+| [03 - Tools](./02-core-concepts/03-tools.md) | Building tools for agents |
+
+### 03 - Orchestration
+
+Multi-agent routing and coordination patterns.
+
+| Document | Description |
+|----------|-------------|
+| [01 - Graph Orchestrator](./03-orchestration/01-graph-orchestrator.md) | **Recommended** - Modern state-machine orchestration |
+| [02 - Legacy ReAct](./03-orchestration/02-legacy-react.md) | Deprecated ReAct-based approach |
+
+### 04 - Advanced Topics
+
+Production-ready features for monitoring, security, and performance.
+
+| Document | Description |
+|----------|-------------|
+| [01 - Observability](./04-advanced/01-observability.md) | Tracing, metrics, and debugging dashboard |
+| [02 - Token Tracking](./04-advanced/02-token-tracking.md) | Token usage and cost monitoring |
+| [03 - Streaming](./04-advanced/03-streaming.md) | Real-time SSE streaming responses |
+| [04 - Guardrails](./04-advanced/04-guardrails.md) | Security: injection detection, PII masking |
+
+### 05 - Reference
+
+Complete API documentation and examples.
+
+| Document | Description |
+|----------|-------------|
+| [01 - API Reference](./05-reference/01-api-reference.md) | Complete API documentation |
+| [02 - Customization](./05-reference/02-customization.md) | Advanced customization guide |
+| [03 - Examples](./05-reference/03-examples.md) | Real-world implementation examples |
+
+---
+
+## Version History
+
+| Version | Changes |
+|---------|---------|
+| v3.0 | Added Graph Orchestrator, Observability, Token Tracking, Streaming, Guardrails |
+| v2.0 | Added multi-provider support, persistent memory |
+| v1.0 | Initial release with ReAct-based orchestration |
+
+---
+
+## Related Documentation
+
+- [Theme AI Documentation](../../themes/default/docs/03-ai/) - Theme-specific AI customization

package/hooks/observability/useMetrics.ts

@@ -0,0 +1,31 @@
+'use client'
+
+import { useQuery } from '@tanstack/react-query'
+
+interface MetricsResponse {
+  success: boolean
+  totalTraces: number
+  successTraces: number
+  errorTraces: number
+  avgLatency: number
+  totalTokens: number
+}
+
+async function fetchMetrics(period: string): Promise<MetricsResponse> {
+  const response = await fetch(`/api/v1/plugin/langchain/observability/metrics?period=${period}`)
+
+  if (!response.ok) {
+    throw new Error('Failed to fetch metrics')
+  }
+
+  return response.json()
+}
+
+export function useMetrics(period: string = '24h') {
+  return useQuery({
+    queryKey: ['observability', 'metrics', period],
+    queryFn: () => fetchMetrics(period),
+    refetchInterval: 30000, // Refresh every 30 seconds
+    staleTime: 20000,
+  })
+}

package/hooks/observability/useTraceDetail.ts

@@ -0,0 +1,48 @@
+'use client'
+
+import { useQuery } from '@tanstack/react-query'
+import type { Trace, Span } from '../../types/observability.types'
+
+interface ParentTraceInfo {
+  traceId: string
+  agentName: string
+}
+
+interface TraceDetailApiResponse {
+  success: boolean
+  data: {
+    trace: Trace
+    spans: Span[]
+    childTraces: Trace[]
+    childSpansMap: Record<string, Span[]>
+    parentTrace?: ParentTraceInfo
+  }
+}
+
+interface TraceDetailResponse {
+  trace: Trace
+  spans: Span[]
+  childTraces: Trace[]
+  childSpansMap: Record<string, Span[]>
+  parentTrace?: ParentTraceInfo
+}
+
+async function fetchTraceDetail(traceId: string): Promise<TraceDetailResponse> {
+  const response = await fetch(`/api/v1/plugin/langchain/observability/traces/${traceId}`)
+
+  if (!response.ok) {
+    throw new Error('Failed to fetch trace detail')
+  }
+
+  const json: TraceDetailApiResponse = await response.json()
+  return json.data
+}
+
+export function useTraceDetail(traceId: string | null) {
+  return useQuery({
+    queryKey: ['observability', 'trace', traceId],
+    queryFn: () => fetchTraceDetail(traceId!),
+    enabled: !!traceId,
+    staleTime: 10000,
+  })
+}

package/hooks/observability/useTraces.ts

@@ -0,0 +1,59 @@
+'use client'
+
+import { useQuery } from '@tanstack/react-query'
+import type { Trace } from '../../types/observability.types'
+
+interface TracesFilters {
+  status?: string
+  agent?: string
+  teamId?: string
+  from?: string
+  to?: string
+  limit?: number
+  cursor?: string
+}
+
+interface TracesApiResponse {
+  success: boolean
+  data: {
+    traces: Trace[]
+    hasMore: boolean
+    nextCursor?: string
+  }
+}
+
+interface TracesResponse {
+  traces: Trace[]
+  hasMore: boolean
+  nextCursor?: string
+}
+
+async function fetchTraces(filters: TracesFilters): Promise<TracesResponse> {
+  const params = new URLSearchParams()
+
+  if (filters.status) params.append('status', filters.status)
+  if (filters.agent) params.append('agent', filters.agent)
+  if (filters.teamId) params.append('teamId', filters.teamId)
+  if (filters.from) params.append('from', filters.from)
+  if (filters.to) params.append('to', filters.to)
+  if (filters.limit) params.append('limit', filters.limit.toString())
+  if (filters.cursor) params.append('cursor', filters.cursor)
+
+  const response = await fetch(`/api/v1/plugin/langchain/observability/traces?${params}`)
+
+  if (!response.ok) {
+    throw new Error('Failed to fetch traces')
+  }
+
+  const json: TracesApiResponse = await response.json()
+  return json.data
+}
+
+export function useTraces(filters: TracesFilters = {}) {
+  return useQuery({
+    queryKey: ['observability', 'traces', filters],
+    queryFn: () => fetchTraces(filters),
+    refetchInterval: 5000, // Refresh every 5 seconds
+    staleTime: 3000,
+  })
+}

package/lib/agent-factory.ts

@@ -0,0 +1,354 @@
+import { HumanMessage, AIMessage, SystemMessage, BaseMessage } from '@langchain/core/messages'
+import { createReactAgent } from '@langchain/langgraph/prebuilt'
+import { getModel } from './providers'
+import { memoryStore } from './memory-store'
+import { ToolDefinition, buildTools, convertToOpenAITools } from './tools-builder'
+import { config } from '../plugin.config'
+import { createAgentLogger } from './logger'
+import { tokenTracker } from './token-tracker'
+import { streamChat as streamChatFn, StreamChunk, StreamChatOptions } from './streaming'
+import { guardrails, GuardrailsConfig } from './guardrails'
+import { tracer } from './tracer'
+import { createTracingCallbacks } from './tracer-callbacks'
+import type { ModelConfig, AgentContext, SessionConfig } from '../types/langchain.types'
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
+
+// Re-export types for convenience
+export type { StreamChunk, StreamChatOptions }
+
+interface CreateAgentOptions {
+    /** Unique session identifier for conversation memory */
+    sessionId: string
+    /** Human-readable agent name for tracing and logging */
+    agentName?: string
+    /** System prompt that defines the agent's behavior */
+    systemPrompt?: string
+    /** Tools available to the agent */
+    tools?: ToolDefinition<any>[]
+    /**
+     * Model configuration override.
+     * If not provided, uses plugin defaults from environment variables.
+     *
+     * @example
+     * // Use OpenAI GPT-4
+     * modelConfig: { provider: 'openai', model: 'gpt-4o' }
+     *
+     * // Use Anthropic Claude
+     * modelConfig: { provider: 'anthropic', model: 'claude-3-5-sonnet-20241022' }
+     *
+     * // Use local Ollama
+     * modelConfig: { provider: 'ollama', model: 'llama3.2:3b' }
+     *
+     * // Use with temperature
+     * modelConfig: { provider: 'openai', model: 'gpt-4o', temperature: 0.7 }
+     */
+    modelConfig?: Partial<ModelConfig>
+    /**
+     * Context for multi-tenant memory storage and prompt injection.
+     * Required for database-persisted conversation history.
+     * Can include additional data for Handlebars template rendering.
+     */
+    context?: AgentContext
+    /**
+     * Session configuration for memory customization.
+     * Allows per-agent TTL and message limits.
+     */
+    sessionConfig?: SessionConfig
+    /**
+     * Guardrails configuration for security and safety
+     */
+    guardrails?: GuardrailsConfig
+    /**
+     * Parent trace ID for nested agent calls (e.g., orchestrator -> sub-agent)
+     */
+    parentId?: string
+    /**
+     * Maximum number of iterations for the ReAct loop.
+     * Default is 25. Increase for complex multi-step tasks.
+     * @default 50
+     */
+    recursionLimit?: number
+}
+
+export const createAgent = async (options: CreateAgentOptions) => {
+    const {
+        sessionId,
+        agentName,
+        systemPrompt = 'You are a helpful AI assistant.',
+        tools = [],
+        modelConfig,
+        context,
+        sessionConfig,
+        parentId,
+        recursionLimit = 50,  // Default higher than LangGraph's 25 for multi-step tasks
+    } = options
+
+    // Warn in development if context is not provided (memory won't be persisted)
+    if (!context && config.debug) {
+        console.warn('[LangChain Agent] No context provided - conversation history will not be persisted to database')
+    }
+
+    // Get model based on configuration (or defaults from env vars)
+    const model = getModel(modelConfig)
+    const langChainTools = buildTools(tools)
+
+    // Determine effective model info for logging
+    const effectiveProvider = modelConfig?.provider || config.defaultProvider
+    const providerConfig = config.providers[effectiveProvider] as { model?: string; baseUrl?: string; temperature?: number }
+    const effectiveModel = modelConfig?.model || providerConfig?.model || 'default'
+    const effectiveBaseUrl = modelConfig?.options?.baseUrl || providerConfig?.baseUrl
+
+    // Create logger for this session (will be garbage collected when agent is done)
+    const logger = createAgentLogger({
+        agentName: agentName || 'single-agent',
+        userName: (context?.userName as string) || 'system',
+    })
+
+    // Log session initialization with model info
+    await logger.info('SESSION_INIT', {
+        provider: effectiveProvider,
+        model: effectiveModel,
+        baseUrl: effectiveBaseUrl || 'default',
+        temperature: modelConfig?.temperature ?? providerConfig?.temperature,
+        toolsCount: tools.length,
+    })
+
+    // For OpenAI-compatible providers (including LM Studio), bind tools with custom conversion
+    // to ensure proper type: "object" in JSON Schema
+    let boundModel: BaseChatModel = model
+    if (effectiveProvider === 'openai' && tools.length > 0) {
+        const openAITools = convertToOpenAITools(tools)
+        // Bind the model with pre-converted tools
+        // Use 'any' cast as LangChain's typing doesn't expose tools in BaseChatModelCallOptions
+        boundModel = (model as any).bind({ tools: openAITools }) as BaseChatModel
+    }
+
+    const agent = createReactAgent({
+        llm: boundModel,
+        tools: langChainTools,
+        messageModifier: systemPrompt,
+    })
+
+    // Log recursion limit for debugging
+    if (config.debug) {
+        console.log(`[LangChain Agent] ${agentName || 'Agent'} created with recursionLimit: ${recursionLimit}`)
+    }
+
+    return {
+        /**
+         * Send a message to the agent and get a response
+         */
+        chat: async (message: string) => {
+            // Start trace if configured
+            const traceContext = context
+                ? await tracer.startTrace(
+                      { userId: context.userId, teamId: context.teamId },
+                      agentName || 'Agent',
+                      message,
+                      { sessionId, parentId }
+                  )
+                : null
+
+            // Create tracing callbacks if trace was started (pass model name for providers like Ollama)
+            const tracingHandler = traceContext && context
+                ? createTracingCallbacks({ userId: context.userId, teamId: context.teamId }, traceContext.traceId, effectiveModel)
+                : null
+            const tracingCallbacks = tracingHandler ? [tracingHandler] : []
+
+            try {
+                // Add user message to history
+                const userMessage = new HumanMessage(message)
+
+                // Get current history (empty array if no context provided)
+                const currentHistory = context
+                    ? await memoryStore.getMessages(sessionId, context)
+                    : []
+
+                // Invoke agent with history + new message
+                if (config.debug) {
+                    console.log(`[Agent] Invoking with message: "${message}"`)
+                }
+
+                await logger.info('USER_MESSAGE', { message })
+
+                const result = await agent.invoke(
+                    {
+                        messages: [...currentHistory, userMessage],
+                    },
+                    {
+                        callbacks: tracingCallbacks,
+                        recursionLimit,
+                    }
+                )
+
+                if (config.debug) {
+                    console.log('[Agent] Result messages:', JSON.stringify(result.messages.map(m => ({ type: m._getType(), content: m.content })), null, 2))
+                }
+
+                const newMessages = result.messages.slice(currentHistory.length)
+                try {
+                    await logger.info('AGENT_RESPONSE', {
+                        messages: newMessages.map(m => ({
+                            type: m._getType(),
+                            content: m.content,
+                            tool_calls: (m as any).tool_calls,
+                            tool_call_id: (m as any).tool_call_id
+                        }))
+                    })
+                } catch (logError) {
+                    if (config.debug) {
+                        console.error('[Logger] Failed to log AGENT_RESPONSE:', logError)
+                    }
+                }
+
+                // Result.messages contains the full conversation including the new response
+                // We need to extract the last message which is the AI response
+                const lastMessage = result.messages[result.messages.length - 1]
+                const responseContent = lastMessage.content as string
+
+                // Track token usage if available and context exists
+                const usage = (lastMessage as any).usage_metadata || (lastMessage as any).response_metadata?.usage
+                if (usage && context) {
+                    await tokenTracker.trackUsage({
+                        context,
+                        sessionId,
+                        provider: modelConfig?.provider || effectiveProvider,
+                        model: modelConfig?.model || effectiveModel,
+                        usage: {
+                            inputTokens: usage.input_tokens || 0,
+                            outputTokens: usage.output_tokens || 0,
+                            totalTokens: usage.total_tokens || 0,
+                        },
+                        agentName,
+                    })
+                }
+
+                // Update memory with the new interaction (User + AI)
+                // Note: LangGraph might return intermediate tool messages too
+                // Save new messages if context is provided
+                if (context) {
+                    await memoryStore.addMessages(sessionId, newMessages, context, sessionConfig)
+                }
+
+                // End trace successfully if started
+                if (traceContext && context) {
+                    // Flush pending operations and get call counts from tracing handler
+                    await tracingHandler?.flush()
+                    const counts = tracingHandler?.getCounts() || { llmCalls: 0, toolCalls: 0 }
+
+                    await tracer.endTrace(
+                        { userId: context.userId, teamId: context.teamId },
+                        traceContext.traceId,
+                        {
+                            output: responseContent,
+                            tokens: usage
+                                ? {
+                                      input: usage.input_tokens || 0,
+                                      output: usage.output_tokens || 0,
+                                      total: usage.total_tokens || 0,
+                                  }
+                                : undefined,
+                            llmCalls: counts.llmCalls,
+                            toolCalls: counts.toolCalls,
+                        }
+                    )
+                }
+
+                return {
+                    content: responseContent,
+                    sessionId,
+                    messages: result.messages, // Expose full messages for orchestration
+                    traceId: traceContext?.traceId, // Expose trace ID for parent-child linking
+                }
+            } catch (error) {
+                // End trace with error if started
+                if (traceContext && context) {
+                    // Flush pending operations and get call counts from tracing handler (even on error)
+                    await tracingHandler?.flush()
+                    const counts = tracingHandler?.getCounts() || { llmCalls: 0, toolCalls: 0 }
+
+                    await tracer.endTrace(
+                        { userId: context.userId, teamId: context.teamId },
+                        traceContext.traceId,
+                        {
+                            error: error instanceof Error ? error : new Error(String(error)),
+                            llmCalls: counts.llmCalls,
+                            toolCalls: counts.toolCalls,
+                        }
+                    )
+                }
+                throw error
+            }
+        },
+
+        /**
+         * Get chat history
+         */
+        getHistory: async () => {
+            if (!context) {
+                return []
+            }
+            return memoryStore.getMessages(sessionId, context)
+        },
+
+        /**
+         * Get the underlying agent for advanced use cases (e.g., streaming)
+         */
+        getAgent: () => agent,
+    }
+}
+
+/**
+ * Interface for agent configuration used by streamChat
+ */
+interface AgentConfig {
+    name?: string
+    modelConfig?: Partial<ModelConfig>
+    guardrails?: GuardrailsConfig
+}
+
+/**
+ * Stream chat with an agent
+ *
+ * Uses LangChain's streamEvents() for token-by-token streaming.
+ * Applies guardrails if configured, handles memory persistence and token tracking.
+ */
+export async function* streamChat(
+    input: string,
+    context: AgentContext,
+    config: AgentConfig,
+    options: StreamChatOptions = {}
+): AsyncGenerator<StreamChunk, void, unknown> {
+    // Create agent for streaming (we need access to the raw agent)
+    const agentInstance = await createAgent({
+        sessionId: options.sessionId || `${context.userId}-${Date.now()}`,
+        agentName: config.name,
+        modelConfig: config.modelConfig,
+        context,
+        sessionConfig: options.sessionConfig,
+    })
+
+    // Get the underlying agent
+    const agent = agentInstance.getAgent()
+
+    // Apply guardrails if configured
+    if (config.guardrails) {
+        try {
+            const { processed, warnings } = await guardrails.processInput(
+                input,
+                config.guardrails
+            )
+            input = processed
+            // Could yield warnings if needed
+        } catch (error) {
+            yield { type: 'error', error: error instanceof Error ? error.message : 'Guardrail blocked' }
+            return
+        }
+    }
+
+    // Delegate to streaming function
+    yield* streamChatFn(agent, input, context, config, {
+        ...options,
+        agentName: config.name,
+    })
+}