xref: /aosp_15_r20/external/federated-compute/fcp/protos/ondevicepersonalization/task_assignments.proto (revision 14675a029014e728ec732f129a32e299b2da0601)

/**
 * Copyright 2023 Google LLC
 *
 * <p>Licensed under the Apache License, Version 2.0 (the "License"); you may
 * not use this file except in compliance with the License. You may obtain a
 * copy of the License at
 *
 * <p>http://www.apache.org/licenses/LICENSE-2.0
 *
 * <p>Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
syntax = "proto3";

package google.ondevicepersonalization.federatedcompute.proto;

import "fcp/protos/federatedcompute/common.proto";
import "fcp/protos/plan.proto";
import "fcp/protos/ondevicepersonalization/eligibility_spec.proto";
import "fcp/protos/ondevicepersonalization/common.proto";

option java_package = "com.google.ondevicepersonalization.federatedcompute.proto";
option java_multiple_files = true;

// Create task assignment request.
// The url to create task assignment under v1 API is:
// https://{host}/taskassignment/v1/population/{populationName}:create-task-assignment
// Next Id: 3
message CreateTaskAssignmentRequest {
  google.internal.federatedcompute.v1.ClientVersion client_version = 1;

  // The client's capabilities when downloading and processing resources.
  google.internal.federatedcompute.v1.ResourceCapabilities resource_capabilities = 2;
}

// Create task assignment response.
// Next Id: 3
message CreateTaskAssignmentResponse {
  // One of two outcomes, depending on server's decision on participation of the
  // client.
  oneof result {
    // If the client joined the task with this call, information on how to
    // proceed.
    TaskAssignment task_assignment = 1;

    // If the client was not accepted, information how to proceed.
    google.internal.federatedcompute.v1.RejectionInfo rejection_info = 2;
  }
}

// When client (device) is accepted for the current task, this data structure
// carries information necessary to begin task execution.
// Next Id: 12
message TaskAssignment {
  // population name.
  string population_name = 1;

  // the task id
  string task_id = 2;

  // The opaque id of the aggregation session the client has joined. This is a
  // string generated by the server and MUST NOT contain any information that
  // could be used to identify a specific device.
  string aggregation_id = 3;

  // assignment id
  string assignment_id = 4;

  // The identifier of the task that was assigned. It's better to use the combination of
  // `population_name` and `task_id` to identify a task.
  string task_name = 5;

  // The checkpoint from which to start execution.
  google.internal.federatedcompute.v1.Resource init_checkpoint = 6;

  // The plan to be used for execution.
  google.internal.federatedcompute.v1.Resource plan = 7;

  // self uri
  string self_uri = 8;

  // The eligibility of the task. Device need to run this eligibility task
  // to check if it's qualified to start the job before execute real task.
  EligibilityTaskInfo eligibility_task_info = 9;

  // The signature of eligibility task.
  Signature eligibility_task_info_signature = 10;

  // Specifies an example selection procedure. Can be used by model versioning.
  google.internal.federated.plan.ExampleSelector example_selector = 11;
}

// The signature information. Device can verify the signature to check integrity of
// the content.
message Signature {}

// Report result request.
// The url to report result under v1 API is:
// https://{host}/taskassignment/v1/population/{populationName}/task/{taskId}/aggregation/{aggregationId}/task-assignment/{assignmentId}:report-result
// Next Id: 3
message ReportResultRequest {
  enum Result {
    // Unknown
    UNKNOWN = 0;

    // Completed
    COMPLETED = 1;

    // Failed.
    FAILED = 2;

    // Failed due to eligibility task is not qualified.
    NOT_ELIGIBLE = 3;

    // Failed due to example generation failure
    FAILED_EXAMPLE_GENERATION = 4;

    // Failed due to model computation error
    FAILED_MODEL_COMPUTATION = 5;

    // Failed due to model ops error
    FAILED_OPS_ERROR = 6;
  }

  Result result = 1;

  // The client's capabilities when uploading result.
  google.internal.federatedcompute.v1.ResourceCapabilities resource_capabilities = 2;
}

// Report result response.
message ReportResultResponse {
  // Upload result instruction on succeeded.
  UploadInstruction upload_instruction = 1;

  // Rejection reason.
  google.internal.federatedcompute.v1.RejectionInfo rejection_info = 2;
}