experiment.proto 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502
  1. // Copyright 2021 Google LLC
  2. //
  3. // Licensed under the Apache License, Version 2.0 (the "License");
  4. // you may not use this file except in compliance with the License.
  5. // You may obtain a copy of the License at
  6. //
  7. // http://www.apache.org/licenses/LICENSE-2.0
  8. //
  9. // Unless required by applicable law or agreed to in writing, software
  10. // distributed under the License is distributed on an "AS IS" BASIS,
  11. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. // See the License for the specific language governing permissions and
  13. // limitations under the License.
  14. syntax = "proto3";
  15. package google.cloud.dialogflow.cx.v3;
  16. import "google/api/annotations.proto";
  17. import "google/api/client.proto";
  18. import "google/api/field_behavior.proto";
  19. import "google/api/resource.proto";
  20. import "google/protobuf/duration.proto";
  21. import "google/protobuf/empty.proto";
  22. import "google/protobuf/field_mask.proto";
  23. import "google/protobuf/timestamp.proto";
  24. option cc_enable_arenas = true;
  25. option csharp_namespace = "Google.Cloud.Dialogflow.Cx.V3";
  26. option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3;cx";
  27. option java_multiple_files = true;
  28. option java_outer_classname = "ExperimentProto";
  29. option java_package = "com.google.cloud.dialogflow.cx.v3";
  30. option objc_class_prefix = "DF";
  31. // Service for managing [Experiments][google.cloud.dialogflow.cx.v3.Experiment].
  32. service Experiments {
  33. option (google.api.default_host) = "dialogflow.googleapis.com";
  34. option (google.api.oauth_scopes) =
  35. "https://www.googleapis.com/auth/cloud-platform,"
  36. "https://www.googleapis.com/auth/dialogflow";
  37. // Returns the list of all experiments in the specified [Environment][google.cloud.dialogflow.cx.v3.Environment].
  38. rpc ListExperiments(ListExperimentsRequest) returns (ListExperimentsResponse) {
  39. option (google.api.http) = {
  40. get: "/v3/{parent=projects/*/locations/*/agents/*/environments/*}/experiments"
  41. };
  42. option (google.api.method_signature) = "parent";
  43. }
  44. // Retrieves the specified [Experiment][google.cloud.dialogflow.cx.v3.Experiment].
  45. rpc GetExperiment(GetExperimentRequest) returns (Experiment) {
  46. option (google.api.http) = {
  47. get: "/v3/{name=projects/*/locations/*/agents/*/environments/*/experiments/*}"
  48. };
  49. option (google.api.method_signature) = "name";
  50. }
  51. // Creates an [Experiment][google.cloud.dialogflow.cx.v3.Experiment] in the specified [Environment][google.cloud.dialogflow.cx.v3.Environment].
  52. rpc CreateExperiment(CreateExperimentRequest) returns (Experiment) {
  53. option (google.api.http) = {
  54. post: "/v3/{parent=projects/*/locations/*/agents/*/environments/*}/experiments"
  55. body: "experiment"
  56. };
  57. option (google.api.method_signature) = "parent,experiment";
  58. }
  59. // Updates the specified [Experiment][google.cloud.dialogflow.cx.v3.Experiment].
  60. rpc UpdateExperiment(UpdateExperimentRequest) returns (Experiment) {
  61. option (google.api.http) = {
  62. patch: "/v3/{experiment.name=projects/*/locations/*/agents/*/environments/*/experiments/*}"
  63. body: "experiment"
  64. };
  65. option (google.api.method_signature) = "experiment,update_mask";
  66. }
  67. // Deletes the specified [Experiment][google.cloud.dialogflow.cx.v3.Experiment].
  68. rpc DeleteExperiment(DeleteExperimentRequest) returns (google.protobuf.Empty) {
  69. option (google.api.http) = {
  70. delete: "/v3/{name=projects/*/locations/*/agents/*/environments/*/experiments/*}"
  71. };
  72. option (google.api.method_signature) = "name";
  73. }
  74. // Starts the specified [Experiment][google.cloud.dialogflow.cx.v3.Experiment]. This rpc only changes the state of
  75. // experiment from PENDING to RUNNING.
  76. rpc StartExperiment(StartExperimentRequest) returns (Experiment) {
  77. option (google.api.http) = {
  78. post: "/v3/{name=projects/*/locations/*/agents/*/environments/*/experiments/*}:start"
  79. body: "*"
  80. };
  81. option (google.api.method_signature) = "name";
  82. }
  83. // Stops the specified [Experiment][google.cloud.dialogflow.cx.v3.Experiment]. This rpc only changes the state of
  84. // experiment from RUNNING to DONE.
  85. rpc StopExperiment(StopExperimentRequest) returns (Experiment) {
  86. option (google.api.http) = {
  87. post: "/v3/{name=projects/*/locations/*/agents/*/environments/*/experiments/*}:stop"
  88. body: "*"
  89. };
  90. option (google.api.method_signature) = "name";
  91. }
  92. }
  93. // Represents an experiment in an environment.
  94. message Experiment {
  95. option (google.api.resource) = {
  96. type: "dialogflow.googleapis.com/Experiment"
  97. pattern: "projects/{project}/locations/{location}/agents/{agent}/environments/{environment}/experiments/{experiment}"
  98. };
  99. // Definition of the experiment.
  100. message Definition {
  101. // The condition defines which subset of sessions are selected for
  102. // this experiment. If not specified, all sessions are eligible. E.g.
  103. // "query_input.language_code=en" See the [conditions
  104. // reference](https://cloud.google.com/dialogflow/cx/docs/reference/condition).
  105. string condition = 1;
  106. // The variants of the experiment. We currently only support single variant
  107. // experiment.
  108. oneof variants {
  109. // The flow versions as the variants of this experiment.
  110. VersionVariants version_variants = 2;
  111. }
  112. }
  113. // The inference result which includes an objective metric to optimize and the
  114. // confidence interval.
  115. message Result {
  116. // A confidence interval is a range of possible values for the experiment
  117. // objective you are trying to measure.
  118. message ConfidenceInterval {
  119. // The confidence level used to construct the interval, i.e. there is X%
  120. // chance that the true value is within this interval.
  121. double confidence_level = 1;
  122. // The percent change between an experiment metric's value and the value
  123. // for its control.
  124. double ratio = 2;
  125. // Lower bound of the interval.
  126. double lower_bound = 3;
  127. // Upper bound of the interval.
  128. double upper_bound = 4;
  129. }
  130. // Metric and corresponding confidence intervals.
  131. message Metric {
  132. // Ratio-based metric type. Only one of type or count_type is specified in
  133. // each Metric.
  134. MetricType type = 1;
  135. // Count-based metric type. Only one of type or count_type is specified in
  136. // each Metric.
  137. CountType count_type = 5;
  138. // The actual value of the metric.
  139. oneof value {
  140. // Ratio value of a metric.
  141. double ratio = 2;
  142. // Count value of a metric.
  143. double count = 4;
  144. }
  145. // The probability that the treatment is better than all other treatments
  146. // in the experiment
  147. ConfidenceInterval confidence_interval = 3;
  148. }
  149. // Version variant and associated metrics.
  150. message VersionMetrics {
  151. // The name of the flow [Version][google.cloud.dialogflow.cx.v3.Version].
  152. // Format: `projects/<Project ID>/locations/<Location
  153. // ID>/agents/<Agent ID>/flows/<Flow ID>/versions/<Version ID>`.
  154. string version = 1 [(google.api.resource_reference) = {
  155. type: "dialogflow.googleapis.com/Version"
  156. }];
  157. // The metrics and corresponding confidence intervals in the inference
  158. // result.
  159. repeated Metric metrics = 2;
  160. // Number of sessions that were allocated to this version.
  161. int32 session_count = 3;
  162. }
  163. // Types of ratio-based metric for Dialogflow experiment.
  164. enum MetricType {
  165. // Metric unspecified.
  166. METRIC_UNSPECIFIED = 0;
  167. // Percentage of contained sessions without user calling back in 24 hours.
  168. CONTAINED_SESSION_NO_CALLBACK_RATE = 1;
  169. // Percentage of sessions that were handed to a human agent.
  170. LIVE_AGENT_HANDOFF_RATE = 2;
  171. // Percentage of sessions with the same user calling back.
  172. CALLBACK_SESSION_RATE = 3;
  173. // Percentage of sessions where user hung up.
  174. ABANDONED_SESSION_RATE = 4;
  175. // Percentage of sessions reached Dialogflow 'END_PAGE' or
  176. // 'END_SESSION'.
  177. SESSION_END_RATE = 5;
  178. }
  179. // Types of count-based metric for Dialogflow experiment.
  180. enum CountType {
  181. // Count type unspecified.
  182. COUNT_TYPE_UNSPECIFIED = 0;
  183. // Total number of occurrences of a 'NO_MATCH'.
  184. TOTAL_NO_MATCH_COUNT = 1;
  185. // Total number of turn counts.
  186. TOTAL_TURN_COUNT = 2;
  187. // Average turn count in a session.
  188. AVERAGE_TURN_COUNT = 3;
  189. }
  190. // Version variants and metrics.
  191. repeated VersionMetrics version_metrics = 1;
  192. // The last time the experiment's stats data was updated. Will have default
  193. // value if stats have never been computed for this experiment.
  194. google.protobuf.Timestamp last_update_time = 2;
  195. }
  196. // The state of the experiment.
  197. enum State {
  198. // State unspecified.
  199. STATE_UNSPECIFIED = 0;
  200. // The experiment is created but not started yet.
  201. DRAFT = 1;
  202. // The experiment is running.
  203. RUNNING = 2;
  204. // The experiment is done.
  205. DONE = 3;
  206. // The experiment with auto-rollout enabled has failed.
  207. ROLLOUT_FAILED = 4;
  208. }
  209. // The name of the experiment.
  210. // Format: projects/<Project ID>/locations/<Location ID>/agents/<Agent
  211. // ID>/environments/<Environment ID>/experiments/<Experiment ID>..
  212. string name = 1;
  213. // Required. The human-readable name of the experiment (unique in an environment). Limit
  214. // of 64 characters.
  215. string display_name = 2 [(google.api.field_behavior) = REQUIRED];
  216. // The human-readable description of the experiment.
  217. string description = 3;
  218. // The current state of the experiment.
  219. // Transition triggered by Experiments.StartExperiment: DRAFT->RUNNING.
  220. // Transition triggered by Experiments.CancelExperiment: DRAFT->DONE or
  221. // RUNNING->DONE.
  222. State state = 4;
  223. // The definition of the experiment.
  224. Definition definition = 5;
  225. // The configuration for auto rollout. If set, there should be exactly two
  226. // variants in the experiment (control variant being the default version of
  227. // the flow), the traffic allocation for the non-control variant will
  228. // gradually increase to 100% when conditions are met, and eventually
  229. // replace the control variant to become the default version of the flow.
  230. RolloutConfig rollout_config = 14;
  231. // State of the auto rollout process.
  232. RolloutState rollout_state = 15;
  233. // The reason why rollout has failed. Should only be set when state is
  234. // ROLLOUT_FAILED.
  235. string rollout_failure_reason = 16;
  236. // Inference result of the experiment.
  237. Result result = 6;
  238. // Creation time of this experiment.
  239. google.protobuf.Timestamp create_time = 7;
  240. // Start time of this experiment.
  241. google.protobuf.Timestamp start_time = 8;
  242. // End time of this experiment.
  243. google.protobuf.Timestamp end_time = 9;
  244. // Last update time of this experiment.
  245. google.protobuf.Timestamp last_update_time = 10;
  246. // Maximum number of days to run the experiment/rollout. If auto-rollout is
  247. // not enabled, default value and maximum will be 30 days. If auto-rollout is
  248. // enabled, default value and maximum will be 6 days.
  249. google.protobuf.Duration experiment_length = 11;
  250. // The history of updates to the experiment variants.
  251. repeated VariantsHistory variants_history = 12;
  252. }
  253. // A list of flow version variants.
  254. message VersionVariants {
  255. // A single flow version with specified traffic allocation.
  256. message Variant {
  257. // The name of the flow version.
  258. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  259. // ID>/flows/<Flow ID>/versions/<Version ID>`.
  260. string version = 1;
  261. // Percentage of the traffic which should be routed to this
  262. // version of flow. Traffic allocation for a single flow must sum up to 1.0.
  263. float traffic_allocation = 2;
  264. // Whether the variant is for the control group.
  265. bool is_control_group = 3;
  266. }
  267. // A list of flow version variants.
  268. repeated Variant variants = 1;
  269. }
  270. // The history of variants update.
  271. message VariantsHistory {
  272. // The variants updated. We currently only support single variant
  273. // experiment.
  274. oneof variants {
  275. // The flow versions as the variants.
  276. VersionVariants version_variants = 1;
  277. }
  278. // Update time of the variants.
  279. google.protobuf.Timestamp update_time = 2;
  280. }
  281. // The configuration for auto rollout.
  282. message RolloutConfig {
  283. // A single rollout step with specified traffic allocation.
  284. message RolloutStep {
  285. // The name of the rollout step;
  286. string display_name = 1;
  287. // The percentage of traffic allocated to the flow version of this rollout
  288. // step. (0%, 100%].
  289. int32 traffic_percent = 2;
  290. // The minimum time that this step should last. Should be longer than 1
  291. // hour. If not set, the default minimum duration for each step will be 1
  292. // hour.
  293. google.protobuf.Duration min_duration = 3;
  294. }
  295. // Steps to roll out a flow version. Steps should be sorted by percentage in
  296. // ascending order.
  297. repeated RolloutStep rollout_steps = 1;
  298. // The conditions that are used to evaluate the success of a rollout
  299. // step. If not specified, all rollout steps will proceed to the next one
  300. // unless failure conditions are met. E.g. "containment_rate > 60% AND
  301. // callback_rate < 20%". See the [conditions
  302. // reference](https://cloud.google.com/dialogflow/cx/docs/reference/condition).
  303. string rollout_condition = 2;
  304. // The conditions that are used to evaluate the failure of a rollout
  305. // step. If not specified, no rollout steps will fail. E.g. "containment_rate
  306. // < 10% OR average_turn_count < 3". See the [conditions
  307. // reference](https://cloud.google.com/dialogflow/cx/docs/reference/condition).
  308. string failure_condition = 3;
  309. }
  310. // State of the auto-rollout process.
  311. message RolloutState {
  312. // Display name of the current auto rollout step.
  313. string step = 1;
  314. // Index of the current step in the auto rollout steps list.
  315. int32 step_index = 3;
  316. // Start time of the current step.
  317. google.protobuf.Timestamp start_time = 2;
  318. }
  319. // The request message for [Experiments.ListExperiments][google.cloud.dialogflow.cx.v3.Experiments.ListExperiments].
  320. message ListExperimentsRequest {
  321. // Required. The [Environment][google.cloud.dialogflow.cx.v3.Environment] to list all environments for.
  322. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  323. // ID>/environments/<Environment ID>`.
  324. string parent = 1 [
  325. (google.api.field_behavior) = REQUIRED,
  326. (google.api.resource_reference) = {
  327. child_type: "dialogflow.googleapis.com/Experiment"
  328. }
  329. ];
  330. // The maximum number of items to return in a single page. By default 20 and
  331. // at most 100.
  332. int32 page_size = 2;
  333. // The next_page_token value returned from a previous list request.
  334. string page_token = 3;
  335. }
  336. // The response message for [Experiments.ListExperiments][google.cloud.dialogflow.cx.v3.Experiments.ListExperiments].
  337. message ListExperimentsResponse {
  338. // The list of experiments. There will be a maximum number of items
  339. // returned based on the page_size field in the request. The list may in some
  340. // cases be empty or contain fewer entries than page_size even if this isn't
  341. // the last page.
  342. repeated Experiment experiments = 1;
  343. // Token to retrieve the next page of results, or empty if there are no more
  344. // results in the list.
  345. string next_page_token = 2;
  346. }
  347. // The request message for [Experiments.GetExperiment][google.cloud.dialogflow.cx.v3.Experiments.GetExperiment].
  348. message GetExperimentRequest {
  349. // Required. The name of the [Environment][google.cloud.dialogflow.cx.v3.Environment].
  350. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  351. // ID>/environments/<Environment ID>/experiments/<Experiment ID>`.
  352. string name = 1 [
  353. (google.api.field_behavior) = REQUIRED,
  354. (google.api.resource_reference) = {
  355. type: "dialogflow.googleapis.com/Experiment"
  356. }
  357. ];
  358. }
  359. // The request message for [Experiments.CreateExperiment][google.cloud.dialogflow.cx.v3.Experiments.CreateExperiment].
  360. message CreateExperimentRequest {
  361. // Required. The [Agent][google.cloud.dialogflow.cx.v3.Agent] to create an [Environment][google.cloud.dialogflow.cx.v3.Environment] for.
  362. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  363. // ID>/environments/<Environment ID>`.
  364. string parent = 1 [
  365. (google.api.field_behavior) = REQUIRED,
  366. (google.api.resource_reference) = {
  367. child_type: "dialogflow.googleapis.com/Experiment"
  368. }
  369. ];
  370. // Required. The experiment to create.
  371. Experiment experiment = 2 [(google.api.field_behavior) = REQUIRED];
  372. }
  373. // The request message for [Experiments.UpdateExperiment][google.cloud.dialogflow.cx.v3.Experiments.UpdateExperiment].
  374. message UpdateExperimentRequest {
  375. // Required. The experiment to update.
  376. Experiment experiment = 1 [(google.api.field_behavior) = REQUIRED];
  377. // Required. The mask to control which fields get updated.
  378. google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
  379. }
  380. // The request message for [Experiments.DeleteExperiment][google.cloud.dialogflow.cx.v3.Experiments.DeleteExperiment].
  381. message DeleteExperimentRequest {
  382. // Required. The name of the [Environment][google.cloud.dialogflow.cx.v3.Environment] to delete.
  383. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  384. // ID>/environments/<Environment ID>/experiments/<Experiment ID>`.
  385. string name = 1 [
  386. (google.api.field_behavior) = REQUIRED,
  387. (google.api.resource_reference) = {
  388. type: "dialogflow.googleapis.com/Experiment"
  389. }
  390. ];
  391. }
  392. // The request message for [Experiments.StartExperiment][google.cloud.dialogflow.cx.v3.Experiments.StartExperiment].
  393. message StartExperimentRequest {
  394. // Required. Resource name of the experiment to start.
  395. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  396. // ID>/environments/<Environment ID>/experiments/<Experiment ID>`.
  397. string name = 1 [
  398. (google.api.field_behavior) = REQUIRED,
  399. (google.api.resource_reference) = {
  400. type: "dialogflow.googleapis.com/Experiment"
  401. }
  402. ];
  403. }
  404. // The request message for [Experiments.StopExperiment][google.cloud.dialogflow.cx.v3.Experiments.StopExperiment].
  405. message StopExperimentRequest {
  406. // Required. Resource name of the experiment to stop.
  407. // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  408. // ID>/environments/<Environment ID>/experiments/<Experiment ID>`.
  409. string name = 1 [
  410. (google.api.field_behavior) = REQUIRED,
  411. (google.api.resource_reference) = {
  412. type: "dialogflow.googleapis.com/Experiment"
  413. }
  414. ];
  415. }