Architecture: hbf-nlp

C4 Component Diagram

Key Flows

Message Processing Flow

1. NLPController.processOrganizationTenant receives request.
2. NLPService.process fetches tenant config from HbfCoreService.
3. Priority keyword pre-processing: checks query against LocalNluSettings.intents using exact match or configured similarity algorithm (Jaro-Winkler/Damerau-Levenshtein). Returns immediately if matched.
4. Language resolution: if detectLanguage=true, calls LlmService.languageDetectionLegacy; otherwise uses the provided language field.
5. Pipeline selection: looks up tenant.nlpMap[language] first; falls back to evaluating PipelineDecisionTree from tenant.nlpTreeMap[language].
6. NLPService.processQuery calls ResolverService to get the provider for the pipeline type (HELVIA_RAG, HELVIA_NLP, or DIALOGFLOW_NLP).
7. Provider delegates to its HTTP/gRPC client, returns NLPProcessResponseDto.
8. Per-message metadata (pipeline used, confidence, timings) is written to MySQL via MessageMetadataService.

Training Flow

1. Request arrives at NLPController (train endpoint).
2. NLPService.trainOne sets pipeline status to TRAINING via HbfCoreService.
3. Fetches training content (KB articles + automated answers) from hbf-core.
4. Provider's train() method is called (e.g., HelviaRAGPipelinesProvider.train sends corpus to helvia-rag-pipelines).
5. SchedulerService schedules a polling task to check training completion.
6. On failure, NotificationsService creates an error notification for the user.

LLM Session Analysis Flow

1. LlmController.analyzeChatSession is called with orgId/tenantId/sessionId.
2. LlmService fetches tenant's LLM_SUMMARIZATION plugin and its integration config.
3. Resolves the appropriate LlmProvider (OpenAI, Azure, Gemini) via ResolverService.
4. Builds session transcript, constructs prompt, calls provider.analyze().
5. Result (summary, classification tags, sentiment) is written back to hbf-core.