model_definition.proto

syntax = "proto3";

package model.model.v1alpha;

// Google API
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
// Protocol Buffers Well-Known Types
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
// OpenAPI
import "protoc-gen-openapiv2/options/annotations.proto";

///////////////////////////////////////////////////////////////////

// ReleaseStage defines the stage of a release.
enum ReleaseStage {
  // Unspecified.
  RELEASE_STAGE_UNSPECIFIED = 0;
  // Alpha.
  RELEASE_STAGE_ALPHA = 1;
  // Beta.
  RELEASE_STAGE_BETA = 2;
  // Generally available.
  RELEASE_STAGE_GENERALLY_AVAILABLE = 3;
  // Custom.
  RELEASE_STAGE_CUSTOM = 4;
}

///////////////////////////////////////////////////////////////////

// ModelDefinition defines how to configure and import a model.
message ModelDefinition {
  option (google.api.resource) = {
    type: "api.instill.tech/ModelDefinition"
    pattern: "model-definitions/{id}"
    pattern: "model-definitions/{uid}"
  };

  // The resource name of the model, which allows its access by ID.
  // - Format: `model-definitions/{id}`.
  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Model definition UUID.
  string uid = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Model definition resource ID (used in `name` as the last segment). This
  // conforms to RFC-1034, which restricts to letters, numbers, and hyphen,
  // with the first character a letter, the last a letter or a number, and a 63
  // character maximum.
  string id = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Official display title.
  string title = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Documentation URL.
  string documentation_url = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Display icon.
  string icon = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Release stage.
  ReleaseStage release_stage = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The model specification represented by a JSON schema. It is used to
  // validate the JSON configurations of a model created from a specific model
  // source, and the resource spec which the model is desired to be deployed on.
  // It must be a valid JSON that includes what fields are needed to
  // create or display a model.
  google.protobuf.Struct model_spec = 8 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Creation time.
  google.protobuf.Timestamp create_time = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Update time.
  google.protobuf.Timestamp update_time = 10 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// View defines how a model definition is presented.
enum View {
  // Unspecified, equivalent to BASIC.
  VIEW_UNSPECIFIED = 0;
  // Default view, only includes basic information (omits `model_spec`).
  VIEW_BASIC = 1;
  // Full representation.
  VIEW_FULL = 2;
}

// ListModelDefinitionsRequest represents a request to list all supported model
// definitions.
message ListModelDefinitionsRequest {
  // The maximum number of model definitions to return. If this parameter
  // is unspecified, at most 10 definitions will be returned. The cap value for
  // this parameter is 100 (i.e. any value above that will be coerced to 100).
  optional int32 page_size = 1 [(google.api.field_behavior) = OPTIONAL];
  // Page token.
  optional string page_token = 2 [(google.api.field_behavior) = OPTIONAL];
  // View allows clients to specify the desired resource view in the response.
  optional View view = 3 [(google.api.field_behavior) = OPTIONAL];
}

// ListModelDefinitionsResponse contains a list of model definitions.
message ListModelDefinitionsResponse {
  // A list of model definition resources.
  repeated ModelDefinition model_definitions = 1;
  // Next page token.
  string next_page_token = 2;
  // Total number of model definitions.
  int32 total_size = 3;
}

// GetModelDefinitionRequest represents a request to fetch the details of a
// model definition.
message GetModelDefinitionRequest {
  // The resource name of the model definition, which allows its access by ID.
  // - Format: `model-definitions/{id}`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference).type = "api.instill.tech/ModelDefinition",
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      field_configuration: {path_param_name: "model_definition_name"}
    }
  ];
  // View allows clients to specify the desired resource view in the response.
  optional View view = 2 [(google.api.field_behavior) = OPTIONAL];
}

// GetModelDefinitionResponse contains the requested model definition.
message GetModelDefinitionResponse {
  // The model definition resource.
  ModelDefinition model_definition = 1;
}