Amazon Neptune Model Training API

openapi: 3.2.0
info:
  title: Amazon Neptune Neptune ML Model Training API
  description: Neptune ML enables machine learning on graph data using graph neural networks. It provides APIs for data processing, model training, model transform, and inference endpoint management powered by Amazon SageMaker. The ML API endpoints are available on the Neptune DB instance HTTP endpoint under the /ml path prefix.
  version: '2024-01-01'
  contact:
    name: Amazon Web Services
    url: https://docs.aws.amazon.com/neptune/latest/userguide/machine-learning.html
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{cluster-endpoint}:8182
  description: Neptune ML REST endpoint
  variables:
    cluster-endpoint:
      default: your-cluster-endpoint.region.neptune.amazonaws.com
      description: The cluster endpoint DNS name for your Neptune DB cluster
security:
- aws_sigv4: []
tags:
- name: Model Training
  description: ML model training job operations
paths:
  /ml/modeltraining:
    post:
      operationId: createModelTrainingJob
      summary: Amazon Neptune Create an ML Model Training Job
      description: Creates a new Neptune ML model training job using Amazon SageMaker. The job trains a graph neural network model using the output from a completed data processing job. Supports relational graph convolutional network (RGCN) and knowledge graph embedding (KGE) models, as well as custom training scripts.
      tags:
      - Model Training
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModelTrainingJobRequest'
      responses:
        '200':
          description: Model training job created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCreatedResponse'
              examples:
                createModelTrainingJob200Example:
                  summary: Default createModelTrainingJob 200 response
                  x-microcks-default: true
                  value:
                    id: neptune-cluster-abc123
        '400':
          description: Bad request - invalid parameters.
        '500':
          description: Internal server error.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      operationId: listModelTrainingJobs
      summary: Amazon Neptune List Active Model Training Jobs
      description: Returns a list of active Neptune ML model training job IDs.
      tags:
      - Model Training
      parameters:
      - name: maxItems
        in: query
        description: Maximum number of items to return (default 10, max 1024).
        schema:
          type: integer
          default: 10
          maximum: 1024
      - name: neptuneIamRoleArn
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Job list retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResponse'
              examples:
                listModelTrainingJobs200Example:
                  summary: Default listModelTrainingJobs 200 response
                  x-microcks-default: true
                  value:
                    ids:
                    - example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /ml/modeltraining/{id}:
    get:
      operationId: getModelTrainingJobStatus
      summary: Amazon Neptune Get Model Training Job Status
      description: Returns the status of a Neptune ML model training job.
      tags:
      - Model Training
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the model training job.
        schema:
          type: string
      - name: neptuneIamRoleArn
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Job status retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
              examples:
                getModelTrainingJobStatus200Example:
                  summary: Default getModelTrainingJobStatus 200 response
                  x-microcks-default: true
                  value:
                    status: available
                    id: neptune-cluster-abc123
                    processingJob:
                      name: my-neptune-cluster
                      arn: arn:aws:neptune:us-east-1:123456789012:db:neptune-cluster-1
                      status: available
                      outputLocation: example-value
                      failureReason: example-value
        '404':
          description: Job not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: stopModelTrainingJob
      summary: Amazon Neptune Stop a Model Training Job
      description: Stops a running Neptune ML model training job. Optionally deletes all S3 artifacts when the clean parameter is set to true.
      tags:
      - Model Training
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: clean
        in: query
        schema:
          type: boolean
          default: false
      - name: neptuneIamRoleArn
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Job stopped successfully.
        '404':
          description: Job not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    JobCreatedResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the created job.
    JobStatusResponse:
      type: object
      properties:
        status:
          type: string
          description: The current status of the job.
        id:
          type: string
          description: The job identifier.
        processingJob:
          type: object
          properties:
            name:
              type: string
            arn:
              type: string
            status:
              type: string
            outputLocation:
              type: string
            failureReason:
              type: string
            cloudwatchLogUrl:
              type: string
    JobListResponse:
      type: object
      properties:
        ids:
          type: array
          description: List of job IDs.
          items:
            type: string
    CreateModelTrainingJobRequest:
      type: object
      required:
      - dataProcessingJobId
      - trainModelS3Location
      properties:
        id:
          type: string
          description: Unique identifier for the job.
        dataProcessingJobId:
          type: string
          description: Job ID of the completed data processing job.
        trainModelS3Location:
          type: string
          description: S3 location for model artifacts output.
        previousModelTrainingJobId:
          type: string
          description: Job ID of a previous training job for incremental training.
        sagemakerIamRoleArn:
          type: string
        neptuneIamRoleArn:
          type: string
        modelName:
          type: string
          description: 'The model type to train: rgcn (relational graph convolutional network), transe, distmult, rotate, or custom.'
          enum:
          - rgcn
          - transe
          - distmult
          - rotate
          - custom
        baseProcessingInstanceType:
          type: string
          description: ML instance type for data preparation step.
        trainingInstanceType:
          type: string
          description: ML instance type for the training step.
          default: ml.p3.2xlarge
        trainingInstanceVolumeSizeInGB:
          type: integer
          description: Disk volume size for training instance in GB.
        trainingTimeOutInSeconds:
          type: integer
          description: Training job timeout in seconds.
          default: 86400
        maxHPONumberOfTrainingJobs:
          type: integer
          description: Maximum total training jobs for hyperparameter tuning. Minimum 10 recommended for meaningful results.
          default: 2
        maxHPOParallelTrainingJobs:
          type: integer
          description: Maximum parallel training jobs.
          default: 2
        subnets:
          type: array
          items:
            type: string
        securityGroupIds:
          type: array
          items:
            type: string
        volumeEncryptionKMSKey:
          type: string
        s3OutputEncryptionKMSKey:
          type: string
        enableInterContainerTrafficEncryption:
          type: boolean
          default: true
        enableManagedSpotTraining:
          type: boolean
          description: Whether to use EC2 spot instances for training.
          default: false
        customModelTrainingParameters:
          type: object
          description: Custom model training configuration.
          properties:
            sourceS3DirectoryPath:
              type: string
              description: S3 path to the custom training script directory.
            trainingEntryPointScript:
              type: string
              description: Name of the training entry point script.
            transformEntryPointScript:
              type: string
              description: Name of the transform entry point script.
  securitySchemes:
    aws_sigv4:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4 authentication via IAM