// 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.developers.knowledge.v1alpha;

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

option go_package = "google.golang.org/genproto/googleapis/developers/knowledge/v1alpha;knowledge";
option java_multiple_files = true;
option java_outer_classname = "DeveloperKnowledgeProto";
option java_package = "com.google.developers.knowledge.v1alpha";

// The Developer Knowledge API provides programmatic access to Google's public
// developer documentation, enabling you to integrate this knowledge base into
// your own applications and workflows.
//
// The API is designed to be the canonical source for machine-readable access to
// Google's developer documentation.
//
// A typical use case is to first use
// [DeveloperKnowledge.SearchDocumentChunks][google.developers.knowledge.v1alpha.DeveloperKnowledge.SearchDocumentChunks]
// to find relevant page URIs based on a query, and then use
// [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1alpha.DeveloperKnowledge.GetDocument]
// or
// [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments]
// to fetch the full content of the top results.
//
// All document content is provided in Markdown format.
service DeveloperKnowledge {
  option (google.api.default_host) = "developerknowledge.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Searches for developer knowledge across Google's developer documentation.
  // Returns [DocumentChunk][google.developers.knowledge.v1alpha.DocumentChunk]s
  // based on the user's query. There may be many chunks from the same
  // [Document][google.developers.knowledge.v1alpha.Document].  To retrieve full
  // documents, use
  // [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1alpha.DeveloperKnowledge.GetDocument]
  // or
  // [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments]
  // with the
  // [DocumentChunk.parent][google.developers.knowledge.v1alpha.DocumentChunk.parent]
  // returned in the
  // [SearchDocumentChunksResponse.results][google.developers.knowledge.v1alpha.SearchDocumentChunksResponse.results].
  rpc SearchDocumentChunks(SearchDocumentChunksRequest)
      returns (SearchDocumentChunksResponse) {
    option (google.api.http) = {
      get: "/v1alpha/documents:searchDocumentChunks"
    };
  }

  // Retrieves a single document with its full Markdown content.
  rpc GetDocument(GetDocumentRequest) returns (Document) {
    option (google.api.http) = {
      get: "/v1alpha/{name=documents/**}"
    };
    option (google.api.method_signature) = "name";
  }

  // Retrieves multiple documents, each with its full Markdown content.
  rpc BatchGetDocuments(BatchGetDocumentsRequest)
      returns (BatchGetDocumentsResponse) {
    option (google.api.http) = {
      get: "/v1alpha/documents:batchGet"
    };
  }

  // Answers a query using grounded generation.
  rpc AnswerQuery(AnswerQueryRequest) returns (AnswerQueryResponse) {
    option (google.api.http) = {
      post: "/v1alpha:answerQuery"
      body: "*"
    };
  }
}

// Specifies which fields of the
// [Document][google.developers.knowledge.v1alpha.Document] are included.
enum DocumentView {
  // The default / unset value. See each API method for its default value if
  // [DocumentView][google.developers.knowledge.v1alpha.DocumentView] is not
  // specified.
  DOCUMENT_VIEW_UNSPECIFIED = 0;

  // Includes only the basic metadata fields:
  // - `name`
  // - `uri`
  // - `data_source`
  // - `title`
  // - `description`
  // - `update_time`
  // - `view`
  //
  // This is the default of view for
  // [DeveloperKnowledge.SearchDocumentChunks][google.developers.knowledge.v1alpha.DeveloperKnowledge.SearchDocumentChunks].
  DOCUMENT_VIEW_BASIC = 1;

  // Includes all [Document][google.developers.knowledge.v1alpha.Document]
  // fields.
  DOCUMENT_VIEW_FULL = 2;

  // Includes the `DOCUMENT_VIEW_BASIC` fields and the `content` field.
  //
  // This is the default of view for
  // [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1alpha.DeveloperKnowledge.GetDocument]
  // and
  // [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments].
  DOCUMENT_VIEW_CONTENT = 3;
}

// A Document represents a piece of content from the Developer Knowledge corpus.
message Document {
  option (google.api.resource) = {
    type: "developerknowledge.googleapis.com/Document"
    pattern: "documents/{document}"
    plural: "documents"
    singular: "document"
  };

  // Identifier. Contains the resource name of the document.
  // Format: `documents/{uri_without_scheme}`
  // Example: `documents/docs.cloud.google.com/storage/docs/creating-buckets`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Output only. Provides the URI of the content, such as
  // `docs.cloud.google.com/storage/docs/creating-buckets`.
  string uri = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Contains the full content of the document in Markdown format.
  string content = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Provides a description of the document.
  string description = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Specifies the data source of the document.
  // Example data source: `firebase.google.com`
  string data_source = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Provides the title of the document.
  string title = 6 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Represents the timestamp when the content or metadata of the
  // document was last updated.
  google.protobuf.Timestamp update_time = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Specifies the
  // [DocumentView][google.developers.knowledge.v1alpha.DocumentView] of the
  // document.
  DocumentView view = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Request message for
// [DeveloperKnowledge.SearchDocumentChunks][google.developers.knowledge.v1alpha.DeveloperKnowledge.SearchDocumentChunks].
message SearchDocumentChunksRequest {
  // Required. Provides the raw query string provided by the user, such as "How
  // to create a Cloud Storage bucket?".
  string query = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Specifies the maximum number of results to return. The service
  // may return fewer than this value.
  //
  // If unspecified, at most 5 results will be returned.
  //
  // The maximum value is 20; values above 20 will result in an INVALID_ARGUMENT
  // error.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Contains a page token, received from a previous
  // `SearchDocumentChunks` call. Provide this to retrieve the subsequent page.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Applies a strict filter to the search results. The expression
  // supports a subset of the syntax described at https://google.aip.dev/160.
  //
  // While `SearchDocumentChunks` returns
  // [DocumentChunk][google.developers.knowledge.v1alpha.DocumentChunk]s, the
  // filter is applied to `DocumentChunk.document` fields.
  //
  // Supported fields for filtering:
  //
  // * `data_source` (STRING): The source of the document, e.g.
  //   `docs.cloud.google.com`. See
  //   https://developers.google.com/knowledge/reference/corpus-reference for
  //   the complete list of data sources in the corpus.
  // * `update_time` (TIMESTAMP): The timestamp of when the document was last
  //   meaningfully updated. A meaningful update is one that changes document's
  //   markdown content or metadata.
  // * `uri` (STRING): The document URI, e.g.
  //   `https://docs.cloud.google.com/bigquery/docs/tables`.
  //
  // STRING fields support `=` (equals) and `!=` (not equals) operators for
  // **exact match** on the whole string. Partial match, prefix match, and
  // regexp match are not supported.
  //
  // TIMESTAMP fields support `=`, `<`, `<=`, `>`, and `>=` operators.
  // Timestamps must be in RFC-3339 format, e.g., `"2025-01-01T00:00:00Z"`.
  //
  // You can combine expressions using `AND`, `OR`, and `NOT` (or `-`) logical
  // operators. `OR` has higher precedence than `AND`. Use parentheses for
  // explicit precedence grouping.
  //
  // Examples:
  //
  // * `data_source = "docs.cloud.google.com" OR data_source =
  // "firebase.google.com"`
  // * `data_source != "firebase.google.com"`
  // * `update_time < "2024-01-01T00:00:00Z"`
  // * `update_time >= "2025-01-22T00:00:00Z" AND (data_source =
  // "developer.chrome.com" OR data_source = "web.dev")`
  // * `uri = "https://docs.cloud.google.com/release-notes"`
  //
  // The `filter` string must not exceed 500 characters; values longer than 500
  // characters will result in an `INVALID_ARGUMENT` error.
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [DeveloperKnowledge.SearchDocumentChunks][google.developers.knowledge.v1alpha.DeveloperKnowledge.SearchDocumentChunks].
message SearchDocumentChunksResponse {
  // Contains the search results for the given query. Each
  // [DocumentChunk][google.developers.knowledge.v1alpha.DocumentChunk] in this
  // list contains a snippet of content relevant to the search query. Use the
  // [DocumentChunk.parent][google.developers.knowledge.v1alpha.DocumentChunk.parent]
  // field of each result with
  // [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1alpha.DeveloperKnowledge.GetDocument]
  // or
  // [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments]
  // to retrieve the full document content.
  repeated DocumentChunk results = 1;

  // Optional. Provides a token that can be sent as `page_token` to retrieve the
  // next page. If this field is omitted, there are no subsequent pages.
  string next_page_token = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for
// [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1alpha.DeveloperKnowledge.GetDocument].
message GetDocumentRequest {
  // Required. Specifies the name of the document to retrieve.
  // Format: `documents/{uri_without_scheme}`
  // Example: `documents/docs.cloud.google.com/storage/docs/creating-buckets`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "developerknowledge.googleapis.com/Document"
    }
  ];

  // Optional. Specifies the
  // [DocumentView][google.developers.knowledge.v1alpha.DocumentView] of the
  // document. If unspecified,
  // [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1alpha.DeveloperKnowledge.GetDocument]
  // defaults to `DOCUMENT_VIEW_CONTENT`.
  DocumentView view = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for
// [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments].
message BatchGetDocumentsRequest {
  // Required. Specifies the names of the documents to retrieve. A maximum of 20
  // documents can be retrieved in a batch. The documents are returned in the
  // same order as the `names` in the request.
  //
  // Format: `documents/{uri_without_scheme}`
  // Example: `documents/docs.cloud.google.com/storage/docs/creating-buckets`
  repeated string names = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "developerknowledge.googleapis.com/Document"
    }
  ];

  // Optional. Specifies the
  // [DocumentView][google.developers.knowledge.v1alpha.DocumentView] of the
  // document. If unspecified,
  // [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments]
  // defaults to `DOCUMENT_VIEW_CONTENT`.
  DocumentView view = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments].
message BatchGetDocumentsResponse {
  // Contains the documents requested.
  repeated Document documents = 1;
}

// Request message for
// [DeveloperKnowledge.AnswerQuery][google.developers.knowledge.v1alpha.DeveloperKnowledge.AnswerQuery].
message AnswerQueryRequest {
  // Required. The query to answer.
  string query = 1 [(google.api.field_behavior) = REQUIRED];
}

// Response message for
// [DeveloperKnowledge.AnswerQuery][google.developers.knowledge.v1alpha.DeveloperKnowledge.AnswerQuery].
message AnswerQueryResponse {
  // The answer to the query.
  Answer answer = 1;
}

// An answer to a query.
message Answer {
  // The text of the answer.
  string answer_text = 1;
}

// A DocumentChunk represents a piece of content from a
// [Document][google.developers.knowledge.v1alpha.Document] in the
// DeveloperKnowledge corpus. To fetch the entire document content, pass the
// `parent` to
// [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1alpha.DeveloperKnowledge.GetDocument]
// or
// [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments].
message DocumentChunk {
  // Output only. Contains the resource name of the document this chunk is from.
  // Format: `documents/{uri_without_scheme}`
  // Example: `documents/docs.cloud.google.com/storage/docs/creating-buckets`
  string parent = 1 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = {
      type: "developerknowledge.googleapis.com/Document"
    }
  ];

  // Output only. Specifies the ID of this chunk within the document. The chunk
  // ID is unique within a document, but not globally unique across documents.
  // The chunk ID is not stable and may change over time.
  string id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Contains the content of the document chunk.
  string content = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Represents metadata about the
  // [Document][google.developers.knowledge.v1alpha.Document] this chunk is
  // from. The [DocumentView][google.developers.knowledge.v1alpha.DocumentView]
  // of this [Document][google.developers.knowledge.v1alpha.Document] message
  // will be set to `DOCUMENT_VIEW_BASIC`. It is included here for convenience
  // so that clients do not need to call
  // [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1alpha.DeveloperKnowledge.GetDocument]
  // or
  // [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments]
  // if they only need the metadata fields. Otherwise, clients should use
  // [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1alpha.DeveloperKnowledge.GetDocument]
  // or
  // [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments]
  // to fetch the full document content.
  Document document = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
}