// 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.shopping.merchant.productstudio.v1alpha;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/struct.proto";

option go_package = "cloud.google.com/go/shopping/merchant/productstudio/apiv1alpha/productstudiopb;productstudiopb";
option java_multiple_files = true;
option java_outer_classname = "TextSuggestionsProto";
option java_package = "com.google.shopping.merchant.productstudio.v1alpha";

// Service that exposes Generative AI (GenAI) endpoints for creating and
// enhancing product text content, such as titles, descriptions, etc.
service TextSuggestionsService {
  option (google.api.default_host) = "merchantapi.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/content";

  // GenerateProductTextSuggestions generates a set of candidate text
  // completions (e.g., product titles, descriptions) based on provided product
  // information. This endpoint leverages GenAI models to create suggestions for
  // improving existing product text or generating new content.
  rpc GenerateProductTextSuggestions(GenerateProductTextSuggestionsRequest)
      returns (GenerateProductTextSuggestionsResponse) {
    option (google.api.http) = {
      post: "/productstudio/v1alpha/{name=accounts/*}:generateProductTextSuggestions"
      body: "*"
    };
    option (google.api.method_signature) = "name";
  }
}

// Request message for the GenerateProductTextSuggestions method.
message GenerateProductTextSuggestionsRequest {
  // Required. The name of the account to generate text suggestions for. This
  // acts as a container for the request and does not affect the generation
  // itself, as this is a stateless API. Format: accounts/{account}
  string name = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. Available information about the product. Used to inform the genAI
  // models.
  ProductInfo product_info = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. Configuration parameters that directly influence what content is
  // generated, and how that content is rendered in the final response.
  optional OutputSpec output_spec = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Provide some hand-crafted examples of title improvements that are
  // unique to your use case. This is a general tool that handles multiple
  // product categories, but your brand identity may require custom
  // functionality. Feel free to specify that here.
  repeated TitleExample title_examples = 4
      [(google.api.field_behavior) = OPTIONAL];
}

// Response message for the GenerateProductTextSuggestions method.
message GenerateProductTextSuggestionsResponse {
  // Generated title suggestion.
  optional ProductTextGenerationSuggestion title = 1;

  // Generated description suggestion.
  optional ProductTextGenerationSuggestion description = 2;

  // Any other generated attributes.
  map<string, string> attributes = 3;

  // Additional info that clients may want to audit surrounding the generation.
  optional ProductTextGenerationMetadata metadata = 4;
}

// A hand-crafted example of a product title improvement. These examples are
// provided to the AI to improve its quality and guide it towards required
// outputs.
message TitleExample {
  // Required. A map containing all existing product information. For example:
  // {"title": "dress", "description": "A red dress", "brand": "Dresses4All"}
  // Any information that you might use to populate your product feed.
  map<string, string> product_info = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The product's category. This helps the AI understand when certain
  // examples are more relevant than others.
  optional string category = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The attributes or approximate attributes that make up the title.
  // For example, title "Google GShoe M" title_format can be "brand | product |
  // size".
  optional string title_format = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. A map in the same format as product_info but with all
  // improvements included. For example, {"brand": "Dresses4All", "product":
  // "dress", "color": "red", ...}. The order of attributes in this map may be
  // used to guide the order in which they appear in the final generated title.
  // For instance, the above will become: Dresses4All dress | red
  map<string, string> final_product_info = 4
      [(google.api.field_behavior) = REQUIRED];
}

// Wrapper data type for any metadata associated with text generation.
message ProductTextGenerationMetadata {
  // Metadata is a pretty loose concept. The data is modeled as a map here to
  // indicate that there is no guaranteed structure to the output past a simple
  // K:V association.
  // The first use-case is to track words added/removed/changed in generations.
  google.protobuf.Struct metadata = 1;
}

// Product image represented as bytes directly or a URI.
message Image {
  // Required. The image to use for text generation.
  oneof image {
    // Generally web-requestable URI.
    string uri = 1;

    // Raw bytes for the image.
    bytes data = 2;
  }
}

// Available information about the product. Used to inform the genAI models.
message ProductInfo {
  // Required. A mapping of all available product attributes. This may include
  // title, description, brand, gender, color, size, etc.
  map<string, string> product_attributes = 1
      [(google.api.field_behavior) = REQUIRED];

  // Optional. Image associated with the product.
  optional Image product_image = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Configuration parameters that directly influence what content is generated,
// and how that content is rendered in the final response.
message OutputSpec {
  // Optional. The workflow to execute for the provided product data. Workflows
  // may populate the response's title, description, or both. Currently
  // supported workflow_ids are: "title", "description", and "tide"
  optional string workflow_id = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The tone of the output generated text. Supported tones are:
  // "playful", "formal", "persuasive", and "conversational"
  optional string tone = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Any editorial changes for the generated product data. For
  // example, replace Small with "S", do not modify color if already present.
  optional string editorial_changes = 3
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The language for output titles/descriptions. For example.
  // 'German', 'es', 'FR'. Default is 'en'.
  optional string target_language = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The order that generated attributes should be placed in the
  // generated title. Eg., if the attribute order is ["brand", "product",
  // "size"], the generated title will have brand first, followed by the product
  // name, and then size information after that.
  repeated string attribute_order = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Character used to separate attributes in the generated title.
  // For example, '|', '-', ','.
  optional string attribute_separator = 6
      [(google.api.field_behavior) = OPTIONAL];
}

// Text generated for a product, optionally including its quality score.
message ProductTextGenerationSuggestion {
  // The text generated
  optional string text = 1;

  // The quality score associated with the generation. Heuristic implemented
  // according to the feedgen team's implementation styles.
  optional float score = 2;

  // A brief summarization of all the changes that have been made.
  optional string change_summary = 3;
}