// 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.v1;

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

option csharp_namespace = "Google.Cloud.GeminiDataAnalytics.V1";
option go_package = "cloud.google.com/go/geminidataanalytics/apiv1/geminidataanalyticspb;geminidataanalyticspb";
option java_multiple_files = true;
option java_outer_classname = "ContextProto";
option java_package = "com.google.cloud.geminidataanalytics.v1";
option php_namespace = "Google\\Cloud\\GeminiDataAnalytics\\V1";
option ruby_package = "Google::Cloud::GeminiDataAnalytics::V1";

// 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;

    // Optional. Sources which generated the schema relation edge.
    repeated Source sources = 3 [(google.api.field_behavior) = OPTIONAL];

    // Optional. A confidence score for the suggested relationship.
    // Manually added edges have the highest confidence score.
    float confidence_score = 4 [(google.api.field_behavior) = OPTIONAL];
  }

  // 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 and
  // databases (alloydb, cloudsql, spanner) 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. Only supported for Looker data sources.
  repeated LookerGoldenQuery looker_golden_queries = 11
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Term definitions (currently, only user authored)
  // Not supported for databases (alloydb, cloudsql, spanner) data sources.
  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];

  // Optional. A collection of user functions to be included in context.
  UserFunctions user_functions = 10 [(google.api.field_behavior) = OPTIONAL];
}

// A collection of user functions to be included in context.
message UserFunctions {
  // A list of BigQuery routines to include in the context.
  repeated BigQueryRoutine bq_routines = 1;
}

// A reference to a BigQuery routine.
message BigQueryRoutine {
  // The reference to the BigQuery routine.
  BigQueryRoutineReference routine_reference = 1;

  // User override or addition to description, to tell the agent when to use the
  // UDF.
  string description = 2;
}

// A reference to a BigQuery routine.
message BigQueryRoutineReference {
  // The project ID of the routine.
  string project_id = 1;

  // The dataset ID of the routine.
  string dataset_id = 2;

  // The routine ID of the routine.
  string routine_id = 3;
}

// 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];

  // Optional. The list of query parameters.
  // Example: The parameterized SQL query
  // "SELECT * FROM my_table WHERE id = @id" can be matched with any value of
  // id.
  repeated QueryParameter parameters = 3
      [(google.api.field_behavior) = OPTIONAL];
}

// A query parameter message represents a parameter that can be used to
// parameterize a SQL query.
message QueryParameter {
  // Required. The name of the parameter reference in the SQL query.
  string name = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The description of the parameter that can be used by LLM to
  // extract the parameter value from the user question.
  string description = 2 [(google.api.field_behavior) = OPTIONAL];

  // Required. The data type of the parameter, e.g. "STRING", "INT64", "DATE",
  // etc. For valid values, see the [BigQuery
  // documentation](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types).
  // This will be used to populate
  // google.cloud.bigquery.v2.QueryParameterType.type.
  string data_type = 3 [(google.api.field_behavior) = REQUIRED];
}

// A matched query message represents the agent having matched one of the
// example queries supplied in context as being applicable to the current
// question. It will also contain additional info during the matching process.
message MatchedQuery {
  // The query that was matched based on an example query.
  ExampleQuery example_query = 1;

  // The extracted values for the query parameters.
  repeated QueryParameterValues query_parameter_values = 2;
}

// A query parameter values message represents the values for the query
// parameters that were extracted from the user question by LLM, based on the
// example query.
message QueryParameterValues {
  // Required. The name of the parameter.
  string name = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The value of the parameter.
  string value = 2 [(google.api.field_behavior) = REQUIRED];
}

// 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];

    // Optional. The value for the field to filter on.
    // Optional so we can preserve the default value as an empty
    // string, important to get a valid and working Looker Explore url.
    optional string value = 2 [(google.api.field_behavior) = OPTIONAL];
  }

  // 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];

  // Optional. The primary identifier for the query resource in Looker, used for
  // API operations. Maps to `id` (or `slug`) in the Looker API `Query`
  // resource.
  optional string query_id = 10 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The short alphanumeric identifier for the query, used for share
  // links and Explore URLs (e.g., in the `qid` parameter). Maps to `client_id`
  // in the Looker API `Query` resource.
  optional string client_id = 11 [(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 {
  // Allowed models for the agent/conversation.
  enum Model {
    // No model specified. The model may be set on the chat request, or the
    // default model will be used. Currently, this is
    // `gemini-3.0-flash-preview`.
    MODEL_UNSPECIFIED = 0;

    // Use the most up-to-date non-preview model. Currently, this is
    // `gemini-2.5-flash`. This constrains the request level settings. The
    // default will change to `gemini-2.5-flash`, and setting `thinking_mode`
    // will not be supported.
    LATEST_GA_MODEL = 1;
  }

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

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

  // Optional. The model to use for the agent loop.
  optional Model model = 6 [(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 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];
}

// Source attributions for content.
message Citation {
  // Output only. List of the sources being cited.
  repeated CitationSource sources = 1
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. List of the anchors of the citations.
  repeated CitationAnchor anchors = 2
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The source of the citation.
message CitationSource {
  // The source of the citation, which can be one of the supported types.
  oneof source_type {
    // Output only. The uri used as the source, such as a web grounding URL.
    string uri = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The example query used as the source.
    ExampleQuery example_query = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The glossary term used as the source.
    GlossaryTerm glossary_term = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Output only. Unique identifier of the source. This ID is service-generated
  // and is unique within the scope of a single `Citation` message.
  string id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The title of the source.
  string title = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The anchor of the citation.
message CitationAnchor {
  // Citation anchor within a TextMessage.
  message TextMessageCitationAnchor {
    // Output only. The 0-based index of the part within the TextMessage.parts
    // field.
    int32 part_index = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The offset, measured in UTF-8 bytes, within the part string
    // where the citation begins (inclusive). Example: For the text "Hello,
    // world" where "world" is cited, the start offset bytes (inclusive) is 7
    // and the end offset bytes (exclusive) is 12.
    int32 start_offset_bytes = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The offset, measured in UTF-8 bytes, within the part string
    // where the citation ends (exclusive). Example: For the text "Hello, world"
    // where "world" is cited, the start offset bytes (inclusive) is 7 and the
    // end offset bytes (exclusive) is 12.
    int32 end_offset_bytes = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The ids of the sources that are cited.
    repeated string source_ids = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The anchor of the citation, which can be one of the supported types.
  oneof anchor_type {
    // Output only. Only set if the citation is for a TextMessage.
    TextMessageCitationAnchor text_message_anchor = 1
        [(google.api.field_behavior) = OUTPUT_ONLY];
  }
}