// Copyright 2019 Google LLC.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

syntax = "proto3";

package google.cloud.talent.v4beta1;

import "google/api/annotations.proto";
import "google/cloud/talent/v4beta1/profile.proto";

option go_package = "google.golang.org/genproto/googleapis/cloud/talent/v4beta1;talent";
option java_multiple_files = true;
option java_outer_classname = "ResumeServiceProto";
option java_package = "com.google.cloud.talent.v4beta1";
option objc_class_prefix = "CTS";

// A service that handles resume parsing.
service ResumeService {
  // Parses a resume into a [Profile][google.cloud.talent.v4beta1.Profile]. The
  // API attempts to fill out the following profile fields if present within the
  // resume:
  //
  // * personNames
  // * addresses
  // * emailAddress
  // * phoneNumbers
  // * personalUris
  // * employmentRecords
  // * educationRecords
  // * skills
  //
  // Note that some attributes in these fields may not be populated if they're
  // not present within the resume or unrecognizable by the resume parser.
  //
  // This API does not save the resume or profile. To create a profile from this
  // resume, clients need to call the CreateProfile method again with the
  // profile returned.
  //
  // The following list of formats are supported:
  //
  // * PDF
  // * TXT
  // * DOC
  // * RTF
  // * DOCX
  // * PNG (only when [ParseResumeRequest.enable_ocr][] is set to `true`,
  // otherwise an error is thrown)
  rpc ParseResume(ParseResumeRequest) returns (ParseResumeResponse) {
    option (google.api.http) = {
      post: "/v4beta1/{parent=projects/*}/resumes:parse"
      body: "*"
    };
  }
}

// Parse resume request.
message ParseResumeRequest {
  // Required.
  //
  // The resource name of the project.
  //
  // The format is "projects/{project_id}", for example,
  // "projects/api-test-project".
  string parent = 1;

  // Required.
  //
  // The bytes of the resume file in common format, for example, PDF, TXT.
  // UTF-8 encoding is required if the resume is text-based, otherwise an error
  // is thrown.
  bytes resume = 2;

  // Optional.
  //
  // The region code indicating where the resume is from. Values
  // are as per the ISO-3166-2 format. For example, US, FR, DE.
  //
  // This value is optional, but providing this value improves the resume
  // parsing quality and performance.
  //
  // An error is thrown if the regionCode is invalid.
  string region_code = 3;

  // Optional.
  //
  // The language code of contents in the resume.
  //
  // Language codes must be in BCP-47 format, such as "en-US" or "sr-Latn".
  // For more information, see
  // [Tags for Identifying Languages](https://tools.ietf.org/html/bcp47){:
  // class="external" target="_blank" }.
  string language_code = 4;

  // Optional.
  //
  // Options that change how the resume parse is performed.
  ParseResumeOptions options = 5;
}

// Options that change how the resume parse is performed.
message ParseResumeOptions {
  // Optional.
  //
  // Controls whether Optical Character Recognition (OCR) is enabled.
  //
  // OCR is used to decipher pictorial resumes, or resumes that have some
  // element of pictorial detail (for example, contact information placed within
  // an image in a pdf). Note that the API call has a higher latency if OCR is
  // enabled.
  bool enable_ocr = 1;

  // Optional.
  //
  // Controls whether detected skills are included in the parsed profile from
  // sections of the resume other than just skills sections.
  //
  // Normally, returned skills are limited to those taken from a resume section
  // intended to list skills. When enabled, this feature causes detected
  // skills in other sections to also be included in the returned profile.
  bool enable_full_skill_detection = 2;
}

// Parse resume response.
message ParseResumeResponse {
  // The profile parsed from resume.
  Profile profile = 1;

  // Raw text from resume.
  string raw_text = 2;
}