Package com.acumenvelocity.ath.controller

Class AutoMlController

  • public class AutoMlController
extends Object
    REST Controller for handling AutoML custom model training operations. Provides endpoints for training custom translation models, checking training status, cancelling training jobs, and listing trained models.

    This controller manages the full lifecycle of AutoML training jobs:

    • Scanning GCS buckets for training files (TMX, TSV, CSV, TXT)
    • Creating AutoML datasets
    • Importing training data
    • Training custom models
    • Monitoring training progress

    All training operations are asynchronous and follow the same pattern as document import/export operations. Training job state is persisted in Solr (ath_automl_jobs core) for durability and multi-node coordination.

    Since:
    1.0
    Version:
    1.0
    Author:
    Acumen Velocity

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      io.swagger.oas.inflector.models.ResponseContext cancelTraining​(io.swagger.oas.inflector.models.RequestContext request, UUID trainingJobId)
      Cancels an in-progress AutoML training job.
      io.swagger.oas.inflector.models.ResponseContext getModels​(io.swagger.oas.inflector.models.RequestContext request, Integer page, Integer pageSize)
      Retrieves a paginated list of trained AutoML models.
      io.swagger.oas.inflector.models.ResponseContext getTrainingStatus​(io.swagger.oas.inflector.models.RequestContext request, UUID trainingJobId)
      Retrieves the current status of an AutoML training job.
      io.swagger.oas.inflector.models.ResponseContext trainModel​(io.swagger.oas.inflector.models.RequestContext request, com.fasterxml.jackson.databind.JsonNode bodyNode)
      Initiates an asynchronous AutoML model training job.

    • Constructor Detail

      • AutoMlController

        public AutoMlController​(AutoMlTrainingService trainingService)
        Constructor with dependency injection for the training service.
        Parameters:
        trainingService - the service handling AutoML training operations

      • AutoMlController

        public AutoMlController()
        Default constructor for Swagger Inflector. Initializes the training service with default configuration.

    • Method Detail

      • trainModel

        public io.swagger.oas.inflector.models.ResponseContext trainModel​(io.swagger.oas.inflector.models.RequestContext request,
                                                                  com.fasterxml.jackson.databind.JsonNode bodyNode)
        Initiates an asynchronous AutoML model training job.

        This endpoint:

        1. Validates the training request parameters
        2. Creates a training job record in Solr
        3. Initiates background processing
        4. Returns immediately with 202 Accepted

        Training Process:

        • SCANNING_BUCKETS: Recursively scanning GCS buckets for files
        • PREPARING_DATASET: Creating AutoML dataset resource
        • IMPORTING_DATA: Importing training files into dataset
        • TRAINING: Training the custom model (takes several hours)
        • COMPLETED: Model ready for use
        • FAILED: Training failed with error details

        File Format Support: Automatically detects and processes TMX, TSV, CSV, and TXT files.

        Data Validation:

        • Minimum segments: 1,000 (returns 400 Bad Request if less)
        • Maximum segments: 15,000,000 (returns 400 Bad Request if more)
        • Automatic 80/10/10 split for train/validation/test
        Parameters:
        request - the HTTP request context from Swagger Inflector
        trainingJobId - UUID for the training job (provided by client)
        modelName - display name for the trained model
        srcLang - source language ISO code (e.g., "en")
        trgLang - target language ISO code (e.g., "es")
        gcsBuckets - list of GCS bucket URIs to scan
        projectId - GCP project ID for AutoML resources
        location - GCP region for AutoML (e.g., "us-central1")
        userId - UUID of the user initiating training
        Returns:
        ResponseContext with 202 Accepted and status URL, or 400/409/500 on error

      • getTrainingStatus

        public io.swagger.oas.inflector.models.ResponseContext getTrainingStatus​(io.swagger.oas.inflector.models.RequestContext request,
                                                                         UUID trainingJobId)
        Retrieves the current status of an AutoML training job.

        Response Codes:

        • 202 Accepted: Training in progress
        • 200 OK: Training completed successfully
        • 500 Internal Server Error: Training failed
        • 404 Not Found: Training job not found

        Status Values:

        • SCANNING_BUCKETS: Scanning GCS buckets for training files
        • PREPARING_DATASET: Creating AutoML dataset
        • IMPORTING_DATA: Importing files to dataset
        • TRAINING: Training model (longest phase, typically hours)
        • COMPLETED: Training successful, model ready
        • FAILED: Training failed, see error details

        Polling Recommendations:

        • SCANNING_BUCKETS / PREPARING_DATASET: Poll every 5-10 seconds
        • IMPORTING_DATA: Poll every 30-60 seconds
        • TRAINING: Poll every 5-10 minutes (training takes hours)
        Parameters:
        request - the HTTP request context from Swagger Inflector
        trainingJobId - UUID of the training job
        Returns:
        ResponseContext with current status (202, 200, 404, or 500)

      • cancelTraining

        public io.swagger.oas.inflector.models.ResponseContext cancelTraining​(io.swagger.oas.inflector.models.RequestContext request,
                                                                      UUID trainingJobId)
        Cancels an in-progress AutoML training job.

        Cancellation Rules:

        • Can cancel: SCANNING_BUCKETS, PREPARING_DATASET, IMPORTING_DATA, TRAINING
        • Cannot cancel: COMPLETED, FAILED (returns 409 Conflict)
        • Only the user who initiated the job can cancel it (403 Forbidden otherwise)
        • Once cancelled, the job cannot be resumed
        • Any created AutoML resources (dataset) may remain and should be cleaned up separately

        Best Practices:

        • Check status before cancelling to avoid 409 errors
        • Consider cost implications of cancelling long-running training
        • Clean up any orphaned AutoML datasets if needed
        Parameters:
        request - the HTTP request context from Swagger Inflector
        trainingJobId - UUID of the training job to cancel
        Returns:
        ResponseContext with 204 No Content on success, 403/404/409/500 on error

      • getModels

        public io.swagger.oas.inflector.models.ResponseContext getModels​(io.swagger.oas.inflector.models.RequestContext request,
                                                                 Integer page,
                                                                 Integer pageSize)
        Retrieves a paginated list of trained AutoML models.

        Pagination Details:

        • Default page size: 10 items
        • Maximum page size: 100 items
        • Page numbers start from 1
        • Automatically adjusts invalid page numbers

        Returns all successfully trained models, sorted by creation date (newest first). Failed or cancelled training jobs are not included in the list.

        Parameters:
        request - the HTTP request context from Swagger Inflector
        page - the requested page number (1-based, optional)
        pageSize - the number of items per page (1-100, optional)
        Returns:
        ResponseContext containing paginated model list or error details