wiki/z-archive/implementation/implementation_adaptive_react_mode_technical.md

# Adaptive React Mode: Technical Implementation

## How the Adaptive Engine Works

### The Core Process Flow

```
User Request → Intent Analysis → Action Planning → Execution → 
Content Validation → Learning Update → Progress Check → Next Action
```

### Step 1: Intent Analysis Process

**What happens**: System analyzes what user actually wants
**Input**: User prompt "Calculate first 1000 prime numbers"
**Process**: 
1. Check for data type keywords (numbers, list, calculate)
2. Check for format preferences (raw data vs formatted)
3. Extract success criteria (first 1000, prime numbers)
4. Determine quality requirements (accuracy, completeness)

**Output**: Intent object
```python
{
    "dataType": "numbers",
    "expectedFormat": "raw_data", 
    "successCriteria": ["first 1000", "prime numbers"],
    "qualityRequirements": {"accuracy": 0.95, "completeness": 0.95}
}
```

### Step 2: Action Planning Process

**What happens**: System plans action based on intent + learned strategies
**Input**: Intent analysis + learned strategies
**Process**:
1. Check learned strategies for similar intents
2. If learned: Use successful strategy
3. If not learned: Use default strategy
4. Generate specific action parameters

**Output**: Action plan
```python
{
    "method": "ai",
    "action": "process",
    "parameters": {
        "aiPrompt": "Deliver the first 1000 prime numbers as a list"
    }
}
```

### Step 3: Content Validation Process

**What happens**: Check if delivered content matches intent
**Input**: ActionResult + Intent analysis
**Process**:
1. Extract content from documents
2. Check data type match (numbers vs code)
3. Check format match (raw data vs formatted)
4. Check success criteria (first 1000, prime numbers)
5. Calculate quality score

**Output**: Validation result
```python
{
    "overallSuccess": true,
    "dataTypeMatch": true,
    "formatMatch": true,
    "successCriteriaMet": [true, true],
    "qualityScore": 0.95,
    "issues": [],
    "improvementSuggestions": []
}
```

### Step 4: Learning Update Process

**What happens**: Learn from the result and update strategies
**Input**: Validation result + action taken
**Process**:
1. Record what was attempted
2. Record how well it worked
3. Update strategy for similar future requests
4. Store pattern for future use

**Output**: Updated strategy
```python
{
    "pattern": "numbers_request",
    "successfulAction": "ai.process with data delivery prompt",
    "successRate": 0.95,
    "lastUpdated": "2025-01-04T10:30:00Z"
}
```

### Step 5: Progress Check Process

**What happens**: Determine if task is complete
**Input**: Validation result + progress state
**Process**:
1. Check if all success criteria are met
2. Check if quality requirements are satisfied
3. Determine if more actions are needed
4. Suggest next action if needed

**Output**: Continue/Stop decision
```python
{
    "decision": "stop",
    "reason": "All success criteria met",
    "progress": 100,
    "nextAction": null
}
```

## Implementation Details

### 1. Intent Analyzer

**Purpose**: Understand what user actually wants
**Location**: `gateway/modules/workflows/processing/adaptive/intentAnalyzer.py`

**Key Methods**:
- `analyzeUserIntent(userPrompt, context)` - Main analysis method
- `_classifyDataType(prompt)` - Determine if user wants numbers, text, documents, etc.
- `_extractSuccessCriteria(prompt, context)` - Extract specific requirements
- `_assessQualityRequirements(prompt)` - Determine quality needs

**Integration**: Called in `reactMode.py` before action planning

### 2. Content Validator

**Purpose**: Validate delivered content against user intent
**Location**: `gateway/modules/workflows/processing/adaptive/contentValidator.py`

**Key Methods**:
- `validateContent(documents, intent)` - Main validation method
- `_checkDataTypeMatch(content, dataType)` - Check if content matches expected type
- `_checkSuccessCriteria(content, criteria)` - Check if requirements are met
- `_calculateQualityScore(content, intent)` - Calculate overall quality

**Integration**: Called in `reactMode.py` after action execution

### 3. Learning Engine

**Purpose**: Learn from feedback and adapt strategies
**Location**: `gateway/modules/workflows/processing/adaptive/learningEngine.py`

**Key Methods**:
- `learnFromFeedback(feedback, context, intent)` - Learn from action result
- `getImprovedStrategy(context, intent)` - Get learned strategy for planning
- `_updateStrategy(pattern, success)` - Update strategy based on result
- `_findRelevantPatterns(context, intent)` - Find applicable learned patterns

**Integration**: Called in `reactMode.py` after validation and before next action

### 4. Progress Tracker

**Purpose**: Track what has been accomplished
**Location**: `gateway/modules/workflows/processing/adaptive/progressTracker.py`

**Key Methods**:
- `updateProgress(result, validation, intent)` - Update progress state
- `getCurrentProgress()` - Get current progress status
- `shouldContinue(progress, validation)` - Determine if should continue
- `getNextActionSuggestions(progress, intent)` - Suggest next actions

**Integration**: Called in `reactMode.py` for progress tracking and stopping decisions

## Integration with Existing React Mode

### Modified Methods in `reactMode.py`

#### 1. `executeTask` Method
**Changes**:
- Add intent analysis at start
- Add progress tracking throughout
- Add learning updates after each action
- Use adaptive stopping logic

```python
async def executeTask(self, taskStep, workflow, context, taskIndex=None, totalTasks=None):
    # NEW: Analyze user intent
    intentAnalysis = self.intentAnalyzer.analyzeUserIntent(taskStep.objective, context)
    
    # NEW: Initialize progress tracking
    progressState = ProgressState()
    
    while step <= max_steps:
        # NEW: Get learned strategy
        strategy = self.learningEngine.getImprovedStrategy(context, intentAnalysis)
        
        # Existing: Execute action
        result = await self._actExecute(context, selection, taskStep, workflow, step)
        
        # NEW: Validate content
        validationResult = self.contentValidator.validateContent(result.documents, intentAnalysis)
        
        # NEW: Learn from result
        feedback = self._collectFeedback(result, validationResult, intentAnalysis)
        self.learningEngine.learnFromFeedback(feedback, context, intentAnalysis)
        
        # NEW: Update progress
        self.progressTracker.updateProgress(result, validationResult, intentAnalysis)
        
        # NEW: Check if should continue
        if not self.progressTracker.shouldContinue(progressState, validationResult):
            break
```

#### 2. `_observeBuild` Method
**Changes**:
- Add content analysis to observation
- Include actual content snippets
- Add intent match assessment

```python
def _observeBuild(self, actionResult):
    # Existing: Basic observation
    observation = {
        "success": bool(actionResult.success),
        "documentsCount": len(actionResult.documents),
        "previews": self._buildDocumentPreviews(actionResult.documents)
    }
    
    # NEW: Add content analysis
    if actionResult.documents:
        content = self._extractContent(actionResult.documents[0])
        observation["contentAnalysis"] = {
            "contentType": self._classifyContent(content),
            "contentSnippet": content[:200] + "..." if len(content) > 200 else content,
            "intentMatch": self._assessIntentMatch(content, self.currentIntent)
        }
    
    return observation
```

#### 3. `_refineDecide` Method
**Changes**:
- Use learned strategies for decision making
- Consider progress state in decisions
- Apply learned patterns to avoid repeated failures

```python
async def _refineDecide(self, context, observation, intentAnalysis, progressState):
    # NEW: Get learned strategies
    strategies = self.learningEngine.getImprovedStrategy(context, intentAnalysis)
    
    # NEW: Check progress state
    if self.progressTracker.shouldContinue(progressState, observation):
        return {"decision": "continue", "reason": "More work needed"}
    
    # NEW: Apply learned patterns
    if strategies and strategies.get("avoidActions"):
        # Avoid actions that have failed before
        pass
    
    return {"decision": "stop", "reason": "Objective completed"}
```

### Enhanced Prompt Templates

#### 1. Action Selection Prompt
**Enhancement**: Include learned strategies and intent-specific guidance

```python
def createActionSelectionPromptTemplate():
    return """
    Select exactly one action to advance the task.
    
    OBJECTIVE: {{KEY:USER_PROMPT}}
    USER INTENT: {{KEY:USER_INTENT}}  # NEW: Intent analysis
    LEARNED STRATEGIES: {{KEY:LEARNED_STRATEGIES}}  # NEW: Learned patterns
    AVAILABLE METHODS: {{KEY:AVAILABLE_METHODS}}
    
    CRITICAL RULES:
    - If user wants DATA (numbers, lists, calculations): Use appropriate method to DELIVER the actual data, not code
    - If user wants DOCUMENTS (Word, PDF, Excel): Use appropriate method to create the document
    - If user wants ANALYSIS: Use appropriate method to analyze and deliver insights
    - NEVER ask AI to write code when user wants data - deliver the data directly
    - Apply learned strategies: {{KEY:LEARNED_STRATEGIES}}
    """
```

#### 2. Refinement Prompt
**Enhancement**: Include content validation and progress assessment

```python
def createRefinementPromptTemplate():
    return """
    Decide next step based on observation.
    
    OBJECTIVE: {{KEY:USER_PROMPT}}
    USER INTENT: {{KEY:USER_INTENT}}  # NEW: Intent analysis
    CONTENT VALIDATION: {{KEY:CONTENT_VALIDATION}}  # NEW: Validation results
    PROGRESS STATE: {{KEY:PROGRESS_STATE}}  # NEW: Progress tracking
    
    CRITICAL RULES:
    - If user wants DATA (numbers, lists, calculations): Ensure AI delivers the actual data, not code
    - If user wants DOCUMENTS (Word, PDF, Excel): Ensure appropriate method is used to create the document
    - If user wants ANALYSIS: Ensure AI analyzes and delivers insights
    - NEVER accept code when user wants data - demand the actual data
    - Consider progress: {{KEY:PROGRESS_STATE}}
    """
```

## Implementation Steps

### Step 1: Create Adaptive Directory Structure
```bash
mkdir -p gateway/modules/workflows/processing/adaptive
```

### Step 2: Implement Core Components
1. **Intent Analyzer** (`intentAnalyzer.py`)
   - Analyze user prompts for intent
   - Classify data types and formats
   - Extract success criteria

2. **Content Validator** (`contentValidator.py`)
   - Validate delivered content
   - Check against user intent
   - Calculate quality scores

3. **Learning Engine** (`learningEngine.py`)
   - Learn from feedback
   - Store and retrieve strategies
   - Adapt future behavior

4. **Progress Tracker** (`progressTracker.py`)
   - Track task progress
   - Make continue/stop decisions
   - Suggest next actions

### Step 3: Integrate with React Mode
1. **Modify `reactMode.py`**:
   - Add adaptive components
   - Enhance observation building
   - Add learning to action planning
   - Add progress tracking

2. **Enhance prompt templates**:
   - Add intent analysis to prompts
   - Include learned strategies
   - Add content validation results

### Step 4: Test and Validate
1. Test with various user intents
2. Validate learning effectiveness
3. Ensure integration with existing refactoring

## Expected Results

### Before (Current React Mode)
- Blind to user intent
- No learning from mistakes
- Fake success indicators
- No progress understanding

### After (Adaptive React Mode)
- Understands user intent
- Learns and improves over time
- Real validation and success assessment
- Tracks progress and makes intelligent decisions

### Example Improvement
```
User: "Calculate first 1000 prime numbers"

Current React Mode:
Step 1: ai.process("Write code to generate primes") → Code → FAIL
Step 2: ai.process("Write code to generate primes") → Code → FAIL
Step 3: ai.process("Write code to generate primes") → Code → FAIL
Result: User gets code, not numbers

Adaptive React Mode:
Step 1: ai.process("Write code to generate primes") → Code → FAIL
Learning: "For number requests, don't ask for code"
Step 2: ai.process("List the first 1000 prime numbers") → Numbers → SUCCESS
Learning: "For number requests, ask for data directly"
Result: User gets actual numbers
```