Add files using upload-large-folder tool

.venv/lib/python3.11/site-packages/google/api/backend.proto

@@ -0,0 +1,185 @@
+// Copyright 2024 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.api;
+
+option go_package = "google.golang.org/genproto/googleapis/api/serviceconfig;serviceconfig";
+option java_multiple_files = true;
+option java_outer_classname = "BackendProto";
+option java_package = "com.google.api";
+option objc_class_prefix = "GAPI";
+
+// `Backend` defines the backend configuration for a service.
+message Backend {
+  // A list of API backend rules that apply to individual API methods.
+  //
+  // **NOTE:** All service configuration rules follow "last one wins" order.
+  repeated BackendRule rules = 1;
+}
+
+// A backend rule provides configuration for an individual API element.
+message BackendRule {
+  // Path Translation specifies how to combine the backend address with the
+  // request path in order to produce the appropriate forwarding URL for the
+  // request.
+  //
+  // Path Translation is applicable only to HTTP-based backends. Backends which
+  // do not accept requests over HTTP/HTTPS should leave `path_translation`
+  // unspecified.
+  enum PathTranslation {
+    PATH_TRANSLATION_UNSPECIFIED = 0;
+
+    // Use the backend address as-is, with no modification to the path. If the
+    // URL pattern contains variables, the variable names and values will be
+    // appended to the query string. If a query string parameter and a URL
+    // pattern variable have the same name, this may result in duplicate keys in
+    // the query string.
+    //
+    // # Examples
+    //
+    // Given the following operation config:
+    //
+    //     Method path:        /api/company/{cid}/user/{uid}
+    //     Backend address:    https://example.cloudfunctions.net/getUser
+    //
+    // Requests to the following request paths will call the backend at the
+    // translated path:
+    //
+    //     Request path: /api/company/widgetworks/user/johndoe
+    //     Translated:
+    //     https://example.cloudfunctions.net/getUser?cid=widgetworks&uid=johndoe
+    //
+    //     Request path: /api/company/widgetworks/user/johndoe?timezone=EST
+    //     Translated:
+    //     https://example.cloudfunctions.net/getUser?timezone=EST&cid=widgetworks&uid=johndoe
+    CONSTANT_ADDRESS = 1;
+
+    // The request path will be appended to the backend address.
+    //
+    // # Examples
+    //
+    // Given the following operation config:
+    //
+    //     Method path:        /api/company/{cid}/user/{uid}
+    //     Backend address:    https://example.appspot.com
+    //
+    // Requests to the following request paths will call the backend at the
+    // translated path:
+    //
+    //     Request path: /api/company/widgetworks/user/johndoe
+    //     Translated:
+    //     https://example.appspot.com/api/company/widgetworks/user/johndoe
+    //
+    //     Request path: /api/company/widgetworks/user/johndoe?timezone=EST
+    //     Translated:
+    //     https://example.appspot.com/api/company/widgetworks/user/johndoe?timezone=EST
+    APPEND_PATH_TO_ADDRESS = 2;
+  }
+
+  // Selects the methods to which this rule applies.
+  //
+  // Refer to [selector][google.api.DocumentationRule.selector] for syntax
+  // details.
+  string selector = 1;
+
+  // The address of the API backend.
+  //
+  // The scheme is used to determine the backend protocol and security.
+  // The following schemes are accepted:
+  //
+  //    SCHEME        PROTOCOL    SECURITY
+  //    http://       HTTP        None
+  //    https://      HTTP        TLS
+  //    grpc://       gRPC        None
+  //    grpcs://      gRPC        TLS
+  //
+  // It is recommended to explicitly include a scheme. Leaving out the scheme
+  // may cause constrasting behaviors across platforms.
+  //
+  // If the port is unspecified, the default is:
+  // - 80 for schemes without TLS
+  // - 443 for schemes with TLS
+  //
+  // For HTTP backends, use [protocol][google.api.BackendRule.protocol]
+  // to specify the protocol version.
+  string address = 2;
+
+  // The number of seconds to wait for a response from a request. The default
+  // varies based on the request protocol and deployment environment.
+  double deadline = 3;
+
+  // Deprecated, do not use.
+  double min_deadline = 4 [deprecated = true];
+
+  // The number of seconds to wait for the completion of a long running
+  // operation. The default is no deadline.
+  double operation_deadline = 5;
+
+  PathTranslation path_translation = 6;
+
+  // Authentication settings used by the backend.
+  //
+  // These are typically used to provide service management functionality to
+  // a backend served on a publicly-routable URL. The `authentication`
+  // details should match the authentication behavior used by the backend.
+  //
+  // For example, specifying `jwt_audience` implies that the backend expects
+  // authentication via a JWT.
+  //
+  // When authentication is unspecified, the resulting behavior is the same
+  // as `disable_auth` set to `true`.
+  //
+  // Refer to https://developers.google.com/identity/protocols/OpenIDConnect for
+  // JWT ID token.
+  oneof authentication {
+    // The JWT audience is used when generating a JWT ID token for the backend.
+    // This ID token will be added in the HTTP "authorization" header, and sent
+    // to the backend.
+    string jwt_audience = 7;
+
+    // When disable_auth is true, a JWT ID token won't be generated and the
+    // original "Authorization" HTTP header will be preserved. If the header is
+    // used to carry the original token and is expected by the backend, this
+    // field must be set to true to preserve the header.
+    bool disable_auth = 8;
+  }
+
+  // The protocol used for sending a request to the backend.
+  // The supported values are "http/1.1" and "h2".
+  //
+  // The default value is inferred from the scheme in the
+  // [address][google.api.BackendRule.address] field:
+  //
+  //    SCHEME        PROTOCOL
+  //    http://       http/1.1
+  //    https://      http/1.1
+  //    grpc://       h2
+  //    grpcs://      h2
+  //
+  // For secure HTTP backends (https://) that support HTTP/2, set this field
+  // to "h2" for improved performance.
+  //
+  // Configuring this field to non-default values is only supported for secure
+  // HTTP backends. This field will be ignored for all other backends.
+  //
+  // See
+  // https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids
+  // for more details on the supported values.
+  string protocol = 9;
+
+  // The map between request protocol and the backend address.
+  map<string, BackendRule> overrides_by_request_protocol = 10;
+}

.venv/lib/python3.11/site-packages/google/api/client.proto

@@ -0,0 +1,462 @@
+// Copyright 2024 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.api;
+
+import "google/api/launch_stage.proto";
+import "google/protobuf/descriptor.proto";
+import "google/protobuf/duration.proto";
+
+option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations";
+option java_multiple_files = true;
+option java_outer_classname = "ClientProto";
+option java_package = "com.google.api";
+option objc_class_prefix = "GAPI";
+
+extend google.protobuf.MethodOptions {
+  // A definition of a client library method signature.
+  //
+  // In client libraries, each proto RPC corresponds to one or more methods
+  // which the end user is able to call, and calls the underlying RPC.
+  // Normally, this method receives a single argument (a struct or instance
+  // corresponding to the RPC request object). Defining this field will
+  // add one or more overloads providing flattened or simpler method signatures
+  // in some languages.
+  //
+  // The fields on the method signature are provided as a comma-separated
+  // string.
+  //
+  // For example, the proto RPC and annotation:
+  //
+  //   rpc CreateSubscription(CreateSubscriptionRequest)
+  //       returns (Subscription) {
+  //     option (google.api.method_signature) = "name,topic";
+  //   }
+  //
+  // Would add the following Java overload (in addition to the method accepting
+  // the request object):
+  //
+  //   public final Subscription createSubscription(String name, String topic)
+  //
+  // The following backwards-compatibility guidelines apply:
+  //
+  //   * Adding this annotation to an unannotated method is backwards
+  //     compatible.
+  //   * Adding this annotation to a method which already has existing
+  //     method signature annotations is backwards compatible if and only if
+  //     the new method signature annotation is last in the sequence.
+  //   * Modifying or removing an existing method signature annotation is
+  //     a breaking change.
+  //   * Re-ordering existing method signature annotations is a breaking
+  //     change.
+  repeated string method_signature = 1051;
+}
+
+extend google.protobuf.ServiceOptions {
+  // The hostname for this service.
+  // This should be specified with no prefix or protocol.
+  //
+  // Example:
+  //
+  //   service Foo {
+  //     option (google.api.default_host) = "foo.googleapi.com";
+  //     ...
+  //   }
+  string default_host = 1049;
+
+  // OAuth scopes needed for the client.
+  //
+  // Example:
+  //
+  //   service Foo {
+  //     option (google.api.oauth_scopes) = \
+  //       "https://www.googleapis.com/auth/cloud-platform";
+  //     ...
+  //   }
+  //
+  // If there is more than one scope, use a comma-separated string:
+  //
+  // Example:
+  //
+  //   service Foo {
+  //     option (google.api.oauth_scopes) = \
+  //       "https://www.googleapis.com/auth/cloud-platform,"
+  //       "https://www.googleapis.com/auth/monitoring";
+  //     ...
+  //   }
+  string oauth_scopes = 1050;
+
+  // The API version of this service, which should be sent by version-aware
+  // clients to the service. This allows services to abide by the schema and
+  // behavior of the service at the time this API version was deployed.
+  // The format of the API version must be treated as opaque by clients.
+  // Services may use a format with an apparent structure, but clients must
+  // not rely on this to determine components within an API version, or attempt
+  // to construct other valid API versions. Note that this is for upcoming
+  // functionality and may not be implemented for all services.
+  //
+  // Example:
+  //
+  //   service Foo {
+  //     option (google.api.api_version) = "v1_20230821_preview";
+  //   }
+  string api_version = 525000001;
+}
+
+// Required information for every language.
+message CommonLanguageSettings {
+  // Link to automatically generated reference documentation.  Example:
+  // https://cloud.google.com/nodejs/docs/reference/asset/latest
+  string reference_docs_uri = 1 [deprecated = true];
+
+  // The destination where API teams want this client library to be published.
+  repeated ClientLibraryDestination destinations = 2;
+
+  // Configuration for which RPCs should be generated in the GAPIC client.
+  SelectiveGapicGeneration selective_gapic_generation = 3;
+}
+
+// Details about how and where to publish client libraries.
+message ClientLibrarySettings {
+  // Version of the API to apply these settings to. This is the full protobuf
+  // package for the API, ending in the version element.
+  // Examples: "google.cloud.speech.v1" and "google.spanner.admin.database.v1".
+  string version = 1;
+
+  // Launch stage of this version of the API.
+  LaunchStage launch_stage = 2;
+
+  // When using transport=rest, the client request will encode enums as
+  // numbers rather than strings.
+  bool rest_numeric_enums = 3;
+
+  // Settings for legacy Java features, supported in the Service YAML.
+  JavaSettings java_settings = 21;
+
+  // Settings for C++ client libraries.
+  CppSettings cpp_settings = 22;
+
+  // Settings for PHP client libraries.
+  PhpSettings php_settings = 23;
+
+  // Settings for Python client libraries.
+  PythonSettings python_settings = 24;
+
+  // Settings for Node client libraries.
+  NodeSettings node_settings = 25;
+
+  // Settings for .NET client libraries.
+  DotnetSettings dotnet_settings = 26;
+
+  // Settings for Ruby client libraries.
+  RubySettings ruby_settings = 27;
+
+  // Settings for Go client libraries.
+  GoSettings go_settings = 28;
+}
+
+// This message configures the settings for publishing [Google Cloud Client
+// libraries](https://cloud.google.com/apis/docs/cloud-client-libraries)
+// generated from the service config.
+message Publishing {
+  // A list of API method settings, e.g. the behavior for methods that use the
+  // long-running operation pattern.
+  repeated MethodSettings method_settings = 2;
+
+  // Link to a *public* URI where users can report issues.  Example:
+  // https://issuetracker.google.com/issues/new?component=190865&template=1161103
+  string new_issue_uri = 101;
+
+  // Link to product home page.  Example:
+  // https://cloud.google.com/asset-inventory/docs/overview
+  string documentation_uri = 102;
+
+  // Used as a tracking tag when collecting data about the APIs developer
+  // relations artifacts like docs, packages delivered to package managers,
+  // etc.  Example: "speech".
+  string api_short_name = 103;
+
+  // GitHub label to apply to issues and pull requests opened for this API.
+  string github_label = 104;
+
+  // GitHub teams to be added to CODEOWNERS in the directory in GitHub
+  // containing source code for the client libraries for this API.
+  repeated string codeowner_github_teams = 105;
+
+  // A prefix used in sample code when demarking regions to be included in
+  // documentation.
+  string doc_tag_prefix = 106;
+
+  // For whom the client library is being published.
+  ClientLibraryOrganization organization = 107;
+
+  // Client library settings.  If the same version string appears multiple
+  // times in this list, then the last one wins.  Settings from earlier
+  // settings with the same version string are discarded.
+  repeated ClientLibrarySettings library_settings = 109;
+
+  // Optional link to proto reference documentation.  Example:
+  // https://cloud.google.com/pubsub/lite/docs/reference/rpc
+  string proto_reference_documentation_uri = 110;
+
+  // Optional link to REST reference documentation.  Example:
+  // https://cloud.google.com/pubsub/lite/docs/reference/rest
+  string rest_reference_documentation_uri = 111;
+}
+
+// Settings for Java client libraries.
+message JavaSettings {
+  // The package name to use in Java. Clobbers the java_package option
+  // set in the protobuf. This should be used **only** by APIs
+  // who have already set the language_settings.java.package_name" field
+  // in gapic.yaml. API teams should use the protobuf java_package option
+  // where possible.
+  //
+  // Example of a YAML configuration::
+  //
+  //  publishing:
+  //    java_settings:
+  //      library_package: com.google.cloud.pubsub.v1
+  string library_package = 1;
+
+  // Configure the Java class name to use instead of the service's for its
+  // corresponding generated GAPIC client. Keys are fully-qualified
+  // service names as they appear in the protobuf (including the full
+  // the language_settings.java.interface_names" field in gapic.yaml. API
+  // teams should otherwise use the service name as it appears in the
+  // protobuf.
+  //
+  // Example of a YAML configuration::
+  //
+  //  publishing:
+  //    java_settings:
+  //      service_class_names:
+  //        - google.pubsub.v1.Publisher: TopicAdmin
+  //        - google.pubsub.v1.Subscriber: SubscriptionAdmin
+  map<string, string> service_class_names = 2;
+
+  // Some settings.
+  CommonLanguageSettings common = 3;
+}
+
+// Settings for C++ client libraries.
+message CppSettings {
+  // Some settings.
+  CommonLanguageSettings common = 1;
+}
+
+// Settings for Php client libraries.
+message PhpSettings {
+  // Some settings.
+  CommonLanguageSettings common = 1;
+}
+
+// Settings for Python client libraries.
+message PythonSettings {
+  // Experimental features to be included during client library generation.
+  // These fields will be deprecated once the feature graduates and is enabled
+  // by default.
+  message ExperimentalFeatures {
+    // Enables generation of asynchronous REST clients if `rest` transport is
+    // enabled. By default, asynchronous REST clients will not be generated.
+    // This feature will be enabled by default 1 month after launching the
+    // feature in preview packages.
+    bool rest_async_io_enabled = 1;
+
+    // Enables generation of protobuf code using new types that are more
+    // Pythonic which are included in `protobuf>=5.29.x`. This feature will be
+    // enabled by default 1 month after launching the feature in preview
+    // packages.
+    bool protobuf_pythonic_types_enabled = 2;
+  }
+
+  // Some settings.
+  CommonLanguageSettings common = 1;
+
+  // Experimental features to be included during client library generation.
+  ExperimentalFeatures experimental_features = 2;
+}
+
+// Settings for Node client libraries.
+message NodeSettings {
+  // Some settings.
+  CommonLanguageSettings common = 1;
+}
+
+// Settings for Dotnet client libraries.
+message DotnetSettings {
+  // Some settings.
+  CommonLanguageSettings common = 1;
+
+  // Map from original service names to renamed versions.
+  // This is used when the default generated types
+  // would cause a naming conflict. (Neither name is
+  // fully-qualified.)
+  // Example: Subscriber to SubscriberServiceApi.
+  map<string, string> renamed_services = 2;
+
+  // Map from full resource types to the effective short name
+  // for the resource. This is used when otherwise resource
+  // named from different services would cause naming collisions.
+  // Example entry:
+  // "datalabeling.googleapis.com/Dataset": "DataLabelingDataset"
+  map<string, string> renamed_resources = 3;
+
+  // List of full resource types to ignore during generation.
+  // This is typically used for API-specific Location resources,
+  // which should be handled by the generator as if they were actually
+  // the common Location resources.
+  // Example entry: "documentai.googleapis.com/Location"
+  repeated string ignored_resources = 4;
+
+  // Namespaces which must be aliased in snippets due to
+  // a known (but non-generator-predictable) naming collision
+  repeated string forced_namespace_aliases = 5;
+
+  // Method signatures (in the form "service.method(signature)")
+  // which are provided separately, so shouldn't be generated.
+  // Snippets *calling* these methods are still generated, however.
+  repeated string handwritten_signatures = 6;
+}
+
+// Settings for Ruby client libraries.
+message RubySettings {
+  // Some settings.
+  CommonLanguageSettings common = 1;
+}
+
+// Settings for Go client libraries.
+message GoSettings {
+  // Some settings.
+  CommonLanguageSettings common = 1;
+}
+
+// Describes the generator configuration for a method.
+message MethodSettings {
+  // Describes settings to use when generating API methods that use the
+  // long-running operation pattern.
+  // All default values below are from those used in the client library
+  // generators (e.g.
+  // [Java](https://github.com/googleapis/gapic-generator-java/blob/04c2faa191a9b5a10b92392fe8482279c4404803/src/main/java/com/google/api/generator/gapic/composer/common/RetrySettingsComposer.java)).
+  message LongRunning {
+    // Initial delay after which the first poll request will be made.
+    // Default value: 5 seconds.
+    google.protobuf.Duration initial_poll_delay = 1;
+
+    // Multiplier to gradually increase delay between subsequent polls until it
+    // reaches max_poll_delay.
+    // Default value: 1.5.
+    float poll_delay_multiplier = 2;
+
+    // Maximum time between two subsequent poll requests.
+    // Default value: 45 seconds.
+    google.protobuf.Duration max_poll_delay = 3;
+
+    // Total polling timeout.
+    // Default value: 5 minutes.
+    google.protobuf.Duration total_poll_timeout = 4;
+  }
+
+  // The fully qualified name of the method, for which the options below apply.
+  // This is used to find the method to apply the options.
+  //
+  // Example:
+  //
+  //    publishing:
+  //      method_settings:
+  //      - selector: google.storage.control.v2.StorageControl.CreateFolder
+  //        # method settings for CreateFolder...
+  string selector = 1;
+
+  // Describes settings to use for long-running operations when generating
+  // API methods for RPCs. Complements RPCs that use the annotations in
+  // google/longrunning/operations.proto.
+  //
+  // Example of a YAML configuration::
+  //
+  //    publishing:
+  //      method_settings:
+  //      - selector: google.cloud.speech.v2.Speech.BatchRecognize
+  //        long_running:
+  //          initial_poll_delay: 60s # 1 minute
+  //          poll_delay_multiplier: 1.5
+  //          max_poll_delay: 360s # 6 minutes
+  //          total_poll_timeout: 54000s # 90 minutes
+  LongRunning long_running = 2;
+
+  // List of top-level fields of the request message, that should be
+  // automatically populated by the client libraries based on their
+  // (google.api.field_info).format. Currently supported format: UUID4.
+  //
+  // Example of a YAML configuration:
+  //
+  //    publishing:
+  //      method_settings:
+  //      - selector: google.example.v1.ExampleService.CreateExample
+  //        auto_populated_fields:
+  //        - request_id
+  repeated string auto_populated_fields = 3;
+}
+
+// The organization for which the client libraries are being published.
+// Affects the url where generated docs are published, etc.
+enum ClientLibraryOrganization {
+  // Not useful.
+  CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED = 0;
+
+  // Google Cloud Platform Org.
+  CLOUD = 1;
+
+  // Ads (Advertising) Org.
+  ADS = 2;
+
+  // Photos Org.
+  PHOTOS = 3;
+
+  // Street View Org.
+  STREET_VIEW = 4;
+
+  // Shopping Org.
+  SHOPPING = 5;
+
+  // Geo Org.
+  GEO = 6;
+
+  // Generative AI - https://developers.generativeai.google
+  GENERATIVE_AI = 7;
+}
+
+// To where should client libraries be published?
+enum ClientLibraryDestination {
+  // Client libraries will neither be generated nor published to package
+  // managers.
+  CLIENT_LIBRARY_DESTINATION_UNSPECIFIED = 0;
+
+  // Generate the client library in a repo under github.com/googleapis,
+  // but don't publish it to package managers.
+  GITHUB = 10;
+
+  // Publish the library to package managers like nuget.org and npmjs.com.
+  PACKAGE_MANAGER = 20;
+}
+
+// This message is used to configure the generation of a subset of the RPCs in
+// a service for client libraries.
+message SelectiveGapicGeneration {
+  // An allowlist of the fully qualified names of RPCs that should be included
+  // on public client surfaces.
+  repeated string methods = 1;
+}

.venv/lib/python3.11/site-packages/google/api/field_behavior.proto

@@ -0,0 +1,104 @@
+// Copyright 2024 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.api;
+
+import "google/protobuf/descriptor.proto";
+
+option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations";
+option java_multiple_files = true;
+option java_outer_classname = "FieldBehaviorProto";
+option java_package = "com.google.api";
+option objc_class_prefix = "GAPI";
+
+extend google.protobuf.FieldOptions {
+  // A designation of a specific field behavior (required, output only, etc.)
+  // in protobuf messages.
+  //
+  // Examples:
+  //
+  //   string name = 1 [(google.api.field_behavior) = REQUIRED];
+  //   State state = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
+  //   google.protobuf.Duration ttl = 1
+  //     [(google.api.field_behavior) = INPUT_ONLY];
+  //   google.protobuf.Timestamp expire_time = 1
+  //     [(google.api.field_behavior) = OUTPUT_ONLY,
+  //      (google.api.field_behavior) = IMMUTABLE];
+  repeated google.api.FieldBehavior field_behavior = 1052 [packed = false];
+}
+
+// An indicator of the behavior of a given field (for example, that a field
+// is required in requests, or given as output but ignored as input).
+// This **does not** change the behavior in protocol buffers itself; it only
+// denotes the behavior and may affect how API tooling handles the field.
+//
+// Note: This enum **may** receive new values in the future.
+enum FieldBehavior {
+  // Conventional default for enums. Do not use this.
+  FIELD_BEHAVIOR_UNSPECIFIED = 0;
+
+  // Specifically denotes a field as optional.
+  // While all fields in protocol buffers are optional, this may be specified
+  // for emphasis if appropriate.
+  OPTIONAL = 1;
+
+  // Denotes a field as required.
+  // This indicates that the field **must** be provided as part of the request,
+  // and failure to do so will cause an error (usually `INVALID_ARGUMENT`).
+  REQUIRED = 2;
+
+  // Denotes a field as output only.
+  // This indicates that the field is provided in responses, but including the
+  // field in a request does nothing (the server *must* ignore it and
+  // *must not* throw an error as a result of the field's presence).
+  OUTPUT_ONLY = 3;
+
+  // Denotes a field as input only.
+  // This indicates that the field is provided in requests, and the
+  // corresponding field is not included in output.
+  INPUT_ONLY = 4;
+
+  // Denotes a field as immutable.
+  // This indicates that the field may be set once in a request to create a
+  // resource, but may not be changed thereafter.
+  IMMUTABLE = 5;
+
+  // Denotes that a (repeated) field is an unordered list.
+  // This indicates that the service may provide the elements of the list
+  // in any arbitrary  order, rather than the order the user originally
+  // provided. Additionally, the list's order may or may not be stable.
+  UNORDERED_LIST = 6;
+
+  // Denotes that this field returns a non-empty default value if not set.
+  // This indicates that if the user provides the empty value in a request,
+  // a non-empty value will be returned. The user will not be aware of what
+  // non-empty value to expect.
+  NON_EMPTY_DEFAULT = 7;
+
+  // Denotes that the field in a resource (a message annotated with
+  // google.api.resource) is used in the resource name to uniquely identify the
+  // resource. For AIP-compliant APIs, this should only be applied to the
+  // `name` field on the resource.
+  //
+  // This behavior should not be applied to references to other resources within
+  // the message.
+  //
+  // The identifier field of resources often have different field behavior
+  // depending on the request it is embedded in (e.g. for Create methods name
+  // is optional and unused, while for Update methods it is required). Instead
+  // of method-specific annotations, only `IDENTIFIER` is required.
+  IDENTIFIER = 8;
+}

.venv/lib/python3.11/site-packages/google/generativeai/types/__init__.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+# Copyright 2023 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.
+"""A collection of type definitions used throughout the library."""
+
+from google.generativeai.types.citation_types import *
+from google.generativeai.types.content_types import *
+from google.generativeai.types.file_types import *
+from google.generativeai.types.generation_types import *
+from google.generativeai.types.helper_types import *
+from google.generativeai.types.model_types import *
+from google.generativeai.types.permission_types import *
+from google.generativeai.types.safety_types import *
+
+
+del model_types
+del citation_types
+del safety_types

.venv/lib/python3.11/site-packages/google/generativeai/types/citation_types.py

@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+# Copyright 2023 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.
+from __future__ import annotations
+from typing import List
+
+from typing_extensions import TypedDict
+
+from google.generativeai import protos
+from google.generativeai import string_utils
+
+
+__all__ = [
+    "CitationMetadataDict",
+    "CitationSourceDict",
+]
+
+
+class CitationSourceDict(TypedDict):
+    start_index: int | None
+    end_index: int | None
+    uri: str | None
+    license: str | None
+
+    __doc__ = string_utils.strip_oneof(protos.CitationSource.__doc__)
+
+
+class CitationMetadataDict(TypedDict):
+    citation_sources: List[CitationSourceDict | None]
+
+    __doc__ = string_utils.strip_oneof(protos.CitationMetadata.__doc__)

.venv/lib/python3.11/site-packages/google/generativeai/types/helper_types.py

@@ -0,0 +1,87 @@
+# -*- coding: utf-8 -*-
+# Copyright 2023 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.
+
+from __future__ import annotations
+
+import google.api_core.timeout
+import google.api_core.retry
+
+import collections
+import dataclasses
+
+from typing import Union
+from typing_extensions import TypedDict
+
+__all__ = ["RequestOptions", "RequestOptionsType"]
+
+
+class RequestOptionsDict(TypedDict, total=False):
+    retry: google.api_core.retry.Retry
+    timeout: Union[int, float, google.api_core.timeout.TimeToDeadlineTimeout]
+
+
+@dataclasses.dataclass(init=False)
+class RequestOptions(collections.abc.Mapping):
+    """Request options
+
+    >>> import google.generativeai as genai
+    >>> from google.generativeai.types import RequestOptions
+    >>> from google.api_core import retry
+    >>>
+    >>> model = genai.GenerativeModel()
+    >>> response = model.generate_content('Hello',
+    ...     request_options=RequestOptions(
+    ...         retry=retry.Retry(initial=10, multiplier=2, maximum=60, timeout=300)))
+    >>> response = model.generate_content('Hello',
+    ...     request_options=RequestOptions(timeout=600)))
+
+    Args:
+        retry: Refer to [retry docs](https://googleapis.dev/python/google-api-core/latest/retry.html) for details.
+        timeout: In seconds (or provide a [TimeToDeadlineTimeout](https://googleapis.dev/python/google-api-core/latest/timeout.html) object).
+    """
+
+    retry: google.api_core.retry.Retry | None
+    timeout: int | float | google.api_core.timeout.TimeToDeadlineTimeout | None
+
+    def __init__(
+        self,
+        *,
+        retry: google.api_core.retry.Retry | None = None,
+        timeout: int | float | google.api_core.timeout.TimeToDeadlineTimeout | None = None,
+    ):
+        self.retry = retry
+        self.timeout = timeout
+
+    # Inherit from Mapping for **unpacking
+    def __getitem__(self, item):
+        if item == "retry":
+            return self.retry
+        elif item == "timeout":
+            return self.timeout
+        else:
+            raise KeyError(
+                f"Invalid key: 'RequestOptions' does not contain a key named '{item}'. "
+                "Please use a valid key."
+            )
+
+    def __iter__(self):
+        yield "retry"
+        yield "timeout"
+
+    def __len__(self):
+        return 2
+
+
+RequestOptionsType = Union[RequestOptions, RequestOptionsDict]

.venv/lib/python3.11/site-packages/google/generativeai/types/retriever_types.py

@@ -0,0 +1,1698 @@
+# -*- coding: utf-8 -*-
+# Copyright 2023 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.
+from __future__ import annotations
+
+import datetime
+import re
+import abc
+import dataclasses
+from typing import Any, AsyncIterable, Optional, Union, Iterable, Mapping
+from typing_extensions import deprecated  # type: ignore
+
+import google.ai.generativelanguage as glm
+from google.generativeai import protos
+
+from google.protobuf import field_mask_pb2
+from google.generativeai.client import get_default_retriever_client
+from google.generativeai.client import get_default_retriever_async_client
+from google.generativeai import string_utils
+from google.generativeai.types import helper_types
+
+from google.generativeai.types import permission_types
+from google.generativeai.types.model_types import idecode_time
+from google.generativeai.utils import flatten_update_paths
+
+_VALID_NAME = r"[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])$"
+NAME_ERROR_MSG = """The `name` must consist of alphanumeric characters (or -) and be 40 or fewer characters; or be empty. The name you entered:
+    len(name)== {length}
+    name={name}
+"""
+
+
+def valid_name(name):
+    return re.match(_VALID_NAME, name) and len(name) < 40
+
+
+Operator = protos.Condition.Operator
+State = protos.Chunk.State
+
+OperatorOptions = Union[str, int, Operator]
+StateOptions = Union[str, int, State]
+
+ChunkOptions = Union[
+    protos.Chunk,
+    str,
+    tuple[str, str],
+    tuple[str, str, Any],
+    Mapping[str, Any],
+]  # fmt: no
+
+BatchCreateChunkOptions = Union[
+    protos.BatchCreateChunksRequest,
+    Mapping[str, str],
+    Mapping[str, tuple[str, str]],
+    Iterable[ChunkOptions],
+]  # fmt: no
+
+UpdateChunkOptions = Union[protos.UpdateChunkRequest, Mapping[str, Any], tuple[str, Any]]
+
+BatchUpdateChunksOptions = Union[protos.BatchUpdateChunksRequest, Iterable[UpdateChunkOptions]]
+
+BatchDeleteChunkOptions = Union[list[protos.DeleteChunkRequest], Iterable[str]]
+
+_OPERATOR: dict[OperatorOptions, Operator] = {
+    Operator.OPERATOR_UNSPECIFIED: Operator.OPERATOR_UNSPECIFIED,
+    0: Operator.OPERATOR_UNSPECIFIED,
+    "operator_unspecified": Operator.OPERATOR_UNSPECIFIED,
+    "unspecified": Operator.OPERATOR_UNSPECIFIED,
+    Operator.LESS: Operator.LESS,
+    1: Operator.LESS,
+    "operator_less": Operator.LESS,
+    "less": Operator.LESS,
+    "<": Operator.LESS,
+    Operator.LESS_EQUAL: Operator.LESS_EQUAL,
+    2: Operator.LESS_EQUAL,
+    "operator_less_equal": Operator.LESS_EQUAL,
+    "less_equal": Operator.LESS_EQUAL,
+    "<=": Operator.LESS_EQUAL,
+    Operator.EQUAL: Operator.EQUAL,
+    3: Operator.EQUAL,
+    "operator_equal": Operator.EQUAL,
+    "equal": Operator.EQUAL,
+    "==": Operator.EQUAL,
+    Operator.GREATER_EQUAL: Operator.GREATER_EQUAL,
+    4: Operator.GREATER_EQUAL,
+    "operator_greater_equal": Operator.GREATER_EQUAL,
+    "greater_equal": Operator.GREATER_EQUAL,
+    Operator.EQUAL: Operator.EQUAL,
+    5: Operator.EQUAL,
+    "operator_equal": Operator.EQUAL,
+    "equal": Operator.EQUAL,
+    "==": Operator.EQUAL,
+    Operator.NOT_EQUAL: Operator.NOT_EQUAL,
+    6: Operator.NOT_EQUAL,
+    "operator_not_equal": Operator.NOT_EQUAL,
+    "not_equal": Operator.NOT_EQUAL,
+    "!=": Operator.NOT_EQUAL,
+    Operator.INCLUDES: Operator.INCLUDES,
+    7: Operator.INCLUDES,
+    "operator_includes": Operator.INCLUDES,
+    "includes": Operator.INCLUDES,
+    Operator.EXCLUDES: Operator.EXCLUDES,
+    8: Operator.EXCLUDES,
+    "operator_excludes": Operator.EXCLUDES,
+    "excludes": Operator.EXCLUDES,
+    "not in": Operator.EXCLUDES,
+}
+
+_STATE: dict[StateOptions, State] = {
+    State.STATE_UNSPECIFIED: State.STATE_UNSPECIFIED,
+    0: State.STATE_UNSPECIFIED,
+    "state_unspecifed": State.STATE_UNSPECIFIED,
+    "unspecified": State.STATE_UNSPECIFIED,
+    State.STATE_PENDING_PROCESSING: State.STATE_PENDING_PROCESSING,
+    1: State.STATE_PENDING_PROCESSING,
+    "pending_processing": State.STATE_PENDING_PROCESSING,
+    "pending": State.STATE_PENDING_PROCESSING,
+    State.STATE_ACTIVE: State.STATE_ACTIVE,
+    2: State.STATE_ACTIVE,
+    "state_active": State.STATE_ACTIVE,
+    "active": State.STATE_ACTIVE,
+    State.STATE_FAILED: State.STATE_FAILED,
+    10: State.STATE_FAILED,
+    "state_failed": State.STATE_FAILED,
+    "failed": State.STATE_FAILED,
+}
+
+
+def to_operator(x: OperatorOptions) -> Operator:
+    if isinstance(x, str):
+        x = x.lower()
+    return _OPERATOR[x]
+
+
+def to_state(x: StateOptions) -> State:
+    if isinstance(x, str):
+        x = x.lower()
+    return _STATE[x]
+
+
+@string_utils.prettyprint
+@dataclasses.dataclass
+class MetadataFilter:
+    key: str
+    conditions: Iterable[Condition]
+
+    def _to_proto(self):
+        kwargs = {}
+        conditions = []
+        for c in self.conditions:
+            if isinstance(c.value, str):
+                kwargs["string_value"] = c.value
+            elif isinstance(c.value, (int, float)):
+                kwargs["numeric_value"] = float(c.value)
+            else:
+                raise ValueError(
+                    f"Invalid value type: The value for the condition must be either a string or an integer/float. Received: '{c.value}' of type {type(c.value).__name__}."
+                )
+            kwargs["operation"] = c.operation
+
+            condition = protos.Condition(**kwargs)
+            conditions.append(condition)
+
+        return protos.MetadataFilter(key=self.key, conditions=conditions)
+
+
+@string_utils.prettyprint
+@dataclasses.dataclass
+class Condition:
+    value: str | float
+    operation: Operator
+
+
+@string_utils.prettyprint
+@dataclasses.dataclass
+class CustomMetadata:
+    key: str
+    value: str | Iterable[str] | float
+
+    def _to_proto(self):
+        kwargs = {}
+        if isinstance(self.value, str):
+            kwargs["string_value"] = self.value
+        elif isinstance(self.value, Iterable):
+            if isinstance(self.value, Mapping):
+                # If already converted to a protos.StringList, get the values
+                kwargs["string_list_value"] = self.value
+            else:
+                kwargs["string_list_value"] = protos.StringList(values=self.value)
+        elif isinstance(self.value, (int, float)):
+            kwargs["numeric_value"] = float(self.value)
+        else:
+            raise ValueError(
+                f"Invalid value type: The value for a custom_metadata specification must be either a list of string values, a string, or an integer/float. Received: '{self.value}' of type {type(self.value).__name__}."
+            )
+        return protos.CustomMetadata(key=self.key, **kwargs)
+
+    @classmethod
+    def _from_dict(cls, cm):
+        key = cm["key"]
+        value = (
+            cm.get("value", None)
+            or cm.get("string_value", None)
+            or cm.get("string_list_value", None)
+            or cm.get("numeric_value", None)
+        )
+        return cls(key=key, value=value)
+
+    def _to_dict(self):
+        proto = self._to_proto()
+        return type(proto).to_dict(proto)
+
+
+CustomMetadataOptions = Union[CustomMetadata, protos.CustomMetadata, dict]
+
+
+def make_custom_metadata(cm: CustomMetadataOptions) -> CustomMetadata:
+    if isinstance(cm, CustomMetadata):
+        return cm
+
+    if isinstance(cm, protos.CustomMetadata):
+        cm = type(cm).to_dict(cm)
+
+    if isinstance(cm, dict):
+        return CustomMetadata._from_dict(cm)
+    else:
+        raise ValueError(  # nofmt
+            f"Invalid input: Could not create a 'CustomMetadata' from the provided input. Received type: '{type(cm).__name__}', value: '{cm}'."
+        )
+
+
+@string_utils.prettyprint
+@dataclasses.dataclass
+class ChunkData:
+    string_value: str
+
+
+@string_utils.prettyprint
+@dataclasses.dataclass()
+class Corpus:
+    """
+    A `Corpus` is a collection of `Documents`.
+    """
+
+    name: str
+    display_name: str
+    create_time: datetime.datetime
+    update_time: datetime.datetime
+
+    @property
+    def permissions(self) -> permission_types.Permissions:
+        return permission_types.Permissions(self)
+
+    def create_document(
+        self,
+        name: str | None = None,
+        display_name: str | None = None,
+        custom_metadata: Iterable[CustomMetadata] | None = None,
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ) -> Document:
+        """
+        Request to create a `Document`.
+
+        Args:
+            name: The `Document` resource name. The ID (name excluding the "corpora/*/documents/" prefix) can contain up to 40 characters
+                that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash.
+            display_name: The human-readable display name for the `Document`.
+            custom_metadata: User provided custom metadata stored as key-value pairs used for querying.
+            request_options: Options for the request.
+
+        Return:
+            Document object with specified name or display name.
+
+        Raises:
+            ValueError: When the name is not specified or formatted incorrectly.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        # Handle the custom_metadata parameter
+        c_data = []
+        if custom_metadata:
+            for cm in custom_metadata:
+                c_data.append(cm._to_proto())
+
+        if name is None:
+            document = protos.Document(display_name=display_name, custom_metadata=c_data)
+        elif valid_name(name):
+            document = protos.Document(
+                name=f"{self.name}/documents/{name}",
+                display_name=display_name,
+                custom_metadata=c_data,
+            )
+        else:
+            raise ValueError(NAME_ERROR_MSG.format(length=len(name), name=name))
+
+        request = protos.CreateDocumentRequest(parent=self.name, document=document)
+        response = client.create_document(request, **request_options)
+        return decode_document(response)
+
+    async def create_document_async(
+        self,
+        name: str | None = None,
+        display_name: str | None = None,
+        custom_metadata: Iterable[CustomMetadata] | None = None,
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ) -> Document:
+        """This is the async version of `Corpus.create_document`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        # Handle the custom_metadata parameter
+        c_data = []
+        if custom_metadata:
+            for cm in custom_metadata:
+                c_data.append(cm._to_proto())
+
+        if name is None:
+            document = protos.Document(display_name=display_name, custom_metadata=c_data)
+        elif valid_name(name):
+            document = protos.Document(
+                name=f"{self.name}/documents/{name}",
+                display_name=display_name,
+                custom_metadata=c_data,
+            )
+        else:
+            raise ValueError(NAME_ERROR_MSG.format(length=len(name), name=name))
+
+        request = protos.CreateDocumentRequest(parent=self.name, document=document)
+        response = await client.create_document(request, **request_options)
+        return decode_document(response)
+
+    def get_document(
+        self,
+        name: str,
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ) -> Document:
+        """
+        Get information about a specific `Document`.
+
+        Args:
+            name: The `Document` name.
+            request_options: Options for the request.
+
+        Return:
+            `Document` of interest.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        if "/" not in name:
+            name = f"{self.name}/documents/{name}"
+
+        request = protos.GetDocumentRequest(name=name)
+        response = client.get_document(request, **request_options)
+        return decode_document(response)
+
+    async def get_document_async(
+        self,
+        name: str,
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ) -> Document:
+        """This is the async version of `Corpus.get_document`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        if "/" not in name:
+            name = f"{self.name}/documents/{name}"
+
+        request = protos.GetDocumentRequest(name=name)
+        response = await client.get_document(request, **request_options)
+        return decode_document(response)
+
+    def _apply_update(self, path, value):
+        parts = path.split(".")
+        for part in parts[:-1]:
+            self = getattr(self, part)
+        setattr(self, parts[-1], value)
+
+    def update(
+        self,
+        updates: dict[str, Any],
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """
+        Update a list of fields for a specified `Corpus`.
+
+        Args:
+            updates: List of fields to update in a `Corpus`.
+            request_options: Options for the request.
+
+        Return:
+            Updated version of the `Corpus` object.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        updates = flatten_update_paths(updates)
+        # At this time, only `display_name` can be updated
+        for item in updates:
+            if item != "display_name":
+                raise ValueError(
+                    "Invalid operation: Currently, only the 'display_name' attribute can be updated for a 'Corpus'."
+                )
+        field_mask = field_mask_pb2.FieldMask()
+
+        for path in updates.keys():
+            field_mask.paths.append(path)
+        for path, value in updates.items():
+            self._apply_update(path, value)
+
+        request = protos.UpdateCorpusRequest(corpus=self.to_dict(), update_mask=field_mask)
+        client.update_corpus(request, **request_options)
+        return self
+
+    async def update_async(
+        self,
+        updates: dict[str, Any],
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """This is the async version of `Corpus.update`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        updates = flatten_update_paths(updates)
+        # At this time, only `display_name` can be updated
+        for item in updates:
+            if item != "display_name":
+                raise ValueError(
+                    "Invalid operation: Currently, only the 'display_name' attribute can be updated for a 'Corpus'."
+                )
+        field_mask = field_mask_pb2.FieldMask()
+
+        for path in updates.keys():
+            field_mask.paths.append(path)
+        for path, value in updates.items():
+            self._apply_update(path, value)
+
+        request = protos.UpdateCorpusRequest(corpus=self.to_dict(), update_mask=field_mask)
+        await client.update_corpus(request, **request_options)
+        return self
+
+    def query(
+        self,
+        query: str,
+        metadata_filters: Iterable[MetadataFilter] | None = None,
+        results_count: int | None = None,
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ) -> Iterable[RelevantChunk]:
+        """
+        Query a corpus for information.
+
+        Args:
+            query: Query string to perform semantic search.
+            metadata_filters: Filter for `Chunk` metadata.
+            results_count: The maximum number of `Chunk`s to return; must be less than 100.
+            request_options: Options for the request.
+
+        Returns:
+            List of relevant chunks.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        if results_count:
+            if results_count > 100:
+                raise ValueError(
+                    "Invalid operation: The number of results returned must be between 1 and 100."
+                )
+
+        m_f_ = []
+        if metadata_filters:
+            for mf in metadata_filters:
+                m_f_.append(mf._to_proto())
+
+        request = protos.QueryCorpusRequest(
+            name=self.name,
+            query=query,
+            metadata_filters=m_f_,
+            results_count=results_count,
+        )
+        response = client.query_corpus(request, **request_options)
+        response = type(response).to_dict(response)
+
+        # Create a RelevantChunk object for each chunk listed in response['relevant_chunks']
+        relevant_chunks = []
+        for c in response["relevant_chunks"]:
+            rc = RelevantChunk(
+                chunk_relevance_score=c["chunk_relevance_score"], chunk=Chunk(**c["chunk"])
+            )
+            relevant_chunks.append(rc)
+
+        return relevant_chunks
+
+    async def query_async(
+        self,
+        query: str,
+        metadata_filters: Iterable[MetadataFilter] | None = None,
+        results_count: int | None = None,
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ) -> Iterable[RelevantChunk]:
+        """This is the async version of `Corpus.query`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        if results_count:
+            if results_count > 100:
+                raise ValueError(
+                    "Invalid operation: The number of results returned must be between 1 and 100."
+                )
+
+        m_f_ = []
+        if metadata_filters:
+            for mf in metadata_filters:
+                m_f_.append(mf._to_proto())
+
+        request = protos.QueryCorpusRequest(
+            name=self.name,
+            query=query,
+            metadata_filters=m_f_,
+            results_count=results_count,
+        )
+        response = await client.query_corpus(request, **request_options)
+        response = type(response).to_dict(response)
+
+        # Create a RelevantChunk object for each chunk listed in response['relevant_chunks']
+        relevant_chunks = []
+        for c in response["relevant_chunks"]:
+            rc = RelevantChunk(
+                chunk_relevance_score=c["chunk_relevance_score"], chunk=Chunk(**c["chunk"])
+            )
+            relevant_chunks.append(rc)
+
+        return relevant_chunks
+
+    def delete_document(
+        self,
+        name: str,
+        force: bool = False,
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """
+        Delete a document in the corpus.
+
+        Args:
+            name: The `Document` name.
+            force: If set to true, any `Chunk`s and objects related to this `Document` will also be deleted.
+            request_options: Options for the request.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        if "/" not in name:
+            name = f"{self.name}/documents/{name}"
+
+        request = protos.DeleteDocumentRequest(name=name, force=bool(force))
+        client.delete_document(request, **request_options)
+
+    async def delete_document_async(
+        self,
+        name: str,
+        force: bool = False,
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """This is the async version of `Corpus.delete_document`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        if "/" not in name:
+            name = f"{self.name}/documents/{name}"
+
+        request = protos.DeleteDocumentRequest(name=name, force=bool(force))
+        await client.delete_document(request, **request_options)
+
+    def list_documents(
+        self,
+        page_size: int | None = None,
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ) -> Iterable[Document]:
+        """
+        List documents in corpus.
+
+        Args:
+            name: The name of the `Corpus` containing `Document`s.
+            page_size: The maximum number of `Document`s to return (per page). The service may return fewer `Document`s.
+            request_options: Options for the request.
+
+        Return:
+            Paginated list of `Document`s.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        request = protos.ListDocumentsRequest(
+            parent=self.name,
+            page_size=page_size,
+        )
+        for doc in client.list_documents(request, **request_options):
+            yield decode_document(doc)
+
+    async def list_documents_async(
+        self,
+        page_size: int | None = None,
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ) -> AsyncIterable[Document]:
+        """This is the async version of `Corpus.list_documents`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        request = protos.ListDocumentsRequest(
+            parent=self.name,
+            page_size=page_size,
+        )
+        async for doc in await client.list_documents(request, **request_options):
+            yield decode_document(doc)
+
+    # PERMISSIONS STUBS: ..deprecated:: >0.5.2
+    @deprecated(
+        "`Corpus.create_permission` is deprecated and will be removed in a future release. \
+            Corpus permissions are now managed using the `permissions` property. Use `Corpus.permissions.create` instead."
+    )
+    def create_permission(
+        self,
+        role: permission_types.RoleOptions,
+        grantee_type: Optional[permission_types.GranteeTypeOptions] = None,
+        email_address: Optional[str] = None,
+        client: glm.PermissionServiceClient | None = None,
+    ) -> permission_types.Permission:
+        return self.permissions.create(
+            role=role, grantee_type=grantee_type, email_address=email_address, client=client
+        )
+
+    @deprecated(
+        "`Corpus.create_permission_async` is deprecated and will be removed in a future release. \
+            Corpus permissions are now managed using the `permissions` property. Use `Corpus.permissions.create_async` instead."
+    )
+    async def create_permission_async(
+        self,
+        role: permission_types.RoleOptions,
+        grantee_type: Optional[permission_types.GranteeTypeOptions] = None,
+        email_address: Optional[str] = None,
+        client: glm.PermissionServiceAsyncClient | None = None,
+    ) -> permission_types.Permission:
+        return await self.permissions.create_async(
+            role=role, grantee_type=grantee_type, email_address=email_address, client=client
+        )
+
+    @deprecated(
+        "`Corpus.list_permission` is deprecated and will be removed in a future release. \
+            Corpus permissions are now managed using the `permissions` property. Use `Corpus.permissions.list` instead."
+    )
+    def list_permissions(
+        self,
+        page_size: Optional[int] = None,
+        client: glm.PermissionServiceClient | None = None,
+    ) -> Iterable[permission_types.Permission]:
+        return self.permissions.list(page_size=page_size, client=client)
+
+    @deprecated(
+        "`Corpus.list_permission_async` is deprecated and will be removed in a future release. \
+            Corpus permissions are now managed using the `permissions` property. Use `Corpus.permissions.list_async` instead."
+    )
+    async def list_permissions_async(
+        self,
+        page_size: Optional[int] = None,
+        client: glm.PermissionServiceAsyncClient | None = None,
+    ) -> AsyncIterable[permission_types.Permission]:
+        return self.permissions.list_async(page_size=page_size, client=client)
+
+    # PERMISSIONS STUBS END
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {"name": self.name, "display_name": self.display_name}
+        return result
+
+
+def decode_document(document):
+    document = type(document).to_dict(document)
+    idecode_time(document, "create_time")
+    idecode_time(document, "update_time")
+    return Document(**document)
+
+
+@string_utils.prettyprint
+@dataclasses.dataclass()
+class Document(abc.ABC):
+    """
+    A `Document` is a collection of `Chunk`s.
+    """
+
+    name: str
+    display_name: str
+    custom_metadata: list[CustomMetadata]
+    create_time: datetime.datetime
+    update_time: datetime.datetime
+
+    def create_chunk(
+        self,
+        data: str | ChunkData,
+        name: str | None = None,
+        custom_metadata: Iterable[CustomMetadata] | None = None,
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ) -> Chunk:
+        """
+        Create a `Chunk` object which has textual data.
+
+        Args:
+            data: The content for the `Chunk`, such as the text string.
+            name: The `Chunk` resource name. The ID (name excluding the "corpora/*/documents/*/chunks/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-).
+            custom_metadata: User provided custom metadata stored as key-value pairs.
+            state: States for the lifecycle of a `Chunk`.
+            request_options: Options for the request.
+
+        Return:
+            `Chunk` object with specified data.
+
+        Raises:
+            ValueError when chunk name not specified correctly.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        # Handle the custom_metadata parameter
+        c_data = []
+        if custom_metadata:
+            for cm in custom_metadata:
+                c_data.append(cm._to_proto())
+
+        if name is not None:
+            if valid_name(name):
+                chunk_name = f"{self.name}/chunks/{name}"
+            else:
+                raise ValueError(NAME_ERROR_MSG.format(length=len(name), name=name))
+        else:
+            chunk_name = name
+
+        if isinstance(data, str):
+            chunk = protos.Chunk(
+                name=chunk_name, data={"string_value": data}, custom_metadata=c_data
+            )
+        else:
+            chunk = protos.Chunk(
+                name=chunk_name,
+                data={"string_value": data.string_value},
+                custom_metadata=c_data,
+            )
+
+        request = protos.CreateChunkRequest(parent=self.name, chunk=chunk)
+        response = client.create_chunk(request, **request_options)
+        return decode_chunk(response)
+
+    async def create_chunk_async(
+        self,
+        data: str | ChunkData,
+        name: str | None = None,
+        custom_metadata: Iterable[CustomMetadata] | None = None,
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ) -> Chunk:
+        """This is the async version of `Document.create_chunk`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        # Handle the custom_metadata parameter
+        c_data = []
+        if custom_metadata:
+            for cm in custom_metadata:
+                c_data.append(cm._to_proto())
+
+        if name is not None:
+            if valid_name(name):
+                chunk_name = f"{self.name}/chunks/{name}"
+            else:
+                raise ValueError(NAME_ERROR_MSG.format(length=len(name), name=name))
+        else:
+            chunk_name = name
+
+        if isinstance(data, str):
+            chunk = protos.Chunk(
+                name=chunk_name, data={"string_value": data}, custom_metadata=c_data
+            )
+        else:
+            chunk = protos.Chunk(
+                name=chunk_name,
+                data={"string_value": data.string_value},
+                custom_metadata=c_data,
+            )
+
+        request = protos.CreateChunkRequest(parent=self.name, chunk=chunk)
+        response = await client.create_chunk(request, **request_options)
+        return decode_chunk(response)
+
+    def _make_chunk(self, chunk: ChunkOptions) -> protos.Chunk:
+        # del self
+        if isinstance(chunk, protos.Chunk):
+            return protos.Chunk(chunk)
+        elif isinstance(chunk, str):
+            return protos.Chunk(data={"string_value": chunk})
+        elif isinstance(chunk, tuple):
+            if len(chunk) == 2:
+                name, data = chunk  # pytype: disable=bad-unpacking
+                custom_metadata = None
+            elif len(chunk) == 3:
+                name, data, custom_metadata = chunk  # pytype: disable=bad-unpacking
+            else:
+                raise ValueError(
+                    f"Tuples should have length 2 or 3, got length: {len(chunk)}\n"
+                    f"value: {chunk}"
+                )
+
+            return protos.Chunk(
+                name=name,
+                data={"string_value": data},
+                custom_metadata=custom_metadata,
+            )
+        elif isinstance(chunk, Mapping):
+            if isinstance(chunk["data"], str):
+                chunk = dict(chunk)
+                chunk["data"] = {"string_value": chunk["data"]}
+            return protos.Chunk(chunk)
+        else:
+            raise TypeError(
+                f"Invalid input: Could not convert instance of type '{type(chunk).__name__}' to a chunk. Received value: '{chunk}'."
+            )
+
+    def _make_batch_create_chunk_request(
+        self, chunks: BatchCreateChunkOptions
+    ) -> protos.BatchCreateChunksRequest:
+        if isinstance(chunks, protos.BatchCreateChunksRequest):
+            return chunks
+
+        if isinstance(chunks, Mapping):
+            chunks = chunks.items()
+            chunks = (
+                # Flatten tuples
+                (key,) + value if isinstance(value, tuple) else (key, value)
+                for key, value in chunks
+            )
+
+        requests = []
+        for i, chunk in enumerate(chunks):
+            chunk = self._make_chunk(chunk)
+            if chunk.name == "":
+                chunk.name = str(i)
+
+            chunk.name = f"{self.name}/chunks/{chunk.name}"
+
+            requests.append(protos.CreateChunkRequest(parent=self.name, chunk=chunk))
+
+        return protos.BatchCreateChunksRequest(parent=self.name, requests=requests)
+
+    def batch_create_chunks(
+        self,
+        chunks: BatchCreateChunkOptions,
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """
+        Create chunks within the given document.
+
+        Args:
+            chunks: `Chunks` to create.
+            request_options: Options for the request.
+
+        Return:
+            Information about the created chunks.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        request = self._make_batch_create_chunk_request(chunks)
+        response = client.batch_create_chunks(request, **request_options)
+        return [decode_chunk(chunk) for chunk in response.chunks]
+
+    async def batch_create_chunks_async(
+        self,
+        chunks: BatchCreateChunkOptions,
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """This is the async version of `Document.batch_create_chunk`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        request = self._make_batch_create_chunk_request(chunks)
+        response = await client.batch_create_chunks(request, **request_options)
+        return [decode_chunk(chunk) for chunk in response.chunks]
+
+    def get_chunk(
+        self,
+        name: str,
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """
+        Get information about a specific chunk.
+
+        Args:
+            name: Name of `Chunk`.
+            request_options: Options for the request.
+
+        Returns:
+            `Chunk` that was requested.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        if "/" not in name:
+            name = f"{self.name}/chunks/{name}"
+
+        request = protos.GetChunkRequest(name=name)
+        response = client.get_chunk(request, **request_options)
+        return decode_chunk(response)
+
+    async def get_chunk_async(
+        self,
+        name: str,
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """This is the async version of `Document.get_chunk`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        if "/" not in name:
+            name = f"{self.name}/chunks/{name}"
+
+        request = protos.GetChunkRequest(name=name)
+        response = await client.get_chunk(request, **request_options)
+        return decode_chunk(response)
+
+    def list_chunks(
+        self,
+        page_size: int | None = None,
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ) -> Iterable[Chunk]:
+        """
+        List chunks of a document.
+
+        Args:
+            page_size: Maximum number of `Chunk`s to request.
+            request_options: Options for the request.
+
+        Return:
+            List of chunks in the document.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        request = protos.ListChunksRequest(parent=self.name, page_size=page_size)
+        for chunk in client.list_chunks(request, **request_options):
+            yield decode_chunk(chunk)
+
+    async def list_chunks_async(
+        self,
+        page_size: int | None = None,
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ) -> AsyncIterable[Chunk]:
+        """This is the async version of `Document.list_chunks`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        request = protos.ListChunksRequest(parent=self.name, page_size=page_size)
+        async for chunk in await client.list_chunks(request, **request_options):
+            yield decode_chunk(chunk)
+
+    def query(
+        self,
+        query: str,
+        metadata_filters: Iterable[MetadataFilter] | None = None,
+        results_count: int | None = None,
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ) -> list[RelevantChunk]:
+        """
+        Query a `Document` in the `Corpus` for information.
+
+        Args:
+            query: Query string to perform semantic search.
+            metadata_filters: Filter for `Chunk` metadata.
+            results_count: The maximum number of `Chunk`s to return.
+
+        Returns:
+            List of relevant chunks.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        if results_count:
+            if results_count < 0 or results_count >= 100:
+                raise ValueError(
+                    "Invalid operation: The number of results returned must be between 1 and 100."
+                )
+
+        m_f_ = []
+        if metadata_filters:
+            for mf in metadata_filters:
+                m_f_.append(mf._to_proto())
+
+        request = protos.QueryDocumentRequest(
+            name=self.name,
+            query=query,
+            metadata_filters=m_f_,
+            results_count=results_count,
+        )
+        response = client.query_document(request, **request_options)
+        response = type(response).to_dict(response)
+
+        # Create a RelevantChunk object for each chunk listed in response['relevant_chunks']
+        relevant_chunks = []
+        for c in response["relevant_chunks"]:
+            rc = RelevantChunk(
+                chunk_relevance_score=c["chunk_relevance_score"], chunk=Chunk(**c["chunk"])
+            )
+            relevant_chunks.append(rc)
+
+        return relevant_chunks
+
+    async def query_async(
+        self,
+        query: str,
+        metadata_filters: Iterable[MetadataFilter] | None = None,
+        results_count: int | None = None,
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ) -> list[RelevantChunk]:
+        """This is the async version of `Document.query`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        if results_count:
+            if results_count < 0 or results_count >= 100:
+                raise ValueError(
+                    "Invalid operation: The number of results returned must be between 1 and 100."
+                )
+
+        m_f_ = []
+        if metadata_filters:
+            for mf in metadata_filters:
+                m_f_.append(mf._to_proto())
+
+        request = protos.QueryDocumentRequest(
+            name=self.name,
+            query=query,
+            metadata_filters=m_f_,
+            results_count=results_count,
+        )
+        response = await client.query_document(request, **request_options)
+        response = type(response).to_dict(response)
+
+        # Create a RelevantChunk object for each chunk listed in response['relevant_chunks']
+        relevant_chunks = []
+        for c in response["relevant_chunks"]:
+            rc = RelevantChunk(
+                chunk_relevance_score=c["chunk_relevance_score"], chunk=Chunk(**c["chunk"])
+            )
+            relevant_chunks.append(rc)
+
+        return relevant_chunks
+
+    def _apply_update(self, path, value):
+        parts = path.split(".")
+        for part in parts[:-1]:
+            self = getattr(self, part)
+        setattr(self, parts[-1], value)
+
+    def update(
+        self,
+        updates: dict[str, Any],
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """
+        Update a list of fields for a specified document.
+
+        Args:
+            updates: The list of fields to update.
+            request_options: Options for the request.
+
+        Return:
+            `Chunk` object with specified updates.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        updates = flatten_update_paths(updates)
+        # At this time, only `display_name` can be updated
+        for item in updates:
+            if item != "display_name":
+                raise ValueError(
+                    "Invalid operation: Currently, only the 'display_name' attribute can be updated for a 'Document'."
+                )
+        field_mask = field_mask_pb2.FieldMask()
+        for path in updates.keys():
+            field_mask.paths.append(path)
+        for path, value in updates.items():
+            self._apply_update(path, value)
+
+        request = protos.UpdateDocumentRequest(document=self.to_dict(), update_mask=field_mask)
+        client.update_document(request, **request_options)
+        return self
+
+    async def update_async(
+        self,
+        updates: dict[str, Any],
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """This is the async version of `Document.update`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        updates = flatten_update_paths(updates)
+        # At this time, only `display_name` can be updated
+        for item in updates:
+            if item != "display_name":
+                raise ValueError(
+                    "Invalid operation: Currently, only the 'display_name' attribute can be updated for a 'Document'."
+                )
+        field_mask = field_mask_pb2.FieldMask()
+        for path in updates.keys():
+            field_mask.paths.append(path)
+        for path, value in updates.items():
+            self._apply_update(path, value)
+
+        request = protos.UpdateDocumentRequest(document=self.to_dict(), update_mask=field_mask)
+        await client.update_document(request, **request_options)
+        return self
+
+    def batch_update_chunks(
+        self,
+        chunks: BatchUpdateChunksOptions,
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """
+        Update multiple chunks within the same document.
+
+        Args:
+            chunks: Data structure specifying which `Chunk`s to update and what the required updates are.
+            request_options: Options for the request.
+
+        Return:
+            Updated `Chunk`s.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        if isinstance(chunks, protos.BatchUpdateChunksRequest):
+            response = client.batch_update_chunks(chunks)
+            response = type(response).to_dict(response)
+            return response
+
+        _requests = []
+        if isinstance(chunks, Mapping):
+            # Key is name of chunk, value is a dictionary of updates
+            for key, value in chunks.items():
+                chunk_to_update = self.get_chunk(name=key)
+
+                # Handle the custom_metadata parameter
+                c_data = []
+                if chunk_to_update.custom_metadata:
+                    for cm in chunk_to_update.custom_metadata:
+                        c_data.append(cm._to_proto())
+
+                # When handling updates, use to the _to_proto result of the custom_metadata
+                chunk_to_update.custom_metadata = c_data
+
+                updates = flatten_update_paths(value)
+                # At this time, only `data` can be updated
+                for item in updates:
+                    if item != "data.string_value":
+                        raise ValueError(
+                            f"Invalid operation: Currently, only the 'data' attribute can be updated for a 'Chunk'. Attempted to update '{item}'."
+                        )
+                field_mask = field_mask_pb2.FieldMask()
+                for path in updates.keys():
+                    field_mask.paths.append(path)
+                for path, value in updates.items():
+                    chunk_to_update._apply_update(path, value)
+                _requests.append(
+                    protos.UpdateChunkRequest(
+                        chunk=chunk_to_update.to_dict(), update_mask=field_mask
+                    )
+                )
+            request = protos.BatchUpdateChunksRequest(parent=self.name, requests=_requests)
+            response = client.batch_update_chunks(request, **request_options)
+            response = type(response).to_dict(response)
+            return response
+        if isinstance(chunks, Iterable) and not isinstance(chunks, Mapping):
+            for chunk in chunks:
+                if isinstance(chunk, protos.UpdateChunkRequest):
+                    _requests.append(chunk)
+                elif isinstance(chunk, tuple):
+                    # First element is name of chunk, second element contains updates
+                    chunk_to_update = self.get_chunk(name=chunk[0])
+
+                    # Handle the custom_metadata parameter
+                    c_data = []
+                    if chunk_to_update.custom_metadata:
+                        for cm in chunk_to_update.custom_metadata:
+                            c_data.append(cm._to_proto())
+
+                    # When handling updates, use to the _to_proto result of the custom_metadata
+                    chunk_to_update.custom_metadata = c_data
+
+                    updates = flatten_update_paths(chunk[1])
+                    field_mask = field_mask_pb2.FieldMask()
+                    for path in updates.keys():
+                        field_mask.paths.append(path)
+                    for path, value in updates.items():
+                        chunk_to_update._apply_update(path, value)
+                    _requests.append(
+                        {"chunk": chunk_to_update.to_dict(), "update_mask": field_mask}
+                    )
+                else:
+                    raise TypeError(
+                        "Invalid input: The 'chunks' parameter must be a list of 'protos.UpdateChunkRequests',"
+                        " dictionaries, or tuples of dictionaries."
+                    )
+            request = protos.BatchUpdateChunksRequest(parent=self.name, requests=_requests)
+            response = client.batch_update_chunks(request, **request_options)
+            response = type(response).to_dict(response)
+            return response
+
+    async def batch_update_chunks_async(
+        self,
+        chunks: BatchUpdateChunksOptions,
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """This is the async version of `Document.batch_update_chunks`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        if isinstance(chunks, protos.BatchUpdateChunksRequest):
+            response = client.batch_update_chunks(chunks)
+            response = type(response).to_dict(response)
+            return response
+
+        _requests = []
+        if isinstance(chunks, Mapping):
+            # Key is name of chunk, value is a dictionary of updates
+            for key, value in chunks.items():
+                chunk_to_update = self.get_chunk(name=key)
+
+                # Handle the custom_metadata parameter
+                c_data = []
+                if chunk_to_update.custom_metadata:
+                    for cm in chunk_to_update.custom_metadata:
+                        c_data.append(cm._to_proto())
+
+                # When handling updates, use to the _to_proto result of the custom_metadata
+                chunk_to_update.custom_metadata = c_data
+
+                updates = flatten_update_paths(value)
+                # At this time, only `data` can be updated
+                for item in updates:
+                    if item != "data.string_value":
+                        raise ValueError(
+                            f"Invalid operation: Currently, only the 'data' attribute can be updated for a 'Chunk'. Attempted to update '{item}'."
+                        )
+                field_mask = field_mask_pb2.FieldMask()
+                for path in updates.keys():
+                    field_mask.paths.append(path)
+                for path, value in updates.items():
+                    chunk_to_update._apply_update(path, value)
+                _requests.append(
+                    protos.UpdateChunkRequest(
+                        chunk=chunk_to_update.to_dict(), update_mask=field_mask
+                    )
+                )
+            request = protos.BatchUpdateChunksRequest(parent=self.name, requests=_requests)
+            response = await client.batch_update_chunks(request, **request_options)
+            response = type(response).to_dict(response)
+            return response
+        if isinstance(chunks, Iterable) and not isinstance(chunks, Mapping):
+            for chunk in chunks:
+                if isinstance(chunk, protos.UpdateChunkRequest):
+                    _requests.append(chunk)
+                elif isinstance(chunk, tuple):
+                    # First element is name of chunk, second element contains updates
+                    chunk_to_update = self.get_chunk(name=chunk[0])
+
+                    # Handle the custom_metadata parameter
+                    c_data = []
+                    if chunk_to_update.custom_metadata:
+                        for cm in chunk_to_update.custom_metadata:
+                            c_data.append(cm._to_proto())
+
+                    # When handling updates, use to the _to_proto result of the custom_metadata
+                    chunk_to_update.custom_metadata = c_data
+
+                    updates = flatten_update_paths(chunk[1])
+                    field_mask = field_mask_pb2.FieldMask()
+                    for path in updates.keys():
+                        field_mask.paths.append(path)
+                    for path, value in updates.items():
+                        chunk_to_update._apply_update(path, value)
+                    _requests.append(
+                        {"chunk": chunk_to_update.to_dict(), "update_mask": field_mask}
+                    )
+                else:
+                    raise TypeError(
+                        "Invalid input: The 'chunks' parameter must be a list of 'protos.UpdateChunkRequests', "
+                        "dictionaries, or tuples of dictionaries."
+                    )
+            request = protos.BatchUpdateChunksRequest(parent=self.name, requests=_requests)
+            response = await client.batch_update_chunks(request, **request_options)
+            response = type(response).to_dict(response)
+            return response
+
+    def delete_chunk(
+        self,
+        name: str,
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,  # fmt: {}
+    ):
+        """
+        Delete a `Chunk`.
+
+        Args:
+            name: The `Chunk` name.
+            request_options: Options for the request.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        if "/" not in name:
+            name = f"{self.name}/chunks/{name}"
+
+        request = protos.DeleteChunkRequest(name=name)
+        client.delete_chunk(request, **request_options)
+
+    async def delete_chunk_async(
+        self,
+        name: str,
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,  # fmt: {}
+    ):
+        """This is the async version of `Document.delete_chunk`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        if "/" not in name:
+            name = f"{self.name}/chunks/{name}"
+
+        request = protos.DeleteChunkRequest(name=name)
+        await client.delete_chunk(request, **request_options)
+
+    def batch_delete_chunks(
+        self,
+        chunks: BatchDeleteChunkOptions,
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """
+        Delete multiple `Chunk`s from a document.
+
+        Args:
+            chunks: Names of `Chunks` to delete.
+            request_options: Options for the request.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        if all(isinstance(x, protos.DeleteChunkRequest) for x in chunks):
+            request = protos.BatchDeleteChunksRequest(parent=self.name, requests=chunks)
+            client.batch_delete_chunks(request, **request_options)
+        elif isinstance(chunks, Iterable):
+            _request_list = []
+            for chunk_name in chunks:
+                _request_list.append(protos.DeleteChunkRequest(name=chunk_name))
+            request = protos.BatchDeleteChunksRequest(parent=self.name, requests=_request_list)
+            client.batch_delete_chunks(request, **request_options)
+        else:
+            raise ValueError(
+                "Invalid operation: To delete chunks, you must pass in either the names of the chunks as an iterable, "
+                "or multiple 'protos.DeleteChunkRequest's."
+            )
+
+    async def batch_delete_chunks_async(
+        self,
+        chunks: BatchDeleteChunkOptions,
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """This is the async version of `Document.batch_delete_chunks`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        if all(isinstance(x, protos.DeleteChunkRequest) for x in chunks):
+            request = protos.BatchDeleteChunksRequest(parent=self.name, requests=chunks)
+            await client.batch_delete_chunks(request, **request_options)
+        elif isinstance(chunks, Iterable):
+            _request_list = []
+            for chunk_name in chunks:
+                _request_list.append(protos.DeleteChunkRequest(name=chunk_name))
+            request = protos.BatchDeleteChunksRequest(parent=self.name, requests=_request_list)
+            await client.batch_delete_chunks(request, **request_options)
+        else:
+            raise ValueError(
+                "Invalid operation: To delete chunks, you must pass in either the names of the chunks as an iterable, "
+                "or multiple 'protos.DeleteChunkRequest's."
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {
+            "name": self.name,
+            "display_name": self.display_name,
+            "custom_metadata": self.custom_metadata,
+        }
+        return result
+
+
+def decode_chunk(chunk: protos.Chunk) -> Chunk:
+    chunk = type(chunk).to_dict(chunk)
+    idecode_time(chunk, "create_time")
+    idecode_time(chunk, "update_time")
+    return Chunk(**chunk)
+
+
+@string_utils.prettyprint
+@dataclasses.dataclass
+class RelevantChunk:
+    chunk_relevance_score: float
+    chunk: Chunk
+
+
+@string_utils.prettyprint
+@dataclasses.dataclass(init=False)
+class Chunk(abc.ABC):
+    """
+    A `Chunk` is part of the `Document`, or the actual text.
+    """
+
+    name: str
+    data: ChunkData
+    custom_metadata: list[CustomMetadata] | None
+    state: State
+    create_time: datetime.datetime | None
+    update_time: datetime.datetime | None
+
+    def __init__(
+        self,
+        name: str,
+        data: ChunkData | str,
+        custom_metadata: Iterable[CustomMetadata] | None,
+        state: State,
+        create_time: datetime.datetime | str | None = None,
+        update_time: datetime.datetime | str | None = None,
+    ):
+        self.name = name
+        if isinstance(data, str):
+            self.data = ChunkData(string_value=data)
+        elif isinstance(data, dict):
+            self.data = ChunkData(string_value=data["string_value"])
+
+        if custom_metadata is None:
+            self.custom_metadata = []
+        else:
+            self.custom_metadata = [make_custom_metadata(cm) for cm in custom_metadata]
+
+        self.state = to_state(state)
+
+        if create_time is None:
+            self.create_time = None
+        elif isinstance(create_time, datetime.datetime):
+            self.create_time = create_time
+        else:
+            self.create_time = datetime.datetime.strptime(create_time, "%Y-%m-%dT%H:%M:%S.%fZ")
+
+        if update_time is None:
+            self.update_time = None
+        elif isinstance(update_time, datetime.datetime):
+            self.update_time = update_time
+        else:
+            self.update_time = datetime.datetime.strptime(update_time, "%Y-%m-%dT%H:%M:%S.%fZ")
+
+    def _apply_update(self, path, value):
+        parts = path.split(".")
+        for part in parts[:-1]:
+            self = getattr(self, part)
+        setattr(self, parts[-1], value)
+
+    def update(
+        self,
+        updates: dict[str, Any],
+        client: glm.RetrieverServiceClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """
+        Update a list of fields for a specified `Chunk`.
+
+        Args:
+            updates: List of fields to update for a `Chunk`.
+            request_options: Options for the request.
+
+        Return:
+            Updated `Chunk` object.
+        """
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_client()
+
+        # Handle the custom_metadata parameter
+        c_data = []
+        if self.custom_metadata:
+            for cm in self.custom_metadata:
+                c_data.append(cm._to_proto())
+
+        # When handling updates, use to the _to_proto result of the custom_metadata
+        self.custom_metadata = c_data
+
+        updates = flatten_update_paths(updates)
+        # At this time, only `data` can be updated
+        for item in updates:
+            if item != "data.string_value":
+                raise ValueError(
+                    f"Invalid operation: Currently, only the 'data' attribute can be updated for a 'Chunk'. Attempted to update '{item}'."
+                )
+        field_mask = field_mask_pb2.FieldMask()
+
+        for path in updates.keys():
+            field_mask.paths.append(path)
+        for path, value in updates.items():
+            self._apply_update(path, value)
+        request = protos.UpdateChunkRequest(chunk=self.to_dict(), update_mask=field_mask)
+
+        client.update_chunk(request, **request_options)
+        return self
+
+    async def update_async(
+        self,
+        updates: dict[str, Any],
+        client: glm.RetrieverServiceAsyncClient | None = None,
+        request_options: helper_types.RequestOptionsType | None = None,
+    ):
+        """This is the async version of `Chunk.update`."""
+        if request_options is None:
+            request_options = {}
+
+        if client is None:
+            client = get_default_retriever_async_client()
+
+        # Handle the custom_metadata parameter
+        c_data = []
+        if self.custom_metadata:
+            for cm in self.custom_metadata:
+                c_data.append(cm._to_proto())
+
+        # When handling updates, use to the _to_proto result of the custom_metadata
+        self.custom_metadata = c_data
+
+        updates = flatten_update_paths(updates)
+        # At this time, only `data` can be updated
+        for item in updates:
+            if item != "data.string_value":
+                raise ValueError(
+                    f"Invalid operation: Currently, only the 'data' attribute can be updated for a 'Chunk'. Attempted to update '{item}'."
+                )
+        field_mask = field_mask_pb2.FieldMask()
+
+        for path in updates.keys():
+            field_mask.paths.append(path)
+        for path, value in updates.items():
+            self._apply_update(path, value)
+        request = protos.UpdateChunkRequest(chunk=self.to_dict(), update_mask=field_mask)
+
+        await client.update_chunk(request, **request_options)
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {
+            "name": self.name,
+            "data": dataclasses.asdict(self.data),
+            "custom_metadata": [cm._to_dict() for cm in self.custom_metadata],
+            "state": self.state,
+        }
+        return result

.venv/lib/python3.11/site-packages/google/logging/type/http_request_pb2.py

@@ -0,0 +1,47 @@
+# -*- coding: utf-8 -*-
+
+# Copyright 2024 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.
+
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: google/logging/type/http_request.proto
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.protobuf import duration_pb2 as google_dot_protobuf_dot_duration__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(
+    b'\n&google/logging/type/http_request.proto\x12\x13google.logging.type\x1a\x1egoogle/protobuf/duration.proto"\xef\x02\n\x0bHttpRequest\x12\x16\n\x0erequest_method\x18\x01 \x01(\t\x12\x13\n\x0brequest_url\x18\x02 \x01(\t\x12\x14\n\x0crequest_size\x18\x03 \x01(\x03\x12\x0e\n\x06status\x18\x04 \x01(\x05\x12\x15\n\rresponse_size\x18\x05 \x01(\x03\x12\x12\n\nuser_agent\x18\x06 \x01(\t\x12\x11\n\tremote_ip\x18\x07 \x01(\t\x12\x11\n\tserver_ip\x18\r \x01(\t\x12\x0f\n\x07referer\x18\x08 \x01(\t\x12*\n\x07latency\x18\x0e \x01(\x0b\x32\x19.google.protobuf.Duration\x12\x14\n\x0c\x63\x61\x63he_lookup\x18\x0b \x01(\x08\x12\x11\n\tcache_hit\x18\t \x01(\x08\x12*\n"cache_validated_with_origin_server\x18\n \x01(\x08\x12\x18\n\x10\x63\x61\x63he_fill_bytes\x18\x0c \x01(\x03\x12\x10\n\x08protocol\x18\x0f \x01(\tB\xbe\x01\n\x17\x63om.google.logging.typeB\x10HttpRequestProtoP\x01Z8google.golang.org/genproto/googleapis/logging/type;ltype\xaa\x02\x19Google.Cloud.Logging.Type\xca\x02\x19Google\\Cloud\\Logging\\Type\xea\x02\x1cGoogle::Cloud::Logging::Typeb\x06proto3'
+)
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(
+    DESCRIPTOR, "google.logging.type.http_request_pb2", _globals
+)
+if _descriptor._USE_C_DESCRIPTORS == False:
+    DESCRIPTOR._options = None
+    DESCRIPTOR._serialized_options = b"\n\027com.google.logging.typeB\020HttpRequestProtoP\001Z8google.golang.org/genproto/googleapis/logging/type;ltype\252\002\031Google.Cloud.Logging.Type\312\002\031Google\\Cloud\\Logging\\Type\352\002\034Google::Cloud::Logging::Type"
+    _globals["_HTTPREQUEST"]._serialized_start = 96
+    _globals["_HTTPREQUEST"]._serialized_end = 463
+# @@protoc_insertion_point(module_scope)

.venv/lib/python3.11/site-packages/google/protobuf/compiler/plugin_pb2.py

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: google/protobuf/compiler/plugin.proto
+# Protobuf Python Version: 5.29.3
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    5,
+    29,
+    3,
+    '',
+    'google/protobuf/compiler/plugin.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.protobuf import descriptor_pb2 as google_dot_protobuf_dot_descriptor__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n%google/protobuf/compiler/plugin.proto\x12\x18google.protobuf.compiler\x1a google/protobuf/descriptor.proto\"c\n\x07Version\x12\x14\n\x05major\x18\x01 \x01(\x05R\x05major\x12\x14\n\x05minor\x18\x02 \x01(\x05R\x05minor\x12\x14\n\x05patch\x18\x03 \x01(\x05R\x05patch\x12\x16\n\x06suffix\x18\x04 \x01(\tR\x06suffix\"\xcf\x02\n\x14\x43odeGeneratorRequest\x12(\n\x10\x66ile_to_generate\x18\x01 \x03(\tR\x0e\x66ileToGenerate\x12\x1c\n\tparameter\x18\x02 \x01(\tR\tparameter\x12\x43\n\nproto_file\x18\x0f \x03(\x0b\x32$.google.protobuf.FileDescriptorProtoR\tprotoFile\x12\\\n\x17source_file_descriptors\x18\x11 \x03(\x0b\x32$.google.protobuf.FileDescriptorProtoR\x15sourceFileDescriptors\x12L\n\x10\x63ompiler_version\x18\x03 \x01(\x0b\x32!.google.protobuf.compiler.VersionR\x0f\x63ompilerVersion\"\x85\x04\n\x15\x43odeGeneratorResponse\x12\x14\n\x05\x65rror\x18\x01 \x01(\tR\x05\x65rror\x12-\n\x12supported_features\x18\x02 \x01(\x04R\x11supportedFeatures\x12\'\n\x0fminimum_edition\x18\x03 \x01(\x05R\x0eminimumEdition\x12\'\n\x0fmaximum_edition\x18\x04 \x01(\x05R\x0emaximumEdition\x12H\n\x04\x66ile\x18\x0f \x03(\x0b\x32\x34.google.protobuf.compiler.CodeGeneratorResponse.FileR\x04\x66ile\x1a\xb1\x01\n\x04\x46ile\x12\x12\n\x04name\x18\x01 \x01(\tR\x04name\x12\'\n\x0finsertion_point\x18\x02 \x01(\tR\x0einsertionPoint\x12\x18\n\x07\x63ontent\x18\x0f \x01(\tR\x07\x63ontent\x12R\n\x13generated_code_info\x18\x10 \x01(\x0b\x32\".google.protobuf.GeneratedCodeInfoR\x11generatedCodeInfo\"W\n\x07\x46\x65\x61ture\x12\x10\n\x0c\x46\x45\x41TURE_NONE\x10\x00\x12\x1b\n\x17\x46\x45\x41TURE_PROTO3_OPTIONAL\x10\x01\x12\x1d\n\x19\x46\x45\x41TURE_SUPPORTS_EDITIONS\x10\x02\x42r\n\x1c\x63om.google.protobuf.compilerB\x0cPluginProtosZ)google.golang.org/protobuf/types/pluginpb\xaa\x02\x18Google.Protobuf.Compiler')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'google.protobuf.compiler.plugin_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'\n\034com.google.protobuf.compilerB\014PluginProtosZ)google.golang.org/protobuf/types/pluginpb\252\002\030Google.Protobuf.Compiler'
+  _globals['_VERSION']._serialized_start=101
+  _globals['_VERSION']._serialized_end=200
+  _globals['_CODEGENERATORREQUEST']._serialized_start=203
+  _globals['_CODEGENERATORREQUEST']._serialized_end=538
+  _globals['_CODEGENERATORRESPONSE']._serialized_start=541
+  _globals['_CODEGENERATORRESPONSE']._serialized_end=1058
+  _globals['_CODEGENERATORRESPONSE_FILE']._serialized_start=792
+  _globals['_CODEGENERATORRESPONSE_FILE']._serialized_end=969
+  _globals['_CODEGENERATORRESPONSE_FEATURE']._serialized_start=971
+  _globals['_CODEGENERATORRESPONSE_FEATURE']._serialized_end=1058
+# @@protoc_insertion_point(module_scope)

.venv/lib/python3.11/site-packages/google/protobuf/internal/__init__.py

@@ -0,0 +1,7 @@
+# Protocol Buffers - Google's data interchange format
+# Copyright 2008 Google Inc.  All rights reserved.
+#
+# Use of this source code is governed by a BSD-style
+# license that can be found in the LICENSE file or at
+# https://developers.google.com/open-source/licenses/bsd
+