# Workflows Component Documentation ## Overview The **Workflows** component is the orchestration engine of the application, responsible for managing complex multi-step user interactions through intelligent task planning, action execution, and adaptive learning. It transforms user requests into structured workflows that are executed through a flexible, mode-based architecture. ### Key Responsibilities - **Workflow Orchestration**: Manages the complete lifecycle of user workflows from initiation to completion - **Task Planning**: Analyzes user intent and generates structured task plans using AI-powered planning - **Action Execution**: Coordinates the execution of actions across multiple methods and services - **State Management**: Maintains workflow state, progress tracking, and context throughout execution - **Adaptive Learning**: Learns from execution results to improve future performance - **Mode-Based Processing**: Supports multiple execution strategies (Actionplan, Dynamic, Automation) --- ## Architecture ### High-Level Design ```mermaid flowchart TD A["API Layer (Routes)
routeChatPlayground, routeWorkflows"] B["Feature Layer
mainChatPlayground
(chatStart, chatStop)"] C["WorkflowManager
• workflowStart()
• workflowStop()
• _workflowProcess() (main pipeline)"] D["WorkflowProcessor (Delegation)
Delegates to mode-specific implementations"] E["Actionplan
Mode"] F["Dynamic
Mode"] G["Automation
Mode"] H["Core Components
• TaskPlanner
• ActionExecutor
• MessageCreator
• WorkflowValidator"] I["Method System
• methodAi
• methodSharepoint
• methodOutlook
(Extensible)"] A --> B B --> C C --> D D --> E D --> F D --> G E --> H F --> H G --> H H --> I ``` ### Design Principles 1. **Separation of Concerns**: Clear boundaries between orchestration, planning, execution, and methods 2. **Mode-Based Strategy Pattern**: Different execution strategies for different use cases 3. **Dependency Injection**: Services object provides access to all system capabilities 4. **Extensibility**: Easy to add new methods and actions without modifying core logic 5. **Asynchronous Processing**: Non-blocking workflow execution with background task processing 6. **State Persistence**: Workflow state is persisted to database and maintained in memory --- ## Component Structure ### Directory Organization ``` modules/workflows/ ├── workflowManager.py # Main orchestration controller ├── processing/ # Processing logic │ ├── workflowProcessor.py # Mode delegation │ ├── core/ # Core processing components │ │ ├── taskPlanner.py # Task planning logic │ │ ├── actionExecutor.py # Action execution │ │ ├── messageCreator.py # Message generation │ │ └── validator.py # Validation logic │ ├── modes/ # Execution modes │ │ ├── modeBase.py # Abstract base mode │ │ ├── modeActionplan.py # Actionplan mode │ │ ├── modeDynamic.py # Dynamic mode │ │ └── modeAutomation.py # Automation mode │ ├── adaptive/ # Adaptive learning │ │ ├── intentAnalyzer.py # Intent analysis │ │ ├── contentValidator.py # Result validation │ │ ├── learningEngine.py # Learning algorithms │ │ └── progressTracker.py # Progress tracking │ └── shared/ # Shared utilities │ ├── methodDiscovery.py # Method discovery │ ├── stateTools.py # State management │ ├── executionState.py # Execution state │ └── placeholderFactory.py # Placeholder generation └── methods/ # Extensible methods ├── methodBase.py # Base class for methods ├── methodAi.py # AI operations ├── methodSharepoint.py # SharePoint integration └── methodOutlook.py # Outlook integration ``` --- ## Core Components ### WorkflowManager **Location**: `modules/workflows/workflowManager.py` The `WorkflowManager` is the main entry point for workflow operations. It coordinates the complete workflow lifecycle from initialization to completion. #### Key Responsibilities - **Workflow Initialization**: Creates or continues workflows with proper state setup and method discovery - **User Input Processing**: Analyzes and normalizes user prompts, detecting language and extracting intent - **Document Management**: Handles user-uploaded documents, extracts bulky context, and manages document neutralization - **Pipeline Coordination**: Orchestrates the complete workflow pipeline through four distinct stages - **Error Handling**: Manages workflow errors and stop requests with graceful degradation - **State Synchronization**: Maintains consistency between in-memory workflow objects and database persistence #### Initialization and Lifecycle **workflowStart(userInput, workflowMode, workflowId?) → ChatWorkflow** The primary entry point for workflow operations. This method handles both new workflow creation and continuation of existing workflows. When starting a workflow: - **New Workflows**: Creates a `ChatWorkflow` record in the database with initial state (status="running", currentRound=1, maxSteps based on mode) - **Existing Workflows**: Loads the workflow, stops it if currently running, increments the round number, and resumes processing - **Method Discovery**: Invokes `discoverMethods()` to update all method instances with the current services object, ensuring methods use the correct workflow context - **Asynchronous Launch**: Creates an async task for `_workflowProcess()`, allowing immediate return to caller while processing continues in background - **Non-Blocking**: Returns the workflow object immediately, enabling the API to respond without waiting for completion **workflowStop(workflowId) → ChatWorkflow** Gracefully terminates a running workflow. The stop operation: - Updates workflow status to "stopped" in both memory and database - Records the stop event in workflow logs with timestamp - Allows currently executing operations to complete their current step - Does not forcefully interrupt ongoing AI calls or method executions - Enables clean resource cleanup and state persistence **_workflowProcess(userInput) → None** (Private) The main processing pipeline that coordinates all workflow stages. This async method orchestrates the complete workflow execution through four sequential phases, with error boundaries at each stage to handle stops and failures gracefully. #### Pipeline Stages **1. _sendFirstMessage(userInput)** Initiates the workflow by creating and persisting the user's initial message. This stage performs several critical operations: - **Intent Analysis**: Calls AI to analyze the user input, extracting detected language, normalized request, core intent, and bulky context items - **Language Detection**: Identifies the user's language (ISO 639-1 code) and stores it in `services.currentUserLanguage` - **Request Normalization**: Creates a full, explicit restatement of the user's request preserving all constraints and details - **Context Extraction**: Identifies large data blocks (code snippets, tables, long lists) and extracts them as separate documents to reduce prompt size - **Document Creation**: Processes extracted context items and user-uploaded files, creating document records in the component database - **Content Neutralization**: If enabled in user settings, neutralizes sensitive information in documents using the neutralization service - **Message Persistence**: Creates the first message with role="user", status="first", and associates all documents with appropriate labels (e.g., "round1_usercontext") The intent analysis can be skipped for AUTOMATION mode which uses predefined JSON plans. **2. _planTasks(userInput)** Generates a structured task plan by delegating to the WorkflowProcessor. This stage: - Uses the cleaned user intent from the previous stage - Calls `WorkflowProcessor.generateTaskPlan()` which delegates to the mode-specific implementation - Receives a `TaskPlan` object containing multiple `TaskStep` objects, each with objectives, success criteria, and dependencies - Validates that the task plan is not empty - Logs the workflow mode and number of tasks for tracking **3. _executeTasks(taskPlan)** Executes each task in the plan sequentially, maintaining context between tasks. For each task: - Builds a `TaskContext` object containing task details, workflow state, available documents/connections, and results from previous tasks - Calls `WorkflowProcessor.executeTask()` which delegates to mode-specific execution logic - Receives a `TaskResult` with success status, feedback, and any created documents - Prepares task handover data containing task information, actions performed, and review results - Accumulates task results for use by subsequent tasks - Checks for workflow stop requests between tasks The task execution behavior varies significantly by mode (batch planning with retries for Actionplan, iterative for Dynamic, predefined for Automation). **4. _processWorkflowResults()** Finalizes the workflow based on its completion status. This stage handles three scenarios: - **Stopped**: Creates a message with status="last" indicating user-initiated stop, updates workflow status to "stopped" - **Failed**: Creates an error message with failure details, updates workflow status to "failed", logs the error - **Completed**: Generates comprehensive feedback by calling `_generateWorkflowFeedback()`, creates completion message with status="last", updates workflow status to "completed" In all cases, the workflow state is updated in both the in-memory object and database, ensuring consistency. #### Helper Methods **_generateWorkflowFeedback() → str** Creates a summary of workflow execution by counting user and assistant messages, reporting task completion status, and providing a concise overview of what was accomplished. **_processFileIds(fileIds, messageId?) → List[ChatDocument]** Processes user-uploaded files, converting file IDs to ChatDocument objects. Handles document neutralization if enabled, creating new neutralized files and updating references. Logs warnings for binary files (not yet supported for neutralization) and errors for neutralization failures. **_neutralizeContentIfEnabled(contentBytes, mimeType) → bytes** Conditionally neutralizes document content based on user settings. Attempts to decode content as text, calls the neutralization service, and returns neutralized bytes. Falls back to original content if neutralization fails or content is binary. --- ### WorkflowProcessor **Location**: `modules/workflows/processing/workflowProcessor.py` The `WorkflowProcessor` acts as a delegation hub, implementing the Strategy pattern to route workflow operations to mode-specific implementations. It provides a stable interface for workflow execution while allowing different execution strategies to be swapped transparently. #### Key Responsibilities - **Mode Selection**: Creates and manages mode-specific processor instances based on WorkflowModeEnum - **Delegation**: Routes all workflow operations to the appropriate mode implementation - **Progress Tracking**: Manages workflow progress logging with operation IDs and completion tracking - **Unified Interface**: Provides consistent API regardless of mode, abstracting mode-specific behavior - **Error Management**: Wraps mode operations with error handling and progress tracking completion - **State Checking**: Ensures workflow stop requests are checked before each major operation #### Initialization and Mode Selection **_createMode(workflowMode) → BaseMode** Factory method that instantiates the appropriate mode class based on the workflow's mode setting: - **WORKFLOW_DYNAMIC**: Creates DynamicMode for iterative, just-in-time action generation - **WORKFLOW_ACTIONPLAN**: Creates ActionplanMode for batch planning with quality review - **WORKFLOW_AUTOMATION**: Creates AutomationMode for predefined JSON-based execution The mode instance is stored and reused throughout the workflow's lifetime, receiving the services object for full system access. #### Core Delegation Methods **generateTaskPlan(userInput, workflow) → TaskPlan** Coordinates task plan generation with progress tracking: - Creates a unique operation ID for tracking this specific planning operation - Starts progress logging with "Workflow Planning" service and "Task Plan Generation" action - Initializes `currentUserLanguage` to empty string for workflow start - Delegates to `mode.generateTaskPlan()` for mode-specific planning logic - Updates progress at 30% (analyzing input) and 80% (creating plan) - Calls `mode.createTaskPlanMessage()` to persist the plan as a workflow message - Completes progress logging with success/failure status - Returns the generated TaskPlan or propagates exceptions **executeTask(taskStep, workflow, context, taskIndex?, totalTasks?) → TaskResult** Coordinates task execution with comprehensive progress tracking: - Creates operation ID combining workflow ID, task index, and timestamp - Checks workflow stop status before proceeding - Starts progress logging with "Workflow Execution" service and task context - Logs detailed task information including objective and mode - Updates progress to 20% when execution begins - Delegates to `mode.executeTask()` for mode-specific execution logic - Completes progress logging based on execution success/failure - Returns TaskResult with execution outcome, feedback, and created documents **generateActionItems(taskStep, workflow, previousResults?, enhancedContext?) → List[ActionItem]** Coordinates action generation for a task: - Checks workflow stop status before generating actions - Logs detailed information about the task and mode - Delegates to `mode.generateActionItems()` for mode-specific action planning - Returns list of ActionItem objects ready for execution - Propagates exceptions with detailed error logging **prepareTaskHandover(taskStep, taskActions, taskResult, workflow) → Dict** Prepares handover data for workflow coordination between tasks: - Checks workflow stop status before processing - Extracts review result information from taskResult (handles both TaskResult and ReviewResult objects) - Creates handover dictionary containing task ID, description, actions performed, review result, workflow ID, and timestamp - Returns structured handover data for use by subsequent tasks - Handles exceptions by returning error dictionary #### Workflow State Update Methods The WorkflowProcessor includes several methods for updating workflow state at key points in execution. These maintain consistency between in-memory objects and database persistence: **updateWorkflowAfterTaskPlanCreated(totalTasks)**: Sets totalTasks and resets current counters after task plan generation **updateWorkflowBeforeExecutingTask(taskNumber)**: Updates currentTask and resets action counters before task execution begins **updateWorkflowAfterActionPlanning(totalActions)**: Sets totalActions for the current task after actions are planned **updateWorkflowBeforeExecutingAction(actionNumber)**: Updates currentAction before individual action execution **setWorkflowTotals(totalTasks?, totalActions?)**: Updates total counts for progress tracking **resetWorkflowForNewSession()**: Resets all counters to zero for new workflow session --- ### Core Processing Components #### TaskPlanner **Location**: `modules/workflows/processing/core/taskPlanner.py` The TaskPlanner is responsible for analyzing user requests and generating structured, executable task plans. It transforms natural language requests into formal task structures with clear objectives, success criteria, and dependencies. **Key Responsibilities**: - **Intent Analysis**: Uses IntentAnalyzer to understand user goals, extract requirements, and identify constraints before planning - **AI-Powered Planning**: Leverages AI models to break down complex requests into discrete, manageable tasks - **Success Criteria Definition**: Defines measurable success criteria for each task to enable validation - **Dependency Management**: Identifies and tracks dependencies between tasks to ensure correct execution order - **Context Building**: Constructs TaskContext objects with available documents, connections, and previous results - **Prompt Generation**: Uses `generateTaskPlanningPrompt()` to build comprehensive prompts with placeholders for dynamic content **Main Method**: **generateTaskPlan(userInput, workflow) → TaskPlan** The core planning method that orchestrates the entire task planning process: - Checks workflow stop status before proceeding - Uses stored user prompt from `services.currentUserPrompt` (cleaned/normalized version) - Conditionally performs intent analysis (skipped for AUTOMATION mode which uses predefined plans) - For non-automation modes, invokes IntentAnalyzer to extract primary goals and cleaned objectives - Stores workflow intent in `workflow._workflowIntent` for reuse during task execution - Creates a minimal TaskStep for planning context (task planning itself is treated as a planning task) - Builds TaskContext with workflow information, empty previous results, and criteria progress tracking - Generates prompt bundle using `generateTaskPlanningPrompt()` with template and placeholders - Calls AI service with quality settings (`callAiPlanning`) for detailed task planning - Parses AI response to extract TaskPlan JSON structure - Validates task plan structure and creates TaskStep objects with full task details - Returns complete TaskPlan with multiple TaskStep objects ready for execution #### ActionExecutor **Location**: `modules/workflows/processing/core/actionExecutor.py` The ActionExecutor handles the execution of individual actions within tasks, managing method invocation, parameter resolution, document processing, and result handling. It serves as the bridge between abstract action plans and concrete method implementations. **Key Responsibilities**: - **Method Invocation**: Looks up and invokes methods from the global methods catalog - **Parameter Resolution**: Resolves document references, connection strings, and other complex parameters - **Document Conversion**: Converts ActionDocument objects to ChatDocument objects for persistence - **Result Extraction**: Extracts text results from action documents for feedback - **Error Handling**: Captures and logs action execution errors with detailed context - **Progress Logging**: Creates detailed logs of action execution for monitoring - **Message Creation**: Delegates message creation to MessageCreator for action results **Core Methods**: **executeAction(methodName, actionName, parameters) → ActionResult** Direct method execution interface: - Validates method exists in global methods catalog - Validates action exists within the specified method - Retrieves action's method callable from catalog - Invokes the action method with provided parameters - Returns ActionResult with success status, documents, and error information - Raises exceptions for unknown methods or actions **executeCompoundAction(compoundActionName, parameters) → ActionResult** Executes compound actions using "method.action" format: - Parses compound name to extract method and action components - Validates format contains exactly one dot separator - Delegates to `executeAction()` with parsed components - Enables cleaner action invocation with single identifier **executeSingleAction(action, workflow, taskStep, taskIndex?, actionIndex?, totalActions?) → ActionResult** Comprehensive single action execution with full workflow integration: - Checks workflow stop status before proceeding - Logs detailed action information including method, action name, and indices - Logs input parameters including document lists and connections - Creates enhanced parameters by copying action parameters and adding expected document formats - Checks workflow stop status again before actual execution - Calls `executeAction()` with method, action, and enhanced parameters - Extracts result label from action's `execResultLabel` field (managed by action handler, not method) - Processes success results by extracting text from all action documents - Sets action status to success and stores result text - Processes failure results by logging errors and storing error message - Creates workflow log entry for failures with detailed error information - Creates action completion message via `_createActionCompletionMessage()` - Returns ActionResult with original ActionDocument objects, success status, result label, and error message - Handles exceptions by setting action error status and returning failure ActionResult **_extractResultText(result) → str** Extracts human-readable text from ActionResult documents: - Returns empty string if result is unsuccessful or has no documents - Iterates through all ActionDocument objects in result - Extracts documentData attribute from each document if available - Joins all document results with separator lines ("---") - Provides consolidated text summary of action output **_createActionCompletionMessage(action, result, workflow, taskStep, taskIndex, actionIndex, totalActions)** Creates and persists action completion messages: - Converts ActionDocument objects to ChatDocument objects using generation service - Calls `services.generation.createDocumentsFromActionResult()` for conversion - Delegates to MessageCreator.createActionMessage() for message creation - Passes action, result, workflow, result label, created documents, task context, and indices - Handles exceptions with detailed error logging #### MessageCreator **Location**: `modules/workflows/processing/core/messageCreator.py` The MessageCreator handles the creation and persistence of all workflow messages. It ensures messages are properly formatted, labeled, associated with documents, and persisted to both database and in-memory workflow state. **Key Responsibilities**: - **Message Formatting**: Structures message data with role, content, status, and workflow context - **Document Association**: Links documents to messages with appropriate labels - **Label Generation**: Creates context-aware document labels (round/task/action prefixes) - **State Persistence**: Stores messages in database and updates in-memory workflow.messages list - **Sequence Management**: Assigns correct sequence numbers for message ordering **Message Types**: **Task Plan Messages**: Created after task planning completes. Contains structured task breakdown with objectives, success criteria, dependencies, and complexity estimates. Uses status="intermediate" and role="assistant". Labeled with "taskplan" document label. **Action Completion Messages**: Created after each action executes. Contains action results, created documents, success/failure status. Uses status="intermediate" and role="assistant". Labeled with context-specific labels like "round1_task2_action3_result". **Task Summary Messages**: Created after task completes. Contains task feedback, success status, summary of actions performed. Uses status="intermediate" and role="assistant". Labeled with task-specific labels. **First Messages**: Created at workflow start with user input. Uses status="first" and role="user". Contains user prompt and uploaded documents. Labeled with "round{n}_usercontext". **Last Messages**: Created at workflow completion/failure/stop. Uses status="last" and role="assistant". Contains final feedback or error information. #### WorkflowValidator **Location**: `modules/workflows/processing/core/validator.py` The WorkflowValidator validates workflow execution results against defined success criteria, enabling quality control and retry logic. It assesses whether task objectives have been met and provides structured feedback for improvement. **Key Responsibilities**: - **Criteria Validation**: Checks action results against task success criteria - **Quality Assessment**: Evaluates completeness and correctness of task output - **Gap Identification**: Identifies which criteria are met and which are unmet - **Feedback Generation**: Creates structured feedback for use in retry attempts - **Progress Tracking**: Maintains history of validation attempts across retries The validator is primarily used by ActionplanMode to determine if tasks need to be retried with improvements. --- ## Workflow Modes The workflows component supports three distinct execution modes, each implementing a different strategy for task execution. Modes are selected at workflow creation time via the `WorkflowModeEnum` parameter and determine how tasks are planned, actions are generated, and quality is ensured. ### BaseMode (Abstract) **Location**: `modules/workflows/processing/modes/modeBase.py` BaseMode serves as the abstract base class that defines the contract all concrete modes must implement. It provides shared infrastructure while enforcing mode-specific implementations of core operations. **Abstract Methods** (must be implemented): **executeTask(taskStep, workflow, context, taskIndex?, totalTasks?) → TaskResult**: Executes a complete task from start to finish using mode-specific logic. Receives task details, workflow state, execution context, and progress indices. Returns TaskResult with success status, feedback, and created documents. **generateActionItems(taskStep, workflow, previousResults?, enhancedContext?) → List[ActionItem]**: Generates actions for a task using mode-specific strategy. Receives task details, workflow state, and context including retry information. Returns list of ActionItem objects ready for execution. **Shared Methods** (provided by base class): **generateTaskPlan(userInput, workflow) → TaskPlan**: Common task planning logic that delegates to TaskPlanner. All modes share the same high-level task planning approach. **createTaskPlanMessage(taskPlan, workflow)**: Creates and persists the task plan message. Common across all modes to ensure consistent message format. **Shared Components** (injected by base class): All modes receive instances of core processing components in their `__init__` method: - **self.taskPlanner**: TaskPlanner instance for task plan generation - **self.actionExecutor**: ActionExecutor instance for action execution - **self.messageCreator**: MessageCreator instance for message creation and persistence - **self.validator**: WorkflowValidator instance for result validation These shared components enable code reuse while allowing modes to implement different execution strategies. ### ActionplanMode **Location**: `modules/workflows/processing/modes/modeActionplan.py` **Strategy**: Batch planning with quality review and intelligent retry ActionplanMode represents the traditional, comprehensive workflow execution strategy. It plans all actions upfront, executes them sequentially, and includes sophisticated quality review with adaptive retry mechanisms. This mode is ideal for complex workflows where upfront planning leads to more efficient execution and where quality control is critical. **Core Characteristics**: - **Batch Planning**: Generates complete action plan before any execution begins, enabling optimization and dependency resolution - **Quality Review**: Reviews results against success criteria after execution completes, providing structured feedback - **Intelligent Retry**: Retries failed tasks up to 3 times with cumulative improvements from previous attempts - **Adaptive Learning**: Learns from execution patterns to improve future action generation - **Criteria Tracking**: Maintains detailed progress tracking showing which criteria are met/unmet across attempts - **Best Use Cases**: Complex multi-step workflows, data processing pipelines, document analysis with specific requirements **Execution Flow Details**: **1. Task Intent Analysis** Before generating actions, analyzes the specific task intent to understand objectives and constraints: - Reuses workflow-level intent if available (stored during task planning) - Performs task-specific intent analysis if needed - Extracts task requirements, constraints, and expected outputs - Stores task intent for use in action generation and validation **2. Action Plan Generation** Creates comprehensive action plan for the entire task: - Builds TaskContext with available documents, connections, previous task results, and retry information - Generates action definition prompt using `generateActionDefinitionPrompt()` - Includes retry context if this is a retry attempt (improvements, failed actions, successful actions) - Calls AI with quality settings to generate detailed action plan JSON - Parses JSON to extract action definitions with method, action name, parameters, expected formats, and result labels - Creates ActionItem objects with execution details and status tracking - Logs action plan for debugging and monitoring **3. Sequential Action Execution** Executes each action in order, maintaining context and state: - Iterates through ActionItem list in sequence - Calls `ActionExecutor.executeSingleAction()` for each action - Collects ActionResult objects with success status and created documents - Accumulates previous action results for use by subsequent actions - Checks workflow stop status between actions - Continues even if individual actions fail (failure handling in review stage) **4. Result Review and Validation** Reviews task results against success criteria: - Calls `reviewTaskResults()` to validate outcomes - Generates review prompt using `generateResultReviewPrompt()` - Includes all action results, success criteria, and context - AI evaluates criteria satisfaction, identifies gaps, suggests improvements - Parses ReviewResult with met/unmet criteria, overall status, and improvement suggestions - Updates criteria progress tracking showing evolution across attempts **5. Retry Decision and Execution** Determines if retry is needed and executes with improvements: - Checks if all criteria are met (success) or max retries reached (failure) - If retry needed: extracts improvements from review, updates TaskContext with retry count and improvement suggestions, identifies failure patterns from unsuccessful actions, preserves successful actions to avoid repeating work, regenerates actions with enhanced context - Maximum 3 retry attempts to prevent infinite loops - Each retry includes cumulative learnings from all previous attempts **6. Task Completion** Returns final TaskResult with comprehensive information: - Success status based on criteria satisfaction - Detailed feedback summarizing what was accomplished - List of all created documents from successful actions - Task execution history for learning **Adaptive Components**: **IntentAnalyzer**: Analyzes both workflow-level and task-level intent to understand goals, requirements, constraints, and expected outcomes. Used at workflow start and before task execution. **ContentValidator**: Validates action results against expected quality and completeness. Checks format compliance, content completeness, constraint satisfaction, and quality thresholds. Integrated into result review process. **LearningEngine**: Basic learning from execution patterns. Identifies successful strategies, failure patterns, and common issues. Used to improve future action generation (currently basic implementation). **ProgressTracker**: Tracks criteria progress across retry attempts. Maintains met_criteria set, unmet_criteria set, and attempt_history list. Enables trend analysis and improvement measurement. **AdaptiveLearningEngine**: Advanced learning engine for quality improvement. Analyzes retry patterns, tracks quality scores, identifies improvement trends. Used by ContentValidator for enhanced validation. ### DynamicMode **Location**: `modules/workflows/processing/modes/modeDynamic.py` **Strategy**: Iterative, just-in-time action generation with adaptive planning DynamicMode implements an exploratory, iterative approach to workflow execution. Instead of planning all actions upfront, it generates one action at a time, executes it, evaluates the result, and uses that information to inform the next action. This mode is ideal for workflows where the path forward depends on intermediate results or where exploration is needed. **Core Characteristics**: - **Just-in-Time Planning**: Generates only the next action based on current state - **Result-Driven**: Each action's result directly influences the next action - **Adaptive Path**: Workflow path emerges organically based on findings - **Max Steps Control**: Workflow.maxSteps limits iterations (default 5 for dynamic mode) - **Exploration Focus**: Designed for research, analysis, and discovery tasks - **Best Use Cases**: Research workflows, exploratory data analysis, iterative problem solving, scenarios with uncertain paths **Execution Flow Details**: **1. Initialize Step Counter** Sets up iteration tracking: - Initializes currentStep to 1 - Retrieves maxSteps from workflow object (default 5) - Prepares for iterative execution loop **2. Iterative Action Loop** Repeatedly generates and executes single actions: - **Action Generation**: Generates single next action using current context, previous action results, and task objective - **Action Execution**: Executes action immediately via ActionExecutor - **Result Evaluation**: Evaluates if task objective is met based on action result - **Decision Point**: Continues if objective not met and under max steps, or completes if objective met or max steps reached - **Context Update**: Accumulates action results for next iteration **3. Action Generation Process** Creates single next action based on current state: - Builds context with accumulated previous action results - Generates prompt asking "What is the single best next action?" - Includes task objective, available documents/connections, previous results summary - Calls AI with balanced settings for quick decision making - Parses single ActionItem from AI response - Validates action has all required fields **4. Completion Evaluation** After each action, evaluates if task is complete: - Checks action result for completion indicators - Evaluates if success criteria are satisfied - Determines if objective has been achieved - Can terminate early if objective met (before max steps) **5. Max Steps Handling** Prevents infinite loops with step limit: - Increments step counter after each action - Checks against workflow.maxSteps - Terminates loop when limit reached even if objective not fully met - Returns TaskResult indicating partial completion if stopped at max steps **6. Task Completion** Returns TaskResult with iterative execution summary: - Success based on objective achievement, not step count - Feedback summarizing discovered information and actions taken - All documents created during iterative process - May indicate partial completion if max steps reached **Key Differences from ActionplanMode**: - No upfront complete action plan - No batch review of all actions - No retry mechanism (each action is one-shot) - Simpler, faster execution per iteration - More flexible, less structured ### AutomationMode **Location**: `modules/workflows/processing/modes/modeAutomation.py` **Strategy**: Predefined JSON-based deterministic execution AutomationMode executes predefined workflow scripts without AI-based planning. Users provide a complete task and action plan in JSON format as part of their input, and the mode executes it deterministically. This mode is ideal for repeated, scripted workflows where the exact sequence of operations is known and should be consistent. **Core Characteristics**: - **No AI Planning**: Skips task planning and action generation AI calls - **JSON Input**: Accepts predefined TaskPlan JSON in user input - **Deterministic**: Same input always produces same execution sequence - **Fast Execution**: No planning overhead, immediate execution - **Template-Based**: Can be used with saved workflow templates - **Best Use Cases**: Repeated workflows, automated jobs, batch processing, template execution **Execution Flow Details**: **1. JSON Plan Parsing** Extracts predefined plan from user input: - Expects user input to contain JSON with TaskPlan structure - Parses JSON to extract tasks array with task definitions - Each task contains objective, actions array, and success criteria - Each action contains method, action name, parameters - Validates JSON structure and required fields - Skips intent analysis completely **2. Direct Task Execution** Executes predefined actions without generation: - Uses predefined action list from JSON - No call to AI for action generation - Validates action structure (method, action, parameters) - Creates ActionItem objects from JSON action definitions - Passes to ActionExecutor for execution **3. Sequential Execution** Executes actions in order specified in JSON: - Maintains order from JSON definition - No adaptive changes to sequence - No retry logic (executes once as defined) - Collects results for feedback **4. Result Collection** Gathers results without review: - No AI-based result review - Simple success/failure based on action execution - No criteria validation (assumed valid if actions succeed) - Returns TaskResult with execution summary **Predefined Plan Structure**: The JSON plan follows this structure: - **TaskPlan**: tasks array containing TaskStep objects - **TaskStep**: objective, actions array, successCriteria array - **Action**: execMethod, execAction, execParameters dictionary, execResultLabel - **Parameters**: method-specific parameters including documentList, connections **Key Differences from Other Modes**: - No AI calls for planning or review - User provides complete execution plan - No adaptive behavior or learning - Fastest execution time - Requires workflow expertise from user --- ## Method System The method system provides an extensible, plugin-like framework for defining reusable actions that workflows can invoke. Methods encapsulate specific capabilities (AI processing, SharePoint access, email operations) and expose them through decorated action functions with automatic discovery and signature introspection. ### MethodBase **Location**: `modules/workflows/methods/methodBase.py` MethodBase is the abstract base class that all methods must inherit from. It provides the foundational infrastructure for action definition, discovery, parameter extraction, and result formatting. **Core Infrastructure**: **Initialization**: Methods are instantiated with a services object providing access to all system capabilities including workflow state, chat operations, AI services, and database interfaces. **Action Decorator**: The `@action` decorator marks methods as workflow-invocable actions. Decorated methods are automatically discovered during method registration and added to the global methods catalog. **Action Discovery**: The `actions` property dynamically inspects the method class to find all decorated actions, extract their signatures, and build action metadata including parameters, types, defaults, and descriptions. **Parameter Extraction**: The `_extractParameterDetails()` method parses action docstrings to extract parameter names, types, and descriptions, enabling rich documentation for AI prompt generation. **Signature Generation**: The `getActionSignature()` method creates formatted signatures for AI prompts, including parameter names, types, descriptions, and return type, enabling AI models to understand available actions. **Key Features**: **Automatic Discovery**: Actions are discovered via introspection at runtime, eliminating need for manual registration. Any async method decorated with `@action` is automatically available to workflows. **Docstring Parsing**: Extracts structured information from action docstrings including main description, parameter details (name, type, description), and usage examples. Supports standard Python docstring formats. **Signature Generation**: Creates human-readable and AI-friendly action signatures for use in planning prompts. Includes all parameter information and context. **Standardized Results**: All actions return ActionResult objects with consistent structure: success boolean, documents list (ActionDocument objects), error string (if failure). **File Naming**: Provides `_generateMeaningfulFileName()` helper for creating context-aware filenames with round/task/action information, ensuring organized document storage. **Services Access**: All methods have access to `self.services` providing workflow state, chat operations, AI calls, document management, and connection handling. **Action Method Requirements**: - Must be async (workflow execution is asynchronous) - Must accept `parameters: Dict[str, Any]` as first argument - Must return `ActionResult` with success, documents, and error fields - Should NOT set `resultLabel` in ActionResult (managed by action handler) - Should include comprehensive docstring with parameter descriptions - Should handle exceptions and return ActionResult with success=False ### Built-in Methods #### MethodAi **Location**: `modules/workflows/methods/methodAi.py` Provides AI-powered operations for text processing, document analysis, content generation, and intelligent data transformation. This method wraps AI service capabilities with workflow-friendly interfaces. **Core Actions**: **process**: General-purpose AI processing action for text transformation, analysis, and generation. Accepts AI prompt, optional document list for context, and processing parameters. Returns ActionDocument with AI-generated results. Highly flexible for various AI tasks. **analyze**: Specialized document analysis action for extracting insights, summarizing content, and identifying key information. Processes multiple documents, applies analysis template, returns structured analysis results. **generate**: Content generation action for creating new documents based on templates, requirements, or examples. Supports various output formats (text, markdown, JSON, HTML). Returns generated content as ActionDocument. **Key Characteristics**: Leverages AI service for model selection and execution. Supports placeholder-based prompts with dynamic content injection. Handles context document integration. Creates meaningful filenames with workflow context. Manages AI response parsing and formatting. #### MethodSharepoint **Location**: `modules/workflows/methods/methodSharepoint.py` Provides integration with Microsoft SharePoint for document management, search, and collaboration. Enables workflows to interact with SharePoint sites, libraries, and documents using user connections. **Core Actions**: **search**: Searches SharePoint sites for documents, folders, or list items matching query criteria. Accepts connection reference, search query, site URL, and optional filters. Returns ActionDocument objects with search results and metadata. **download**: Downloads documents from SharePoint to workflow document storage. Accepts connection reference, document URL/ID, and optional destination. Creates ChatDocument for downloaded file enabling further processing. **upload**: Uploads documents to SharePoint library. Accepts connection reference, document reference, destination library/folder, and optional metadata. Returns confirmation ActionDocument. **Key Characteristics**: Requires user connection for authentication (connection reference in parameters). Uses token manager for OAuth token handling and refresh. Handles SharePoint API interactions via sharepoint service. Supports both SharePoint Online and On-Premises. Manages document format conversions and metadata. #### MethodOutlook **Location**: `modules/workflows/methods/methodOutlook.py` Provides integration with Microsoft Outlook for email operations, calendar management, and contact access. Enables workflows to send emails, search messages, and manage calendar events using user connections. **Core Actions**: **searchEmail**: Searches user's mailbox for emails matching criteria. Accepts connection reference, search query, folder filter, date range. Returns ActionDocument with email list including subject, sender, date, preview. **sendEmail**: Sends email message via user's Outlook account. Accepts connection reference, recipients (to/cc/bcc), subject, body (text/HTML), optional attachments. Returns confirmation ActionDocument. **getCalendarEvents**: Retrieves calendar events for specified time range. Accepts connection reference, start date, end date, calendar name (optional). Returns ActionDocument with event list including title, time, location, attendees. **Key Characteristics**: Requires user connection for Microsoft Graph API access. Handles OAuth authentication and token refresh automatically. Supports rich email formatting (HTML, attachments). Manages calendar timezone conversions. Provides email search with Outlook query syntax. ### Method Discovery **Location**: `modules/workflows/processing/shared/methodDiscovery.py` The method discovery system automatically finds, instantiates, and registers all method classes at workflow startup, building a global methods catalog that action executors use to invoke actions. **Discovery Process**: **1. Package Scanning**: Imports the `modules.workflows.methods` package and uses `pkgutil.iter_modules()` to find all modules in the directory. Filters for modules starting with "method" to identify method implementation files. **2. Class Detection**: For each module, inspects all classes using `inspect.getmembers()`. Identifies classes that inherit from MethodBase (excluding MethodBase itself). These are valid method implementations. **3. Instance Creation**: Instantiates each discovered method class with the current services object. This gives methods access to workflow state and system capabilities. **4. Action Discovery**: Calls the method's `actions` property which introspects the class for `@action` decorated methods. Extracts action metadata including description, parameters, types, and callable reference. **5. Catalog Building**: Stores method information in global `methods` dictionary with two keys: full class name (e.g., "MethodAi") and short name (e.g., "ai"). Enables flexible method lookup during action execution. **6. Services Update**: If method already exists in catalog (cached from previous discovery), updates its services reference to use current workflow. Critical for ensuring methods use correct workflow context when new workflows start. **Global Methods Catalog Structure**: The catalog is a dictionary mapping method names to method information: - **Key**: Method name (both full "MethodAi" and short "ai" forms) - **Value**: Method info dict with instance (method object), actions (action metadata dict), description (method description) - **Action Metadata**: Each action has description, parameters (dict of param info), and method (callable function reference) - **Parameter Info**: Each parameter has type, required boolean, description, and default value **Critical Services Update Mechanism**: When `discoverMethods()` is called with a new services object: - Checks if method already exists in catalog (from previous discovery) - If exists, updates `instance.services` reference to new services object - Ensures cached method instances use current workflow, not stale workflow from previous request - Prevents workflow ID mismatches and cross-workflow contamination - Called at workflow start in WorkflowManager.workflowStart() **Helper Functions**: **getMethodsList(serviceCenter)**: Returns formatted list of all methods with action signatures. Used for documentation and debugging. **getActionParameterList(methodName, actionName, methods)**: Extracts parameter descriptions for specific action. Used in prompt generation to provide AI with parameter details. --- ## Connection to ServiceChat The workflows component integrates with `serviceChat` through a clean separation of concerns. ### Integration Architecture ```mermaid flowchart TD A["Feature Layer
mainChatPlayground.chatStart()

1. Creates Services object (getServices)
2. Instantiates WorkflowManager(services)
3. Calls workflowManager.workflowStart()"] B["Services Object (Service Center)

• services.chat → ChatService
• services.ai → AiService
• services.workflow → Current ChatWorkflow object
• services.user → Current User

Provides unified access to all system capabilities"] C["WorkflowManager

Uses services.chat for:
• createWorkflow() - Create workflow record
• updateWorkflow() - Update workflow state
• storeMessageWithDocuments() - Store messages
• storeLog() - Log workflow events
• getFileInfo() - Access file metadata
• getChatDocumentsFromDocumentList() - Resolve docs

Stores workflow in services.workflow for access by:
• All methods (via self.services.workflow)
• All processing components
• AI service (for context)"] A --> B B --> C ``` ### ChatService Integration Points The workflows component relies heavily on ChatService for data persistence, state management, and document operations. All interaction happens through the `services.chat` interface, ensuring clean separation between workflow logic and data access. #### Workflow Management **createWorkflow(workflowData) → ChatWorkflow**: Creates new workflow record in database with provided data dictionary containing name, status, timestamps, round/task/action counters, mandateId, and workflowMode. Returns complete ChatWorkflow object with generated ID and full state. Called at workflow start in WorkflowManager. **updateWorkflow(workflowId, updateData)**: Updates existing workflow record with partial data. Accepts dictionary with any workflow fields (status, timestamps, counters). Performs partial update without affecting unchanged fields. Used throughout execution to update progress and status. **getWorkflow(workflowId) → ChatWorkflow**: Retrieves complete workflow object from database including all messages, logs, and stats. Returns fully hydrated ChatWorkflow with relationships loaded. Used when continuing existing workflows. #### Message Management **storeMessageWithDocuments(workflow, messageData, documents) → ChatMessage**: Creates message and associates documents in single transaction. Message data includes role (user/assistant), message text, status (first/intermediate/last), sequence number, timestamps, and workflow context (round/task/action). Documents list contains ChatDocument objects to link. Returns created ChatMessage object. Automatically updates workflow.messages list in memory for consistency. **updateMessage(messageId, messageData)**: Updates existing message with partial data. Used to modify message text, status, or other fields after creation. Rare operation - most messages are immutable after creation. #### Document Management **getChatDocumentsFromDocumentList(documentList) → List[ChatDocument]**: Resolves document references to actual ChatDocument objects. Accepts list of references in three formats: `docItem:id:filename` (individual document), `docList:label` (all documents with label), `docList:messageId:label` (specific message's documents). Returns list of resolved ChatDocument objects with file info. Critical for action parameter resolution. **getAvailableDocuments(workflow) → str**: Generates formatted string describing all documents available to workflow. Groups documents by current round vs past rounds. Returns text suitable for AI prompts showing what documents are accessible. Used in action planning prompts. **getFileInfo(fileId) → Dict**: Retrieves file metadata from component storage. Returns dictionary with fileName, size, mimeType, fileHash, and creationDate. Does not load actual file content. Used for document attribute resolution. **getFileData(fileId) → bytes**: Loads actual file content from component storage. Returns raw bytes. Used when actions need to process document content. #### Logging and Progress **storeLog(workflow, logData) → ChatLog**: Creates workflow log entry in database and adds to workflow.logs list. Log data includes message (text), type (info/warning/error/success), status (current workflow status), and progress (0-100 or -1 for errors). Provides detailed execution audit trail. Returns created ChatLog object. **progressLogStart(operationId, serviceName, actionName, context)**: Starts progress tracking for long-running operation. Creates ProgressLogger instance with unique operation ID. Records operation start time and context. Enables real-time progress monitoring. **progressLogUpdate(operationId, progress, statusUpdate)**: Updates progress for ongoing operation. Progress is 0-100 percentage. Status update provides text description of current step. Creates log entries for significant progress milestones. **progressLogFinish(operationId, success)**: Completes progress tracking for operation. Records end time, final status (success/failure), and duration. Cleans up progress tracking state. #### Connection Management **getConnectionReferenceList() → List[str]**: Returns list of all user connections formatted as reference strings. Format is `connection:authority:username [status:..., token:...]`. Includes connection state information (status, token expiration). Used in action planning to show available connections. **getUserConnectionFromConnectionReference(connectionReference) → UserConnection**: Parses connection reference string and retrieves UserConnection object. Handles reference format parsing, strips state information, looks up connection by authority and username. Returns None if not found. **getFreshConnectionToken(connectionId)**: Retrieves current token for connection, refreshing if expired. Uses TokenManager to handle OAuth token refresh. Returns valid token ready for API calls. Critical for method actions requiring authentication. ### State Flow 1. **Workflow Initialization**: - Feature layer creates `Services` object with user - `WorkflowManager` creates or retrieves `ChatWorkflow` - Workflow stored in `services.workflow` - Method instances updated via `discoverMethods(services)` 2. **During Execution**: - All components access workflow via `self.services.workflow` - Workflow state updated in database and memory simultaneously - Messages and logs stored via `services.chat` - Documents created and referenced via `services.generation` 3. **Method Access**: - Methods receive `services` in constructor - Access current workflow via `self.services.workflow` - Use `services.chat` for document operations - Use `services.ai` for AI operations ### Workflow Context Management Workflow context tracks the current position within the workflow execution hierarchy, enabling proper document labeling, progress tracking, and message routing. Context consists of three counters maintained on the workflow object itself. **Context Structure**: - **currentRound**: Which user interaction round (incremented each time user sends new input to existing workflow) - **currentTask**: Which task in current task plan (incremented as tasks execute sequentially) - **currentAction**: Which action within current task (incremented as actions execute) **setWorkflowContext(roundNumber?, taskNumber?, actionNumber?)**: Updates one or more context counters on workflow object. Updates both in-memory workflow and database record for consistency. Optional parameters allow updating only specific counters. Used by WorkflowProcessor to track execution progress. **getWorkflowContext() → Dict**: Returns dictionary with current round, task, and action numbers. Provides snapshot of current execution position. Used when generating document labels and meaningful filenames. **Context Applications**: **Document Labeling**: Creates hierarchical labels like `round1_task2_action3_result` that encode workflow position. Enables organized document storage and retrieval. Labels persist in message.documentsLabel field. **Progress Tracking**: Context counters combined with totalTasks and totalActions enable progress percentage calculation. UI can show "Task 2 of 5, Action 3 of 8" with precise progress bars. **Message Routing**: Messages tagged with round/task/action numbers enable filtering and organization. Frontend can group messages by task or display only current round. **Logging Context**: Log entries include context information showing exactly where in workflow execution log was created. Critical for debugging complex workflows. --- ## State Management ### Workflow State Lifecycle ```mermaid stateDiagram-v2 [*] --> NEW NEW --> RUNNING RUNNING --> COMPLETED RUNNING --> STOPPED RUNNING --> FAILED COMPLETED --> [*] STOPPED --> [*] FAILED --> [*] ``` **States**: - `NEW`: Workflow created but not started - `RUNNING`: Workflow actively processing - `COMPLETED`: Workflow finished successfully - `STOPPED`: Workflow stopped by user - `FAILED`: Workflow encountered unrecoverable error ### State Synchronization The workflow component maintains state in two places: 1. **In-Memory** (`services.workflow`): Fast access during execution 2. **Database**: Persistent storage via `interfaceDbChat` **Synchronization Strategy**: All workflow state updates follow a consistent two-step pattern: first update the in-memory workflow object for immediate access by running operations, then persist the change to database via `services.chat.updateWorkflow()`. This ensures consistency between memory and persistence while maintaining fast access during execution. For example, when completing a workflow, the status field is set to "completed" on the workflow object, then the same change is written to database with timestamp, ensuring both representations match. ### State Tools **Location**: `modules/workflows/processing/shared/stateTools.py` Utilities for managing workflow state. #### checkWorkflowStopped() This utility function provides the primary mechanism for responsive workflow stopping. It checks if the current workflow's status has been set to "stopped" (by user request via workflowStop API call) and raises WorkflowStoppedException if so. This exception is caught at workflow boundaries to enable graceful shutdown without abrupt termination. **Strategic Placement**: The function is called at all major workflow checkpoints to ensure responsive stop behavior: before task planning (prevents starting new plan), before task execution (stops between tasks), before action execution (stops between actions), before AI calls (prevents expensive operations), and before result processing (avoids unnecessary work). **Graceful Shutdown Effect**: When the exception is raised and caught, workflow can perform cleanup operations, persist current state, create stop message, and update status consistently. This is far superior to forceful termination which could leave inconsistent state or lose work. ### Progress Tracking #### Workflow Progress Fields The workflow object maintains several progress-related fields that enable precise progress tracking and reporting: **totalTasks**: Set after task planning completes. Represents the number of tasks in the current task plan. Remains constant during task execution. **currentTask**: Incremented before each task execution begins. Ranges from 0 (no tasks started) to totalTasks (all complete). Provides task-level progress indication. **totalActions**: Set after action planning for current task. Represents number of actions in the current task's action plan. Changes with each task. **currentAction**: Incremented before each action execution. Ranges from 0 to totalActions. Provides fine-grained progress within current task. **currentRound**: Incremented each time user sends new input to existing workflow. Distinguishes between different conversation rounds. #### Progress Calculation Progress can be calculated at multiple granularities: **Task-Level Progress**: Simple ratio of currentTask to totalTasks. Shows how many tasks have been completed out of total. Provides coarse-grained progress (e.g., "Task 2 of 5" = 40%). **Action-Level Progress**: Ratio of currentAction to totalActions within current task. Shows fine-grained progress within the current task (e.g., "Action 3 of 8" = 37.5% of current task). **Overall Progress**: Combines task and action progress for comprehensive view. Formula: ((currentTask - 1) / totalTasks) gives completed tasks progress, plus (currentAction / totalActions / totalTasks) for current task's partial progress. Provides smooth progress bar from 0% to 100% across entire workflow. ### Document State Documents are tracked throughout workflow execution with state preserved in: 1. **Document References**: Stable identifiers - `docItem:id:filename` - Individual document - `docList:label` - Group of documents - `docList:messageId:label` - Specific message's documents 2. **Document Labels**: Context-aware naming - `round{n}_usercontext` - User-provided context - `round{n}_task{t}_action{a}_{purpose}` - Action results 3. **Message Association**: Documents linked to messages - Messages have `documentsLabel` field - Documents have `messageId` field - Enables document resolution and routing --- ## Processing Pipeline ### Complete Workflow Pipeline ```mermaid flowchart TD A["1. User Request"] B["2. workflowStart()
• Create/retrieve workflow
• Update method instances
• Launch async processing"] C["3. _sendFirstMessage()
• Analyze user intent
• Extract context documents
• Create first message"] D["4. _planTasks()
• Call WorkflowProcessor.generateTaskPlan()
• Mode delegates to TaskPlanner
• AI generates structured task plan
• Create task plan message"] E["5. _executeTasks()
For each task:
a. Build TaskContext
b. Call WorkflowProcessor.executeTask()
c. Mode executes task (mode-specific logic)
d. Prepare task handover
e. Pass results to next task"] F["6. _processWorkflowResults()
• Generate workflow feedback
• Create completion message
• Update workflow status"] G["7. Workflow Complete"] A --> B B --> C C --> D D --> E E --> F F --> G ``` ### Task Execution (Actionplan Mode) ```mermaid flowchart TD A["1. executeTask()"] B["2. generateActionItems()
• Build action context
• Call AI to generate actions
• Parse action plan JSON
• Create ActionItem objects"] C["3. For each action:
a. executeSingleAction()
• Call ActionExecutor
• Execute via method system
• Convert results to documents
b. createActionCompletionMessage()
• Create message with documents
• Log action completion"] D["4. reviewTaskResults()
• Validate against success criteria
• Check if criteria met
• Determine if retry needed"] E{"Retry needed?"} F["5. Extract improvements
• Update retry context
• Increment retry count"] G["6. Return TaskResult
• Success/failure status
• Feedback summary
• Documents created"] A --> B B --> C C --> D D --> E E -->|Yes & < 3 attempts| F F --> B E -->|No or max retries| G ``` ### Action Execution Flow ```mermaid flowchart TD A["1. ActionExecutor.executeSingleAction()"] B["2. Resolve Parameters
• Convert document references to objects
• Get user connections
• Prepare action parameters"] C["3. Execute Method Action
• Look up method in catalog
• Call action method
• Receive ActionResult"] D["4. Process Result
• Extract result text
• Convert ActionDocuments to ChatDocuments
• Store documents in database"] E["5. Create Completion Message
• Create message with documents
• Set document label
• Link to workflow context"] F["6. Return ActionResult
• Success/failure status
• Documents created
• Result label for routing"] A --> B B --> C C --> D D --> E E --> F ``` ### Document Flow ```mermaid flowchart TD A["1. User Upload
• Files uploaded via API
• Stored in component database
• Referenced by fileId"] B["2. Context Extraction
• Large content extracted from prompt
• Stored as separate documents
• Labeled as usercontext"] C["3. Action Processing
• Actions receive document references
• Resolve to actual documents
• Process content"] D["4. Result Generation
• Actions create result documents
• Labeled with context (round/task/action)
• Stored in database"] E["5. Document Routing
• Results available to next actions
• Referenced by label or docItem
• Used in subsequent processing"] A --> B B --> C C --> D D --> E ``` --- ## Adaptive Learning ### Overview The workflows component includes adaptive learning capabilities that improve execution quality over time. ### Components #### IntentAnalyzer **Location**: `modules/workflows/processing/adaptive/intentAnalyzer.py` Analyzes user and task intent to understand goals and requirements. **Capabilities**: - Extract primary goals - Identify constraints - Detect implicit requirements - Understand context #### ContentValidator **Location**: `modules/workflows/processing/adaptive/contentValidator.py` Validates action results against expected quality and completeness. **Validation Aspects**: - Content completeness - Quality assessment - Format validation - Constraint satisfaction #### LearningEngine **Location**: `modules/workflows/processing/adaptive/learningEngine.py` Learns from execution patterns to improve future performance. **Learning Mechanisms**: - Pattern recognition - Success/failure analysis - Strategy adaptation - Parameter optimization #### ProgressTracker **Location**: `modules/workflows/processing/adaptive/progressTracker.py` Tracks progress toward success criteria across attempts. **Tracking**: - Met criteria - Unmet criteria - Attempt history - Quality trends ### Adaptive Workflow (Actionplan Mode) ``` 1. Analyze Intent • Understand user goal • Extract requirements • Identify constraints ↓ 2. Generate Actions • Create action plan • Include validation points ↓ 3. Execute Actions • Run each action • Collect results ↓ 4. Validate Results • Check against criteria • Assess quality • Identify gaps ↓ 5. Learn & Adapt • If incomplete: Extract improvements • Update context with learnings • Retry with improvements ↓ 6. Success or Max Retries • Return result • Update learning model ``` ---