PreProcessor

Overview

PreProcessor allows you to intercept and process user messages before they reach your AI agent. Use preprocessors to filter spam, route messages, validate inputs, or modify messages before the agent sees them.

import { PreProcessor } from 'lua-cli';

const profanityFilter = new PreProcessor({
  name: 'profanity-filter',
  description: 'Filter inappropriate content',
  priority: 10,
  execute: async (user, messages, channel) => {
    const hasProfanity = messages.some(msg => 
      msg.type === 'text' && msg.text.includes('badword')
    );
    
    if (hasProfanity) {
      // Block message and respond
      return {
        action: 'block',
        response: "Please keep the conversation respectful."
      };
    }
    
    // Allow messages to proceed
    return { action: 'proceed' };
  }
});

export default profanityFilter;

Message preprocessing for filtering, routing, and validation. Use with LuaAgent.

Use Cases

Content Filtering

Block spam, profanity, or inappropriate content

Message Routing

Route messages to different agents or handlers

Input Validation

Validate message format or required information

Analytics

Track message metrics before processing

Constructor

new PreProcessor(config)

Creates a new message preprocessor.

config

PreProcessorConfig

required

Preprocessor configuration object

Configuration Parameters

Required Fields

description

string

required

Preprocessor description for documentation

execute

function

required

Function that processes incoming messagesSignature:

(user: UserDataInstance, messages: ChatMessage[], channel: string) => Promise<PreProcessorBlockResponse | PreProcessorProceedResponse>

Arguments:

user: The UserDataInstance representing the current user.
messages: Array of ChatMessage objects sent by the user.
channel: The channel identifier (e.g., 'whatsapp', 'web', 'api').

Recommended: Use the Lua Runtime API instead of the function parameters:

User: User.get() to retrieve the current user
Channel: Lua.request.channel for the current channel
Webhook: Lua.request.webhook?.payload for raw webhook data (WhatsApp, Slack, Teams, etc.)

The function parameters may be removed in a future version.

Optional Fields

name

string

Unique preprocessor name. Defaults to 'unnamed-preprocessor' if not provided.Examples: 'profanity-filter', 'message-router'

priority

number

Execution priority (lower runs first). Default: 100

async

boolean

Run this preprocessor asynchronously on the server. When true, the preprocessor executes in a non-blocking mode. Default: false

UserData Object

The user argument passed to execute provides access to the current user’s data and methods.

interface UserDataInstance {
  // Direct access to user data properties
  uid: string;
  name?: string;
  email?: string;
  [key: string]: any;

  // Helper methods
  getChatHistory(): Promise<ChatHistoryMessage[]>;
  // ... other user management methods
}

Message Structure

The messages array passed to your execute function contains ChatMessage objects:

type ChatMessage = TextMessage | ImageMessage | FileMessage;

interface TextMessage {
  type: 'text';
  text: string;
}

interface ImageMessage {
  type: 'image';
  image: string;      // URL or base64
  mimeType: string;   // e.g. "image/png", "image/jpeg"
}

interface FileMessage {
  type: 'file';
  data: string;       // URL or base64
  mimeType: string;   // e.g. "application/pdf"
}

Return Type

Your execute function must return a PreProcessorBlockResponse or PreProcessorProceedResponse object indicating whether to proceed or block.

1. Proceed

To allow the message to continue to the next preprocessor or the agent:

// Proceed with original message
return { action: 'proceed' };

// OR proceed with a modified message
return {
  action: 'proceed',
  modifiedMessage: [{ type: 'text', text: 'Modified content' }],
  metadata: { reason: 'message-modified' }  // optional metadata
};

2. Block

To stop processing immediately and respond to the user:

return {
  action: 'block',
  response: "This message was blocked.",
  metadata: { reason: 'profanity' }  // optional metadata
};

Complete Examples

Profanity Filter

import { PreProcessor } from 'lua-cli';

const profanityWords = ['badword1', 'badword2', 'badword3'];

const profanityFilter = new PreProcessor({
  name: 'profanity-filter',
  description: 'Block messages containing inappropriate language',
  priority: 10, // Run early
  
  execute: async (user, messages, channel) => {
    // Check all text messages
    const hasProfanity = messages.some(msg => {
      if (msg.type === 'text') {
        return profanityWords.some(word => msg.text.toLowerCase().includes(word));
      }
      return false;
    });
    
    if (hasProfanity) {
      console.log(`Blocked profanity from user ${user.uid}`);
      return {
        action: 'block',
        response: "Please keep the conversation respectful. Inappropriate language is not allowed."
      };
    }
    
    return { action: 'proceed' };
  }
});

export default profanityFilter;

Business Hours Filter

import { PreProcessor } from 'lua-cli';

const businessHoursFilter = new PreProcessor({
  name: 'business-hours-filter',
  description: 'Block messages outside business hours',
  
  execute: async (user, messages, channel) => {
    const now = new Date();
    const hour = now.getHours();
    const day = now.getDay();
    
    // Business hours: Mon-Fri, 9 AM - 5 PM
    const isWeekday = day >= 1 && day <= 5;
    const isBusinessHours = hour >= 9 && hour < 17;
    
    if (!isWeekday || !isBusinessHours) {
      return {
        action: 'block',
        response: "Thank you for contacting us. Our business hours are Monday-Friday, 9 AM - 5 PM. We'll respond to your message during our next business day."
      };
    }
    
    return { action: 'proceed' };
  }
});

export default businessHoursFilter;

Message Enrichment

import { PreProcessor } from 'lua-cli';

const messageEnricher = new PreProcessor({
  name: 'message-enricher',
  description: 'Add context to messages before processing',
  priority: 50,
  
  execute: async (user, messages, channel) => {
    // Enrich message with user info
    const enrichedMessages = messages.map(msg => {
      if (msg.type === 'text') {
        return {
          ...msg,
          text: `${msg.text}\n\n[Context: User ID ${user.uid}]`
        };
      }
      return msg;
    });
    
    return {
      action: 'proceed',
      modifiedMessage: enrichedMessages
    };
  }
});

export default messageEnricher;

Execution Flow

Preprocessors are executed in a pipeline:

Sequential Execution: Preprocessors run one after another, sorted by priority.
Modifications: If a preprocessor modifies a message, the next preprocessor receives the modified version.
Blocking: If any preprocessor returns action: 'block', execution stops immediately, and the response is sent to the user. The agent is not called.

Testing Preprocessors

lua test
# Select: PreProcessor → your-preprocessor-name
# Provide test message

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Overview

Use Cases

Content Filtering

Message Routing

Input Validation

Analytics

Constructor

new PreProcessor(config)

Configuration Parameters

Required Fields

Optional Fields

UserData Object

Message Structure

Return Type

1. Proceed

2. Block

Complete Examples

Profanity Filter

Business Hours Filter

Message Enrichment

Execution Flow

Testing Preprocessors

See Also

​Overview

​Use Cases

Content Filtering

Message Routing

Input Validation

Analytics

​Constructor

​new PreProcessor(config)

​Configuration Parameters

​Required Fields

​Optional Fields

​UserData Object

​Message Structure

​Return Type

​1. Proceed

​2. Block

​Complete Examples

​Profanity Filter

​Business Hours Filter

​Message Enrichment

​Execution Flow

​Testing Preprocessors

​See Also

Overview

Use Cases

Constructor

new PreProcessor(config)

Configuration Parameters

Required Fields

Optional Fields

UserData Object

Message Structure

Return Type

1. Proceed

2. Block

Complete Examples

Profanity Filter

Business Hours Filter

Message Enrichment

Execution Flow

Testing Preprocessors

See Also