// 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/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/aiplatform/v1beta1/content.proto";
import "google/cloud/aiplatform/v1beta1/example.proto";
import "google/protobuf/timestamp.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 = "ExampleStoreProto";
option java_package = "com.google.cloud.aiplatform.v1beta1";
option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1";
option ruby_package = "Google::Cloud::AIPlatform::V1beta1";

// Represents an executable service to manage and retrieve examples.
message ExampleStore {
  option (google.api.resource) = {
    type: "aiplatform.googleapis.com/ExampleStore"
    pattern: "projects/{project}/locations/{location}/exampleStores/{example_store}"
    plural: "exampleStores"
    singular: "exampleStore"
  };

  // Identifier. The resource name of the ExampleStore. This is a unique
  // identifier. Format:
  // projects/{project}/locations/{location}/exampleStores/{example_store}
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Required. Display name of the ExampleStore.
  string display_name = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. Description of the ExampleStore.
  string description = 3 [(google.api.field_behavior) = OPTIONAL];

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

  // Output only. Timestamp when this ExampleStore was most recently updated.
  google.protobuf.Timestamp update_time = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. Example Store config.
  ExampleStoreConfig example_store_config = 6
      [(google.api.field_behavior) = REQUIRED];
}

// Configuration for the Example Store.
message ExampleStoreConfig {
  // Required. The embedding model to be used for vector embedding.
  // Immutable.
  // Supported models:
  // * "textembedding-gecko@003"
  // * "text-embedding-004"
  // * "text-embedding-005"
  // * "text-multilingual-embedding-002"
  string vertex_embedding_model = 1 [(google.api.field_behavior) = REQUIRED];
}

// The metadata filters that will be used to remove or fetch
// StoredContentsExamples. If a field is unspecified, then no filtering for that
// field will be applied.
message StoredContentsExampleFilter {
  // Optional. The search keys for filtering. Only examples with one of the
  // specified search keys
  // ([StoredContentsExample.search_key][google.cloud.aiplatform.v1beta1.StoredContentsExample.search_key])
  // are eligible to be returned.
  repeated string search_keys = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The function names for filtering.
  ExamplesArrayFilter function_names = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// The metadata filters that will be used to search StoredContentsExamples.
// If a field is unspecified, then no filtering for that field will be applied
message StoredContentsExampleParameters {
  // The chat history to use to generate the search key for retrieval.
  message ContentSearchKey {
    // Required. The conversation for generating a search key.
    repeated Content contents = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. The method of generating a search key.
    StoredContentsExample.SearchKeyGenerationMethod
        search_key_generation_method = 2
        [(google.api.field_behavior) = REQUIRED];
  }

  // The query to use to retrieve similar StoredContentsExamples.
  oneof query {
    // The exact search key to use for retrieval.
    string search_key = 1;

    // The chat history to use to generate the search key for retrieval.
    ContentSearchKey content_search_key = 2;
  }

  // Optional. The function names for filtering.
  ExamplesArrayFilter function_names = 3
      [(google.api.field_behavior) = OPTIONAL];
}

// Filters for examples' array metadata fields. An array field is example
// metadata where multiple values are attributed to a single example.
message ExamplesArrayFilter {
  // The logic to use for filtering.
  enum ArrayOperator {
    // Not specified. This value should not be used.
    ARRAY_OPERATOR_UNSPECIFIED = 0;

    // The metadata array field in the example must contain at least one of the
    // values.
    CONTAINS_ANY = 1;

    // The metadata array field in the example must contain all of the values.
    CONTAINS_ALL = 2;
  }

  // Required. The values by which to filter examples.
  repeated string values = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The operator logic to use for filtering.
  ArrayOperator array_operator = 2 [(google.api.field_behavior) = REQUIRED];
}