README

⚡ Complex AI Workflow Composition Engine

What This Does (No Bullshit)

Builds complex AI workflows that adapt, optimize, and handle dependencies automatically - way beyond basic ECA chains.

What Basic ECA Can't Handle:

Circular Dependencies: A→B→C→A loops that break normal workflow engines
Adaptive Execution: Workflows that change strategy based on data/performance
Complex Context: Sharing rich context between 20+ steps across hours/days
AI-Driven Optimization: Workflows that optimize themselves using AI analysis
Conditional Composition: Steps that appear/disappear based on AI decisions

What This Module Does:

🔄 Dependency Resolution: AI solves circular dependencies and complex graphs
⚡ Adaptive Execution: Switches between parallel/sequential/chunked strategies automatically
🧠 Workflow Intelligence: AI analyzes and optimizes workflow performance
🔗 Context Management: Sophisticated context sharing across long-running workflows
📊 Advanced Analytics: Deep insights into workflow bottlenecks and optimization

🏗️ Architecture Philosophy

This module follows the "Extend Native, Don't Replace" principle:

┌─────────────────────────────────────────────────────┐
│  AI Agentic Workflows (UNIQUE COMPOSITION ENGINE)  │
├─────────────────────────────────────────────────────┤
│  ┌─────────────────┐ ┌───────────────────────────┐   │
│  │ Workflow        │ │ Adaptive Execution        │   │
│  │ Intelligence    │ │ Strategies                │   │
│  └─────────────────┘ └───────────────────────────┘   │
│  ┌─────────────────┐ ┌───────────────────────────┐   │
│  │ Complex         │ │ Context Propagation       │   │
│  │ Dependencies    │ │ Management                │   │
│  └─────────────────┘ └───────────────────────────┘   │
├─────────────────────────────────────────────────────┤
│  Native Drupal AI + ECA Ecosystem (LEVERAGE THESE!) │
├─────────────────────────────────────────────────────┤
│  ┌─────────────┐ ┌─────────────┐ ┌───────────────┐   │
│  │     eca     │ │   ai_eca    │ │ ai_automators │   │
│  │             │ │             │ │               │   │
│  └─────────────┘ └─────────────┘ └───────────────┘   │
│  ┌─────────────┐ ┌─────────────┐ ┌───────────────┐   │
│  │ai_assistant │ │ ai_logging  │ │   ai_search   │   │
│  │    _api     │ │             │ │               │   │
│  └─────────────┘ └─────────────┘ └───────────────┘   │
└─────────────────────────────────────────────────────┘

🎯 Workflow Execution Strategies

1. Parallel Optimized Execution

Execute independent steps simultaneously:

$composer = \Drupal::service('ai_agentic_workflows.composer');

$workflow = [
  'name' => 'Content Processing Pipeline',
  'steps' => [
    'analyze_sentiment' => ['type' => 'ai_agent', /* config */],
    'extract_keywords' => ['type' => 'ai_automator', /* config */],
    'generate_summary' => ['type' => 'ai_agent', /* config */],
    'create_metadata' => ['type' => 'eca_action', /* config */],
  ],
];

$results = $composer->composeAgenticWorkflow($workflow, $context);

2. Adaptive Resolution Execution

Handle circular dependencies intelligently:

$workflow = [
  'name' => 'Content Review Cycle',
  'steps' => [
    'initial_review' => [
      'type' => 'ai_agent',
      'depends_on' => ['final_approval'], // Circular dependency!
    ],
    'content_revision' => [
      'type' => 'ai_automator', 
      'depends_on' => ['initial_review'],
    ],
    'final_approval' => [
      'type' => 'eca_action',
      'depends_on' => ['content_revision'],
    ],
  ],
];

// AI-driven resolution of circular dependencies
$results = $composer->composeAgenticWorkflow($workflow, $context);

3. Chunked Memory-Optimized Execution

Handle large workflows efficiently:

$large_workflow = [
  'name' => 'Mass Content Processing',
  'steps' => array_fill(0, 100, ['type' => 'ai_automator']), // 100 steps
];

// Automatically chunks into memory-optimal sizes
$results = $composer->composeAgenticWorkflow($large_workflow, $context);

4. Composite Step Execution

Complex multi-component steps:

$workflow = [
  'steps' => [
    'content_enhancement' => [
      'type' => 'composite',
      'composition_strategy' => 'conditional',
      'components' => [
        'spell_check' => ['type' => 'ai_automator'],
        'grammar_check' => ['type' => 'ai_agent'],
        'style_improvement' => ['type' => 'ai_agent'],
        'fact_verification' => ['type' => 'eca_action'],
      ],
      'conditions' => [
        'spell_check' => 'always',
        'grammar_check' => 'if_errors_found',
        'style_improvement' => 'if_content_type=blog',
        'fact_verification' => 'if_contains_claims',
      ],
    ],
  ],
];

🔧 Core Services

WorkflowComposer

Purpose: Compose and execute complex agentic workflows Native Dependencies: eca, ai_automators, ai_assistant_api

// Intelligent workflow composition with optimization
$composer->composeAgenticWorkflow($workflow_definition, $context);

WorkflowIntelligence

Purpose: AI-driven workflow analysis and optimization Native Dependencies: ai providers, ai_search for RAG

// Analyze workflow complexity and optimize
$intelligence->optimizeWorkflow($workflow);

AdaptiveExecutor

Purpose: Dynamic execution strategies based on complexity Native Dependencies: Native queue system, Redis cache

// Execute with best strategy for the scenario
$executor->executeWithOptimalStrategy($workflow, $context);

ContextManager

Purpose: Sophisticated context propagation between steps Native Dependencies: Native tempstore, serialization

// Manage complex context sharing
$context_manager->propagateContext($step_results, $next_steps);

WorkflowAnalytics

Purpose: Advanced workflow performance analysis Native Dependencies: ai_logging, native database

// Get deep insights into workflow performance
$analytics->analyzeWorkflowPerformance($workflow_id);

📦 Installation

Install native Drupal AI + ECA ecosystem first:

composer require drupal/ai drupal/ai_automators drupal/ai_assistant_api drupal/ai_eca drupal/eca

Enable required modules:

drush en ai ai_automators ai_assistant_api ai_eca eca eca_base eca_content eca_queue

Enable AI Agentic Workflows:
```
drush en ai_agentic_workflows
```

🧠 Workflow Intelligence Features

Automatic Optimization

The system analyzes workflows and applies optimizations:

Parallelization Detection: Identifies steps that can run in parallel
Resource Optimization: Allocates resources based on step requirements
Provider Selection: Chooses optimal AI providers for each step
Caching Strategy: Implements intelligent caching for repeated operations

Dependency Resolution

Advanced dependency handling:

Circular Dependency Detection: Identifies circular dependencies
AI-Driven Resolution: Uses AI to break circular dependencies intelligently
Dynamic Ordering: Optimizes execution order for best performance

Context Intelligence

Sophisticated context management:

Context Propagation: Shares relevant context between workflow steps
Memory Optimization: Manages context size for large workflows
Semantic Context: Uses AI to understand context relevance

🎼 Usage Examples

Content Creation Pipeline

$content_pipeline = [
  'name' => 'AI Content Creation Pipeline',
  'steps' => [
    // Research phase (parallel)
    'topic_research' => [
      'type' => 'ai_agent',
      'provider' => 'openai',
      'prompt' => 'Research trending topics in {category}',
    ],
    'competitor_analysis' => [
      'type' => 'ai_automator',
      'automator_id' => 'web_scraper',
      'parallel_with' => ['topic_research'],
    ],
    
    // Content creation phase (sequential)
    'outline_creation' => [
      'type' => 'ai_agent',
      'depends_on' => ['topic_research', 'competitor_analysis'],
      'provider' => 'anthropic',
    ],
    'content_writing' => [
      'type' => 'composite',
      'composition_strategy' => 'iterative',
      'components' => [
        'draft_creation' => ['type' => 'ai_agent'],
        'fact_checking' => ['type' => 'ai_automator'],
        'style_refinement' => ['type' => 'ai_agent'],
      ],
      'depends_on' => ['outline_creation'],
    ],
    
    // Publication phase (sequential with ECA)
    'content_review' => [
      'type' => 'eca_action',
      'action_id' => 'content_moderation',
      'depends_on' => ['content_writing'],
    ],
    'seo_optimization' => [
      'type' => 'ai_automator',
      'automator_id' => 'seo_optimizer',
      'depends_on' => ['content_review'],
    ],
    'publication' => [
      'type' => 'eca_action',
      'action_id' => 'publish_content',
      'depends_on' => ['seo_optimization'],
    ],
  ],
];

$results = $composer->composeAgenticWorkflow($content_pipeline, [
  'category' => 'technology',
  'target_audience' => 'developers',
]);

Multi-Language Content Localization

$localization_workflow = [
  'name' => 'Multi-Language Content Localization',
  'steps' => [
    'source_analysis' => [
      'type' => 'ai_agent',
      'task' => 'analyze_source_content',
    ],
    'translation_preparation' => [
      'type' => 'composite',
      'composition_strategy' => 'parallel',
      'components' => [
        'extract_translatable_strings' => ['type' => 'ai_automator'],
        'identify_cultural_references' => ['type' => 'ai_agent'],
        'create_translation_memory' => ['type' => 'eca_action'],
      ],
    ],
    'parallel_translation' => [
      'type' => 'composite', 
      'composition_strategy' => 'parallel',
      'components' => [
        'translate_to_spanish' => ['type' => 'ai_agent', 'provider' => 'deepl'],
        'translate_to_french' => ['type' => 'ai_agent', 'provider' => 'deepl'],
        'translate_to_german' => ['type' => 'ai_agent', 'provider' => 'deepl'],
        'translate_to_japanese' => ['type' => 'ai_agent', 'provider' => 'anthropic'],
      ],
    ],
    'quality_assurance' => [
      'type' => 'composite',
      'composition_strategy' => 'sequential',
      'components' => [
        'linguistic_review' => ['type' => 'ai_agent'],
        'cultural_adaptation' => ['type' => 'ai_agent'],
        'final_validation' => ['type' => 'eca_action'],
      ],
    ],
  ],
];

Customer Support Automation

$support_workflow = [
  'name' => 'Intelligent Customer Support',
  'steps' => [
    'ticket_classification' => [
      'type' => 'ai_agent',
      'provider' => 'openai',
      'model' => 'gpt-4',
    ],
    'solution_routing' => [
      'type' => 'composite',
      'composition_strategy' => 'conditional',
      'components' => [
        'auto_resolve_simple' => [
          'type' => 'ai_automator',
          'condition' => 'complexity_score < 3',
        ],
        'escalate_to_specialist' => [
          'type' => 'eca_action',
          'condition' => 'complexity_score >= 7',
        ],
        'ai_assisted_resolution' => [
          'type' => 'ai_agent',
          'condition' => 'complexity_score >= 3 AND complexity_score < 7',
        ],
      ],
    ],
    'follow_up_management' => [
      'type' => 'eca_action',
      'action_id' => 'schedule_follow_up',
    ],
  ],
];

📊 Workflow Analytics

Performance Metrics

$analytics = \Drupal::service('ai_agentic_workflows.analytics');

// Get comprehensive workflow analytics
$performance = $analytics->analyzeWorkflowPerformance($workflow_id);
/*
Returns:
[
  'execution_time' => 45.2,
  'step_performance' => [...],
  'bottlenecks' => ['content_writing' => 'high_latency'],
  'optimization_suggestions' => [...],
  'cost_breakdown' => [...],
  'success_rate' => 94.5,
]
*/

Optimization Recommendations

// Get AI-driven optimization recommendations
$recommendations = $analytics->getOptimizationRecommendations($workflow);
/*
Returns:
[
  'parallelization_opportunities' => [...],
  'provider_optimization' => [...],
  'caching_strategies' => [...],
  'cost_reduction_tips' => [...],
]
*/

🔌 Integration with Native Drupal

ECA Integration

Trigger complex agentic workflows from ECA:

# In ECA model configuration
events:
  - type: "entity_insert"
    bundle: "article"
actions:
  - type: "ai_agentic_workflow_execute"
    workflow_id: "content_enhancement_pipeline"
    context:
      entity: "[entity]"
      user: "[current_user]"

AI Automators Integration

Use automators as workflow steps:

'enhance_content' => [
  'type' => 'ai_automator',
  'automator_id' => 'content_enhancer',
  'configuration' => [...],
],

AI Assistant API Integration

Use assistants as workflow agents:

'content_reviewer' => [
  'type' => 'ai_agent',
  'agent_config' => [
    'assistant_id' => 'content_review_assistant',
    'provider' => 'openai',
  ],
],

🔍 API Examples

REST API

POST /api/ai-workflows/compose
{
  "workflow": {...},
  "context": {...},
  "execution_strategy": "parallel_optimized"
}

Drupal Services

$composer = \Drupal::service('ai_agentic_workflows.composer');
$intelligence = \Drupal::service('ai_agentic_workflows.intelligence');
$analytics = \Drupal::service('ai_agentic_workflows.analytics');

🧪 Testing

# Test workflow composition
phpunit tests/src/Unit/WorkflowComposerTest.php

# Test adaptive execution
phpunit tests/src/Kernel/AdaptiveExecutorTest.php

# Test workflow intelligence
phpunit tests/src/Functional/WorkflowIntelligenceTest.php

📈 Roadmap

Visual Workflow Builder: Drag-and-drop workflow composition UI
Workflow Templates: Pre-built templates for common scenarios
Advanced Analytics: ML-driven workflow optimization
Real-time Monitoring: Live workflow execution monitoring

🤝 Contributing

This module focuses on advanced workflow composition. Contributions should:

Extend native ECA/AI capabilities (don't duplicate)
Add workflow intelligence (optimization, analytics, adaptation)
Follow Drupal standards (coding standards, testing, documentation)

📄 License

GPL-2.0+

bluefly / ai_agentic_workflows

Maintainers

Details