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

package/dist/templates/contents/plugins/langchain/lib/graph/orchestrator-graph.ts

@@ -1,386 +0,0 @@
-/**
- * LangGraph Orchestrator Graph (GENERIC - Theme-Agnostic)
- *
- * Explicit state machine for multi-agent orchestration.
- * Replaces inefficient ReAct loops with deterministic graph flow.
- *
- * GENERIC ARCHITECTURE:
- * - Graph structure is generated dynamically from OrchestratorConfig
- * - No hardcoded knowledge of specific entities (task, customer, page)
- * - Supports N tools registered by theme
- *
- * Flow:
- * START → Router (1 LLM) → Handlers (0 LLM, sequential) → Combiner (1 LLM if needed) → END
- *
- * Benefits:
- * - 1-2 LLM calls instead of 50+
- * - No recursion limit issues
- * - Deterministic execution
- * - Theme-agnostic - works with any registered tools
- */
-
-import { StateGraph, END, START } from '@langchain/langgraph'
-import type { BaseMessage } from '@langchain/core/messages'
-import type { AgentContext, SessionConfig } from '../../types/langchain.types'
-import { createAgentLogger } from '../logger'
-import type {
-    OrchestratorState,
-    Intent,
-    HandlerResults,
-    IntentType,
-    RouterRoute,
-    GraphConfig,
-    OrchestratorConfig,
-    ModelConfig,
-} from './types'
-import { DEFAULT_GRAPH_CONFIG } from './types'
-import { createRouterNode } from './nodes/router'
-import { combinerNode } from './nodes/combiner'
-
-// ============================================
-// STATE CHANNELS DEFINITION
-// ============================================
-
-/**
- * Channel definitions for state management
- */
-const orchestratorChannels = {
-    // Input channels
-    input: {
-        value: (x: string, y?: string) => y ?? x,
-        default: () => '',
-    },
-    sessionId: {
-        value: (x: string, y?: string) => y ?? x,
-        default: () => '',
-    },
-    context: {
-        value: (x: AgentContext, y?: AgentContext) => y ?? x,
-        default: () => ({ userId: '', teamId: '' } as AgentContext),
-    },
-    conversationHistory: {
-        value: (x: BaseMessage[], y?: BaseMessage[]) => y ?? x,
-        default: () => [] as BaseMessage[],
-    },
-    sessionConfig: {
-        value: (x: SessionConfig | undefined, y?: SessionConfig | undefined) => y ?? x,
-        default: () => undefined as SessionConfig | undefined,
-    },
-    modelConfig: {
-        value: (x: ModelConfig | undefined, y?: ModelConfig | undefined) => y ?? x,
-        default: () => undefined as ModelConfig | undefined,
-    },
-
-    // Router output channels
-    intents: {
-        value: (_: Intent[], y?: Intent[]) => y ?? [],
-        default: () => [] as Intent[],
-    },
-    needsClarification: {
-        value: (_: boolean, y?: boolean) => y ?? false,
-        default: () => false,
-    },
-    clarificationQuestion: {
-        value: (x: string | undefined, y?: string | undefined) => y ?? x,
-        default: () => undefined as string | undefined,
-    },
-
-    // Handler output channels - merge results
-    handlerResults: {
-        value: (current: HandlerResults, update?: HandlerResults) =>
-            update ? { ...current, ...update } : current,
-        default: () => ({} as HandlerResults),
-    },
-    completedHandlers: {
-        value: (current: IntentType[], update?: IntentType[]) =>
-            update ? [...new Set([...current, ...update])] : current,
-        default: () => [] as IntentType[],
-    },
-
-    // Final output channels
-    finalResponse: {
-        value: (_: string | null, y?: string | null) => y ?? null,
-        default: () => null as string | null,
-    },
-    error: {
-        value: (_: string | null, y?: string | null) => y ?? null,
-        default: () => null as string | null,
-    },
-
-    // Tracing channels
-    traceId: {
-        value: (x: string | undefined, y?: string | undefined) => y ?? x,
-        default: () => undefined as string | undefined,
-    },
-    parentTraceId: {
-        value: (x: string | undefined, y?: string | undefined) => y ?? x,
-        default: () => undefined as string | undefined,
-    },
-
-    // Logging channels
-    loggerTimestamp: {
-        value: (x: number | undefined, y?: number | undefined) => y ?? x,
-        default: () => undefined as number | undefined,
-    },
-}
-
-// ============================================
-// GENERIC ROUTING FUNCTIONS
-// ============================================
-
-/**
- * Create generic routing function from router to first handler
- */
-function createRouteByIntents(config: OrchestratorConfig) {
-    const toolNames = config.tools.map(t => t.name)
-    const systemIntents = config.systemIntents || ['greeting', 'clarification']
-
-    return function routeByIntents(state: OrchestratorState): RouterRoute {
-        // Handle errors
-        if (state.error) {
-            return 'error_handler'
-        }
-
-        // Handle clarification
-        if (state.needsClarification) {
-            return 'clarification'
-        }
-
-        const intentTypes = state.intents.map((i) => i.type)
-
-        // Check for greeting-only
-        if (intentTypes.length === 1 && intentTypes[0] === 'greeting') {
-            return 'greeting'
-        }
-
-        // Find first tool handler that's needed
-        const neededTools = toolNames.filter(t => intentTypes.includes(t))
-        if (neededTools.length === 0) {
-            return 'clarification'
-        }
-
-        // Route to first tool handler
-        return `${neededTools[0]}_handler`
-    }
-}
-
-/**
- * Create generic routing function for after a handler completes
- */
-function createRouteAfterHandler(config: OrchestratorConfig, currentToolIndex: number) {
-    const toolNames = config.tools.map(t => t.name)
-
-    return function routeAfterHandler(state: OrchestratorState): string {
-        const intentTypes = state.intents.map((i) => i.type)
-        const completed = state.completedHandlers
-
-        // Find next needed handler that hasn't been completed
-        for (let i = currentToolIndex + 1; i < toolNames.length; i++) {
-            const toolName = toolNames[i]
-            if (intentTypes.includes(toolName) && !completed.includes(toolName)) {
-                return `${toolName}_handler`
-            }
-        }
-
-        // All handlers done, go to combiner
-        return 'combiner'
-    }
-}
-
-// ============================================
-// SIMPLE NODE WRAPPERS
-// ============================================
-
-/**
- * Simple pass-through for greeting
- */
-async function greetingNodeWrapper(state: OrchestratorState): Promise<Partial<OrchestratorState>> {
-    return { completedHandlers: ['greeting' as IntentType] }
-}
-
-/**
- * Clarification node - sets response asking for more info
- */
-async function clarificationNodeWrapper(state: OrchestratorState): Promise<Partial<OrchestratorState>> {
-    const question = state.clarificationQuestion || 'Could you please clarify what you would like me to do?'
-    return {
-        finalResponse: question,
-        completedHandlers: ['clarification' as IntentType],
-    }
-}
-
-/**
- * Error handling node
- */
-async function errorNodeWrapper(state: OrchestratorState): Promise<Partial<OrchestratorState>> {
-    return {
-        finalResponse: state.error || 'An unexpected error occurred. Please try again.',
-    }
-}
-
-// ============================================
-// GRAPH BUILDER (GENERIC)
-// ============================================
-
-/**
- * Create the orchestrator graph dynamically from configuration
- *
- * @param config - Orchestrator configuration with tools
- * @param _graphConfig - Optional graph configuration (reserved for future use)
- * @returns Compiled LangGraph
- */
-export function createOrchestratorGraph(
-    config: OrchestratorConfig,
-    _graphConfig: Partial<GraphConfig> = {}
-) {
-    // Create the graph with channels
-    // Using 'any' to bypass strict typing of StateGraph which expects literal node names
-    const graph: any = new StateGraph<OrchestratorState>({
-        channels: orchestratorChannels as any,
-    })
-
-    // Add router node (uses config for dynamic prompt/schema)
-    const routerNode = createRouterNode(config)
-    graph.addNode('router', routerNode)
-
-    // Add handler nodes dynamically from config
-    for (const tool of config.tools) {
-        graph.addNode(`${tool.name}_handler`, tool.handler)
-    }
-
-    // Add system nodes
-    graph.addNode('combiner', combinerNode)
-    graph.addNode('greeting', greetingNodeWrapper)
-    graph.addNode('clarification', clarificationNodeWrapper)
-    graph.addNode('error_handler', errorNodeWrapper)
-
-    // Edge from START to router
-    graph.addEdge(START, 'router')
-
-    // Build routing map for router node
-    const routingMap: Record<string, string> = {
-        greeting: 'greeting',
-        clarification: 'clarification',
-        error_handler: 'error_handler',
-    }
-
-    // Add each tool handler as a possible route
-    for (const tool of config.tools) {
-        routingMap[`${tool.name}_handler`] = `${tool.name}_handler`
-    }
-
-    // Conditional edges from router
-    const routeByIntents = createRouteByIntents(config)
-    graph.addConditionalEdges('router', routeByIntents, routingMap)
-
-    // Add conditional edges from each handler to next handler or combiner
-    for (let i = 0; i < config.tools.length; i++) {
-        const tool = config.tools[i]
-        const routeAfterHandler = createRouteAfterHandler(config, i)
-
-        // Build routing map for this handler
-        const handlerRoutingMap: Record<string, string> = { combiner: 'combiner' }
-
-        // Add all handlers that could come after this one
-        for (let j = i + 1; j < config.tools.length; j++) {
-            const nextTool = config.tools[j]
-            handlerRoutingMap[`${nextTool.name}_handler`] = `${nextTool.name}_handler`
-        }
-
-        graph.addConditionalEdges(
-            `${tool.name}_handler`,
-            routeAfterHandler,
-            handlerRoutingMap
-        )
-    }
-
-    // Greeting goes to combiner for friendly response
-    graph.addEdge('greeting', 'combiner')
-
-    // Terminal nodes
-    graph.addEdge('combiner', END)
-    graph.addEdge('clarification', END)
-    graph.addEdge('error_handler', END)
-
-    // Compile and return
-    return graph.compile()
-}
-
-// ============================================
-// INVOKE HELPER (UPDATED FOR GENERIC CONFIG)
-// ============================================
-
-/**
- * Invoke the orchestrator graph with user input
- *
- * @param input - User message
- * @param sessionId - Session identifier
- * @param context - Multi-tenant context
- * @param conversationHistory - Recent conversation history
- * @param config - Orchestrator configuration with tools (NEW)
- * @param options - Additional options
- * @returns Final state with response
- */
-export async function invokeOrchestrator(
-    input: string,
-    sessionId: string,
-    context: AgentContext,
-    conversationHistory: BaseMessage[] = [],
-    config: OrchestratorConfig,
-    options: {
-        sessionConfig?: SessionConfig
-        traceId?: string
-        parentTraceId?: string
-        graphConfig?: Partial<GraphConfig>
-        modelConfig?: ModelConfig
-    } = {}
-): Promise<OrchestratorState> {
-    const graph = createOrchestratorGraph(config, options.graphConfig)
-    const loggerTimestamp = Date.now()
-    const logger = createAgentLogger({
-        agentName: 'graph-orchestrator',
-        userName: (context.userName as string) || 'system',
-        timestamp: loggerTimestamp,
-    })
-
-    await logger.info('GRAPH_ORCHESTRATOR_START', {
-        input,
-        sessionId,
-        userId: context.userId,
-        teamId: context.teamId,
-        historyLength: conversationHistory.length,
-        toolsRegistered: config.tools.map(t => t.name),
-    })
-
-    const initialState: OrchestratorState = {
-        input,
-        sessionId,
-        context,
-        conversationHistory,
-        sessionConfig: options.sessionConfig,
-        modelConfig: options.modelConfig,
-        intents: [],
-        needsClarification: false,
-        handlerResults: {},
-        completedHandlers: [],
-        finalResponse: null,
-        error: null,
-        traceId: options.traceId,
-        parentTraceId: options.parentTraceId,
-        loggerTimestamp,
-    }
-
-    const result = await graph.invoke(initialState)
-
-    await logger.info('GRAPH_ORCHESTRATOR_END', {
-        intents: (result as OrchestratorState).intents,
-        completedHandlers: (result as OrchestratorState).completedHandlers,
-        hasResponse: !!(result as OrchestratorState).finalResponse,
-        error: (result as OrchestratorState).error,
-    })
-
-    return result as OrchestratorState
-}
-
-// Export types
-export type { GraphConfig, OrchestratorConfig }

package/dist/templates/contents/plugins/langchain/lib/graph/prompts/combiner.md

@@ -1,131 +0,0 @@
-# Response Combiner
-
-You are a response synthesizer that converts JSON operation results into natural language responses for users.
-
-## Your Task
-
-Given the original user request and the results from various operations (tasks, customers, pages), generate a clear, natural response that:
-1. Summarizes ALL results
-2. Uses the same language as the user
-3. Is concise but complete
-4. Includes relevant data (names, counts, IDs)
-
-## Input Format
-
-You receive JSON with:
-- `originalRequest`: The user's original message
-- `results`: Object containing handler results (task, customer, page)
-
-Each result contains:
-- `success`: Whether the operation succeeded
-- `operation`: What was done (list, create, update, search, etc.)
-- `data`: The actual data (array or single object)
-- `count`: Number of items (for list/search)
-- `message`: Technical description
-- `error`: Error message if failed
-
-## Output Format
-
-Return ONLY the response text. No JSON, no markdown code blocks, just natural text.
-
-## Examples
-
-### Single Result - Tasks List
-Input:
-```json
-{
-  "originalRequest": "Show me my tasks",
-  "results": {
-    "task": {
-      "success": true,
-      "operation": "list",
-      "data": [
-        {"title": "Buy milk", "priority": "high", "status": "todo"},
-        {"title": "Call mom", "priority": "medium", "status": "in_progress"}
-      ],
-      "count": 2
-    }
-  }
-}
-```
-
-Output:
-```
-You have 2 tasks:
-- Buy milk (high priority, pending)
-- Call mom (medium priority, in progress)
-```
-
-### Multi Result - Tasks and Customer Search
-Input:
-```json
-{
-  "originalRequest": "Muéstrame mis tareas y el número de cuenta de StartupXYZ",
-  "results": {
-    "task": {
-      "success": true,
-      "operation": "list",
-      "data": [{"title": "Review proposal", "priority": "high"}],
-      "count": 1
-    },
-    "customer": {
-      "success": true,
-      "operation": "search",
-      "data": [{"name": "StartupXYZ", "account": 12345}],
-      "count": 1
-    }
-  }
-}
-```
-
-Output:
-```
-Tienes 1 tarea:
-- Review proposal (alta prioridad)
-
-El número de cuenta de StartupXYZ es 12345.
-```
-
-### Error Handling
-Input:
-```json
-{
-  "originalRequest": "Find customer ACME",
-  "results": {
-    "customer": {
-      "success": false,
-      "operation": "search",
-      "data": null,
-      "error": "No customers found matching 'ACME'"
-    }
-  }
-}
-```
-
-Output:
-```
-I couldn't find any customers matching "ACME". Would you like me to search with different criteria?
-```
-
-### Greeting Response
-Input:
-```json
-{
-  "originalRequest": "Hola!",
-  "results": {}
-}
-```
-
-Output:
-```
-¡Hola! ¿En qué puedo ayudarte hoy? Puedo gestionar tus tareas, buscar clientes o consultar páginas.
-```
-
-## Rules
-
-1. **Match the user's language** - If they wrote in Spanish, respond in Spanish
-2. **Be concise** - Don't repeat unnecessary information
-3. **Format lists nicely** - Use bullet points for multiple items
-4. **Include key data** - Account numbers, task titles, counts, etc.
-5. **Handle errors gracefully** - Explain what went wrong and offer alternatives
-6. **Don't expose technical details** - No JSON, no error codes, no internal messages

package/dist/templates/contents/plugins/langchain/lib/graph/prompts/router.md

@@ -1,193 +0,0 @@
-# Intent Router
-
-You are an intent classifier for a multi-agent system. Your job is to analyze user messages and extract ALL intents in structured JSON format.
-
-## Your Task
-
-Parse the user's message and identify:
-1. What type(s) of operation they want
-2. What action to perform
-3. What parameters are needed
-4. Which part of their message maps to each intent
-
-## Intent Types
-
-| Type | Description | Example Actions |
-|------|-------------|-----------------|
-| `task` | Task/todo management | list, create, update, delete, search, get |
-| `customer` | Customer/contact management | list, create, update, delete, search, get |
-| `page` | Page/content management | list, create, update, delete, search, get |
-| `greeting` | Greeting or small talk | - |
-| `clarification` | Unclear request | - |
-
-## Output Format
-
-Always respond with valid JSON:
-
-```json
-{
-  "intents": [
-    {
-      "type": "task|customer|page|greeting|clarification",
-      "action": "list|create|update|delete|search|get|unknown",
-      "parameters": { ... },
-      "originalText": "part of the user message"
-    }
-  ],
-  "needsClarification": false,
-  "clarificationQuestion": null
-}
-```
-
-## Examples
-
-### Single Intent - List Tasks
-**Input:** "Show me my tasks"
-**Output:**
-```json
-{
-  "intents": [
-    {
-      "type": "task",
-      "action": "list",
-      "parameters": {},
-      "originalText": "Show me my tasks"
-    }
-  ],
-  "needsClarification": false
-}
-```
-
-### Single Intent - Create Task with Parameters
-**Input:** "Create a task called 'Buy milk' with high priority"
-**Output:**
-```json
-{
-  "intents": [
-    {
-      "type": "task",
-      "action": "create",
-      "parameters": {
-        "title": "Buy milk",
-        "priority": "high"
-      },
-      "originalText": "Create a task called 'Buy milk' with high priority"
-    }
-  ],
-  "needsClarification": false
-}
-```
-
-### Multi-Intent - Tasks and Customer
-**Input:** "Show me my tasks and find the account number for StartupXYZ"
-**Output:**
-```json
-{
-  "intents": [
-    {
-      "type": "task",
-      "action": "list",
-      "parameters": {},
-      "originalText": "Show me my tasks"
-    },
-    {
-      "type": "customer",
-      "action": "search",
-      "parameters": {
-        "query": "StartupXYZ",
-        "fields": ["accountNumber", "name"]
-      },
-      "originalText": "find the account number for StartupXYZ"
-    }
-  ],
-  "needsClarification": false
-}
-```
-
-### Multi-Intent - Tasks with Filter and Customer
-**Input:** "Muéstrame mis tareas de prioridad baja y el número de cuenta de StartupXYZ"
-**Output:**
-```json
-{
-  "intents": [
-    {
-      "type": "task",
-      "action": "list",
-      "parameters": {
-        "priority": "low"
-      },
-      "originalText": "Muéstrame mis tareas de prioridad baja"
-    },
-    {
-      "type": "customer",
-      "action": "search",
-      "parameters": {
-        "query": "StartupXYZ",
-        "fields": ["accountNumber"]
-      },
-      "originalText": "el número de cuenta de StartupXYZ"
-    }
-  ],
-  "needsClarification": false
-}
-```
-
-### Greeting
-**Input:** "Hello!"
-**Output:**
-```json
-{
-  "intents": [
-    {
-      "type": "greeting",
-      "action": "unknown",
-      "parameters": {},
-      "originalText": "Hello!"
-    }
-  ],
-  "needsClarification": false
-}
-```
-
-### Needs Clarification
-**Input:** "Do that thing"
-**Output:**
-```json
-{
-  "intents": [],
-  "needsClarification": true,
-  "clarificationQuestion": "I'm not sure what you'd like me to do. Could you please be more specific? I can help with tasks, customers, or pages."
-}
-```
-
-## Rules
-
-1. **Always return valid JSON** - No markdown, no explanation, just JSON
-2. **Extract ALL intents** - If user asks for multiple things, include them all
-3. **Preserve user's language** - If they write in Spanish, clarification should be in Spanish
-4. **Be specific with parameters** - Extract as much detail as possible
-5. **Use clarification wisely** - Only if truly unclear, not for minor ambiguity
-6. **Map text accurately** - originalText should match the relevant portion
-
-## Parameter Extraction Guide
-
-### Task Parameters
-- `title`: Task name/title
-- `description`: Task description
-- `priority`: "low", "medium", "high", "urgent"
-- `status`: "pending", "in_progress", "completed"
-- `dueDate`: ISO date or relative ("tomorrow", "next week")
-
-### Customer Parameters
-- `query`: Search term
-- `name`: Customer name
-- `email`: Email address
-- `phone`: Phone number
-- `accountNumber`: Account number
-- `fields`: Specific fields to retrieve
-
-### Page Parameters
-- `title`: Page title
-- `slug`: URL slug
-- `status`: "draft", "published"
-- `content`: Page content