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**:
```python
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**:
```json
{
  "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:
```json
{
  "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