Geniusia_v2/.kiro/specs/workflow-detection-fix/design.md

Design Document - Workflow Detection Fix

Overview

This design addresses the critical bugs preventing workflow detection in GeniusIA v2. The main issues are:

1. SessionManager and WorkflowDetector are not integrated into the Orchestrator
2. VisionAnalysis has an attribute name bug (self.llm_manager vs self.llm)
3. No workflow persistence mechanism exists

The solution integrates these components into the existing cognitive loop and fixes the bugs.

Architecture

Current Architecture (Broken)

Orchestrator
  ├─ EventCapture (captures actions)
  ├─ VisionAnalysis (BROKEN - wrong attribute)
  ├─ SuggestionManager (never receives workflows)
  └─ LearningManager

Fixed Architecture

Orchestrator
  ├─ EventCapture (captures actions)
  ├─ SessionManager (NEW - segments actions)
  │   └─ WorkflowDetector (NEW - detects patterns)
  ├─ VisionAnalysis (FIXED - correct attribute)
  ├─ SuggestionManager (receives workflow notifications)
  └─ LearningManager

Components and Interfaces

1. Orchestrator Integration

Changes Required:

• Import SessionManager and WorkflowDetector
• Initialize both components in __init__
• Pass actions to SessionManager in the cognitive loop
• Connect WorkflowDetector callbacks to SuggestionManager

New Attributes:

self.session_manager: SessionManager
self.workflow_detector: WorkflowDetector

New Method:

def _on_workflow_detected(self, workflow: Dict[str, Any]) -> None:
    """Callback when a workflow is detected."""
    # Notify suggestion manager
    # Log workflow details
    # Persist workflow

2. SessionManager Integration

Initialization:

self.session_manager = SessionManager(
    logger=logger,
    config=config
)

Usage in Cognitive Loop:

# After action is captured
session = self.session_manager.add_action(action_data)
if session and session.is_complete:
    self.workflow_detector.analyze_session(session)

3. WorkflowDetector Integration

Initialization:

self.workflow_detector = WorkflowDetector(
    embeddings_manager=learning_manager.embeddings_manager,
    logger=logger,
    config=config
)
self.workflow_detector.on_workflow_detected = self._on_workflow_detected

Workflow Persistence:

• Save to data/user_profiles/workflows/workflow_{id}.json
• Load on startup
• Update confidence scores on execution

4. VisionAnalysis Bug Fix

Current Bug:

if self.llm_manager:  # WRONG - attribute is self.llm
    response = self.llm_manager.generate_with_vision(...)

Fixed:

if self.llm:  # CORRECT
    response = self.llm.generate_with_vision(...)

Data Models

Session Model (Existing)

@dataclass
class Session:
    session_id: str
    start_time: datetime
    end_time: Optional[datetime]
    actions: List[Dict[str, Any]]
    window: Optional[str]

Workflow Model (New)

@dataclass
class Workflow:
    workflow_id: str
    name: str
    pattern: List[str]  # Action signatures
    confidence: float
    repetitions: int
    last_seen: datetime
    window: str

Error Handling

VisionAnalysis Errors

• Catch all exceptions in analyze_action
• Log errors with context
• Return partial signature on failure
• Continue processing other actions

SessionManager Errors

• Handle invalid action data gracefully
• Log session creation failures
• Don't crash on timeout issues

WorkflowDetector Errors

• Handle embedding comparison failures
• Log pattern matching errors
• Continue processing other sessions

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

Property 1: Action forwarding to SessionManager

For any valid user action processed by the Orchestrator, the action should be passed to the SessionManager for segmentation. Validates: Requirements 1.1

Property 2: Session grouping by time and context

For any sequence of actions with timestamps and window contexts, actions within the time window threshold and same window should be grouped into the same session. Validates: Requirements 1.2

Property 3: Completed sessions trigger workflow analysis

For any completed session, the WorkflowDetector should receive the session for pattern analysis. Validates: Requirements 1.3

Property 4: Workflow detection triggers notifications

For any detected workflow pattern, the SuggestionManager callback should be invoked with the workflow details. Validates: Requirements 1.4

Property 5: Workflow notifications generate suggestions

For any workflow notification received by SuggestionManager, at least one suggestion should be created for the user. Validates: Requirements 1.5

Property 6: VisionAnalysis error resilience

For any error encountered during VisionAnalysis, the system should log the error and continue processing without crashing. Validates: Requirements 2.2

Property 7: Action signature completeness

For any action analyzed by VisionAnalysis, the resulting signature should contain both visual embeddings and element descriptions (or defaults if LLM unavailable). Validates: Requirements 2.3

Property 8: Workflow persistence

For any detected workflow, a corresponding JSON file should be created in the user profile workflows directory with all workflow details. Validates: Requirements 3.1

Property 9: Confidence score updates

For any workflow that is executed successfully, its confidence score should increase. Validates: Requirements 3.3

Property 10: Session logging completeness

For any session created by SessionManager, a log entry should be created containing the session ID and action count. Validates: Requirements 4.1

Property 11: Workflow detection logging

For any workflow detected by WorkflowDetector, a log entry should be created containing the workflow pattern and confidence score. Validates: Requirements 4.2

Property 12: Error logging with context

For any workflow detection failure, a log entry should be created containing the error message and relevant context. Validates: Requirements 4.3

Testing Strategy

Unit Tests

• Test SessionManager action grouping with specific examples
• Test WorkflowDetector pattern matching with known patterns
• Test VisionAnalysis attribute access (bug fix verification)
• Test Orchestrator integration points with mocks

Property-Based Tests

We will use Hypothesis for property-based testing in Python. Each property above will be implemented as a property-based test that runs 100+ iterations with randomly generated inputs to verify the correctness properties hold across all valid inputs.