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

package/templates/contents/plugins/langchain/lib/graph/types.ts

@@ -1,365 +0,0 @@
-/**
- * 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/templates/contents/plugins/langchain/lib/guardrails.ts

@@ -1,230 +0,0 @@
-/**
- * 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/templates/contents/plugins/langchain/lib/index.ts

@@ -1,44 +0,0 @@
-// 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/templates/contents/plugins/langchain/lib/logger.ts

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