Skip to main content

Forms and Services Functionality - Comprehensive Documentation

Table of Contents​

  1. Overview
  2. Architecture
  3. Setup and Configuration
  4. Technical Requirements
  5. Workflow
  6. Early Detection System
  7. API Integration
  8. Frontend Integration
  9. Configuration Examples
  10. Troubleshooting

Overview​

The Forms and Services functionality enables the chatbot to:

  • List available forms when users request to see what forms are available
  • Email forms to users when they request a specific form
  • List available services when users want to see what services can be requested
  • Process service requests by sending notifications to administrators

This system transforms the chatbot from a simple Q&A tool into a complete customer service solution that can handle actionable requests.

Key Features​

  • Early Detection: Pattern-based detection intercepts form/service requests before LLM processing
  • Multi-language Support: Supports English, Farsi, Arabic, French, Spanish, German, and Turkish
  • Domain-specific Configuration: Each domain can have its own forms and services
  • Automatic Email Delivery: Forms can be automatically emailed to users
  • Service Request Notifications: Service requests trigger email notifications to administrators
  • Frontend Integration: Structured responses enable rich UI components (clickable buttons, lists)

Architecture​

System Components​

┌─────────────────────────────────────────────────────────────┐
│                    User Query                                │
│              "show available forms"                          │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│           Early Detection Preprocessor                       │
│  (ComprehensivePatternDetection)                             │
│  - Pattern matching                                         │
│  - Tool identification                                      │
└────────────────────┬────────────────────────────────────────┘
                     │
         ┌───────────┴───────────┐
         │                       │
         ▼                       ▼
┌──────────────────┐   ┌──────────────────┐
│  Special Tool    │   │  Normal LLM Flow │
│  Detected        │   │  (if no match)    │
└────────┬─────────┘   └──────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│           Handler Functions                                  │
│  - list_forms_handler()                                      │
│  - email_form_handler()                                      │
│  - list_services_handler()                                   │
│  - request_service_handler()                                 │
└────────────────────┬────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│           Manager Classes                                    │
│  - FormManager (loads forms.json)                           │
│  - ServiceManager (loads services.json)                      │
└────────────────────┬────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│           Response with Structured Data                      │
│  - message_type: "forms_list" | "services_list"            │
│  - clickableForms: [...]                                    │
│  - clickableServices: [...]                                 │
└────────────────────┬────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│           Frontend (Flutter App)                             │
│  - FormsListWidget                                           │
│  - ServicesListWidget                                        │
└─────────────────────────────────────────────────────────────┘

File Structure​

domain-chatbot/
├── LLM_full/
│   └── query/
│       ├── form_manager.py          # Form management logic
│       ├── service_manager.py       # Service management logic
│       ├── functions.py             # Handler functions
│       ├── tool_detection/
│       │   └── comprehensive_pattern_detection.py  # Early detection
│       └── service_vector.py        # Query processing (with early detection)
├── LLM_full/
│   └── domains/
│       └── {domain_name}/
│           ├── forms/
│           │   └── forms.json      # Domain forms configuration
│           └── services/
│               └── services.json    # Domain services configuration

Key Classes and Functions​

FormManager (form_manager.py)​

  • load_domain_forms(domain): Loads and caches forms from forms.json
  • get_available_forms(domain): Returns list of active form types
  • get_form_info(domain, form_type, language): Gets localized form information
  • detect_form_type_from_query(query, language, domain): Detects form type from user query

ServiceManager (service_manager.py)​

  • load_domain_services(domain): Loads and caches services from services.json
  • get_available_services(domain, language): Returns list of active services
  • get_service_info(domain, service_id, language): Gets localized service information
  • detect_service_request(query, domain, language): Detects service request intent

Handler Functions (functions.py)​

  • list_forms_handler(name, language, domain): Handles "list forms" requests
  • email_form_handler(name, email, query, language, domain, form_type): Handles "email form" requests
  • list_services_handler(name, language, domain): Handles "list services" requests
  • request_service_handler(name, email, service_id, language, domain): Handles service requests

Early Detection (comprehensive_pattern_detection.py)​

  • ComprehensivePatternDetection: Pattern matching system
  • detect_intent(query, language, domain): Detects special tool intent
  • Returns DetectionResult with tool type, confidence, and reasoning

Setup and Configuration​

Prerequisites​

  1. Domain Folder Structure: Each domain must have a folder structure:

    {SEARCH_DOMAIN_FOLDER}/{domain_name}/
    ├── forms/
    │   └── forms.json
    └── services/
        └── services.json

  2. Environment Variable: Ensure EARLY_DETECTION=true in your .env file:

    EARLY_DETECTION=true

  3. Domain Path: The SEARCH_DOMAIN_FOLDER setting must point to your domains directory.

Forms Configuration (forms.json)​

Location: {SEARCH_DOMAIN_FOLDER}/{domain_name}/forms/forms.json

Structure​

{
  "forms": {
    "{form_type}": {
      "name": {
        "en": "English Name",
        "fa": "نام فارسی",
        "ar": "الاسم العربي",
        "fr": "Nom français",
        "es": "Nombre español",
        "de": "Deutscher Name",
        "tr": "Türkçe ad"
      },
      "url": "https://example.com/forms/{form_type}",
      "keywords": {
        "en": ["keyword1", "keyword2", "keyword3"],
        "fa": ["کلمه کلیدی 1", "کلمه کلیدی 2"],
        "ar": ["كلمة مفتاحية 1", "كلمة مفتاحية 2"],
        "fr": ["mot-clé 1", "mot-clé 2"],
        "es": ["palabra clave 1", "palabra clave 2"],
        "de": ["Schlüsselwort 1", "Schlüsselwort 2"],
        "tr": ["anahtar kelime 1", "anahtar kelime 2"]
      },
      "email_template": {
        "subject": {
          "en": "{form_name} - {domain_title}",
          "fa": "{form_name} - {domain_title}"
        },
        "body": {
          "en": "Dear {user_name},\n\nThank you for your request...",
          "fa": "عزیز {user_name}،\n\nاز درخواست شما متشکرم..."
        }
      },
      "active": true
    }
  },
  "metadata": {
    "version": "1.0",
    "last_updated": "2024-01-25",
    "domain": "{domain_name}",
    "supported_languages": ["en", "fa", "ar", "fr", "es", "de", "tr"]
  }
}

Field Descriptions​

Form Object:

  • name (object, required): Localized form names for each language
  • url (string, required): URL to the form (must start with http:// or https://)
  • keywords (object, required): Keywords for form detection, organized by language
  • email_template (object, optional): Email template for sending forms
    • subject: Email subject template (supports {form_name}, {domain_title})
    • body: Email body template (supports {user_name}, {form_name}, {form_url}, {domain_title})
  • active (boolean, required): Whether the form is currently available

Metadata:

  • version (string): Configuration version
  • last_updated (string): Last update date
  • domain (string): Domain name
  • supported_languages (array): List of supported language codes

Services Configuration (services.json)​

Location: {SEARCH_DOMAIN_FOLDER}/{domain_name}/services/services.json

Structure​

{
  "services": {
    "{service_id}": {
      "id": "{service_id}",
      "name": {
        "en": "English Service Name",
        "fa": "نام سرویس فارسی"
      },
      "description": {
        "en": "Service description in English",
        "fa": "توضیحات سرویس به فارسی"
      },
      "icon": "🧻",
      "category": "room_amenities",
      "active": true
    }
  },
  "metadata": {
    "version": "1.0",
    "detection_keywords": {
      "en": "room service",
      "fa": "سرویس اتاق"
    },
    "confirmation_message": {
      "en": "Your request for {service_name} has been sent to our team. Someone will assist you shortly.",
      "fa": "درخواست شما برای {service_name} به تیم ما ارسال شد. به زودی کسی به شما کمک خواهد کرد."
    },
    "supported_languages": ["en", "fa"]
  }
}

Field Descriptions​

Service Object:

  • id (string, required): Unique service identifier
  • name (object, required): Localized service names
  • description (object, optional): Localized service descriptions
  • icon (string, optional): Emoji or icon identifier for the service
  • category (string, optional): Service category (e.g., "room_amenities", "food_beverage")
  • active (boolean, required): Whether the service is currently available

Metadata:

  • version (string): Configuration version
  • detection_keywords (object, required): Keywords for detecting service requests (one string per language, NOT arrays)
  • confirmation_message (object, required): Message shown after service request (supports {service_name} placeholder)
  • supported_languages (array): List of supported language codes

Technical Requirements​

Backend Requirements​

  1. Python 3.11+

  2. Dependencies:

    • FastAPI
    • Pydantic (for request/response models)
    • Email sending capability (SMTP configuration)

  3. Settings:

    EARLY_DETECTION=true  # Enable early detection
    SEARCH_DOMAIN_FOLDER=/path/to/domains  # Domain folder path

  4. Email Configuration (for form emailing):

    SMTP_HOST=smtp.example.com
    SMTP_PORT=587
    SMTP_USER=your-email@example.com
    SMTP_PASSWORD=your-password
    SMTP_FROM=noreply@example.com

Frontend Requirements​

  1. Flutter/Dart (for aventora-bot)
  2. WebSocket Support (for real-time communication)
  3. JSON Parsing (for structured messages)

Database Requirements​

  • PostgreSQL (for storing chat logs and form submissions)
  • Tables:
    • chat_logs: Stores conversation history
    • form_submissions: Stores form request logs (if implemented)
    • service_requests: Stores service request logs (if implemented)

Workflow​

1. List Forms Workflow​

User Query: "show available forms"
    │
    ▼
Early Detection (ComprehensivePatternDetection)
    │
    ├─ Pattern Match: LIST_FORMS detected
    │
    ▼
list_forms_handler()
    │
    ├─ FormManager.load_domain_forms(domain)
    │   └─ Loads forms.json from disk
    │
    ├─ FormManager.get_available_forms(domain)
    │   └─ Filters active forms
    │
    ├─ For each form:
    │   └─ FormManager.get_form_info(domain, form_type, language)
    │       └─ Returns localized name and URL
    │
    ▼
Response:
{
  "answer": "Here are the available forms:\n1. Employment Form\n2. Contact Form",
  "message_type": "forms_list",
  "clickableForms": [
    {"type": "employment", "name": "Employment Form", "url": "https://..."},
    {"type": "contact", "name": "Contact Form", "url": "https://..."}
  ],
  "complete": true,
  "continue": false
}
    │
    ▼
WebSocket Handler
    │
    ├─ Adds message_type and clickableForms to message_data
    │
    ▼
Frontend (Flutter)
    │
    ├─ Parses ASSISTANT_STRUCTURED message
    │
    ├─ Detects messageType == "forms_list"
    │
    ▼
FormsListWidget
    │
    └─ Displays clickable form buttons

2. Email Form Workflow​

User Query: "send me the employment form"
    │
    ▼
Early Detection
    │
    ├─ Pattern Match: EMAIL_FORM detected
    │
    ▼
email_form_handler()
    │
    ├─ FormManager.detect_form_type_from_query()
    │   └─ Matches keywords: "employment" → "employment"
    │
    ├─ FormManager.get_form_info(domain, "employment", language)
    │   └─ Returns form name and URL
    │
    ▼
Response:
{
  "answer": "I can send you the Employment Application Form. Please confirm your email address.",
  "message_type": "form_request",
  "formData": {
    "form_type": "employment",
    "form_name": "Employment Application Form",
    "form_url": "https://...",
    "form_id": "employment"
  },
  "complete": false,
  "continue": true,
  "action_needed": "confirm_email_send"
}
    │
    ▼
Frontend
    │
    ├─ Displays form request UI
    │
    ├─ User confirms email
    │
    ▼
POST /query/send-form-email
    │
    ├─ send_form_email_handler()
    │   └─ Sends email using email_template
    │
    ▼
Confirmation message sent to user

3. List Services Workflow​

User Query: "what services are available?"
    │
    ▼
Early Detection
    │
    ├─ Pattern Match: REQUEST_SERVICE detected (or LIST_FORMS pattern)
    │
    ▼
list_services_handler()
    │
    ├─ ServiceManager.load_domain_services(domain)
    │   └─ Loads services.json from disk
    │
    ├─ ServiceManager.get_available_services(domain, language)
    │   └─ Filters active services, localizes names
    │
    ▼
Response:
{
  "answer": "Here are the available services:",
  "message_type": "services_list",
  "clickableServices": [
    {"id": "towels", "name": "Extra Towels", "description": "...", "icon": "🧻"},
    {"id": "water", "name": "Drinking Water", "description": "...", "icon": "💧"}
  ],
  "complete": true,
  "continue": false
}
    │
    ▼
Frontend
    │
    └─ ServicesListWidget displays service buttons

4. Request Service Workflow​

User clicks service button: "towels"
    │
    ▼
Frontend sends: "I want to request towels service"
    │
    ▼
Early Detection
    │
    ├─ Pattern Match: REQUEST_SERVICE detected
    │
    ▼
request_service_handler()
    │
    ├─ ServiceManager.get_service_info(domain, "towels", language)
    │   └─ Returns service details
    │
    ├─ Email notification sent to admin
    │   └─ Includes user name, email, service name
    │
    ▼
Response:
{
  "answer": "Your request for Extra Towels has been sent to our team. Someone will assist you shortly.",
  "complete": true,
  "continue": false
}

Early Detection System​

Overview​

The Early Detection system uses pattern matching to identify special tool requests before the query reaches the LLM. This provides:

  • Fast Response: No LLM API call needed
  • Accurate Detection: Pattern-based matching is more reliable than LLM interpretation
  • Cost Savings: Reduces LLM API usage
  • Consistent Behavior: Same patterns always trigger same actions

How It Works​

  1. Pattern Database: Pre-defined regex patterns for each tool and language
  2. Detection Process: 
    detector = ComprehensivePatternDetection()
    result = detector.detect_intent(query, language, domain)
    # Returns DetectionResult with tool, confidence, reasoning
  3. Pattern Matching: Tests query against all patterns for the user's language
  4. Confidence Scoring: Calculates confidence based on pattern matches
  5. Tool Routing: Routes to appropriate handler if tool detected

Supported Tools​

  1. EMAIL_TRANSCRIPT: User wants a copy of the conversation
  2. EMAIL_FORM: User wants a form emailed to them
  3. LIST_FORMS: User wants to see available forms
  4. REQUEST_SERVICE: User wants to request a service

Pattern Examples​

English Patterns​

LIST_FORMS:

  • "(what|which).*(forms|documents|papers).*(available|do you have|can i get)"
  • "(show|list|tell me).*(forms|documents|papers)"
  • "show available forms" ✅

EMAIL_FORM:

  • "(form|document|paper).*(email|send|get|give|provide)"
  • "(email|send|get|give|provide).*(form|document|paper)"
  • "send me the employment form" ✅

REQUEST_SERVICE:

  • "(i want|i need|request|order).*(service|room service)"
  • "room service" ✅

Farsi Patterns​

LIST_FORMS:

  • "(چه|کدوم).*(فرم|سند|کاغذ).*(موجوده|دارید|می‌تونم بگیرم)"
  • "لیست فرم‌ها را نشان بده" ✅

EMAIL_FORM:

  • "(فرم|سند|کاغذ).*(ایمیل|فرست|بده|ارسال)"
  • "فرم استخدام را برایم بفرست" ✅

Adding New Patterns​

To add new patterns, edit comprehensive_pattern_detection.py:

"en": {
    SpecialTool.LIST_FORMS: [
        r"your new pattern here",
        r"another pattern",
    ]
}

Pattern Tips:

  • Use regex groups () for optional parts
  • Use .* for flexible word order
  • Test patterns with various phrasings
  • Consider common typos and variations

Configuration​

Enable/disable early detection in .env:

EARLY_DETECTION=true  # Enable
EARLY_DETECTION=false # Disable (falls back to normal LLM flow)

API Integration​

Endpoints​

1. Query Endpoint (with Early Detection)​

POST /query/

{
  "question": "show available forms",
  "domain": "kalano",
  "language": "en",
  "name": "John Doe",
  "email": "john@example.com",
  "user_id": 123,
  "domain_metadata": {}
}

Response (Forms List):

{
  "answer": "Here are the available forms:\n1. Employment Application Form\n2. Contact Form",
  "message_type": "forms_list",
  "clickableForms": [
    {
      "type": "employment",
      "name": "Employment Application Form",
      "url": "https://kalano.com/forms/employment"
    },
    {
      "type": "contact",
      "name": "Contact Form",
      "url": "https://kalano.com/forms/contact"
    }
  ],
  "complete": true,
  "continue": false,
  "session": [...]
}

Response (Form Request):

{
  "answer": "I can send you the Employment Application Form. Please confirm your email address.",
  "message_type": "form_request",
  "formData": {
    "form_type": "employment",
    "form_name": "Employment Application Form",
    "form_url": "https://kalano.com/forms/employment",
    "form_id": "employment"
  },
  "complete": false,
  "continue": true,
  "session": [...]
}

2. Send Form Email Endpoint​

POST /query/send-form-email

{
  "form_id": "employment",
  "user_email": "john@example.com",
  "user_name": "John Doe",
  "language": "en",
  "domain": "kalano"
}

Response:

{
  "message": "The Employment Application Form has been sent to your email.",
  "success": true
}

3. Request Service Endpoint​

POST /query/request-service

{
  "service_id": "towels",
  "user_name": "John Doe",
  "user_email": "john@example.com",
  "language": "en",
  "domain": "kalano"
}

Response:

{
  "message": "Your request for Extra Towels has been sent to our team. Someone will assist you shortly.",
  "success": true
}

WebSocket Integration​

The WebSocket handler (Agent/server/websocket.py) processes responses and adds structured data:

if resp.get("message_type") == "forms_list":
    message_data["message_type"] = resp.get("message_type")
    message_data["clickableForms"] = resp.get("clickableForms")

if resp.get("message_type") == "services_list":
    message_data["message_type"] = resp.get("message_type")
    message_data["clickableServices"] = resp.get("clickableServices")

Frontend Integration​

Flutter Integration (aventora-bot)​

1. Message Parsing​

The ChatScreenD widget parses structured messages:

if (value.startsWith('ASSISTANT_STRUCTURED:')) {
  final structuredData = value.substring(21);
  final messageData = jsonDecode(structuredData);
  
  final messageType = messageData['messageType'];
  final clickableForms = messageData['clickableForms'];
  final clickableServices = messageData['clickableServices'];
  
  _addMessageToChat(
    messageId,
    assistantText,
    'assistant',
    null,
    nowMs,
    messageType: messageType,
    clickableForms: clickableForms,
    clickableServices: clickableServices,
  );
}

2. Forms List Widget​

FormsListWidget displays clickable form buttons:

if (widget.message.messageType?.toLowerCase() == 'forms_list' && 
    widget.message.clickableForms != null) {
  return FormsListWidget(
    forms: widget.message.clickableForms!,
    onFormSelected: widget.onUserResponse,
    isRTL: widget.isRTL,
  );
}

3. Services List Widget​

ServicesListWidget displays clickable service buttons:

if (widget.message.messageType?.toLowerCase() == 'services_list' && 
    widget.message.clickableServices != null) {
  return ServicesListWidget(
    services: widget.message.clickableServices!,
    onServiceRequested: widget.onUserResponse,
    isRTL: widget.isRTL,
  );
}

4. Trigger Phrases​

The "View Forms" button sends a trigger phrase:

void _onFormsButtonPressed() {
  String triggerPhrase;
  switch (currentLanguage) {
    case 'fa':
      triggerPhrase = 'لیست فرم‌ها را نشان بده';
      break;
    case 'ar':
      triggerPhrase = 'أظهر قائمة النماذج';
      break;
    default:
      triggerPhrase = 'show available forms';
  }
  _sendMessage(triggerPhrase);
}

Message Format​

Structured Message Format:

ASSISTANT_STRUCTURED:{"text":"...","messageType":"forms_list","clickableForms":[...]}

Fields:

  • text: Human-readable message text
  • messageType: "forms_list" | "services_list" | "form_request" | "admin_call_form" | null
  • clickableForms: Array of form objects (if messageType == "forms_list")
  • clickableServices: Array of service objects (if messageType == "services_list")
  • formData: Form request data (if messageType == "form_request")
  • adminCallFormData: Inline form for "talk to admin" (if messageType == "admin_call_form")

Admin Call Form (messageType == "admin_call_form")​

When the user says "talk to admin" / "can I speak with an administrator", the backend returns messageType: "admin_call_form" and adminCallFormData with an inline form (no regex parsing). The frontend should render the form and, on submit, send a continue request with:

  • admin_call_name: from field id: "name"
  • admin_call_phone: from field id: "phone"
  • admin_call_subject: from field id: "subject"
  • admin_call_preferred_channel: one of "sms" | "wmsg" | "phone" from field id: "preferred_channel"

adminCallFormData shape:

  • intro: string (optional message)
  • fields: [{ id, type, label, required, value?, options? }] — id is "name" | "phone" | "subject" | "preferred_channel"; preferred_channel has options: [{ value: "sms"|"wmsg"|"phone", label }]
  • submit_label: string for the submit button

Configuration Examples​

Example 1: Healthcare Domain Forms​

{
  "forms": {
    "patient_intake": {
      "name": {
        "en": "Patient Intake Form",
        "fa": "فرم پذیرش بیمار"
      },
      "url": "https://hospital.example.com/forms/patient-intake",
      "keywords": {
        "en": ["intake", "patient form", "registration", "admission"],
        "fa": ["پذیرش", "فرم بیمار", "ثبت نام", "بستری"]
      },
      "email_template": {
        "subject": {
          "en": "Patient Intake Form - {domain_title}",
          "fa": "فرم پذیرش بیمار - {domain_title}"
        },
        "body": {
          "en": "Dear {user_name},\n\nPlease complete the Patient Intake Form at:\n{form_url}\n\nThank you.",
          "fa": "عزیز {user_name}،\n\nلطفاً فرم پذیرش بیمار را در لینک زیر تکمیل کنید:\n{form_url}\n\nمتشکرم."
        }
      },
      "active": true
    },
    "appointment": {
      "name": {
        "en": "Appointment Booking Form",
        "fa": "فرم رزرو نوبت"
      },
      "url": "https://hospital.example.com/forms/appointment",
      "keywords": {
        "en": ["appointment", "booking", "schedule", "visit"],
        "fa": ["نوبت", "رزرو", "وقت", "ویزیت"]
      },
      "active": true
    }
  },
  "metadata": {
    "version": "1.0",
    "domain": "hospital",
    "supported_languages": ["en", "fa"]
  }
}

Example 2: Hotel Domain Services​

{
  "services": {
    "room_service": {
      "id": "room_service",
      "name": {
        "en": "Room Service",
        "fa": "سرویس اتاق"
      },
      "description": {
        "en": "Order food and beverages to your room",
        "fa": "سفارش غذا و نوشیدنی به اتاق شما"
      },
      "icon": "🍽️",
      "category": "food_beverage",
      "active": true
    },
    "laundry": {
      "id": "laundry",
      "name": {
        "en": "Laundry Service",
        "fa": "خدمات لباسشویی"
      },
      "description": {
        "en": "Request laundry and dry cleaning services",
        "fa": "درخواست خدمات لباسشویی و خشک‌شویی"
      },
      "icon": "👔",
      "category": "housekeeping",
      "active": true
    }
  },
  "metadata": {
    "version": "1.0",
    "detection_keywords": {
      "en": "room service",
      "fa": "سرویس اتاق"
    },
    "confirmation_message": {
      "en": "Your request has been sent to our team. We'll assist you shortly.",
      "fa": "درخواست شما به تیم ما ارسال شد. به زودی به شما کمک خواهیم کرد."
    },
    "supported_languages": ["en", "fa"]
  }
}

Troubleshooting​

Issue: Early Detection Not Triggering​

Symptoms:

  • User query "show available forms" goes to LLM instead of handler
  • No "EARLY DETECTION" logs in console

Solutions:

  1. Check Environment Variable:

    # In .env file
    EARLY_DETECTION=true

  2. Verify Pattern Matching:

    • Check logs for detection attempts
    • Test patterns manually with regex tester
    • Ensure query matches pattern (case-insensitive)

  3. Check Service File:

    • Verify router.py imports from service_vector.py (or service.py)
    • Ensure early detection code is present in both process_query and continue_query

  4. Language Mismatch:

    • Verify request.language matches pattern language
    • Check that patterns exist for the user's language

Issue: Forms Not Loading​

Symptoms:

  • Error: "Forms file not found"
  • Empty forms list returned

Solutions:

  1. Check File Path:

    {SEARCH_DOMAIN_FOLDER}/{domain_name}/forms/forms.json

  2. Verify JSON Structure:

    • Validate JSON syntax
    • Ensure forms and metadata keys exist
    • Check required fields: name, url, keywords, active

  3. Check Permissions:

    • Ensure file is readable
    • Check file encoding (must be UTF-8)

  4. Clear Cache:

    from LLM_full.query.form_manager import form_manager
    form_manager.clear_cache(domain="your_domain")

Issue: Services Not Loading​

Symptoms:

  • Error: "Services file not found"
  • Empty services list returned

Solutions:

  1. Check File Path:

    {SEARCH_DOMAIN_FOLDER}/{domain_name}/services/services.json

  2. Verify JSON Structure:

    • Validate JSON syntax
    • Ensure services and metadata keys exist
    • Check detection_keywords is a dictionary (not array)

  3. Validate Detection Keywords:

    // ✅ Correct
    "detection_keywords": {
      "en": "room service",
      "fa": "سرویس اتاق"
    }

    // ❌ Wrong (arrays not supported)
    "detection_keywords": {
      "en": ["room", "service"],
      "fa": ["سرویس", "اتاق"]
    }

Issue: Frontend Not Displaying Forms/Services​

Symptoms:

  • Backend returns clickableForms but frontend shows plain text

Solutions:

  1. Check Message Type:

    • Verify message_type is set in response
    • Check WebSocket handler adds messageType to message_data

  2. Verify Frontend Parsing:

    • Check ASSISTANT_STRUCTURED: prefix is present
    • Verify JSON parsing in ChatScreenD
    • Check messageType comparison (case-insensitive)

  3. Check Widget Conditions:

    // Ensure both conditions are met
    messageType?.toLowerCase() == 'forms_list' &&
    clickableForms != null

  4. Debug Logging:

    print('DEBUG: messageType=$messageType');
    print('DEBUG: clickableForms=$clickableForms');

Issue: Email Not Sending​

Symptoms:

  • Form request succeeds but email not received

Solutions:

  1. Check SMTP Configuration:

    SMTP_HOST=smtp.example.com
    SMTP_PORT=587
    SMTP_USER=your-email@example.com
    SMTP_PASSWORD=your-password
    SMTP_FROM=noreply@example.com

  2. Verify Email Template:

    • Check email_template exists in forms.json
    • Verify placeholders: {user_name}, {form_name}, {form_url}, {domain_title}

  3. Check Logs:

    • Look for email sending errors
    • Verify email address format

Issue: Pattern Not Matching​

Symptoms:

  • Query should match pattern but doesn't

Solutions:

  1. Test Pattern Manually:

    import re
    pattern = r"(show|list|tell me).*(forms|documents|papers)"
    query = "show available forms"
    match = re.search(pattern, query, re.IGNORECASE)
    print(match)  # Should not be None

  2. Check Case Sensitivity:

    • Patterns use re.IGNORECASE flag
    • But verify query is lowercased in detection

  3. Add Debug Logging:

    logger.info(f"Testing pattern: {pattern}")
    logger.info(f"Against query: {query}")
    logger.info(f"Match result: {match}")

  4. Consider Variations:

    • Add more patterns for common phrasings
    • Test with typos and variations

Common Configuration Errors​

  1. Missing Required Fields:

    // ❌ Missing "active" field
    {
      "name": {...},
      "url": "...",
      "keywords": {...}
    }

    // ✅ Correct
    {
      "name": {...},
      "url": "...",
      "keywords": {...},
      "active": true
    }

  2. Invalid URL Format:

    // ❌ Missing http://
    "url": "example.com/forms/employment"

    // ✅ Correct
    "url": "https://example.com/forms/employment"

  3. Wrong Detection Keywords Format:

    // ❌ Array instead of string
    "detection_keywords": {
      "en": ["room", "service"]
    }

    // ✅ Correct
    "detection_keywords": {
      "en": "room service"
    }

Best Practices​

Forms Configuration​

  1. Use Descriptive Keywords:

    • Include common variations and synonyms
    • Add both full form names and abbreviations
    • Consider typos and common misspellings

  2. Localize Thoroughly:

    • Provide translations for all supported languages
    • Use native speakers for translations
    • Test with native speakers

  3. Keep URLs Updated:

    • Use absolute URLs (https://)
    • Test URLs regularly
    • Provide fallback URLs if needed

Services Configuration​

  1. Clear Service Names:

    • Use descriptive, user-friendly names
    • Keep names concise
    • Avoid technical jargon

  2. Helpful Descriptions:

    • Explain what the service does
    • Include any prerequisites or requirements
    • Set user expectations

  3. Appropriate Categories:

    • Group related services
    • Use consistent category names
    • Consider UI grouping

Pattern Design​

  1. Start Broad, Then Narrow:

    • Begin with general patterns
    • Add specific patterns for edge cases
    • Test with real user queries

  2. Avoid Over-Matching:

    • Be specific enough to avoid false positives
    • Test patterns with unrelated queries
    • Monitor false positive rates

  3. Document Patterns:

    • Comment complex patterns
    • Explain why patterns are needed
    • Keep pattern database organized

Performance​

  1. Cache Management:

    • Forms and services are cached in memory
    • Clear cache after configuration changes
    • Monitor cache size for large domains

  2. Early Detection First:

    • Always enable early detection for cost savings
    • Monitor detection accuracy
    • Adjust patterns based on metrics

  3. Error Handling:

    • Gracefully handle missing files
    • Provide fallback messages
    • Log errors for debugging

Conclusion​

The Forms and Services functionality provides a powerful way to extend the chatbot beyond simple Q&A. By following this documentation, you can:

  • Configure forms and services for your domain
  • Understand the complete workflow from user query to response
  • Troubleshoot common issues
  • Extend the system with new patterns and handlers

For additional support, refer to:

  • domain-chatbot/docs/Technical-documentation.md - General technical documentation
  • domain-chatbot/docs/Features.md - Feature overview
  • domain-chatbot/docs/APIs.md - API documentation