IRIS Admin

An intent is a label that classifies what the user wants (for example work_order_status or invoice_overdue). A reply is the markdown string the chatbot returns. In IRIS, intents are detected by a hybrid regex + LLM engine, then routed to a DataHandler that fetches ERP data, then to a Formatter that renders the data to markdown. This page is the developer reference for that pipeline.

Important: intents and replies in this system are defined entirely in code — PHP config files and service classes — not in database tables. The only chatbot-related DB table is chatbot_query_logs, which logs queries (with the detected intent and a response preview) but does not store intent or reply definitions. So the "schema" below is the config-array and class structure, not a SQL schema.

Audience: a developer who needs to add a new intent or change a reply format. Every fact here is derived live from the codebase (counts and lists are read from the actual config/classes by IntentGuideController); the steps and gotchas come from a verified study of the source. For the authoritative deep dive, see .cursor/guide/INTENT_SYSTEM_GUIDE.md.

Three views of the IRIS intent + reply pipeline. Switch tabs to compare the flowchart, the runtime sequence, and the class structure. Diagrams are rendered live with React Flow.

An intent is defined in three places that must be kept consistent by hand. They are not generated from each other — an intent can exist in one and not the others. There is no database table for intents.

The category field is used for grouping and reporting. The examples feed the LLM classification prompt (up to 3 are shown per intent). The entities list declares which entity keys the matching DataHandler expects to receive.

This is the manual recipe for adding a first-class ERP intent. It touches all three definition sources plus the handler/formatter pair. Use real file paths.

IntentDetectionService::detectIntent() always runs regex first, then LLM. The intent_detection.mode config (currently llm) is declared in config/chatbot.php, but the live detectIntent() code performs the regex-then-LLM sequence regardless of mode (so in practice the engine behaves as hybrid).

Active mode

llm declared regex-then-LLM in code

LLM confidence threshold

0.7

Intent cache

enabled · TTL 3600s

Default model

qwen3:30b

Multilingual model

qwen3:30b

LLM temperature

0.3

Iterates config/intent_patterns.php in order. The first group whose any pattern matches the lower-cased query wins. Special pre-processing:

• Conversational first: greeting, thanks are checked first — but only if the query has no ERP content.
• Help intent: short-query special logic (isHelpIntent()), e.g. help, menu, what can you do.
• Part-number intents: detectWorkOrdersByPartIntent() & detectBomIntent() distinguish exact vs partial part numbers → work_orders_by_part vs work_orders_by_part_list, and bom_details vs bom_search.
• New-feature fallback: isNewFeatureRequest() — if the query has ≥2 ERP keywords but no pattern matched → new_erp_feature_request.
• Otherwise → unknown, which falls through to the LLM.

Calls Ollama with a classification prompt built by buildClassificationPrompt(). The prompt includes the full intent list (grouped by category), the entity types below, CRITICAL RULES (general-knowledge vs ERP, multilingual EN/BM, greeting+ERP, part-number patterns), and a 7-factor decision framework with weights:

The LLM returns JSON: has_intent, confidence, intent, entities, clarification_needed, factor_analysis, alternative_intents[]. When alternatives exist, selectBestCandidate() picks the best by combined_score = (confidence × 0.7) + (entity_score × 0.3). Confidence bands: 0.9–1.0 very clear, 0.7–0.89 clear, 0.5–0.69 moderate, <0.5 low. Results below the threshold (0.7) fall through to the conversational/unknown path.

normalizeEntities() cleans the result: WO/SO/PO numbers are forced to 8 digits, invoice numbers must start with 11/12, the T prefix is stripped from trip numbers, natural dates are parsed to Y-m-d, currency codes upper-cased to 3 letters. A regex-based EntityExtractionService supplements LLM entities with dates and document numbers when the LLM returns none.

A reply is not a stored row. It is generated at runtime: a DataHandler returns a payload array, and a Formatter renders that array to a markdown string. The contract between them is the payload's type key.

14 DataHandlers and 14 Formatters, paired 1:1 by domain. Formatter registration order matters — more specific formatters are registered first so a generic one does not swallow a specific payload (see ChatbotService::registerFormatters()).

Counts are read live via reflection (without invoking constructors), so they always match the deployed code. A handler's count is its $supportedIntents size; a formatter's count is its $identifyingKeys size (the number of payload shapes it claims).

The chatbot writes one row per query to chatbot_query_logs (model ChatbotQueryLog, owned by the ERP schema). It records the outcome of intent matching — not the definitions. Key columns: conversation_id, user_id, client (web/mobile/desktop), question, detected_intent, extracted_entities (JSON), response_preview, was_successful, response_time_ms. Scopes: dateRange, byUser, byIntent, byClient, failed. (No migration exists for it in either project; the table is created/maintained by the ERP.)

A formatter builds the reply as an array of markdown lines, then joins them with finishOutput(). Use the BaseFormatter helpers below — do not hand-concatenate strings. The web/mobile clients render this markdown (headings, bold, lists, tables, images, links).

For exportable intents, ChatbotService::buildResponse() appends Excel/Word download links to the markdown and adds an actions[] array to the JSON response:

For trip-photo payloads, a media gallery object ({ type: 'gallery', photos_by_trip, gallery_url, total_photos }) is added to the JSON response for the client's image viewer. These are not separate rich-content types you author in a formatter — they are appended automatically based on the payload shape.

Conversational intents (greeting, thanks, help, farewell, clarification_needed, general/unknown) return hardcoded markdown from handleConversationalQuery(), or an LLM-generated reply for general. They never touch a DataHandler/Formatter.

A separate set of static templates live in config/chatbot.php under templates. They use {field} placeholders (single braces). These are reference/legacy templates; the live pipeline uses the formatter classes above.

What is NOT supported: there are no button / card / quick-reply / list-template rich-content types as separate authorable formats. Everything is markdown; interactivity (export buttons, galleries) is added by ChatbotService as JSON actions/media alongside the markdown, and rendered by the client.

A worked example of one intent + reply, start to finish. The snippets below are the actual live definitions read from the codebase by the controller.

Expected: regex matches work_order_status → WorkOrderDataHandler fetches the WO → WorkOrderFormatter renders the markdown detail card (with BOM image if available).