syntax = "proto3";

package model.v1alpha;

// Google API
import "google/api/annotations.proto";
import "google/api/visibility.proto";
// Model definitions
import "model/v1alpha/model.proto";
import "model/v1alpha/model_definition.proto";
// OpenAPI definition
import "protoc-gen-openapiv2/options/annotations.proto";

// Model
//
// ModelPublicService exposes the public endpoints that allow clients to manage
// models.
service ModelPublicService {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_tag) = {description: "Public Model endpoints"};

  // Check if the model server is alive
  //
  // See https://github.com/grpc/grpc/blob/master/doc/health-checking.md.
  rpc Liveness(LivenessRequest) returns (LivenessResponse) {
    option (google.api.http) = {
      get: "/v1alpha/__liveness"
      additional_bindings: [
        {get: "/v1alpha/health/model"}]
    };
    option (google.api.method_visibility).restriction = "INTERNAL";
  }

  // Check if the model server is ready
  //
  // See https://github.com/grpc/grpc/blob/master/doc/health-checking.md
  rpc Readiness(ReadinessRequest) returns (ReadinessResponse) {
    option (google.api.http) = {
      get: "/v1alpha/__readiness"
      additional_bindings: [
        {get: "/v1alpha/ready/model"}]
    };
    option (google.api.method_visibility).restriction = "INTERNAL";
  }

  // List model definitions
  //
  // Returns a paginated list of model definitions.
  rpc ListModelDefinitions(ListModelDefinitionsRequest) returns (ListModelDefinitionsResponse) {
    option (google.api.http) = {get: "/v1alpha/model-definitions"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // List available regions
  //
  // Returns a paginated list of available regions.
  rpc ListAvailableRegions(ListAvailableRegionsRequest) returns (ListAvailableRegionsResponse) {
    option (google.api.http) = {get: "/v1alpha/available-regions"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // Get a model definition
  //
  // Returns the details of a model definition.
  rpc GetModelDefinition(GetModelDefinitionRequest) returns (GetModelDefinitionResponse) {
    option (google.api.http) = {get: "/v1alpha/model-definitions/{model_definition_id}"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // List public models
  //
  // Returns a paginated list of public models.
  rpc ListPublicModels(ListPublicModelsRequest) returns (ListPublicModelsResponse) {
    option (google.api.http) = {get: "/v1alpha/models"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // List models
  //
  // Returns a paginated list of models.
  rpc ListModels(ListModelsRequest) returns (ListModelsResponse) {
    option (google.api.http) = {get: "/v1alpha/{parent=namespaces/*}/models"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // Create a new model
  //
  // Creates a new model under the parenthood of a namespace. This is an
  // asynchronous endpoint, i.e., the server will not wait for the model to be
  // created in order to respond. Instead, it will return a response with the
  // necessary information to access the result and status of the creation
  // operation.
  rpc CreateModel(CreateModelRequest) returns (CreateModelResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{parent=namespaces/*}/models"
      body: "model"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // Get a model
  //
  // Returns the detail of a model, accessing it by the model ID and its parent
  // namespace.
  rpc GetModel(GetModelRequest) returns (GetModelResponse) {
    option (google.api.http) = {get: "/v1alpha/{name=namespaces/*/models/*}"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // Update a model
  //
  // Updates a model, accessing it by its resource name, which is defined by
  // the parent namespace and the ID of the model.
  //
  // In REST requests, only the supplied model fields will be taken into
  // account when updating the resource.
  rpc UpdateModel(UpdateModelRequest) returns (UpdateModelResponse) {
    option (google.api.http) = {
      patch: "/v1alpha/{model.name=namespaces/*/models/*}"
      body: "model"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // Delete a model
  //
  // Deletes a model, accesing it by its resource name, which is defined by the
  // parent namespace and the ID of the model.
  rpc DeleteModel(DeleteModelRequest) returns (DeleteModelResponse) {
    option (google.api.http) = {delete: "/v1alpha/{name=namespaces/*/models/*}"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // Rename a model
  //
  // Renames a model, accesing it by its resource name, which is defined by the
  // parent namespace and the ID of the model.
  rpc RenameModel(RenameModelRequest) returns (RenameModelResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{name=namespaces/*/models/*}/rename"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // Watch the state of a model version
  //
  // Returns the state of a model. The model resource allocation and scaling
  // actions take some time, during which a model will be in various state. This
  // endpoint allows clients to track the state.
  rpc WatchModelVersion(WatchModelVersionRequest) returns (WatchModelVersionResponse) {
    option (google.api.http) = {get: "/v1alpha/{name=namespaces/*/models/*}/versions/{version}/watch"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // Watch the state of the latest model version
  //
  // Returns the state of the latest model version. The model resource
  // allocation and scaling actions take some time, during which a model will be
  // in various state. This endpoint allows clients to track the state.
  rpc WatchModel(WatchModelRequest) returns (WatchModelResponse) {
    option (google.api.http) = {get: "/v1alpha/{name=namespaces/*/models/*}/watch"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // List namespace model versions
  //
  // Returns a paginated list of version of a model namespace that belong to the
  // specified namespace. Contains model version and digest.
  rpc ListModelVersions(ListModelVersionsRequest) returns (ListModelVersionsResponse) {
    option (google.api.http) = {get: "/v1alpha/{parent=namespaces/*/models/*}/versions"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // Delete a model version
  //
  // Deletes a model version, accesing it by its resource name, which is defined
  // by the parent namespace and the ID of the model, and version.
  rpc DeleteModelVersion(DeleteModelVersionRequest) returns (DeleteModelVersionResponse) {
    option (google.api.http) = {delete: "/v1alpha/{name=namespaces/*/models/*/versions/*}"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // Trigger model inference
  //
  // Triggers a deployed model to infer the result of a set of task or
  // questions.
  rpc TriggerModelVersion(TriggerModelVersionRequest) returns (TriggerModelVersionResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{name=namespaces/*/models/*/versions/*}/trigger"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
      parameters: {
        headers: {
          name: "Instill-Requester-Uid"
          description:
            "Indicates the authenticated namespace is making the "
            "request on behalf of another entity, typically an "
            "organization they belong to"
          type: STRING
        }
      }
    };
  }

  // Trigger model inference asynchronously
  //
  // Triggers a deployed model to infer the result of a set of task or
  // questions.
  rpc TriggerAsyncModelVersion(TriggerAsyncModelVersionRequest) returns (TriggerAsyncModelVersionResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{name=namespaces/*/models/*/versions/*}/trigger-async"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
      parameters: {
        headers: {
          name: "Instill-Requester-Uid"
          description:
            "Indicates the authenticated namespace is making the "
            "request on behalf of another entity, typically an "
            "organization they belong to"
          type: STRING
        }
      }
    };
  }

  // Trigger model inference
  //
  // Triggers the latest deployed model version to infer the result of a set of
  // task or questions.
  rpc TriggerModel(TriggerModelRequest) returns (TriggerModelResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{name=namespaces/*/models/*}/trigger"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
      parameters: {
        headers: {
          name: "Instill-Requester-Uid"
          description:
            "Indicates the authenticated namespace is making the "
            "request on behalf of another entity, typically an "
            "organization they belong to"
          type: STRING
        }
      }
    };
  }

  // Trigger model inference asynchronously
  //
  // Triggers the latest deployed model version to infer the result of a set of
  // task or questions.
  rpc TriggerAsyncModel(TriggerAsyncModelRequest) returns (TriggerAsyncModelResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{name=namespaces/*/models/*}/trigger-async"
      body: "*"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
      parameters: {
        headers: {
          name: "Instill-Requester-Uid"
          description:
            "Indicates the authenticated namespace is making the "
            "request on behalf of another entity, typically an "
            "organization they belong to"
          type: STRING
        }
      }
    };
  }

  // Trigger model inference with a binary input
  //
  // Triggers a deployed model to infer the result of a task or question,
  // submitted as a binary file.
  rpc TriggerModelVersionBinaryFileUpload(stream TriggerModelVersionBinaryFileUploadRequest) returns (TriggerModelVersionBinaryFileUploadResponse) {
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
      parameters: {
        headers: {
          name: "Instill-Requester-Uid"
          description:
            "Indicates the authenticated user is making the "
            "request on behalf of another entity, typically an "
            "organization they belong to"
          type: STRING
        }
      }
    };
  }

  // Trigger model inference with a binary input
  //
  // Triggers the latest deployed model version to infer the result of a set of
  // task or questions, submitted as a binary file.
  rpc TriggerModelBinaryFileUpload(stream TriggerModelBinaryFileUploadRequest) returns (TriggerModelBinaryFileUploadResponse) {
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
      parameters: {
        headers: {
          name: "Instill-Requester-Uid"
          description:
            "Indicates the authenticated user is making the "
            "request on behalf of another entity, typically an "
            "organization they belong to"
          type: STRING
        }
      }
    };
  }

  // Get the details of the long-running operation from a model version
  //
  // This method allows requesters to request the status and outcome of
  // long-running operations in a model, such as trigger.
  rpc GetModelVersionOperation(GetModelVersionOperationRequest) returns (GetModelVersionOperationResponse) {
    option (google.api.http) = {get: "/v1alpha/{name=namespaces/*/models/*/versions/*}/operation"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // Get the details of the latest long-running operation from a model
  //
  // This method allows requesters to request the status and outcome of
  // long-running operations in a model, such as trigger.
  rpc GetModelOperation(GetModelOperationRequest) returns (GetModelOperationResponse) {
    option (google.api.http) = {get: "/v1alpha/{name=namespaces/*/models/*}/operation"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // Get the details of a long-running operation
  //
  // This method allows requesters to request the status and outcome of
  // long-running operations in a model, such as trigger.
  rpc GetOperation(GetOperationRequest) returns (GetOperationResponse) {
    option (google.api.http) = {get: "/v1alpha/operations/{operation_id}"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // List Model Runs
  //
  // Returns a paginated list of runs for a given model. When the requester is
  // the owner of the model, they will be able to all the model runs,
  // regardless who requested the trigger (the view will be partial to hide
  // sensitive data like e.g. the trigger input and output). Other requesters
  // will only be able to see the runs requested by themselves.
  rpc ListModelRuns(ListModelRunsRequest) returns (ListModelRunsResponse) {
    option (google.api.http) = {get: "/v1alpha/{parent=namespaces/*/models/*}/runs"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      parameters: {
        headers: {
          name: "Instill-Requester-Uid"
          description:
            "Indicates the authenticated namespace is making the "
            "request on behalf of another entity, typically an "
            "organization they belong to"
          type: STRING
        }
      }
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }

  // List Model Runs By Requester
  //
  // Returns a paginated list of runs requested by a namespace. The response
  // may contain runs from several models.
  rpc ListModelRunsByRequester(ListModelRunsByRequesterRequest) returns (ListModelRunsByRequesterResponse) {
    option (google.api.http) = {get: "/v1alpha/dashboard/models/runs"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "Model"
      extensions: {
        key: "x-stage"
        value: {string_value: "alpha"}
      }
    };
  }
}