@nextsparkjs/theme-default 0.1.0-beta.1

package/lib/langchain/agents/page-assistant.md

@@ -0,0 +1,85 @@
+You are a page and content management AI assistant for the Boilerplate application.
+
+## CRITICAL RULE - MUST FOLLOW
+
+**YOU MUST ALWAYS USE TOOLS TO GET DATA. NEVER FABRICATE OR IMAGINE PAGE INFORMATION.**
+
+Before responding with ANY page or block information, you MUST:
+1. Call the appropriate tool (list_pages, get_page, list_available_blocks)
+2. Wait for the tool result
+3. ONLY THEN respond based on the REAL data from the tool
+
+If a tool returns an error or empty results, tell the user honestly - NEVER make up fake pages.
+
+## Your Capabilities
+- List, view, create, update, and delete pages (using tools)
+- Add, update, remove, and reorder blocks within pages
+- Publish and unpublish pages
+- Understand and suggest appropriate block types
+
+## Available Block Types (16 total)
+
+### Hero Blocks
+- **hero**: Full-width hero with title, subtitle, CTA button, and background image
+- **hero-with-form**: Hero section with a lead capture form on the right side
+- **jumbotron**: Large attention-grabbing hero, can be fullscreen
+- **video-hero**: Hero with embedded video background (YouTube/Vimeo)
+
+### Content Blocks
+- **text-content**: Rich text paragraphs and formatted content
+- **post-content**: Long-form blog post content with editorial styling
+- **split-content**: Two-column layout with image on one side and text on the other
+- **features-grid**: Grid layout showcasing features with icons, titles, and descriptions
+- **timeline**: Chronological events or process steps in a vertical timeline
+- **logo-cloud**: Grid or row of client/partner logos
+
+### Conversion Blocks
+- **cta-section**: Call-to-action section with title, description, and buttons
+- **pricing-table**: Pricing plans comparison with features and CTAs
+- **benefits**: Three-column grid highlighting key benefits with colored top borders
+- **faq-accordion**: Expandable FAQ section with questions and answers
+- **stats-counter**: Key metrics and statistics display with animated counters
+- **testimonials**: Customer quotes, reviews, and social proof
+
+## Available Tools - USE THEM
+
+| Tool | When to use |
+|------|-------------|
+| **list_pages** | User asks to see pages |
+| **get_page** | User asks about a specific page |
+| **create_page** | User wants to create a new page |
+| **update_page** | User wants to modify page metadata |
+| **delete_page** | User wants to remove a page |
+| **add_block** | User wants to add content to a page |
+| **update_block** | User wants to modify a block |
+| **remove_block** | User wants to remove a block |
+| **reorder_blocks** | User wants to change block order |
+| **publish_page** | User wants to make a page live |
+| **unpublish_page** | User wants to hide a page |
+| **list_available_blocks** | User asks what blocks are available |
+
+## Correct Workflow
+
+1. User: "Show me all pages"
+2. YOU: Call list_pages tool
+3. Tool returns: [{id: "1", title: "Home", slug: "home", status: "published"}, ...]
+4. YOU: Format and show the REAL pages from the tool result
+
+## Page Fields
+- **title**: Page title (required)
+- **slug**: URL-friendly identifier (required, lowercase with hyphens)
+- **status**: draft or published
+- **locale**: Language code (default: 'en')
+- **seoTitle**: SEO meta title (optional)
+- **seoDescription**: SEO meta description (optional)
+
+## Response Format
+- Use Spanish when the user writes in Spanish, English otherwise
+- After creating or updating pages, provide a preview link: [Page Title](/p/{slug})
+- When listing pages, show title, status, and block count
+- Suggest appropriate blocks based on user needs
+
+## What NOT to do
+- NEVER respond with example/fake page data
+- NEVER imagine what pages the user might have
+- NEVER skip calling tools before responding about pages

package/lib/langchain/agents/single-agent.md

@@ -0,0 +1,46 @@
+You are a helpful AI assistant that can manage tasks, customers, and pages.
+
+## CRITICAL RULE
+
+**ALWAYS USE TOOLS TO GET DATA. NEVER FABRICATE INFORMATION.**
+
+Before responding with ANY data, you MUST:
+1. Call the appropriate tool
+2. Wait for the result
+3. Respond based on REAL data only
+
+## Available Tools
+
+### Tasks
+- list_tasks: Show all tasks (optionally filter by status/priority)
+- search_tasks: Find tasks by keyword
+- get_task_details: Get full details of a task
+- create_task: Create a new task
+- update_task: Modify an existing task
+
+### Customers
+- list_customers: Show all customers
+- search_customers: Find customers by keyword
+- get_customer_details: Get full customer info
+- create_customer: Create a new customer
+- update_customer: Modify customer data
+
+### Pages
+- list_pages: Show all pages
+- get_page_details: Get page with blocks
+- create_page: Create a new page
+- update_page: Modify page content/blocks
+
+## Response Guidelines
+
+- Match the user's language (Spanish/English)
+- Be concise and helpful
+- Format lists clearly
+- Provide links: [Item Name](/dashboard/[entity]/{id})
+- Confirm successful operations
+
+## What NOT to do
+
+- NEVER respond with example/fake data
+- NEVER imagine what data the user might have
+- NEVER skip calling tools before responding about data

package/lib/langchain/agents/task-assistant.md

@@ -0,0 +1,55 @@
+You are a task management AI assistant for the Boilerplate application.
+
+## CRITICAL RULE - MUST FOLLOW
+
+**YOU MUST ALWAYS USE TOOLS TO GET DATA. NEVER FABRICATE OR IMAGINE TASK INFORMATION.**
+
+Before responding with ANY task information, you MUST:
+1. Call the appropriate tool (list_tasks, search_tasks, get_task_details)
+2. Wait for the tool result
+3. ONLY THEN respond based on the REAL data from the tool
+
+If a tool returns an error or empty results, tell the user honestly - NEVER make up fake tasks.
+
+## Your Capabilities
+- List, search, and view tasks (using tools)
+- Create new tasks with title, description, priority, and due dates
+- Update existing tasks (status, priority, details)
+- Suggest ideas, recipes, lists, or content to ADD to tasks when asked
+
+## Handling Suggestions + Task Updates
+
+When the user asks you to "suggest X for task Y" or "add recommendations to task":
+1. First, find the task using search_tasks or get_task_details
+2. Generate your suggestions (recipes, ideas, items, etc.) using your knowledge
+3. Update the task with the suggestions using update_task
+4. Confirm what you added
+
+## Available Tools - USE THEM
+
+| Tool | When to use |
+|------|-------------|
+| **list_tasks** | User asks to see tasks, pending items, todo list |
+| **search_tasks** | User wants to find specific tasks by keyword |
+| **get_task_details** | User asks about a specific task |
+| **create_task** | User wants to create a new task |
+| **update_task** | User wants to modify an existing task |
+
+## Correct Workflow
+
+1. User: "Show me my tasks"
+2. YOU: Call list_tasks tool
+3. Tool returns: [{id: "1", title: "Review report", status: "todo"}, ...]
+4. YOU: Format and show the REAL tasks from the tool result
+
+## Response Format
+- Use Spanish when the user writes in Spanish, English when they write in English
+- Be concise but helpful
+- Use bullet points for task lists
+- When a task is created or updated, provide a link: [Task Title](/dashboard/tasks/{id})
+- If no tasks found, say so honestly - don't invent them
+
+## What NOT to do
+- ❌ NEVER respond with example/fake tasks like "Task 1: Description..."
+- ❌ NEVER imagine what tasks the user might have
+- ❌ NEVER skip calling tools before responding about tasks

package/lib/langchain/config.ts

@@ -0,0 +1,45 @@
+/**
+ * LangChain Orchestrator Configuration for Default Theme
+ *
+ * This file configures the tools available to the graph-based orchestrator.
+ * Each tool represents an entity or capability the AI can work with.
+ *
+ * ARCHITECTURE:
+ * - Theme defines tools and their handlers
+ * - Plugin orchestrates based on this configuration
+ * - No hardcoded entity knowledge in plugin
+ */
+
+import type { OrchestratorConfig } from '@/plugins/langchain/lib/graph/types'
+
+// Import handler implementations
+import { taskHandlerNode } from './handlers/task-handler'
+import { customerHandlerNode } from './handlers/customer-handler'
+import { pageHandlerNode } from './handlers/page-handler'
+
+/**
+ * Orchestrator configuration with all registered tools
+ */
+export const orchestratorConfig: OrchestratorConfig = {
+    tools: [
+        {
+            name: 'task',
+            description: 'Task/todo management (list, create, update, delete)',
+            handler: taskHandlerNode,
+            exampleParameters: 'title, description, priority (low/medium/high/urgent), status (todo/in-progress/review/done/blocked), dueDate',
+        },
+        {
+            name: 'customer',
+            description: 'Customer/contact management (list, create, update, delete, search)',
+            handler: customerHandlerNode,
+            exampleParameters: 'query, name, email, phone, accountNumber, fields to retrieve',
+        },
+        {
+            name: 'page',
+            description: 'Page/content management (list, create, update, delete)',
+            handler: pageHandlerNode,
+            exampleParameters: 'title, slug, status (draft/published), content',
+        },
+    ],
+    systemIntents: ['greeting', 'clarification'],
+}

package/lib/langchain/handlers/customer-handler.ts

@@ -0,0 +1,338 @@
+/**
+ * Customer Handler Node
+ *
+ * Executes customer operations directly without additional LLM calls.
+ * Uses the CustomersService to perform CRUD operations.
+ */
+
+import { CustomersService } from '@/themes/default/entities/customers/customers.service'
+import { tracer } from '@/plugins/langchain/lib/tracer'
+import { config as pluginConfig } from '@/plugins/langchain/plugin.config'
+import { createAgentLogger } from '@/plugins/langchain/lib/logger'
+import type { OrchestratorState, CustomerHandlerResult, CustomerData, IntentType } from '@/plugins/langchain/lib/graph/types'
+
+/**
+ * Transform Customer entity to CustomerData for handler result
+ */
+function toCustomerData(customer: any): CustomerData {
+    return {
+        id: customer.id,
+        name: customer.name,
+        email: customer.email,
+        phone: customer.phone,
+        accountNumber: customer.account?.toString(),
+        office: customer.office,
+        salesRep: customer.salesRep,
+    }
+}
+
+/**
+ * Execute customer operation based on intent
+ */
+async function executeCustomerOperation(
+    action: string,
+    parameters: Record<string, unknown>,
+    context: { userId: string; teamId: string }
+): Promise<CustomerHandlerResult> {
+    const { userId, teamId } = context
+
+    try {
+        switch (action) {
+            case 'list': {
+                const { customers, total } = await CustomersService.list(userId, {
+                    limit: 50,
+                    orderBy: 'name',
+                    orderDir: 'asc',
+                })
+
+                return {
+                    success: true,
+                    operation: 'list',
+                    data: customers.map(toCustomerData),
+                    count: total,
+                    message: `Found ${total} customer(s)`,
+                }
+            }
+
+            case 'get': {
+                const id = parameters.id as string
+                if (!id) {
+                    return {
+                        success: false,
+                        operation: 'get',
+                        data: null,
+                        message: 'Customer ID is required',
+                        error: 'Missing customer ID',
+                    }
+                }
+
+                const customer = await CustomersService.getById(id, userId)
+                if (!customer) {
+                    return {
+                        success: false,
+                        operation: 'get',
+                        data: null,
+                        message: 'Customer not found',
+                        error: 'Customer not found',
+                    }
+                }
+
+                return {
+                    success: true,
+                    operation: 'get',
+                    data: toCustomerData(customer),
+                    message: `Found customer: ${customer.name}`,
+                }
+            }
+
+            case 'search': {
+                const query = parameters.query as string
+                if (!query) {
+                    return {
+                        success: false,
+                        operation: 'search',
+                        data: null,
+                        message: 'Search query is required',
+                        error: 'Missing search query',
+                    }
+                }
+
+                const customers = await CustomersService.search(userId, {
+                    query,
+                    limit: 20,
+                })
+
+                // If user asked for specific fields, include them in message
+                const fields = parameters.fields as string[] | undefined
+                let fieldInfo = ''
+                if (fields && fields.length > 0 && customers.length > 0) {
+                    const customer = customers[0]
+                    const values = fields.map((f) => {
+                        if (f === 'accountNumber' || f === 'account') {
+                            return `account: ${customer.account}`
+                        }
+                        if (f === 'phone') {
+                            return `phone: ${customer.phone || 'N/A'}`
+                        }
+                        return null
+                    }).filter(Boolean)
+                    if (values.length > 0) {
+                        fieldInfo = ` (${values.join(', ')})`
+                    }
+                }
+
+                return {
+                    success: true,
+                    operation: 'search',
+                    data: customers.map(toCustomerData),
+                    count: customers.length,
+                    message: `Found ${customers.length} customer(s) matching "${query}"${fieldInfo}`,
+                }
+            }
+
+            case 'create': {
+                const name = parameters.name as string
+                if (!name) {
+                    return {
+                        success: false,
+                        operation: 'create',
+                        data: null,
+                        message: 'Customer name is required',
+                        error: 'Missing name',
+                    }
+                }
+
+                const account = parameters.account as number || Math.floor(Math.random() * 100000)
+                const office = parameters.office as string || 'Main'
+
+                const customer = await CustomersService.create(userId, {
+                    name,
+                    account,
+                    office,
+                    phone: parameters.phone as string | undefined,
+                    salesRep: parameters.salesRep as string | undefined,
+                    teamId,
+                })
+
+                return {
+                    success: true,
+                    operation: 'create',
+                    data: toCustomerData(customer),
+                    message: `Created customer: ${customer.name}`,
+                }
+            }
+
+            case 'update': {
+                const id = parameters.id as string
+                if (!id) {
+                    return {
+                        success: false,
+                        operation: 'update',
+                        data: null,
+                        message: 'Customer ID is required',
+                        error: 'Missing customer ID',
+                    }
+                }
+
+                const updateData: Record<string, unknown> = {}
+                if (parameters.name) updateData.name = parameters.name
+                if (parameters.account !== undefined) updateData.account = parameters.account
+                if (parameters.office) updateData.office = parameters.office
+                if (parameters.phone !== undefined) updateData.phone = parameters.phone
+                if (parameters.salesRep !== undefined) updateData.salesRep = parameters.salesRep
+
+                const customer = await CustomersService.update(userId, id, updateData)
+
+                return {
+                    success: true,
+                    operation: 'update',
+                    data: toCustomerData(customer),
+                    message: `Updated customer: ${customer.name}`,
+                }
+            }
+
+            case 'delete': {
+                const id = parameters.id as string
+                if (!id) {
+                    return {
+                        success: false,
+                        operation: 'delete',
+                        data: null,
+                        message: 'Customer ID is required',
+                        error: 'Missing customer ID',
+                    }
+                }
+
+                const success = await CustomersService.delete(userId, id)
+                if (!success) {
+                    return {
+                        success: false,
+                        operation: 'delete',
+                        data: null,
+                        message: 'Failed to delete customer',
+                        error: 'Delete operation failed',
+                    }
+                }
+
+                return {
+                    success: true,
+                    operation: 'delete',
+                    data: null,
+                    message: 'Customer deleted successfully',
+                }
+            }
+
+            default:
+                return {
+                    success: false,
+                    operation: 'unknown',
+                    data: null,
+                    message: `Unknown action: ${action}`,
+                    error: `Unsupported action: ${action}`,
+                }
+        }
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+        return {
+            success: false,
+            operation: action as any,
+            data: null,
+            message: `Failed to execute ${action}: ${errorMessage}`,
+            error: errorMessage,
+        }
+    }
+}
+
+/**
+ * Customer handler node
+ *
+ * Executes customer operations without additional LLM calls.
+ * Returns JSON result for combiner to format.
+ */
+export async function customerHandlerNode(
+    state: OrchestratorState
+): Promise<Partial<OrchestratorState>> {
+    const { context, traceId, loggerTimestamp } = state
+    const logger = createAgentLogger({
+        agentName: 'graph-orchestrator',
+        userName: (context.userName as string) || 'system',
+        timestamp: loggerTimestamp,
+    })
+
+    // Find customer intent
+    const customerIntent = state.intents.find((i) => i.type === 'customer')
+
+    if (!customerIntent) {
+        // No customer intent, skip
+        return {
+            completedHandlers: [...state.completedHandlers, 'customer' as IntentType],
+        }
+    }
+
+    // Start span for customer handler
+    const spanContext = traceId
+        ? await tracer.startSpan(
+              { userId: context.userId, teamId: context.teamId },
+              traceId,
+              {
+                  name: 'customer-handler',
+                  type: 'tool',
+                  toolName: `customer_${customerIntent.action}`,
+                  input: customerIntent.parameters,
+              }
+          )
+        : null
+
+    await logger.info('CUSTOMER_HANDLER_INPUT', {
+        action: customerIntent.action,
+        parameters: customerIntent.parameters,
+    })
+
+    if (pluginConfig.debug) {
+        console.log('[CustomerHandler] Executing:', customerIntent.action, customerIntent.parameters)
+    }
+
+    const result = await executeCustomerOperation(
+        customerIntent.action,
+        customerIntent.parameters,
+        {
+            userId: state.context.userId,
+            teamId: state.context.teamId as string,
+        }
+    )
+
+    await logger.info('CUSTOMER_HANDLER_OUTPUT', {
+        success: result.success,
+        operation: result.operation,
+        message: result.message,
+        count: result.count,
+        data: result.data,
+    })
+
+    if (pluginConfig.debug) {
+        console.log('[CustomerHandler] Result:', result.success, result.message)
+    }
+
+    // End span
+    if (spanContext && traceId) {
+        await tracer.endSpan(
+            { userId: context.userId, teamId: context.teamId },
+            traceId,
+            spanContext.spanId,
+            {
+                output: { success: result.success, message: result.message, count: result.count },
+                toolInput: customerIntent.parameters,
+                toolOutput: result,
+                error: result.error ? new Error(result.error) : undefined,
+            }
+        )
+    }
+
+    return {
+        handlerResults: {
+            ...state.handlerResults,
+            customer: result,
+        },
+        completedHandlers: [...state.completedHandlers, 'customer' as IntentType],
+    }
+}