Machine Learning Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require baks-dev/machine-learning
   php bin/console baks:assets:install
   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

   • Verify PHP version (≥8.4) and baks-dev/core (≥7.4) compatibility.

2. First Use Case:

   • Predictive Model Training:

     use BaksDev\MachineLearning\Services\TrainingService;
     
     $service = app(TrainingService::class);
     $model = $service->trainFromData(
         'path/to/training_data.csv',
         'model_name',
         ['feature1', 'feature2'] // Features to train on
     );
     

   • Prediction:

     $prediction = $service->predict($model, ['feature1' => 1.2, 'feature2' => 3.4]);
     

3. Where to Look First:

   • Documentation: Check config/packages/baks_machine_learning.yaml for default settings.
   • Console Commands: Run php bin/console list baks to explore available commands (e.g., baks:ml:train, baks:ml:predict).
   • Examples: Review tests/Unit/MachineLearning for usage patterns.

Implementation Patterns

Core Workflows

1. Data Preparation:

   • Use DataPreprocessor to clean/normalize data before training:

     $preprocessor = app(DataPreprocessor::class);
     $cleanedData = $preprocessor->process($rawData, ['impute' => true, 'scale' => 'minmax']);
     

2. Model Training:

   • Batch Training:

     $service->trainFromData(
         'data.csv',
         'customer_churn_model',
         ['purchase_frequency', 'support_calls'],
         ['algorithm' => 'random_forest', 'epochs' => 100]
     );
     

   • Incremental Learning:

     $service->updateModel('existing_model', 'new_data.csv');
     

3. Prediction Integration:

   • API Endpoint:

     // In a Symfony Controller
     public function predict(Request $request, TrainingService $service)
     {
         $model = $service->loadModel('customer_churn_model');
         $input = $request->validate(['feature1' => 'required|numeric']);
         return response()->json($service->predict($model, $input));
     }
     

4. Model Management:

   • Save/Load Models:

     $service->saveModel($model, 'custom_path/models');
     $loadedModel = $service->loadModel('model_name', 'custom_path/models');
     

5. Event-Driven Workflows:

   • Subscribe to model training events:

     // In a Service Provider
     $this->bus->subscribe(
         ModelTrainedEvent::class,
         function (ModelTrainedEvent $event) {
             // Notify team, log, etc.
         }
     );
     

Integration Tips

• Queue Jobs for Training: Use Symfony Messenger to offload long-running training:

  $this->messageBus->dispatch(
      new TrainModelMessage('data.csv', 'model_name', ['feature1', 'feature2'])
  );
  

• Cache Predictions: Cache frequent predictions with Symfony Cache:

  $cache = $this->container->get('cache.app');
  $key = 'prediction:model_name:'.md5(json_encode($input));
  $prediction = $cache->get($key, function() use ($service, $model, $input) {
      return $service->predict($model, $input);
  });
  

• Monitor Models: Track model performance with Doctrine Events:

  $entityManager->getEventManager()->addEventListener(
      ModelSavedEvent::class,
      new ModelPerformanceLogger()
  );
  

Gotchas and Tips

Pitfalls

1. Data Schema Mismatches:

   • Ensure CSV/JSON input matches the expected feature schema. Use DataValidator to validate:

     $validator = app(DataValidator::class);
     $errors = $validator->validate($data, ['feature1', 'feature2']);
     

   • Fix: Re-run migrations if schema changes (php bin/console doctrine:migrations:execute).

2. Memory Limits:

   • Large datasets may hit PHP memory limits. Use chunked processing:

     $service->trainFromData('large_data.csv', 'model', [], ['chunk_size' => 1000]);
     

3. Model Serialization:

   • Custom model classes must implement Serializable. Override serialize()/unserialize() if needed.

4. Dependency Conflicts:

   • baks-dev/core (≥7.4) is required. Downgrade if conflicts arise:

     composer require baks-dev/core:^7.3
     

5. Russian Documentation:

   • Some docs/comments are in Russian. Use Google Translate or check src/Resources/config/ for YAML configs.

Debugging

• Training Logs: Enable verbose logging in config/packages/baks_machine_learning.yaml:

  debug: true
  logging: true
  

• Model Dump: Inspect model structure:

  $service->dumpModel('model_name', 'path/to/dump.json');
  

• Common Errors:
  • "Algorithm not found": Verify the algorithm name (e.g., random_forest, neural_net) matches src/Algorithms/ classes.
  • "Features mismatch": Use DataPreprocessor::getFeatureSchema() to debug.

Tips

1. Custom Algorithms: Extend AbstractAlgorithm to add new models:

   namespace App\MachineLearning;
   
   use BaksDev\MachineLearning\Algorithms\AbstractAlgorithm;
   
   class CustomAlgorithm extends AbstractAlgorithm {
       public function train(array $data): void { /* ... */ }
       public function predict(array $input): mixed { /* ... */ }
   }
   

   Register in config/packages/baks_machine_learning.yaml:

   algorithms:
       custom:
           class: App\MachineLearning\CustomAlgorithm
   

2. GPU Acceleration: Configure CUDA support (if available):

   # config/packages/baks_machine_learning.yaml
   gpu:
       enabled: true
       device_id: 0
   

3. Testing: Use the provided test group:

   php bin/phpunit --group=machine-learning --filter=testCustomAlgorithm
   

4. Performance Tuning:

   • Adjust config/packages/baks_machine_learning.yaml:

     training:
         batch_size: 512
         threads: 4
     

   • For neural networks, tune hyperparameters via the hyperparams option:

     $service->trainFromData(/* ... */, ['hyperparams' => ['learning_rate' => 0.001]]);
     

5. Backup Models: Automate model backups with a cron job:

   php bin/console baks:ml:backup --path=/backups/models --days=7