Ida Dittrich f12ac49d32 finished pagination feature with filter and search options

2025-11-27 13:18:07 +01:00

66 KiB

Raw Blame History

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

flowchart TD
    A["API Layer (Routes)<br/>routeChatPlayground, routeWorkflows"]
    B["Feature Layer<br/>mainChatPlayground<br/>(chatStart, chatStop)"]
    C["WorkflowManager<br/>• workflowStart()<br/>• workflowStop()<br/>• _workflowProcess() (main pipeline)"]
    D["WorkflowProcessor (Delegation)<br/>Delegates to mode-specific implementations"]
    E["Actionplan<br/>Mode"]
    F["Dynamic<br/>Mode"]
    G["Automation<br/>Mode"]
    H["Core Components<br/>• TaskPlanner<br/>• ActionExecutor<br/>• MessageCreator<br/>• WorkflowValidator"]
    I["Method System<br/>• methodAi<br/>• methodSharepoint<br/>• methodOutlook<br/>(Extensible)"]
    
    A --> B
    B --> C
    C --> D
    D --> E
    D --> F
    D --> G
    E --> H
    F --> H
    G --> H
    H --> I

Design Principles

Separation of Concerns: Clear boundaries between orchestration, planning, execution, and methods
Mode-Based Strategy Pattern: Different execution strategies for different use cases
Dependency Injection: Services object provides access to all system capabilities
Extensibility: Easy to add new methods and actions without modifying core logic
Asynchronous Processing: Non-blocking workflow execution with background task processing
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

flowchart TD
    A["Feature Layer<br/>mainChatPlayground.chatStart()<br/><br/>1. Creates Services object (getServices)<br/>2. Instantiates WorkflowManager(services)<br/>3. Calls workflowManager.workflowStart()"]
    B["Services Object (Service Center)<br/><br/>• services.chat → ChatService<br/>• services.ai → AiService<br/>• services.workflow → Current ChatWorkflow object<br/>• services.user → Current User<br/><br/>Provides unified access to all system capabilities"]
    C["WorkflowManager<br/><br/>Uses services.chat for:<br/>• createWorkflow() - Create workflow record<br/>• updateWorkflow() - Update workflow state<br/>• storeMessageWithDocuments() - Store messages<br/>• storeLog() - Log workflow events<br/>• getFileInfo() - Access file metadata<br/>• getChatDocumentsFromDocumentList() - Resolve docs<br/><br/>Stores workflow in services.workflow for access by:<br/>• All methods (via self.services.workflow)<br/>• All processing components<br/>• 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

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)
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
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

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:

In-Memory (services.workflow): Fast access during execution
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:

Document References: Stable identifiers
- docItem:id:filename - Individual document
- docList:label - Group of documents
- docList:messageId:label - Specific message's documents
Document Labels: Context-aware naming
- round{n}_usercontext - User-provided context
- round{n}_task{t}_action{a}_{purpose} - Action results
Message Association: Documents linked to messages
- Messages have documentsLabel field
- Documents have messageId field
- Enables document resolution and routing

Processing Pipeline

Complete Workflow Pipeline

flowchart TD
    A["1. User Request"]
    B["2. workflowStart()<br/>• Create/retrieve workflow<br/>• Update method instances<br/>• Launch async processing"]
    C["3. _sendFirstMessage()<br/>• Analyze user intent<br/>• Extract context documents<br/>• Create first message"]
    D["4. _planTasks()<br/>• Call WorkflowProcessor.generateTaskPlan()<br/>• Mode delegates to TaskPlanner<br/>• AI generates structured task plan<br/>• Create task plan message"]
    E["5. _executeTasks()<br/>For each task:<br/>a. Build TaskContext<br/>b. Call WorkflowProcessor.executeTask()<br/>c. Mode executes task (mode-specific logic)<br/>d. Prepare task handover<br/>e. Pass results to next task"]
    F["6. _processWorkflowResults()<br/>• Generate workflow feedback<br/>• Create completion message<br/>• Update workflow status"]
    G["7. Workflow Complete"]
    
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G

Task Execution (Actionplan Mode)

flowchart TD
    A["1. executeTask()"]
    B["2. generateActionItems()<br/>• Build action context<br/>• Call AI to generate actions<br/>• Parse action plan JSON<br/>• Create ActionItem objects"]
    C["3. For each action:<br/>a. executeSingleAction()<br/>   • Call ActionExecutor<br/>   • Execute via method system<br/>   • Convert results to documents<br/>b. createActionCompletionMessage()<br/>   • Create message with documents<br/>   • Log action completion"]
    D["4. reviewTaskResults()<br/>• Validate against success criteria<br/>• Check if criteria met<br/>• Determine if retry needed"]
    E{"Retry needed?"}
    F["5. Extract improvements<br/>• Update retry context<br/>• Increment retry count"]
    G["6. Return TaskResult<br/>• Success/failure status<br/>• Feedback summary<br/>• 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

flowchart TD
    A["1. ActionExecutor.executeSingleAction()"]
    B["2. Resolve Parameters<br/>• Convert document references to objects<br/>• Get user connections<br/>• Prepare action parameters"]
    C["3. Execute Method Action<br/>• Look up method in catalog<br/>• Call action method<br/>• Receive ActionResult"]
    D["4. Process Result<br/>• Extract result text<br/>• Convert ActionDocuments to ChatDocuments<br/>• Store documents in database"]
    E["5. Create Completion Message<br/>• Create message with documents<br/>• Set document label<br/>• Link to workflow context"]
    F["6. Return ActionResult<br/>• Success/failure status<br/>• Documents created<br/>• Result label for routing"]
    
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F

Document Flow

flowchart TD
    A["1. User Upload<br/>• Files uploaded via API<br/>• Stored in component database<br/>• Referenced by fileId"]
    B["2. Context Extraction<br/>• Large content extracted from prompt<br/>• Stored as separate documents<br/>• Labeled as usercontext"]
    C["3. Action Processing<br/>• Actions receive document references<br/>• Resolve to actual documents<br/>• Process content"]
    D["4. Result Generation<br/>• Actions create result documents<br/>• Labeled with context (round/task/action)<br/>• Stored in database"]
    E["5. Document Routing<br/>• Results available to next actions<br/>• Referenced by label or docItem<br/>• 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

66 KiB Raw Blame History

Workflows Component Documentation

Overview

Key Responsibilities

Architecture

High-Level Design

Design Principles

Component Structure

Directory Organization

Core Components

WorkflowManager

Key Responsibilities

Initialization and Lifecycle

Pipeline Stages

Helper Methods

WorkflowProcessor

Key Responsibilities

Initialization and Mode Selection

Core Delegation Methods

Workflow State Update Methods

Core Processing Components

TaskPlanner

ActionExecutor

MessageCreator

WorkflowValidator

Workflow Modes

BaseMode (Abstract)

ActionplanMode

DynamicMode

AutomationMode

Method System

MethodBase

Built-in Methods

MethodAi

MethodSharepoint

MethodOutlook

Method Discovery

Connection to ServiceChat

Integration Architecture

ChatService Integration Points

Workflow Management

Message Management

Document Management

Logging and Progress

Connection Management

State Flow

Workflow Context Management

State Management

Workflow State Lifecycle

State Synchronization

State Tools

checkWorkflowStopped()

Progress Tracking

Workflow Progress Fields

Progress Calculation

Document State

Processing Pipeline

Complete Workflow Pipeline

Task Execution (Actionplan Mode)

Action Execution Flow

Document Flow

Adaptive Learning

Overview

Components

IntentAnalyzer

ContentValidator

LearningEngine

ProgressTracker

Adaptive Workflow (Actionplan Mode)

66 KiB

Raw Blame History