// Copyright 2026 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.v1alpha;

import "google/api/field_behavior.proto";
import "google/cloud/geminidataanalytics/v1alpha/datasource.proto";
import "google/protobuf/wrappers.proto";

option csharp_namespace = "Google.Cloud.GeminiDataAnalytics.V1Alpha";
option go_package = "cloud.google.com/go/geminidataanalytics/apiv1alpha/geminidataanalyticspb;geminidataanalyticspb";
option java_multiple_files = true;
option java_outer_classname = "ContextProto";
option java_package = "com.google.cloud.geminidataanalytics.v1alpha";
option php_namespace = "Google\\Cloud\\GeminiDataAnalytics\\V1alpha";
option ruby_package = "Google::Cloud::GeminiDataAnalytics::V1alpha";

// A collection of context to apply to this conversation
message Context {
  // The relationship between two tables, including referencing and referenced
  // columns. This is a derived context retrieved from Dataplex Dataset
  // Insights.
  message SchemaRelationship {
    // Represents an ordered set of paths within the table schema.
    message SchemaPaths {
      // The service-qualified full resource name of the table
      // Ex:
      // bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID
      string table_fqn = 1;

      // The ordered list of paths within the table schema.
      repeated string paths = 2;
    }

    // Source which generated the schema relation edge.
    enum Source {
      // The source of the schema relationship is unspecified.
      SOURCE_UNSPECIFIED = 0;

      // The source of the schema relationship is BigQuery job history.
      BIGQUERY_JOB_HISTORY = 1;

      // The source of the schema relationship is LLM suggested.
      LLM_SUGGESTED = 2;

      // The source of the schema relationship is BigQuery table constraints.
      BIGQUERY_TABLE_CONSTRAINTS = 3;
    }

    // An ordered list of fields for the join from the first table.
    // The size of this list must be the same as `right_schema_paths`.
    // Each field at index i in this list must correspond to a field at the same
    // index in the `right_schema_paths` list.
    SchemaPaths left_schema_paths = 1;

    // An ordered list of fields for the join from the second table.
    // The size of this list must be the same as `left_schema_paths`.
    // Each field at index i in this list must correspond to a field at the same
    // index in the `left_schema_paths` list.
    SchemaPaths right_schema_paths = 2;

    // Sources which generated the schema relation edge.
    repeated Source sources = 3;

    // A confidence score for the suggested relationship.
    // Manually added edges have the highest confidence score.
    float confidence_score = 4;
  }

  // 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. Currently only used for BigQuery data sources.
  repeated ExampleQuery example_queries = 5
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of golden queries, providing examples of relevant and
  // commonly used Looker queries and their corresponding natural language
  // queries optionally present.
  repeated LookerGoldenQuery looker_golden_queries = 11
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Term definitions (currently, only user authored)
  repeated GlossaryTerm glossary_terms = 8
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Relationships between table schema, including referencing and
  // referenced columns.
  repeated SchemaRelationship schema_relationships = 9
      [(google.api.field_behavior) = OPTIONAL];
}

// Example of relevant and commonly used SQL query and its corresponding natural
// language queries optionally present. Currently only used for BigQuery data
// sources.
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];
}

// A golden query for Looker, including natural language questions and a
// corresponding Looker Query. Analogous to ExampleQuery.
message LookerGoldenQuery {
  // Optional. Natural language questions that a user might ask.
  // For example: "How many orders were placed last month?"
  repeated string natural_language_questions = 4
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The Looker Query corresponding to the natural language questions.
  LookerQuery looker_query = 5 [(google.api.field_behavior) = OPTIONAL];
}

// Looker Query Object
// [Looker API
// documentation](https://cloud.google.com/looker/docs/reference/looker-api/latest/methods/Query/run_inline_query).
message LookerQuery {
  // A Looker query filter.
  message Filter {
    // Required. The field to filter on.
    string field = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. The value for the field to filter on.
    string value = 2 [(google.api.field_behavior) = REQUIRED];
  }

  // Required. The LookML model used to generate the query.
  string model = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The LookML explore used to generate the query.
  string explore = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. The fields to retrieve from the explore.
  repeated string fields = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The filters to apply to the explore.
  repeated Filter filters = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The sorts to apply to the explore.
  repeated string sorts = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Limit in the query.
  optional string limit = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Definition of a term within a specific domain.
message GlossaryTerm {
  // Required. User friendly display name of the glossary term being defined.
  // For example: "CTR", "conversion rate", "pending"
  string display_name = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The description or meaning of the term.
  // For example: "Click-through rate", "The percentage of users who complete a
  // desired action", "An order that is waiting to be processed."
  string description = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. A list of general purpose labels associated to this term.
  // For example: ["click rate", "clickthrough", "waiting"]
  repeated string labels = 3 [(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];

  // Optional. Options for datasources.
  DatasourceOptions datasource = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Options for datasources configurations.
message DatasourceOptions {
  // Optional. This option applies to datasources that require BigQuery queries
  // only. Limits the bytes billed for each BQ query job. Queries that will have
  // bytes billed beyond this limit will fail (without incurring a charge).
  // If unspecified, no limit will be applied.
  google.protobuf.Int64Value big_query_max_billed_bytes = 1
      [(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];
}