wiki/implementation/Chatbot/implementation_chatbot_feature.md

Chatbot vs FastTrack: Architecture Comparison

Chatbot Basic Implementation

Overview

The chatbot is a specialized feature designed for handling user queries that require database access or web research. It provides immediate responses by returning a workflow object instantly, then processes the request asynchronously in the background.

Core Purpose

The chatbot analyzes user input to determine what database queries or web research are needed, executes them, and generates comprehensive answers based on real data rather than just AI knowledge.

Main Entry Point

Function: modules/features/chatbot/mainChatbot.py::chatProcess()

Signature:

async def chatProcess(
    currentUser: User,
    userInput: UserInputRequest,
    workflowId: Optional[str] = None
) -> ChatWorkflow

Basic Flow

1. Workflow Creation/Resumption

   • Creates new workflow or resumes existing one
   • Generates conversation name from user prompt
   • Sets workflow mode to WORKFLOW_CHATBOT
   • Creates event queue for streaming

2. Message Storage

   • Stores user message immediately
   • Emits message event for streaming
   • Returns workflow object (instant response to user)

3. Background Processing (async)

   • Analyzes user input to determine query needs
   • Generates SQL queries if database access needed
   • Executes queries in parallel
   • Performs web research if needed
   • Generates final answer with all results

Key Components

1. Analysis Phase (_processChatbotMessage)

Purpose: Determines what queries/research are needed

Implementation:

• Uses get_initial_analysis_prompt() from chatbotConstants.py
• Calls AI via MethodAi.process() with simpleMode=True
• Returns JSON with:
  • needsDatabaseQuery: Boolean
  • needsWebResearch: Boolean
  • sqlQueries[]: Array of SQL query objects
  • reasoning: Explanation of analysis

Query Structure:

{
  "query": "SELECT ...",
  "purpose": "Description of what query retrieves",
  "table": "Primary table name"
}

2. Query Execution (_execute_queries_parallel)

Purpose: Executes multiple SQL queries simultaneously

Implementation:

• Uses PreprocessorConnector for database access
• Executes all queries in parallel via asyncio.gather()
• Returns results as dictionary:
  • query_1, query_2, etc.: Success result text
  • query_1_data, query_2_data, etc.: Raw data arrays
  • query_1_error, query_2_error, etc.: Error messages if failed

Benefits:

• Parallel execution = faster overall time
• Continues even if some queries fail
• Provides detailed error information per query

3. Web Research (_buildWebResearchQuery)

Purpose: Enriches web search queries with context from conversation

Implementation:

• Extracts product information from:
  • Current user prompt (article numbers, product mentions)
  • Database query results (if available)
  • Previous assistant messages (conversation history)
• Builds enriched search query with article number, description, supplier
• Calls services.web.performWebResearch()

4. Final Answer Generation

Purpose: Combines all results into comprehensive answer

Implementation:

• Uses get_final_answer_system_prompt() for structured response
• Builds context with:
  • User question
  • Database query results (organized by query number)
  • Web research results
  • Error information if queries failed
• Single AI call with all data
• Streams result as assistant message

Key Functions

Function	Purpose	Location
chatProcess()	Main entry point, creates workflow and starts processing	mainChatbot.py:60
_processChatbotMessage()	Background processing: analysis → execution → answer	mainChatbot.py:522
_execute_queries_parallel()	Executes multiple SQL queries in parallel	mainChatbot.py:194
_buildWebResearchQuery()	Enriches web search with conversation context	mainChatbot.py:318
_extractJsonFromResponse()	Extracts JSON from AI response (handles markdown)	mainChatbot.py:33
_emit_log_and_event()	Stores logs and emits events for streaming	mainChatbot.py:254
get_initial_analysis_prompt()	System prompt for query analysis	chatbotConstants.py
get_final_answer_system_prompt()	System prompt for final answer generation	chatbotConstants.py
generate_conversation_name()	Generates conversation name from user prompt	chatbotConstants.py

Database Schema

The chatbot has knowledge of the database schema:

Tables:

• Artikel: Product information (I_ID, Artikelbezeichnung, Artikelnummer, etc.)
• Einkaufspreis: Price data (m_Artikel, EP_CHF)
• Lagerplatz_Artikel: Stock and warehouse location data (R_ARTIKEL, R_LAGERPLATZ, Bestände, etc.)
• Lagerplatz: Warehouse location names (I_ID, Lagerplatz, R_LAGER, R_LAGERORT)

Relationships:

• Artikel.I_ID = Einkaufspreis.m_Artikel
• Artikel.I_ID = Lagerplatz_Artikel.R_ARTIKEL
• Lagerplatz_Artikel.R_LAGERPLATZ = Lagerplatz.I_ID

Streaming Architecture

Route: /api/chatbot/start/stream

Format: Server-Sent Events (SSE)

Data Format: Exact chatData format:

{
  "type": "message" | "log" | "stat",
  "createdAt": "timestamp",
  "item": { ... }
}

Features:

• Initial chat data sent immediately
• Periodic fetching of new chat data (every 0.5s)
• Event queue for real-time updates
• Round-based filtering for resumed conversations

Error Handling

Strategy: Graceful degradation

• If analysis fails: Uses fallback empty analysis
• If queries fail: Logs errors per query, continues with successful ones
• If web research fails: Logs warning, continues without web data
• If final answer fails: Stores error message, updates workflow status

Result: Always provides some response, even if partial

Workflow States

• running: Processing in progress
• completed: Successfully finished
• stopped: User stopped the workflow
• error: Error occurred during processing

Key Design Decisions

1. Immediate Return: Returns workflow object instantly, processes in background
2. Parallel Execution: Executes multiple queries simultaneously for speed
3. Streaming Feedback: Provides real-time progress updates
4. Data-Driven: Uses real database/web data rather than AI knowledge only
5. Graceful Degradation: Continues with partial results if some steps fail
6. Conversation Context: Uses conversation history to enrich queries

---

Comparison Chatbot and Fasttrack Workflow

This document compares two approaches for handling simple user requests:

• Chatbot: A specialized feature for database queries and web research
• FastTrack: A fast path optimization in the general workflow system

Both serve similar purposes but have different execution models and characteristics.

Chatbot Architecture

Execution Flow

User sends message
    ↓
[STEP 1] Store message immediately → RETURN workflow (instant response)
    ↓
[STEP 2] Background processing starts (async)
    ↓
[STEP 3] Focused Analysis (~2-5s)
    - Determines: needsDatabaseQuery? needsWebResearch?
    - Generates SQL queries if needed
    - Lightweight, purpose-specific prompt
    ↓
[STEP 4] Execute queries in PARALLEL (if DB needed)
    - Multiple SQL queries run simultaneously
    - Database execution is fast
    ↓
[STEP 5] Web research (if needed, parallel to DB)
    ↓
[STEP 6] Final AI call with ALL results (~5-10s)
    - Has actual data from DB/web
    - Generates comprehensive answer
    ↓
Stream everything back (queries, results, final answer)
    ↓
Done (Total: ~7-20s, but user sees response immediately)

Key Characteristics

• Immediate Response: Returns workflow object immediately, processes in background
• Focused Analysis: Single-purpose analysis to determine DB/web needs
• Parallel Execution: Executes multiple SQL queries simultaneously
• Data-Driven: Uses real database and web research results
• Streaming Feedback: Streams queries, results, and progress updates
• Workflow Mode: Uses WorkflowModeEnum.WORKFLOW_CHATBOT

Implementation Details

Entry Point: modules/features/chatbot/mainChatbot.py::chatProcess()

Analysis Phase:

• Uses get_initial_analysis_prompt() for focused analysis
• Returns: needsDatabaseQuery, needsWebResearch, sqlQueries[]
• Executes via MethodAi.process() with simpleMode=True

Query Execution:

• Parallel execution via _execute_queries_parallel()
• Uses PreprocessorConnector for database access
• Results stored as query_1, query_2_data, etc.

Final Answer:

• Single AI call with all query results and web research
• Uses get_final_answer_system_prompt() for structured response
• Streams result as assistant message

FastTrack Architecture

Execution Flow

User sends message
    ↓
[STEP 1] COMBINED ANALYSIS (heavy AI call - ~5-10s)
    - Analyzes complexity, language, intent
    - Normalizes request (full restatement)
    - Extracts context items
    - Determines dataType, expectedFormats, qualityRequirements
    - Checks needsWorkflowHistory
    - Determines fastTrack eligibility
    ↓
[STEP 2] If simple → FastTrack path
    ↓
[STEP 3] FastTrack AI call (~5-15s)
    - Single AI call with prompt
    - Basic processing mode
    - Max 15s timeout
    ↓
[STEP 4] Store answer
    ↓
Done (Total: ~10-25s + overhead)

Key Characteristics

• Comprehensive Analysis: Multi-purpose analysis covering 11 different aspects
• Sequential Execution: Single AI call after analysis
• Knowledge-Based: Relies on AI's training data (no database access)
• Silent Processing: No intermediate feedback until final answer
• Workflow Integration: Part of general workflow system

Implementation Details

Entry Point: modules/workflows/workflowManager.py::_executeFastPath()

Analysis Phase:

• Uses _analyzeUserInputAndComplexity() for comprehensive analysis
• Returns: complexity, detectedLanguage, normalizedRequest, intent, contextItems, dataType, expectedFormats, qualityRequirements, successCriteria, needsWorkflowHistory, fastTrack
• Executes via services.ai.callAiPlanning()

FastTrack Execution:

• Single AI call via workflowProcessor.fastPathExecute()
• Uses callWithTextContext() for text-only responses
• Processing mode: BASIC
• Max cost: 0.10, Max time: 15s

Response:

• Creates ActionDocument with response text
• Stores as assistant message with status="last"

Comparison

Performance Characteristics

Aspect	Chatbot	FastTrack
Time to first response	Instant (returns workflow immediately)	~5-10s (waits for analysis)
Initial analysis	2-5s (focused)	5-10s (comprehensive)
Query execution	Parallel (fast)	N/A (no DB)
Final answer	5-10s (with real data)	5-15s (AI knowledge only)
User sees progress	Yes (streaming)	No (silent)
Total perceived time	~2-5s (feels instant)	~10-25s (feels slower)

Analysis Complexity

Chatbot Analysis:

• Single-purpose: Determines if DB/web research needed
• Lightweight prompt focused on query generation
• Returns: needsDatabaseQuery, needsWebResearch, sqlQueries[]

FastTrack Analysis:

• Multi-purpose: Comprehensive request analysis
• Detailed prompt covering 11 different aspects
• Returns: Complexity, language, intent, normalized request, context items, data type, formats, quality requirements, success criteria, workflow history needs, fastTrack eligibility

Data Access

Chatbot:

• ✅ Direct database access via PreprocessorConnector
• ✅ Web research via services.web.performWebResearch()
• ✅ Uses real data for answers

FastTrack:

• ❌ No database access
• ❌ No web research
• ✅ Uses AI's training knowledge

User Experience

Chatbot:

• Immediate workflow return
• Streaming progress updates
• See queries being generated
• See query results
• See final answer being built

FastTrack:

• Waits for analysis completion
• Silent processing
• Single final answer
• No intermediate feedback

Code Complexity

Chatbot:

• Single-purpose feature
• Focused code path
• Direct query execution
• Minimal conditional logic

FastTrack:

• Part of larger workflow system
• Multiple routing decisions
• Integrated with task planning
• More conditional branches