services.proto

syntax = "proto3";

import "admin_account.proto";
import "admin_apikey.proto";
import "admin.proto";
import "admin_job.proto";
import "admin_metric.proto";
import "admin_security.proto";
import "admin_user.proto";

import "chat.proto";
import "common.proto";
import "indexing.proto";
import "serving.proto";
import "status.proto";
import "list_documents.proto";
import "google/api/annotations.proto";

option java_package = "com.vectara";
option java_outer_classname = "ServiceProtos";

option go_package = "vectara.com/public/proto/services";

package com.vectara;

// Request to index a document.
message IndexDocumentRequest {
  // The Customer ID to issue the request for.
  int64 customer_id = 1;
  // The Corpus ID to index the document into.
  int64 corpus_id = 2;
  // The Document to index.
  com.vectara.indexing.Document document = 3;

}

message IndexDocumentResponse {
  // ALREADY_EXISTS (6) The document has already been indexed, and no new quota was consumed.
  // RESOURCE_EXHAUSTED (8): The indexing request cannot complete because the system is out of resources. This error may be due to too many simultaneous requests or you exceeded your quota.
  // CONFLICT (409): The Document ID already exists. Indexing doesn't support updating documents. 
  // The new request does not match the previous request for the Document ID. If you would like 
  // to update the document, delete it first, and then add it to the index again.
  // TOO_MANY_REQUESTS (429): The server is overloaded, or you sent too many indexing requests 
  // to the server in a short amount of time. This is similar to RESOURCE_EXHAUSTED.
  // IDX__TRANSIENT_PARTIAL_DELETION_FAILURE (5000): The indexing request resulted in a transient error during the partial deletion of documents. Try the request again.
  // IDX__PERMANENT_PARTIAL_DELETION_FAILURE (5001): The indexing request resulted in a 
  // permanent error during the partial deletion of documents. See https://status.vectara.com 
  // for the latest info on any outages. If the problem persists, please contact us via support 
  // or via our community forums at https://discuss.vectara.com if you’re a Growth user. 
  // during the partial deletion of documents.
  //
  // Some common relevant error codes may also be returned for corresponding errors, 
  // for example, PERMISSION_DENIED, DISABLED_CUSTOMER, NOT_FOUND.
  Status status = 1;

  // The storage quota needed for the document indexed in the request.
  // If "status" is ALREADY_EXISTS, it means that the document was already in the index prior to
  // this request. In such cases, quota is not consumed again and the value in this field
  // represents the quota consumed when the document was indexed the first time.
  StorageQuota quota_consumed = 2;
}

service IndexService {
  rpc Index(IndexDocumentRequest) returns (IndexDocumentResponse) {
    option (google.api.http) = {
      post: "/v1/index"
      body: "*"
    };
  }

  rpc Delete(DeleteDocumentRequest) returns (DeleteDocumentResponse) {
    option (google.api.http) = {
      post: "/v1/delete-doc"
      body: "*"
    };
  }
}

service QueryService {
  // A standard single-request, single-response endpoint designed for high performance.
  rpc Query(com.vectara.serving.BatchQueryRequest)
          returns (com.vectara.serving.BatchQueryResponse) {
    option (google.api.http) = {
      post: "/v1/query"
      body: "*"
    };
  }

  // A streamed response interface when lower latency is absolutely critical.
  rpc StreamQuery(com.vectara.serving.BatchQueryRequest)
      returns (stream com.vectara.serving.QueryResponsePart) {
    option (google.api.http) = {
      post: "/v1/stream-query"
      body: "*"
    };
  }
}


service AdminService {
  rpc CreateCorpus(com.vectara.admin.CreateCorpusRequest) returns (com.vectara.admin.CreateCorpusResponse){
    option (google.api.http) = {
      post: "/v1/create-corpus"
      body: "*"
    };
  }

  rpc UpdateCorpus(com.vectara.admin.UpdateCorpusRequest)
    returns (com.vectara.admin.UpdateCorpusResponse) {
    option (google.api.http) = {
      post: "/v1/update-corpus"
      body: "*"
    };
  }

  rpc DeleteCorpus(com.vectara.admin.DeleteCorpusRequest) returns (com.vectara.admin.DeleteCorpusResponse){
    option (google.api.http) = {
      post: "/v1/delete-corpus"
      body: "*"
    };
  }

  rpc ResetCorpus(com.vectara.admin.ResetCorpusRequest) returns (com.vectara.admin.ResetCorpusResponse){
    option (google.api.http) = {
      post: "/v1/reset-corpus"
      body: "*"
    };
  }
  
  rpc ListCorpora(com.vectara.admin.ListCorporaRequest)
      returns (com.vectara.admin.ListCorporaResponse) {
    option (google.api.http) = {
      post: "/v1/list-corpora"
      body: "*"
    };
  }

  rpc ListJobs(com.vectara.admin.ListJobsRequest) returns (com.vectara.admin.ListJobsResponse) {
    option (google.api.http) = {
      post: "/v1/list-jobs"
      body: "*"
    };
  }

  // Return information about corpora.
  rpc ReadCorpus(com.vectara.admin.ReadCorpusRequest)
          returns (com.vectara.admin.ReadCorpusResponse) {
    option (google.api.http) = {
      post: "/v1/read-corpus"
      body: "*"
    };
  }

  rpc ComputeCorpusSize(com.vectara.admin.ComputeCorpusSizeRequest)
          returns (com.vectara.admin.ComputeCorpusSizeResponse) {
    option (google.api.http) = {
      post: "/v1/compute-corpus-size"
      body: "*"
    };
  }

  rpc ComputeAccountSize(com.vectara.admin.ComputeAccountSizeRequest)
        returns (com.vectara.admin.ComputeAccountSizeResponse) {
    option (google.api.http) = {
      post: "/v1/compute-account-size"
      body: "*"
    };
  }

  rpc ListUsers(com.vectara.admin.ListUsersRequest)
          returns (com.vectara.admin.ListUsersResponse) {
    option (google.api.http) = {
      post: "/v1/list-users"
      body: "*"
    };
  }

  rpc ManageUser(com.vectara.admin.ManageUserRequest)
          returns (com.vectara.admin.ManageUserResponse) {
    option (google.api.http) = {
      post: "/v1/manage-user"
      body: "*"
    };
  }

  rpc UpdateCorpusEnablement(com.vectara.admin.UpdateCorpusEnablementRequest) returns (com.vectara.admin.UpdateCorpusEnablementResponse) {
    option (google.api.http) = {
      post: "/v1/update-corpus-enablement"
      body: "*"
    };
  }

  rpc ReplaceCorpusFilterAttrs(com.vectara.admin.ReplaceCorpusFilterAttrsRequest) returns (com.vectara.admin.ReplaceCorpusFilterAttrsResponse) {
    option (google.api.http) = {
      post: "/v1/replace-corpus-filter-attrs"
      body: "*"
    };
  }

  // Get metric usage of either sliding windows or between two timestamps
  rpc GetUsageMetrics(com.vectara.admin.UsageMetricsRequest) returns (com.vectara.admin.UsageMetricsResponse){
    option (google.api.http) = {
      post: "/v1/get-usage-metrics"
      body: "*"
    };
  }

  rpc CreateApiKey(com.vectara.admin.CreateApiKeyRequest) returns (com.vectara.admin.CreateApiKeyResponse) {
    option (google.api.http) = {
      post: "/v1/create-api-key"
      body: "*"
    };
  }

  rpc EnableApiKey(com.vectara.admin.EnableApiKeyRequest) returns (com.vectara.admin.EnableApiKeyResponse) {
    option (google.api.http) = {
      post: "/v1/enable-api-key"
      body: "*"
    };
  }

  rpc DeleteApiKey(com.vectara.admin.DeleteApiKeyRequest) returns (com.vectara.admin.DeleteApiKeyResponse) {
    option (google.api.http) = {
      post: "/v1/delete-api-key"
      body: "*"
    };
  }

  rpc ListApiKeys(com.vectara.admin.ListApiKeysRequest) returns (com.vectara.admin.ListApiKeysResponse) {
    option (google.api.http) = {
      post: "/v1/list-api-keys"
      body: "*"
    };
  }

}

// Service for working with documents.
service DocumentService {
  // Returns a list of documents for customer/corpus with pagination and optional document metadata filtering.
  rpc ListDocuments(com.vectara.lists.ListDocumentsRequest) returns (com.vectara.lists.ListDocumentsResponse) {
    option (google.api.http) = {
      post: "/v1/list-documents"
      body: "*"
    };
  }
}

// Service for working with chat conversations.
service ChatService {

  // List all conversations.
  rpc ListConversations(com.vectara.chat.ListConversationsRequest)
      returns (com.vectara.chat.ListConversationsResponse) {
    option (google.api.http) = {
      post: "/v1/list-conversations"
      body: "*"
    };
  }

  // Read all turns within the passed conversations.
  rpc ReadConversations(com.vectara.chat.ReadConversationsRequest)
      returns (com.vectara.chat.ReadConversationsResponse) {
    option (google.api.http) = {
      post: "/v1/read-conversations"
      body: "*"
    };
  }

  // Delete conversations (including all turns in it).
  rpc DeleteConversations(com.vectara.chat.DeleteConversationsRequest)
      returns (com.vectara.chat.DeleteConversationsResponse) {
    option (google.api.http) = {
      post: "/v1/delete-conversations"
      body: "*"
    };
  }

  // Delete turns.
  rpc DeleteTurns(com.vectara.chat.DeleteTurnsRequest)
      returns (com.vectara.chat.DeleteTurnsResponse) {
    option (google.api.http) = {
      post: "/v1/delete-turns"
      body: "*"
    };
  }

  // Disable turn. The turn will no longer be used in conversations.
  rpc DisableTurns(com.vectara.chat.DisableTurnsRequest)
      returns (com.vectara.chat.DisableTurnsResponse) {
    option (google.api.http) = {
      post: "/v1/disable-turns"
      body: "*"
    };
  }
}