syntax = "proto3";

// Not necessary for Python but should still be declared to avoid name collisions 
// in the Protocol Buffers namespace and non-Python languages
package tfserving;
import "google/protobuf/any.proto";


// Config proto for FileSystemStoragePathSource.
message FileSystemStoragePathSourceConfig {
    // A policy that dictates which version(s) of a servable should be served.
    message ServableVersionPolicy {
      // Serve the latest versions (i.e. the ones with the highest version
      // numbers), among those found on disk.
      //
      // This is the default policy, with the default number of versions as 1.
      message Latest {
        // Number of latest versions to serve. (The default is 1.)
        uint32 num_versions = 1;
      }
  
      // Serve all versions found on disk.
      message All {
      }
  
      // Serve a specific version (or set of versions).
      //
      // This policy is useful for rolling back to a specific version, or for
      // canarying a specific version while still serving a separate stable
      // version.
      message Specific {
        // The version numbers to serve.
        repeated int64 versions = 1;
      }
  
      oneof policy_choice {
        Latest latest = 100;
        All all = 101;
        Specific specific = 102;
      }
    }
  
    // A servable name and base path to look for versions of the servable.
    message ServableToMonitor {
      // The servable name to supply in aspired-versions callback calls. Child
      // paths of 'base_path' are considered to be versions of this servable.
      string servable_name = 1;
  
      // The path to monitor, i.e. look for child paths of the form base_path/123.
      string base_path = 2;
  
      // The policy to determines the number of versions of the servable to be
      // served at the same time.
      
      string servable_version_policy = 4;
  
      reserved 3;  // Legacy version_policy definition.
    }
  
    // The servables to monitor for new versions, and aspire.
    repeated ServableToMonitor servables = 5;
  
    // A single servable name/base_path pair to monitor.
    // DEPRECATED: Use 'servables' instead.
    // TODO(b/30898016): Stop using these fields, and ultimately remove them here.
    string servable_name = 1 [deprecated = true];
    string base_path = 2 [deprecated = true];
  
    // How long to wait between file-system polling to look for children of
    // 'base_path', in seconds.
    //
    // If set to zero, filesystem will be polled exactly once. If set to a
    // negative value (for testing use only), polling will be entirely disabled.
    int64 file_system_poll_wait_seconds = 3;
  
    // If true, then FileSystemStoragePathSource::Create() and ::UpdateConfig()
    // fail if, for any configured servables, the file system doesn't currently
    // contain at least one version under the base path.
    // (Otherwise, it will emit a warning and keep pinging the file system to
    // check for a version to appear later.)
    // DEPRECATED: Use 'servable_versions_always_present' instead, which includes
    // this behavior.
    // TODO(b/30898016): Remove 2019-10-31 or later.
    bool fail_if_zero_versions_at_startup = 4 [deprecated = true];
  
    // If true, the servable is always expected to exist on the underlying
    // filesystem. FileSystemStoragePathSource::Create() and ::UpdateConfig() will
    // fail if, for any configured servables, the file system doesn't currently
    // contain at least one version under the base path. In addition, if a polling
    // loop find the base path empty, it will not unload existing servables.
    bool servable_versions_always_present = 6;
  }
  

// The type of model.
// TODO(b/31336131): DEPRECATED.
enum ModelType {
  MODEL_TYPE_UNSPECIFIED = 0 [deprecated = true];
  TENSORFLOW = 1 [deprecated = true];
  OTHER = 2 [deprecated = true];
}

// Common configuration for loading a model being served.
message ModelConfig {
  // Name of the model.
  string name = 1;

  // Base path to the model, excluding the version directory.
  // E.g> for a model at /foo/bar/my_model/123, where 123 is the version, the
  // base path is /foo/bar/my_model.
  //
  // (This can be changed once a model is in serving, *if* the underlying data
  // remains the same. Otherwise there are no guarantees about whether the old
  // or new data will be used for model versions currently loaded.)
  string base_path = 2;

  // Type of model.
  // TODO(b/31336131): DEPRECATED. Please use 'model_platform' instead.
  ModelType model_type = 3 [deprecated = true];

  // Type of model (e.g. "tensorflow").
  //
  // (This cannot be changed once a model is in serving.)
  string model_platform = 4;

  reserved 5, 9;

  // Version policy for the model indicating which version(s) of the model to
  // load and make available for serving simultaneously.
  // The default option is to serve only the latest version of the model.
  //
  // (This can be changed once a model is in serving.)
  FileSystemStoragePathSourceConfig.ServableVersionPolicy model_version_policy = 7;

  // String labels to associate with versions of the model, allowing inference
  // queries to refer to versions by label instead of number. Multiple labels
  // can map to the same version, but not vice-versa.
  //
  // An envisioned use-case for these labels is canarying tentative versions.
  // For example, one can assign labels "stable" and "canary" to two specific
  // versions. Perhaps initially "stable" is assigned to version 0 and "canary"
  // to version 1. Once version 1 passes canary, one can shift the "stable"
  // label to refer to version 1 (at that point both labels map to the same
  // version -- version 1 -- which is fine). Later once version 2 is ready to
  // canary one can move the "canary" label to version 2. And so on.
  map<string, int64> version_labels = 8;

  // Configures logging requests and responses, to the model.
  //
  // (This can be changed once a model is in serving.)
}

// Static list of models to be loaded for serving.
message ModelConfigList {
  repeated ModelConfig config = 1;
}

// ModelServer config.
message ModelServerConfig {
  // ModelServer takes either a static file-based model config list or an Any
  // proto representing custom model config that is fetched dynamically at
  // runtime (through network RPC, custom service, etc.).
  oneof config {
    ModelConfigList model_config_list = 1;
    google.protobuf.Any custom_model_config = 2;
  }
}