@nextsparkjs/core 0.1.0-beta.3 → 0.1.0-beta.4

package/templates/contents/plugins/langchain/docs/index.md

@@ -1,85 +0,0 @@
-# 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/templates/contents/plugins/langchain/hooks/observability/useMetrics.ts

@@ -1,31 +0,0 @@
-'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/templates/contents/plugins/langchain/hooks/observability/useTraceDetail.ts

@@ -1,48 +0,0 @@
-'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/templates/contents/plugins/langchain/hooks/observability/useTraces.ts

@@ -1,59 +0,0 @@
-'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/templates/contents/plugins/langchain/lib/agent-factory.ts

@@ -1,354 +0,0 @@
-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,
-    })
-}