feat: comprehensive AI Sorting overhaul with entity-agnostic support and human-readable experiment names

[jjroelofs]

Summary

Fixes #10, Fixes #12, Fixes #13

This PR implements a comprehensive overhaul of AI Sorting, transforming it from a node-only module into a universal, entity-agnostic machine learning solution with proper cold start handling, human-readable experiment names, and production-ready code quality.

Problems Solved

• Cold start crashes (Cold start crash when no experiment data exists #10): Views crashed with "No scores for experiment" when no RL data existed
• Entity limitations (AI Sorting only works with nodes - need support for all entity types #12): Only worked with nodes, couldn't sort users, taxonomy terms, media, or custom entities
• JavaScript duplication (Consolidate duplicate JavaScript files and modernize tracking code #13): Separate files for turns and rewards tracking created maintenance overhead
• Code bloat: Unused services, decorators, and permissions cluttering the codebase
• Silent failures: Hard to debug issues due to fallback mechanisms

Changes Made

Universal Entity Support (#12)

• Entity-agnostic architecture: Now works with nodes, users, taxonomy terms, media, custom entities, and external data
• Dynamic base field detection: Uses view's base_field instead of hardcoded nid
• Enhanced Views integration: AI Sorting available for all entity types in Views UI
• Flexible entity detection: Handles _entity, _object, and field-based entity access patterns

Complete Cold Start Solution (#10)

• Proper multi-armed bandit approach: Passes all eligible arm IDs to RL module for centralized handling
• Eliminates duplicate logic: Removed local cold start code, relies on RL module's comprehensive solution
• Fail-hard debugging: Throws explicit errors instead of silent fallbacks to aid troubleshooting
• Seamless transition: Auto-switches to ML sorting as data grows

JavaScript Modernization (#13)

• Consolidated tracking: Merged ai-sorting-turns.js and ai-sorting-rewards.js into single ai-sorting-tracking.js
• Entity-agnostic variables: Changed from nids/nidUrlMap to entityIds/entityUrlMap
• Enhanced error handling: Explicit error messages and console warnings for debugging
• Improved performance: Reduced HTTP requests and browser processing overhead

Human-Readable Experiment Names Integration

• User-friendly reporting: Works with RL module's human-readable names (Reports show cryptic SHA1 hashes instead of human-readable experiment names rl#10)
• Automatic name generation: Uses view_id:display_id format for clear identification
• Integration with RL module: Leverages new experiment name storage in RL registry

Code Quality & Cleanup

• Removed redundant code: Deleted unused ExperimentResolver, TotalTrialsService, and AiSortingExperimentDecorator
• Simplified services: Streamlined to essential ExperimentRegistrationService only
• Removed unused permissions: Deleted ai_sorting.permissions.yml
• Documentation cleanup: Removed marketing docs, kept essential technical documentation
• Drupal coding standards: Full compliance with automated linting and fixing

Technical Implementation

Universal Entity Query

// Get all possible arm IDs from view results
$id_query = clone $this->query;
$id_query->clearFields();
$id_alias = $id_query->addField($this->tableAlias, $base_field);
$result = $id_query->execute();

// Pass all IDs to RL module for proper scoring
$scores = $this->experimentManager->getThompsonScores(
  $experiment_uuid,
  $time_window_seconds,
  $arm_ids  // Enables proper cold start handling
);

Fail-Hard Error Handling

if (empty($scores)) {
  throw new \RuntimeException(sprintf(
    'AI Sorting FAILED: No scores returned for experiment "%s". RL module must always return scores for requested arms.',
    $experiment_uuid
  ));
}

Entity-Agnostic Views Integration

foreach ($entity_types as $entity_type_id => $entity_type) {
  $table_name = $entity_type->getDataTable() ?: $entity_type->getBaseTable();
  if ($table_name && isset($data[$table_name])) {
    $data[$table_name]['ai_sorting'] = [
      'title' => t('AI Sorting'),
      'help' => t('Sort @entity_type using reinforcement learning algorithm.', [
        '@entity_type' => $entity_type->getLabel(),
      ]),
      'sort' => ['id' => 'ai_sorting'],
    ];
  }
}

Benefits

✅ Universal compatibility - Works with any Drupal entity type
✅ Proper cold start - New items get appropriate exploration scores
✅ User-friendly reporting - Readable experiment names in admin interface
✅ Reduced complexity - Single JavaScript file, streamlined codebase
✅ Better debugging - Clear error messages instead of silent failures
✅ Production ready - Clean code following Drupal standards
✅ Performance optimized - Consolidated assets, efficient database queries
✅ Future-proof architecture - Extensible design for new entity types

Use Cases Now Supported

• Blog Posts - Surface most engaging articles first
• User Directories - Highlight most valuable team members
• Product Catalogs - Showcase best-converting items
• Media Galleries - Promote most viewed images/videos
• Taxonomy Terms - Feature most relevant categories
• Custom Entities - Sort any content type with engagement data

Testing

✅ Verified with nodes, users, taxonomy terms, and media entities
✅ Cold start handling confirmed across all entity types
✅ Human-readable experiment names displaying correctly in reports
✅ JavaScript tracking working for both turns and rewards
✅ Drupal coding standards compliance verified
✅ No breaking changes for existing node-based experiments

Compatibility

• Drupal 10/11 compatible
• Backward compatible with existing node-based experiments
• No data migration required - existing experiments continue working
• Requires RL module v1.x with human-readable names support

Related Issues & PRs

• Cold start crash (Cold start crash when no experiment data exists #10): Comprehensive solution implemented
• Entity-agnostic support (AI Sorting only works with nodes - need support for all entity types #12): Full universal entity compatibility added
• JavaScript consolidation (Consolidate duplicate JavaScript files and modernize tracking code #13): Files merged and modernized
• Works with RL module enhancements: feat: comprehensive RL module overhaul with human-readable names, cold start fixes, and total turns correction rl#8 (symlink support, human-readable names)
• Enables RL human-readable reporting: Reports show cryptic SHA1 hashes instead of human-readable experiment names rl#10 (experiment names)
• Benefits from RL total turns fix: Total turns showing 0 in overview reports despite individual experiments having data rl#11 (reporting accuracy)

This comprehensive overhaul transforms AI Sorting from a limited node-only tool into a universal machine learning platform that works with any Drupal content while providing the production-ready code quality and user experience expected in modern Drupal modules.

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]