// Copyright 2025 Google LLC
//
// 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
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// 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.cloud.aiplatform.v1beta1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/aiplatform/v1beta1/example.proto";
import "google/cloud/aiplatform/v1beta1/example_store.proto";
import "google/cloud/aiplatform/v1beta1/operation.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";
import "google/rpc/status.proto";

option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1";
option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb";
option java_multiple_files = true;
option java_outer_classname = "ExampleStoreServiceProto";
option java_package = "com.google.cloud.aiplatform.v1beta1";
option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1";
option ruby_package = "Google::Cloud::AIPlatform::V1beta1";

// A service for managing and retrieving few-shot examples.
service ExampleStoreService {
  option (google.api.default_host) = "aiplatform.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Create an ExampleStore.
  rpc CreateExampleStore(CreateExampleStoreRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1beta1/{parent=projects/*/locations/*}/exampleStores"
      body: "example_store"
      additional_bindings {
        post: "/v1beta1/{parent=projects/*/locations/*}/exampleStores:create"
      }
    };
    option (google.api.method_signature) = "parent,example_store";
    option (google.longrunning.operation_info) = {
      response_type: "ExampleStore"
      metadata_type: "CreateExampleStoreOperationMetadata"
    };
  }

  // Get an ExampleStore.
  rpc GetExampleStore(GetExampleStoreRequest) returns (ExampleStore) {
    option (google.api.http) = {
      get: "/v1beta1/{name=projects/*/locations/*/exampleStores/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Update an ExampleStore.
  rpc UpdateExampleStore(UpdateExampleStoreRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      patch: "/v1beta1/{example_store.name=projects/*/locations/*/exampleStores/*}"
      body: "example_store"
    };
    option (google.api.method_signature) = "example_store,update_mask";
    option (google.longrunning.operation_info) = {
      response_type: "ExampleStore"
      metadata_type: "UpdateExampleStoreOperationMetadata"
    };
  }

  // Delete an ExampleStore.
  rpc DeleteExampleStore(DeleteExampleStoreRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      delete: "/v1beta1/{name=projects/*/locations/*/exampleStores/*}"
    };
    option (google.api.method_signature) = "name";
    option (google.longrunning.operation_info) = {
      response_type: "google.protobuf.Empty"
      metadata_type: "DeleteExampleStoreOperationMetadata"
    };
  }

  // List ExampleStores in a Location.
  rpc ListExampleStores(ListExampleStoresRequest)
      returns (ListExampleStoresResponse) {
    option (google.api.http) = {
      get: "/v1beta1/{parent=projects/*/locations/*}/exampleStores"
    };
    option (google.api.method_signature) = "parent";
  }

  // Create or update Examples in the Example Store.
  rpc UpsertExamples(UpsertExamplesRequest) returns (UpsertExamplesResponse) {
    option (google.api.http) = {
      post: "/v1beta1/{example_store=projects/*/locations/*/exampleStores/*}:upsertExamples"
      body: "*"
    };
  }

  // Remove Examples from the Example Store.
  rpc RemoveExamples(RemoveExamplesRequest) returns (RemoveExamplesResponse) {
    option (google.api.http) = {
      post: "/v1beta1/{example_store=projects/*/locations/*/exampleStores/*}:removeExamples"
      body: "*"
    };
  }

  // Search for similar Examples for given selection criteria.
  rpc SearchExamples(SearchExamplesRequest) returns (SearchExamplesResponse) {
    option (google.api.http) = {
      post: "/v1beta1/{example_store=projects/*/locations/*/exampleStores/*}:searchExamples"
      body: "*"
    };
  }

  // Get Examples from the Example Store.
  rpc FetchExamples(FetchExamplesRequest) returns (FetchExamplesResponse) {
    option (google.api.http) = {
      post: "/v1beta1/{example_store=projects/*/locations/*/exampleStores/*}:fetchExamples"
      body: "*"
    };
  }
}

// Request message for
// [ExampleStoreService.CreateExampleStore][google.cloud.aiplatform.v1beta1.ExampleStoreService.CreateExampleStore].
message CreateExampleStoreRequest {
  // Required. The resource name of the Location to create the ExampleStore in.
  // Format:
  // `projects/{project}/locations/{location}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "locations.googleapis.com/Location"
    }
  ];

  // Required. The Example Store to be created.
  ExampleStore example_store = 2 [(google.api.field_behavior) = REQUIRED];
}

// Details of
// [ExampleStoreService.CreateExampleStore][google.cloud.aiplatform.v1beta1.ExampleStoreService.CreateExampleStore]
// operation.
message CreateExampleStoreOperationMetadata {
  // The common part of the operation metadata.
  GenericOperationMetadata generic_metadata = 1;
}

// Request message for
// [ExampleStoreService.GetExampleStore][google.cloud.aiplatform.v1beta1.ExampleStoreService.GetExampleStore].
message GetExampleStoreRequest {
  // Required. The resource name of the ExampleStore.
  // Format:
  // `projects/{project}/locations/{location}/exampleStores/{example_store}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "aiplatform.googleapis.com/ExampleStore"
    }
  ];
}

// Request message for
// [ExampleStoreService.UpdateExampleStore][google.cloud.aiplatform.v1beta1.ExampleStoreService.UpdateExampleStore].
message UpdateExampleStoreRequest {
  // Required. The Example Store which replaces the resource on the server.
  ExampleStore example_store = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Mask specifying which fields to update.
  // Supported fields:
  //
  //    * `display_name`
  //    * `description`
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// Details of
// [ExampleStoreService.UpdateExampleStore][google.cloud.aiplatform.v1beta1.ExampleStoreService.UpdateExampleStore]
// operation.
message UpdateExampleStoreOperationMetadata {
  // The common part of the operation metadata.
  GenericOperationMetadata generic_metadata = 1;
}

// Request message for
// [ExampleStoreService.DeleteExampleStore][google.cloud.aiplatform.v1beta1.ExampleStoreService.DeleteExampleStore].
message DeleteExampleStoreRequest {
  // Required. The resource name of the ExampleStore to be deleted.
  // Format:
  // `projects/{project}/locations/{location}/exampleStores/{example_store}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "aiplatform.googleapis.com/ExampleStore"
    }
  ];
}

// Details of
// [ExampleStoreService.DeleteExampleStore][google.cloud.aiplatform.v1beta1.ExampleStoreService.DeleteExampleStore]
// operation.
message DeleteExampleStoreOperationMetadata {
  // The common part of the operation metadata.
  GenericOperationMetadata generic_metadata = 1;
}

// Request message for
// [ExampleStoreService.ListExampleStores][google.cloud.aiplatform.v1beta1.ExampleStoreService.ListExampleStores].
message ListExampleStoresRequest {
  // Required. The resource name of the Location to list the ExampleStores from.
  // Format:
  // `projects/{project}/locations/{location}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "locations.googleapis.com/Location"
    }
  ];

  // Optional. The standard list filter.
  // More detail in [AIP-160](https://google.aip.dev/160).
  string filter = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The standard list page size.
  int32 page_size = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The standard list page token.
  string page_token = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [ExampleStoreService.ListExampleStores][google.cloud.aiplatform.v1beta1.ExampleStoreService.ListExampleStores].
message ListExampleStoresResponse {
  // List of ExampleStore in the requested page.
  repeated ExampleStore example_stores = 1;

  // A token to retrieve the next page of results.
  // Pass to
  // [ListExampleStoresRequest.page_token][google.cloud.aiplatform.v1beta1.ListExampleStoresRequest.page_token]
  // to obtain that page.
  string next_page_token = 2;
}

// A single example to upload or read from the Example Store.
message Example {
  // The type of the example. Each example type has a defined format
  oneof example_type {
    // An example of chat history and its expected outcome to be used with
    // GenerateContent.
    StoredContentsExample stored_contents_example = 6;
  }

  // Optional. The display name for Example.
  string display_name = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Immutable. Unique identifier of an example. If not specified when
  // upserting new examples, the example_id will be generated.
  string example_id = 4 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Output only. Timestamp when this Example was created.
  google.protobuf.Timestamp create_time = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Request message for
// [ExampleStoreService.UpsertExamples][google.cloud.aiplatform.v1beta1.ExampleStoreService.UpsertExamples].
message UpsertExamplesRequest {
  // Required. The name of the ExampleStore resource that examples are added to
  // or updated in. Format:
  // `projects/{project}/locations/{location}/exampleStores/{example_store}`
  string example_store = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "aiplatform.googleapis.com/ExampleStore"
    }
  ];

  // Required. A list of examples to be created/updated.
  repeated Example examples = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. A flag indicating whether an example can be overwritten if it
  // already exists. If False (default) and the example already exists, the
  // example will not be updated. This does not affect behavior if the example
  // does not exist already.
  bool overwrite = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [ExampleStoreService.UpsertExamples][google.cloud.aiplatform.v1beta1.ExampleStoreService.UpsertExamples].
message UpsertExamplesResponse {
  // The result for creating/updating a single example.
  message UpsertResult {
    // The outcome of creating/updating a single example. It's either the
    // example that was successfully created/updated or a status with an error
    // message.
    oneof result {
      // The example created/updated successfully.
      Example example = 1;

      // The error message of the example that was not created/updated
      // successfully.
      google.rpc.Status status = 2;
    }
  }

  // A list of results for creating/updating. It's either a successfully
  // created/updated example or a status with an error message.
  repeated UpsertResult results = 1;
}

// Request message for
// [ExampleStoreService.RemoveExamples][google.cloud.aiplatform.v1beta1.ExampleStoreService.RemoveExamples].
message RemoveExamplesRequest {
  // The metadata filters that will be used to select which examples should be
  // removed.
  oneof metadata_filter {
    // The metadata filters for StoredContentsExamples.
    StoredContentsExampleFilter stored_contents_example_filter = 8;
  }

  // Required. The name of the ExampleStore resource that the examples should be
  // removed from. Format:
  // `projects/{project}/locations/{location}/exampleStores/{example_store}`
  string example_store = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "aiplatform.googleapis.com/ExampleStore"
    }
  ];

  // Optional. Example IDs to remove. If both metadata filters and Example IDs
  // are specified, the metadata filters will be applied to the specified
  // examples in order to identify which should be removed.
  repeated string example_ids = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [ExampleStoreService.RemoveExamples][google.cloud.aiplatform.v1beta1.ExampleStoreService.RemoveExamples].
message RemoveExamplesResponse {
  // The IDs for the removed examples.
  repeated string example_ids = 1;
}

// Request message for
// [ExampleStoreService.SearchExamples][google.cloud.aiplatform.v1beta1.ExampleStoreService.SearchExamples].
message SearchExamplesRequest {
  // The parameters to search for similar examples. This includes which value to
  // use for similarity search and the filters that should be applied to the
  // search. Filters limit which examples are considered as candidates for
  // similarity search.
  oneof parameters {
    // The parameters of StoredContentsExamples to be searched.
    StoredContentsExampleParameters stored_contents_example_parameters = 6;
  }

  // Required. The name of the ExampleStore resource that examples are retrieved
  // from. Format:
  // `projects/{project}/locations/{location}/exampleStores/{example_store}`
  string example_store = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "aiplatform.googleapis.com/ExampleStore"
    }
  ];

  // Optional. The number of similar examples to return.
  int64 top_k = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [ExampleStoreService.SearchExamples][google.cloud.aiplatform.v1beta1.ExampleStoreService.SearchExamples].
message SearchExamplesResponse {
  // The result of the similar example.
  message SimilarExample {
    // The example that is similar to the searched query.
    Example example = 1;

    // The similarity score of this example.
    float similarity_score = 2;
  }

  // The results of searching for similar examples.
  repeated SimilarExample results = 1;
}

// Request message for
// [ExampleStoreService.FetchExamples][google.cloud.aiplatform.v1beta1.ExampleStoreService.FetchExamples].
message FetchExamplesRequest {
  // The example type-specific filters to be applied to the fetch operation.
  oneof metadata_filter {
    // The metadata filters for StoredContentsExamples.
    StoredContentsExampleFilter stored_contents_example_filter = 8;
  }

  // Required. The name of the ExampleStore resource that the examples should be
  // fetched from. Format:
  // `projects/{project}/locations/{location}/exampleStores/{example_store}`
  string example_store = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "aiplatform.googleapis.com/ExampleStore"
    }
  ];

  // Optional. The maximum number of examples to return. The service may return
  // fewer than this value. If unspecified, at most 100 examples will be
  // returned.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The
  // [next_page_token][google.cloud.aiplatform.v1beta1.FetchExamplesResponse.next_page_token]
  // value returned from a previous list
  // [ExampleStoreService.FetchExamplesResponse][] call.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Example IDs to fetch. If both metadata filters and Example IDs
  // are specified, then both ID and metadata filtering will be applied.
  repeated string example_ids = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [ExampleStoreService.FetchExamples][google.cloud.aiplatform.v1beta1.ExampleStoreService.FetchExamples].
message FetchExamplesResponse {
  // The examples in the Example Store that satisfy the metadata filters.
  repeated Example examples = 1;

  // A token, which can be sent as [FetchExamplesRequest.page_token][] to
  // retrieve the next page. Absence of this field indicates there are no
  // subsequent pages.
  string next_page_token = 2;
}