// 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.geminidataanalytics.v1beta;

import "google/api/field_behavior.proto";
import "google/cloud/geminidataanalytics/v1beta/datasource.proto";

option csharp_namespace = "Google.Cloud.GeminiDataAnalytics.V1Beta";
option go_package = "cloud.google.com/go/geminidataanalytics/apiv1beta/geminidataanalyticspb;geminidataanalyticspb";
option java_multiple_files = true;
option java_outer_classname = "ContextProto";
option java_package = "com.google.cloud.geminidataanalytics.v1beta";
option php_namespace = "Google\\Cloud\\GeminiDataAnalytics\\V1beta";
option ruby_package = "Google::Cloud::GeminiDataAnalytics::V1beta";

// A collection of context to apply to this conversation
message Context {
  // Optional. The basic entry point for data owners creating domain knowledge
  // for Agent.
  //
  // Why: Business jargon (e.g., YTD revenue is calculated as…, Retirement Age
  // is 65 in the USA, etc) and system instructions (e.g., answer like a Pirate)
  // can help the model understand the business context around a user question.
  string system_instruction = 1 [(google.api.field_behavior) = OPTIONAL];

  // Required. Data sources that are available for answering the question.
  DatasourceReferences datasource_references = 7
      [(google.api.field_behavior) = REQUIRED];

  // Optional. Additional options for the conversation.
  ConversationOptions options = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of example queries, providing examples of relevant and
  // commonly used SQL queries and their corresponding natural language queries
  // optionally present.
  repeated ExampleQuery example_queries = 5
      [(google.api.field_behavior) = OPTIONAL];
}

// Example of relevant and commonly used SQL query and its corresponding natural
// language queries optionally present.
message ExampleQuery {
  // The SQL or Looker query that should be generated to answer the natural
  // language query.
  oneof query {
    // Optional. The SQL query that should be generated to answer the natural
    // language question. For example: "SELECT COUNT(*) FROM orders WHERE
    // order_date BETWEEN '2024-01-01' AND '2024-01-31'"
    string sql_query = 101 [(google.api.field_behavior) = OPTIONAL];
  }

  // Optional. A natural language question that a user might ask.
  // For example: "How many orders were placed last month?"
  string natural_language_question = 1 [(google.api.field_behavior) = OPTIONAL];
}

// Options for the conversation.
message ConversationOptions {
  // Optional. Options for chart generation.
  ChartOptions chart = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Options for analysis.
  AnalysisOptions analysis = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Options for chart generation.
message ChartOptions {
  // Options for rendering images of generated charts.
  message ImageOptions {
    // No image.
    message NoImage {}

    // SVG options.
    message SvgOptions {}

    // The kind of image to render.
    oneof kind {
      // No image.
      NoImage no_image = 1;

      // SVG format.
      SvgOptions svg = 2;
    }
  }

  // Optional. When specified, the agent will render generated charts using the
  // provided format. Defaults to no image.
  ImageOptions image = 1 [(google.api.field_behavior) = OPTIONAL];
}

// Options for analysis.
message AnalysisOptions {
  // Options for Python analysis.
  message Python {
    // Optional. Whether to enable Python analysis.
    // Defaults to false.
    bool enabled = 1 [(google.api.field_behavior) = OPTIONAL];
  }

  // Optional. Options for Python analysis.
  Python python = 1 [(google.api.field_behavior) = OPTIONAL];
}