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

{
    "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

{
    "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

{
    "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

{
    "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

{
    "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

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

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

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

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

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

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