@nextsparkjs/plugin-langchain 0.1.0-beta.1

package/lib/graph/types.ts

@@ -0,0 +1,365 @@
+/**
+ * LangGraph Orchestrator Types
+ *
+ * State schema and types for the explicit graph-based orchestrator.
+ * Replaces ReAct loops with deterministic state machine flow.
+ *
+ * GENERIC ARCHITECTURE:
+ * - Plugin defines generic interfaces (AgentTool, OrchestratorConfig)
+ * - Theme provides tool implementations and configuration
+ * - No hardcoded entity knowledge in plugin
+ */
+
+import type { BaseMessage } from '@langchain/core/messages'
+import type { AgentContext, SessionConfig, LLMProvider } from '../../types/langchain.types'
+import type { z } from 'zod'
+
+// ============================================
+// AGENT TOOL INTERFACE (NEW - GENERIC)
+// ============================================
+
+/**
+ * Handler node function type
+ * Theme must implement these and pass to graph factory
+ */
+export type HandlerNodeFn = (state: OrchestratorState) => Promise<Partial<OrchestratorState>>
+
+/**
+ * Agent tool definition - describes a capability the orchestrator can use
+ *
+ * Example:
+ * {
+ *   name: 'task',
+ *   description: 'Task/todo management (list, create, update, delete)',
+ *   handler: taskHandlerNode,
+ *   exampleParameters: 'title, description, priority (low/medium/high/urgent)',
+ * }
+ */
+export interface AgentTool {
+    /** Unique identifier (e.g., 'task', 'customer', 'product') */
+    name: string
+    /** Description for router prompt */
+    description: string
+    /** Optional Zod schema for parameter extraction */
+    parameterSchema?: z.ZodSchema
+    /** Handler implementation (theme-provided) */
+    handler: HandlerNodeFn
+    /** Example parameters for router prompt (optional) */
+    exampleParameters?: string
+}
+
+/**
+ * Orchestrator configuration - provided by theme
+ */
+export interface OrchestratorConfig {
+    /** Tools registered by theme */
+    tools: AgentTool[]
+    /** System intents like 'greeting', 'clarification' (default: both) */
+    systemIntents?: ('greeting' | 'clarification')[]
+    /** Additional router prompt context (optional) */
+    routerPromptExtras?: string
+}
+
+// ============================================
+// INTENT TYPES (NOW DYNAMIC)
+// ============================================
+
+/**
+ * System intent types (built into plugin)
+ */
+export type SystemIntentType = 'greeting' | 'clarification'
+
+/**
+ * Intent types that the router can classify
+ * Now dynamic - can be any tool name registered in OrchestratorConfig
+ */
+export type IntentType = string
+
+/**
+ * Actions that can be performed on entities
+ */
+export type IntentAction = 'list' | 'create' | 'update' | 'delete' | 'search' | 'get' | 'unknown'
+
+/**
+ * A single parsed intent from user input
+ */
+export interface Intent {
+    /** Type of intent (which handler should process it) */
+    type: IntentType
+    /** Action to perform */
+    action: IntentAction
+    /** Extracted parameters for the action */
+    parameters: Record<string, unknown>
+    /** Original text that maps to this intent */
+    originalText: string
+    /** Confidence score from router (0-1) */
+    confidence?: number
+}
+
+/**
+ * Router output schema (for structured output)
+ */
+export interface RouterOutput {
+    intents: Intent[]
+    /** If true, needs clarification from user */
+    needsClarification: boolean
+    /** Clarification question if needed */
+    clarificationQuestion?: string
+}
+
+// ============================================
+// HANDLER RESULT TYPES (NOW GENERIC)
+// ============================================
+
+/**
+ * Generic handler result interface
+ * Replaces entity-specific types (TaskHandlerResult, CustomerHandlerResult, etc.)
+ */
+export interface GenericHandlerResult {
+    success: boolean
+    operation: IntentAction
+    message: string
+    data: unknown
+    count?: number
+    error?: string
+}
+
+/**
+ * All handler results combined - now generic
+ * Keys are tool names, values are results
+ */
+export type HandlerResults = Record<string, GenericHandlerResult>
+
+// ============================================
+// DEPRECATED TYPES (for backward compatibility during migration)
+// ============================================
+
+/**
+ * @deprecated Use GenericHandlerResult instead
+ */
+export interface TaskHandlerResult extends GenericHandlerResult {
+    data: TaskData[] | TaskData | null
+}
+
+/**
+ * @deprecated Use generic data structure instead
+ */
+export interface TaskData {
+    id: string
+    title: string
+    status?: string
+    priority?: string
+    dueDate?: string
+    description?: string
+    [key: string]: unknown
+}
+
+/**
+ * @deprecated Use GenericHandlerResult instead
+ */
+export interface CustomerHandlerResult extends GenericHandlerResult {
+    data: CustomerData[] | CustomerData | null
+}
+
+/**
+ * @deprecated Use generic data structure instead
+ */
+export interface CustomerData {
+    id: string
+    name: string
+    email?: string
+    phone?: string
+    accountNumber?: string
+    [key: string]: unknown
+}
+
+/**
+ * @deprecated Use GenericHandlerResult instead
+ */
+export interface PageHandlerResult extends GenericHandlerResult {
+    data: PageData[] | PageData | null
+}
+
+/**
+ * @deprecated Use generic data structure instead
+ */
+export interface PageData {
+    id: string
+    title: string
+    slug?: string
+    status?: string
+    [key: string]: unknown
+}
+
+// ============================================
+// ORCHESTRATOR STATE
+// ============================================
+
+/**
+ * The main state that flows through the orchestrator graph
+ */
+export interface OrchestratorState {
+    // ---- Input ----
+    /** Original user input */
+    input: string
+    /** Session identifier for memory */
+    sessionId: string
+    /** Multi-tenant context (userId, teamId, etc.) */
+    context: AgentContext
+    /** Recent conversation history (last N messages) */
+    conversationHistory: BaseMessage[]
+    /** Session configuration for memory */
+    sessionConfig?: SessionConfig
+
+    // ---- Router Configuration ----
+    /** Model configuration injected by theme (for router node) */
+    modelConfig?: ModelConfig
+
+    // ---- Router Output ----
+    /** Parsed intents from router */
+    intents: Intent[]
+    /** Whether clarification is needed */
+    needsClarification: boolean
+    /** Clarification question if needed */
+    clarificationQuestion?: string
+
+    // ---- Handler Outputs ----
+    /** Results from each handler (JSON) */
+    handlerResults: HandlerResults
+    /** Which handlers have been executed */
+    completedHandlers: IntentType[]
+
+    // ---- Final Output ----
+    /** Final response to send to user */
+    finalResponse: string | null
+    /** Error message if something failed */
+    error: string | null
+
+    // ---- Tracing ----
+    /** Trace ID for observability */
+    traceId?: string
+    /** Parent trace ID for nested calls */
+    parentTraceId?: string
+
+    // ---- Logging ----
+    /** Timestamp for logger filename (ensures all handlers write to same file) */
+    loggerTimestamp?: number
+}
+
+/**
+ * Initial state factory
+ */
+export function createInitialState(
+    input: string,
+    sessionId: string,
+    context: AgentContext,
+    conversationHistory: BaseMessage[] = [],
+    sessionConfig?: SessionConfig
+): OrchestratorState {
+    return {
+        input,
+        sessionId,
+        context,
+        conversationHistory,
+        sessionConfig,
+        intents: [],
+        needsClarification: false,
+        handlerResults: {},
+        completedHandlers: [],
+        finalResponse: null,
+        error: null,
+    }
+}
+
+// ============================================
+// GRAPH ROUTING TYPES (NOW DYNAMIC)
+// ============================================
+
+/**
+ * Possible routes from the router node - now dynamic based on tools
+ * Examples: 'task_handler', 'customer_handler', 'greeting', 'clarification', 'error'
+ */
+export type RouterRoute = string
+
+/**
+ * Possible routes after a handler completes - now dynamic
+ * Examples: 'customer_handler', 'page_handler', 'combiner'
+ */
+export type PostHandlerRoute = string
+
+// ============================================
+// NODE FUNCTION TYPES
+// ============================================
+
+/**
+ * Type for graph node functions
+ */
+export type GraphNode = (state: OrchestratorState) => Promise<Partial<OrchestratorState>>
+
+/**
+ * Type for conditional edge functions
+ */
+export type ConditionalEdge = (state: OrchestratorState) => RouterRoute | PostHandlerRoute
+
+// ============================================
+// CONFIGURATION
+// ============================================
+
+/**
+ * Graph configuration options
+ */
+export interface GraphConfig {
+    /** Maximum conversation history messages to include */
+    maxHistoryMessages: number
+    /** Temperature for router LLM */
+    routerTemperature: number
+    /** Temperature for combiner LLM */
+    combinerTemperature: number
+    /** Whether to use parallel handler execution */
+    parallelExecution: boolean
+    /** Timeout for handler execution (ms) */
+    handlerTimeout: number
+}
+
+/**
+ * Default graph configuration
+ */
+export const DEFAULT_GRAPH_CONFIG: GraphConfig = {
+    maxHistoryMessages: 5,
+    routerTemperature: 0.1,
+    combinerTemperature: 0.3,
+    parallelExecution: true,
+    handlerTimeout: 30000,
+}
+
+// ============================================
+// HANDLER FACTORY TYPES (DEPRECATED)
+// ============================================
+
+/**
+ * @deprecated Use OrchestratorConfig.tools instead
+ * Handler factory configuration
+ * Theme provides implementations for these handlers
+ */
+export interface HandlerFactories {
+    /** Handler for task-related operations */
+    taskHandler: HandlerNodeFn
+    /** Handler for customer-related operations */
+    customerHandler: HandlerNodeFn
+    /** Handler for page-related operations */
+    pageHandler: HandlerNodeFn
+}
+
+// ============================================
+// MODEL CONFIGURATION TYPES
+// ============================================
+
+/**
+ * Model configuration to inject into state
+ * Avoids router needing to import from theme
+ */
+export interface ModelConfig {
+    provider: LLMProvider
+    model?: string
+    temperature?: number
+}

package/lib/guardrails.ts

@@ -0,0 +1,230 @@
+/**
+ * Guardrails Service
+ *
+ * Security middleware for AI agents:
+ * - Prompt injection detection
+ * - PII masking
+ * - Content filtering
+ */
+
+// Injection detection patterns
+const INJECTION_PATTERNS = [
+    /ignore\s+(previous|all|above)\s+(instructions?|prompts?)/i,
+    /forget\s+(everything|all|previous)/i,
+    /you\s+are\s+now\s+/i,
+    /disregard\s+(all|previous|your)\s/i,
+    /pretend\s+(you\s+are|to\s+be)/i,
+    /act\s+as\s+(if|a|an)\s/i,
+    /jailbreak/i,
+    /bypass\s+(restrictions?|filters?|rules?)/i,
+    /system\s*:\s*/i,  // Attempting to inject system prompt
+    /\[system\]/i,
+    /\<system\>/i,
+    /\{\{.*system.*\}\}/i,  // Template injection
+]
+
+// PII patterns
+const PII_PATTERNS = {
+    email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+    phone: /\b(\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g,
+    ssn: /\b\d{3}[-.\s]?\d{2}[-.\s]?\d{4}\b/g,
+    creditCard: /\b(?:\d{4}[-.\s]?){3}\d{4}\b/g,
+    ipAddress: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+}
+
+// Content filter patterns (examples - should be customizable)
+const CONTENT_FILTER_PATTERNS: RegExp[] = [
+    // Add patterns for harmful content
+    // These are placeholders - real implementation should be customizable
+]
+
+export interface InjectionCheckResult {
+    safe: boolean
+    reason?: string
+    pattern?: string
+}
+
+export interface PIIMaskResult {
+    masked: string
+    mappings: Array<{ original: string; masked: string; type: string }>
+    hasPII: boolean
+}
+
+export interface ContentFilterResult {
+    filtered: string
+    blocked: boolean
+    reason?: string
+}
+
+export interface GuardrailsConfig {
+    promptInjection?: {
+        enabled: boolean
+        action: 'block' | 'warn' | 'log'
+        customPatterns?: RegExp[]
+    }
+    piiMasking?: {
+        enabled: boolean
+        types: Array<'email' | 'phone' | 'ssn' | 'creditCard' | 'ipAddress'>
+        action: 'mask' | 'remove' | 'log'
+    }
+    contentFilter?: {
+        enabled: boolean
+        customPatterns?: RegExp[]
+        action: 'block' | 'redact'
+    }
+}
+
+export const guardrails = {
+    /**
+     * Check input for prompt injection attempts
+     */
+    checkInjection(
+        input: string,
+        config?: GuardrailsConfig['promptInjection']
+    ): InjectionCheckResult {
+        if (!config?.enabled) {
+            return { safe: true }
+        }
+
+        const patterns = [
+            ...INJECTION_PATTERNS,
+            ...(config.customPatterns || []),
+        ]
+
+        for (const pattern of patterns) {
+            if (pattern.test(input)) {
+                return {
+                    safe: false,
+                    reason: 'Potential prompt injection detected',
+                    pattern: pattern.toString(),
+                }
+            }
+        }
+
+        return { safe: true }
+    },
+
+    /**
+     * Mask PII in input text
+     */
+    maskPII(
+        input: string,
+        config?: GuardrailsConfig['piiMasking']
+    ): PIIMaskResult {
+        if (!config?.enabled) {
+            return { masked: input, mappings: [], hasPII: false }
+        }
+
+        let masked = input
+        const mappings: PIIMaskResult['mappings'] = []
+
+        for (const type of config.types) {
+            const pattern = PII_PATTERNS[type]
+            if (!pattern) continue
+
+            // Reset lastIndex for global patterns
+            pattern.lastIndex = 0
+
+            const matches = input.matchAll(new RegExp(pattern))
+            for (const match of matches) {
+                const original = match[0]
+                const maskChar = '*'
+                const maskedValue = config.action === 'remove'
+                    ? '[REDACTED]'
+                    : original.slice(0, 2) + maskChar.repeat(original.length - 4) + original.slice(-2)
+
+                mappings.push({ original, masked: maskedValue, type })
+                masked = masked.replace(original, maskedValue)
+            }
+        }
+
+        return {
+            masked,
+            mappings,
+            hasPII: mappings.length > 0,
+        }
+    },
+
+    /**
+     * Filter content from AI output
+     */
+    filterContent(
+        output: string,
+        config?: GuardrailsConfig['contentFilter']
+    ): ContentFilterResult {
+        if (!config?.enabled) {
+            return { filtered: output, blocked: false }
+        }
+
+        const patterns = [
+            ...CONTENT_FILTER_PATTERNS,
+            ...(config.customPatterns || []),
+        ]
+
+        for (const pattern of patterns) {
+            if (pattern.test(output)) {
+                if (config.action === 'block') {
+                    return {
+                        filtered: '',
+                        blocked: true,
+                        reason: 'Content blocked by filter',
+                    }
+                } else {
+                    // Redact matching content
+                    output = output.replace(pattern, '[FILTERED]')
+                }
+            }
+        }
+
+        return { filtered: output, blocked: false }
+    },
+
+    /**
+     * Run all guardrails on input
+     * Returns processed input or throws if blocked
+     */
+    async processInput(
+        input: string,
+        config?: GuardrailsConfig
+    ): Promise<{ processed: string; warnings: string[] }> {
+        const warnings: string[] = []
+        let processed = input
+
+        // Check injection
+        if (config?.promptInjection?.enabled) {
+            const injectionResult = this.checkInjection(input, config.promptInjection)
+            if (!injectionResult.safe) {
+                if (config.promptInjection.action === 'block') {
+                    throw new Error(`Input blocked: ${injectionResult.reason}`)
+                }
+                warnings.push(injectionResult.reason || 'Potential injection detected')
+            }
+        }
+
+        // Mask PII
+        if (config?.piiMasking?.enabled) {
+            const piiResult = this.maskPII(processed, config.piiMasking)
+            processed = piiResult.masked
+            if (piiResult.hasPII) {
+                warnings.push(`PII detected and masked: ${piiResult.mappings.length} items`)
+            }
+        }
+
+        return { processed, warnings }
+    },
+
+    /**
+     * Run content filter on output
+     */
+    async processOutput(
+        output: string,
+        config?: GuardrailsConfig
+    ): Promise<{ processed: string; blocked: boolean }> {
+        if (!config?.contentFilter?.enabled) {
+            return { processed: output, blocked: false }
+        }
+
+        const result = this.filterContent(output, config.contentFilter)
+        return { processed: result.filtered, blocked: result.blocked }
+    },
+}

package/lib/index.ts

@@ -0,0 +1,44 @@
+// Agent
+export { createAgent } from './agent-factory'
+
+// Tools
+export { createTool, buildTools, type ToolDefinition } from './tools-builder'
+
+// Memory
+export {
+    memoryStore,
+    dbMemoryStore,
+    type AgentContext,
+    type SessionConfig,
+} from './memory-store'
+
+// Prompt Renderer
+export { renderPrompt, hasTemplateVariables, compilePrompt } from './prompt-renderer'
+
+// Message Serialization
+export {
+    serializeMessages,
+    deserializeMessages,
+    type SerializedMessage,
+} from './message-serializer'
+
+// Providers
+export {
+    createOllamaModel,
+    createOpenAIModel,
+    createAnthropicModel,
+    getModel,
+    isProviderAvailable,
+    getAvailableProviders,
+} from './providers'
+
+// Types (re-export for convenience)
+export type {
+    ModelConfig,
+    LLMProvider,
+    ThemeLangChainConfig,
+    AgentConfig,
+    AgentResponse,
+    ChatMessage,
+    ProviderConfig,
+} from '../types/langchain.types'

package/lib/logger.ts

@@ -0,0 +1,70 @@
+import { FileLogger } from '@nextsparkjs/core/lib/utils/file-logger'
+
+export interface AgentLoggerOptions {
+    /** Agent name (e.g., 'graph-orchestrator', 'single-agent') */
+    agentName: string
+    /** User display name (firstname-lastname), defaults to 'system' */
+    userName?: string
+    /** Session timestamp, defaults to Date.now() */
+    timestamp?: number
+}
+
+/**
+ * Sanitize a string for use in filenames.
+ * - Converts to lowercase
+ * - Replaces spaces with hyphens
+ * - Removes special characters except hyphens and underscores
+ * - Collapses multiple hyphens into one
+ */
+function sanitizeForFilename(str: string): string {
+    return str
+        .toLowerCase()
+        .trim()
+        .replace(/\s+/g, '-')           // spaces to hyphens
+        .replace(/[^a-z0-9\-_]/g, '')   // remove special chars
+        .replace(/-+/g, '-')            // collapse multiple hyphens
+        .replace(/^-|-$/g, '')          // trim leading/trailing hyphens
+        || 'unknown'                     // fallback if empty
+}
+
+/**
+ * Create a logger for an AI agent session.
+ *
+ * Logs are stored in: logger/langchain/{agentName}/{userName}-{timestamp}.log
+ *
+ * The caller is responsible for managing the logger lifecycle.
+ * When the agent/session ends, the logger will be garbage collected.
+ *
+ * Logging is controlled by the LOG_ENABLED environment variable.
+ *
+ * @example
+ * ```typescript
+ * const logger = createAgentLogger({
+ *     agentName: 'graph-orchestrator',
+ *     userName: 'Carlos García',  // → carlos-garcia
+ * })
+ *
+ * await logger.info('SESSION_INIT', { model: 'gpt-4' })
+ * await logger.info('USER_MESSAGE', { message })
+ * await logger.error('LLM_FAILED', { error })
+ * ```
+ */
+export function createAgentLogger(options: AgentLoggerOptions): FileLogger {
+    const { agentName, userName = 'system', timestamp = Date.now() } = options
+    const sanitizedUserName = sanitizeForFilename(userName)
+
+    return new FileLogger({
+        folder: `langchain/${agentName}`,
+        filename: `${sanitizedUserName}-${timestamp}`,
+    })
+}
+
+/**
+ * Clear all LangChain agent logs
+ * @param agentName - Optional agent name to clear specific agent logs
+ * @returns Number of log files deleted
+ */
+export async function clearAgentLogs(agentName?: string): Promise<number> {
+    const folder = agentName ? `langchain/${agentName}` : 'langchain'
+    return FileLogger.clearAll(folder)
+}