From 49b95395de3099866bd26ad4d5cab74225c0b3e6 Mon Sep 17 00:00:00 2001 From: Gary Date: Wed, 4 Sep 2024 21:55:52 +0800 Subject: [PATCH] chore(app): set up app in protobuf repo (#447) Because we are going to develop app backend. This commit sets up need initial file and change for app backend --------- Co-authored-by: droplet-bot --- .github/workflows/buf-gen-openapi.yaml | 4 + .github/workflows/sync-api-docs.yml | 11 + app/app/v1alpha/app.proto | 122 ++++ app/app/v1alpha/app_public_service.proto | 125 ++++ app/app/v1alpha/conversation.proto | 204 ++++++ app/app/v1alpha/openapi.proto.templ | 16 + openapiv2/app/service.swagger.yaml | 787 +++++++++++++++++++++++ 7 files changed, 1269 insertions(+) create mode 100644 app/app/v1alpha/app.proto create mode 100644 app/app/v1alpha/app_public_service.proto create mode 100644 app/app/v1alpha/conversation.proto create mode 100644 app/app/v1alpha/openapi.proto.templ create mode 100644 openapiv2/app/service.swagger.yaml diff --git a/.github/workflows/buf-gen-openapi.yaml b/.github/workflows/buf-gen-openapi.yaml index f52828a0..8d66cc0d 100644 --- a/.github/workflows/buf-gen-openapi.yaml +++ b/.github/workflows/buf-gen-openapi.yaml @@ -44,6 +44,10 @@ jobs: uses: readmeio/rdme@v8 with: rdme: openapi:validate openapiv2/artifact/service.swagger.yaml + - name: Lint generated App OpenAPI definitions + uses: readmeio/rdme@v8 + with: + rdme: openapi:validate openapiv2/app/service.swagger.yaml - name: Commit and push run: | if [[ `git status --porcelain` ]]; then diff --git a/.github/workflows/sync-api-docs.yml b/.github/workflows/sync-api-docs.yml index 411b9862..3a81e10c 100644 --- a/.github/workflows/sync-api-docs.yml +++ b/.github/workflows/sync-api-docs.yml @@ -9,6 +9,7 @@ on: - main paths: - 'openapiv2/artifact/**' + - 'openapiv2/app/**' - 'openapiv2/common/**' - 'openapiv2/core/**' - 'openapiv2/model/**' @@ -48,6 +49,11 @@ jobs: uses: readmeio/rdme@v8 with: rdme: openapi openapiv2/artifact/service.swagger.yaml --title "💾 Artifact (PR ${{ github.ref_name }})" --key=${{ secrets.README_API_KEY }} --id=669fb9c72dd8c500184c6531 + + # - name: Sync App 💾 + # uses: readmeio/rdme@v8 + # with: + # rdme: openapi openapiv2/app/service.swagger.yaml --title "📱 App (PR ${{ github.ref_name }})" --key=${{ secrets.README_API_KEY }} --id=669fb9c72dd8c500184c6531 - name: Check new release 🔍 id: check-new-release @@ -102,6 +108,11 @@ jobs: with: rdme: openapi openapiv2/artifact/service.swagger.yaml --key=${{ secrets.README_API_KEY }} --id=669fb97f2071e2004a8f9183 + # - name: Sync App 💾 + # uses: readmeio/rdme@v8 + # with: + # rdme: openapi openapiv2/app/service.swagger.yaml --key=${{ secrets.README_API_KEY }} --id=669fb97f2071e2004a8f9183 + - name: Check new release 🔍 id: check-new-release run: | diff --git a/app/app/v1alpha/app.proto b/app/app/v1alpha/app.proto new file mode 100644 index 00000000..2841a6b0 --- /dev/null +++ b/app/app/v1alpha/app.proto @@ -0,0 +1,122 @@ +syntax = "proto3"; + +package app.app.v1alpha; + +import "common/healthcheck/v1beta/healthcheck.proto"; +// Google API +import "google/api/field_behavior.proto"; +// Protocol Buffers Well-Known Types +import "google/protobuf/timestamp.proto"; + +// LivenessRequest represents a request to check a service liveness status +message LivenessRequest { + // HealthCheckRequest message + optional common.healthcheck.v1beta.HealthCheckRequest health_check_request = 1 [(google.api.field_behavior) = OPTIONAL]; +} + +// LivenessResponse represents a response for a service liveness status +message LivenessResponse { + // HealthCheckResponse message + common.healthcheck.v1beta.HealthCheckResponse health_check_response = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// ReadinessRequest represents a request to check a service readiness status +message ReadinessRequest { + // HealthCheckRequest message + optional common.healthcheck.v1beta.HealthCheckRequest health_check_request = 1 [(google.api.field_behavior) = OPTIONAL]; +} + +// ReadinessResponse represents a response for a service readiness status +message ReadinessResponse { + // HealthCheckResponse message + common.healthcheck.v1beta.HealthCheckResponse health_check_response = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +/* + + This API is under development and, therefore, some of its entities and + endpoints are not implemented yet. This section aims to give context about the + current interface and how it fits in the App vision. + + # App + + The App domain is responsible of ready-to-use AI applications. + +*/ + +// App represents a app. +message App { + // The app id. + string app_id = 1 [(google.api.field_behavior) = REQUIRED]; + // The app name. + string name = 2 [(google.api.field_behavior) = REQUIRED]; + // The app description. + string description = 3 [(google.api.field_behavior) = OPTIONAL]; + // The creation time of the app. + google.protobuf.Timestamp create_time = 5 [(google.api.field_behavior) = OUTPUT_ONLY]; + // The last update time of the app. + google.protobuf.Timestamp update_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY]; + // The owner/namespace of the app. + string owner_name = 7 [(google.api.field_behavior) = OUTPUT_ONLY]; + // The app tags. + repeated string tags = 8 [(google.api.field_behavior) = OPTIONAL]; +} + +// CreateAppRequest represents a request to create a app. +message CreateAppRequest { + // The app's owner(namespaces). + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; + // The app name. + string name = 2 [(google.api.field_behavior) = REQUIRED]; + // The app description. + string description = 3 [(google.api.field_behavior) = OPTIONAL]; + // The app tags. + repeated string tags = 4 [(google.api.field_behavior) = OPTIONAL]; +} + +// CreateAppResponse represents a response for creating a app. +message CreateAppResponse { + // The created app. + App app = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// Request message for ListApps +message ListAppsRequest { + // User ID for which to list the apps + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; +} + +// GetAppsResponse represents a response for getting all apps from users. +message ListAppsResponse { + // The apps container. + repeated App apps = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// UpdateAppRequest represents a request to update a app. +message UpdateAppRequest { + // The app id. + string app_id = 1 [(google.api.field_behavior) = REQUIRED]; + // The app description. + string description = 2 [(google.api.field_behavior) = OPTIONAL]; + // The app tags. + repeated string tags = 3 [(google.api.field_behavior) = OPTIONAL]; + // The app owner(namespace). + string namespace_id = 4 [(google.api.field_behavior) = REQUIRED]; +} + +// UpdateAppResponse represents a response for updating a app. +message UpdateAppResponse { + // The updated app. + App app = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// DeleteAppRequest represents a request to delete a app. +message DeleteAppRequest { + // The owner's id. i.e. namespace. + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; + // The app id. + string app_id = 2 [(google.api.field_behavior) = REQUIRED]; +} + +// DeleteAppResponse represents a response for deleting a app. +message DeleteAppResponse {} diff --git a/app/app/v1alpha/app_public_service.proto b/app/app/v1alpha/app_public_service.proto new file mode 100644 index 00000000..fd231c42 --- /dev/null +++ b/app/app/v1alpha/app_public_service.proto @@ -0,0 +1,125 @@ +syntax = "proto3"; + +package app.app.v1alpha; + +// App definitions +import "app/app/v1alpha/app.proto"; +import "app/app/v1alpha/conversation.proto"; +// Google API +import "google/api/annotations.proto"; +import "google/api/visibility.proto"; +// OpenAPI definition +import "protoc-gen-openapiv2/options/annotations.proto"; + +// AppPublicService exposes the public endpoints that allow clients to +// manage apps. +service AppPublicService { + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_tag) = {description: "Public App endpoints"}; + + // Check if the app server is alive + // + // See https://github.com/grpc/grpc/blob/master/doc/health-checking.md. + rpc Liveness(LivenessRequest) returns (LivenessResponse) { + option (google.api.http) = { + get: "/v1alpha/__liveness" + additional_bindings: [ + {get: "/v1alpha/health/app"}] + }; + option (google.api.method_visibility).restriction = "INTERNAL"; + } + + // Check if the app server is ready + // + // See https://github.com/grpc/grpc/blob/master/doc/health-checking.md + rpc Readiness(ReadinessRequest) returns (ReadinessResponse) { + option (google.api.http) = { + get: "/v1alpha/__readiness" + additional_bindings: [ + {get: "/v1alpha/ready/app"}] + }; + option (google.api.method_visibility).restriction = "INTERNAL"; + } + + // Create a App + rpc CreateApp(CreateAppRequest) returns (CreateAppResponse) { + option (google.api.http) = { + post: "/v1alpha/namespaces/{namespace_id}/apps" + body: "*" + }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "App"}; + } + + // Get all apps info + rpc ListApps(ListAppsRequest) returns (ListAppsResponse) { + option (google.api.http) = {get: "/v1alpha/namespaces/{namespace_id}/apps"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "App"}; + } + + // Update a app info + rpc UpdateApp(UpdateAppRequest) returns (UpdateAppResponse) { + option (google.api.http) = { + put: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}" + body: "*" + }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "App"}; + } + + // Delete a app + rpc DeleteApp(DeleteAppRequest) returns (DeleteAppResponse) { + option (google.api.http) = {delete: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "App"}; + } + + // Create a Conversation + rpc CreateConversation(CreateConversationRequest) returns (CreateConversationResponse) { + option (google.api.http) = { + post: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations" + body: "*" + }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "app"}; + } + // List conversations + rpc ListConversations(ListConversationsRequest) returns (ListConversationsResponse) { + option (google.api.http) = {get: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "app"}; + } + // Update a conversation + rpc UpdateConversation(UpdateConversationRequest) returns (UpdateConversationResponse) { + option (google.api.http) = { + put: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations/{conversation_id}" + body: "*" + }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "app"}; + } + // Delete a conversation + rpc DeleteConversation(DeleteConversationRequest) returns (DeleteConversationResponse) { + option (google.api.http) = {delete: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations/{conversation_id}"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "app"}; + } + // Create a message + rpc CreateMessage(CreateMessageRequest) returns (CreateMessageResponse) { + option (google.api.http) = { + post: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations/{conversation_id}/messages" + body: "*" + }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "app"}; + } + // List messages + rpc ListMessages(ListMessagesRequest) returns (ListMessagesResponse) { + option (google.api.http) = {get: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations/{conversation_id}/messages"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "app"}; + } + // Update a message + rpc UpdateMessage(UpdateMessageRequest) returns (UpdateMessageResponse) { + option (google.api.http) = { + put: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations/{conversation_id}/messages/{message_uid}" + body: "*" + }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "app"}; + } + // Delete a message + rpc DeleteMessage(DeleteMessageRequest) returns (DeleteMessageResponse) { + option (google.api.http) = {delete: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations/{conversation_id}/messages/{message_uid}"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "app"}; + } +} diff --git a/app/app/v1alpha/conversation.proto b/app/app/v1alpha/conversation.proto new file mode 100644 index 00000000..8f7632a3 --- /dev/null +++ b/app/app/v1alpha/conversation.proto @@ -0,0 +1,204 @@ +syntax = "proto3"; + +package app.app.v1alpha; + +import "google/api/field_behavior.proto"; +// Protocol Buffers Well-Known Types +import "google/protobuf/timestamp.proto"; + +// Conversation represents a chat conversation +message Conversation { + // unique identifier of the conversation created by the system + string uid = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; + // namespace id + string namespace_id = 2 [(google.api.field_behavior) = REQUIRED]; + // app id + string app_id = 3 [(google.api.field_behavior) = REQUIRED]; + // conversation id/name + string id = 4 [(google.api.field_behavior) = REQUIRED]; + // creation time of the conversation + google.protobuf.Timestamp create_time = 5 [(google.api.field_behavior) = OUTPUT_ONLY]; + // update time of the conversation + google.protobuf.Timestamp update_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// Message represents a single message in a conversation +message Message { + // message type + enum MessageType { + // unspecified + MESSAGE_TYPE_UNSPECIFIED = 0; + // text + MESSAGE_TYPE_TEXT = 1; + } + // message uid + string uid = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; + // app uid + string app_uid = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; + // conversation uid + string conversation_uid = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; + // message content + string content = 4 [(google.api.field_behavior) = REQUIRED]; + // message role e.g., "user" or "assistant" + string role = 5 [(google.api.field_behavior) = REQUIRED]; + // message type + MessageType type = 6 [(google.api.field_behavior) = REQUIRED]; + // creation time of the message + google.protobuf.Timestamp create_time = 7 [(google.api.field_behavior) = OUTPUT_ONLY]; + // update time of the message + google.protobuf.Timestamp update_time = 8 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// CreateConversationRequest is used to create a new conversation +message CreateConversationRequest { + // namespace id + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; + // app id + string app_id = 2 [(google.api.field_behavior) = REQUIRED]; + // conversation id. only allow kebab case + string conversation_id = 3 [(google.api.field_behavior) = REQUIRED]; +} + +// CreateConversationResponse returns the created conversation +message CreateConversationResponse { + // conversation + Conversation conversation = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// ListConversationsRequest is used to list conversations +message ListConversationsRequest { + // namespace id + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; + // app id + string app_id = 2 [(google.api.field_behavior) = REQUIRED]; + // page size + int32 page_size = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; + // page token + string page_token = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// ListConversationsResponse returns a list of conversations +message ListConversationsResponse { + // conversations + repeated Conversation conversations = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; + // next page token + string next_page_token = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; + // total size + int32 total_size = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// UpdateConversationRequest is used to update a conversation +message UpdateConversationRequest { + // namespace id + string namespace_id = 1; + // app id + string app_id = 2 [(google.api.field_behavior) = REQUIRED]; + // conversation id + string conversation_id = 3 [(google.api.field_behavior) = REQUIRED]; + // new conversation id + string new_conversation_id = 4 [(google.api.field_behavior) = REQUIRED]; +} + +// UpdateConversationResponse returns the updated conversation +message UpdateConversationResponse { + // conversation + Conversation conversation = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// DeleteConversationRequest is used to delete a conversation +message DeleteConversationRequest { + // namespace id + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; + // app id + string app_id = 2 [(google.api.field_behavior) = REQUIRED]; + // conversation id + string conversation_id = 3 [(google.api.field_behavior) = REQUIRED]; +} + +// DeleteConversationResponse is empty as no content needs to be returned +message DeleteConversationResponse {} + +// CreateMessageRequest is used to create a new message +message CreateMessageRequest { + // namespace id + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; + // app id + string app_id = 2 [(google.api.field_behavior) = REQUIRED]; + // conversation id + string conversation_id = 3 [(google.api.field_behavior) = REQUIRED]; + // message content + string content = 4 [(google.api.field_behavior) = REQUIRED]; + // message role + string role = 5 [(google.api.field_behavior) = REQUIRED]; + // message type + Message.MessageType type = 6 [(google.api.field_behavior) = REQUIRED]; +} + +// CreateMessageResponse returns the created message +message CreateMessageResponse { + // message + Message message = 1; +} + +// ListMessagesRequest is used to list messages in a conversation +message ListMessagesRequest { + // namespace id + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; + // app id + string app_id = 2 [(google.api.field_behavior) = REQUIRED]; + // conversation id + string conversation_id = 3 [(google.api.field_behavior) = REQUIRED]; + // latest k messages + int32 latest_k = 4 [(google.api.field_behavior) = OPTIONAL]; + // page size + int32 page_size = 5 [(google.api.field_behavior) = OUTPUT_ONLY]; + // page token + string page_token = 6 [(google.api.field_behavior) = OUTPUT_ONLY]; + // include system messages + bool include_system_messages = 7 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// ListMessagesResponse returns a list of messages +message ListMessagesResponse { + // messages + repeated Message messages = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; + // next page token + string next_page_token = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; + // total size + int32 total_size = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// UpdateMessageRequest is used to update a message +message UpdateMessageRequest { + // namespace id + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; + // app id + string app_id = 2 [(google.api.field_behavior) = REQUIRED]; + // conversation id + string conversation_id = 3 [(google.api.field_behavior) = REQUIRED]; + // message uid + string message_uid = 4 [(google.api.field_behavior) = REQUIRED]; + // new message content + string content = 5 [(google.api.field_behavior) = REQUIRED]; +} + +// UpdateMessageResponse returns the updated message +message UpdateMessageResponse { + // message + Message message = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// DeleteMessageRequest is used to delete a message +message DeleteMessageRequest { + // namespace id + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; + // app id + string app_id = 2 [(google.api.field_behavior) = REQUIRED]; + // conversation id + string conversation_id = 3 [(google.api.field_behavior) = REQUIRED]; + // message uid + string message_uid = 4 [(google.api.field_behavior) = REQUIRED]; +} + +// DeleteMessageResponse is empty as no content needs to be returned +message DeleteMessageResponse {} diff --git a/app/app/v1alpha/openapi.proto.templ b/app/app/v1alpha/openapi.proto.templ new file mode 100644 index 00000000..cc877298 --- /dev/null +++ b/app/app/v1alpha/openapi.proto.templ @@ -0,0 +1,16 @@ +syntax = "proto3"; + +package app.app.v1alpha; + +import "protoc-gen-openapiv2/options/annotations.proto"; + +// These options define the OpenAPI definition document information. +option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = { + info: { + title: "📱 App " + description: "App endpoints to manage app resources" +{{$info}} + } + tags: [] +{{$conf}} +}; diff --git a/openapiv2/app/service.swagger.yaml b/openapiv2/app/service.swagger.yaml new file mode 100644 index 00000000..5532108a --- /dev/null +++ b/openapiv2/app/service.swagger.yaml @@ -0,0 +1,787 @@ +swagger: "2.0" +info: + title: "\U0001F4F1 App " + description: App endpoints to manage app resources + version: v0.39.0-beta + contact: + name: Instill AI + url: https://github.com/instill-ai + email: hello@instill.tech + license: + name: Elastic License 2.0 (ELv2) + url: https://github.com/instill-ai/protobufs/blob/main/LICENSE +host: api.instill.tech +schemes: + - https + - http +consumes: + - application/json +produces: + - application/json +paths: + /v1alpha/namespaces/{namespaceId}/apps: + get: + summary: Get all apps info + operationId: AppPublicService_ListApps + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/v1alphaListAppsResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpcStatus' + parameters: + - name: namespaceId + description: User ID for which to list the apps + in: path + required: true + type: string + tags: + - App + post: + summary: Create a App + operationId: AppPublicService_CreateApp + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/v1alphaCreateAppResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpcStatus' + parameters: + - name: namespaceId + description: The app's owner(namespaces). + in: path + required: true + type: string + - name: body + in: body + required: true + schema: + $ref: '#/definitions/AppPublicServiceCreateAppBody' + tags: + - App + /v1alpha/namespaces/{namespaceId}/apps/{appId}: + delete: + summary: Delete a app + operationId: AppPublicService_DeleteApp + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/v1alphaDeleteAppResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpcStatus' + parameters: + - name: namespaceId + description: The owner's id. i.e. namespace. + in: path + required: true + type: string + - name: appId + description: The app id. + in: path + required: true + type: string + tags: + - App + put: + summary: Update a app info + operationId: AppPublicService_UpdateApp + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/v1alphaUpdateAppResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpcStatus' + parameters: + - name: namespaceId + description: The app owner(namespace). + in: path + required: true + type: string + - name: appId + description: The app id. + in: path + required: true + type: string + - name: body + in: body + required: true + schema: + $ref: '#/definitions/AppPublicServiceUpdateAppBody' + tags: + - App + /v1alpha/namespaces/{namespaceId}/apps/{appId}/conversations: + get: + summary: List conversations + operationId: AppPublicService_ListConversations + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/v1alphaListConversationsResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpcStatus' + parameters: + - name: namespaceId + description: namespace id + in: path + required: true + type: string + - name: appId + description: app id + in: path + required: true + type: string + - name: pageSize + description: page size + in: query + required: false + type: integer + format: int32 + - name: pageToken + description: page token + in: query + required: false + type: string + tags: + - app + post: + summary: Create a Conversation + operationId: AppPublicService_CreateConversation + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/v1alphaCreateConversationResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpcStatus' + parameters: + - name: namespaceId + description: namespace id + in: path + required: true + type: string + - name: appId + description: app id + in: path + required: true + type: string + - name: body + in: body + required: true + schema: + $ref: '#/definitions/AppPublicServiceCreateConversationBody' + tags: + - app + /v1alpha/namespaces/{namespaceId}/apps/{appId}/conversations/{conversationId}: + delete: + summary: Delete a conversation + operationId: AppPublicService_DeleteConversation + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/v1alphaDeleteConversationResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpcStatus' + parameters: + - name: namespaceId + description: namespace id + in: path + required: true + type: string + - name: appId + description: app id + in: path + required: true + type: string + - name: conversationId + description: conversation id + in: path + required: true + type: string + tags: + - app + put: + summary: Update a conversation + operationId: AppPublicService_UpdateConversation + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/v1alphaUpdateConversationResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpcStatus' + parameters: + - name: namespaceId + description: namespace id + in: path + required: true + type: string + - name: appId + description: app id + in: path + required: true + type: string + - name: conversationId + description: conversation id + in: path + required: true + type: string + - name: body + in: body + required: true + schema: + $ref: '#/definitions/AppPublicServiceUpdateConversationBody' + tags: + - app + /v1alpha/namespaces/{namespaceId}/apps/{appId}/conversations/{conversationId}/messages: + get: + summary: List messages + operationId: AppPublicService_ListMessages + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/v1alphaListMessagesResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpcStatus' + parameters: + - name: namespaceId + description: namespace id + in: path + required: true + type: string + - name: appId + description: app id + in: path + required: true + type: string + - name: conversationId + description: conversation id + in: path + required: true + type: string + - name: latestK + description: latest k messages + in: query + required: false + type: integer + format: int32 + - name: pageSize + description: page size + in: query + required: false + type: integer + format: int32 + - name: pageToken + description: page token + in: query + required: false + type: string + - name: includeSystemMessages + description: include system messages + in: query + required: false + type: boolean + tags: + - app + post: + summary: Create a message + operationId: AppPublicService_CreateMessage + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/v1alphaCreateMessageResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpcStatus' + parameters: + - name: namespaceId + description: namespace id + in: path + required: true + type: string + - name: appId + description: app id + in: path + required: true + type: string + - name: conversationId + description: conversation id + in: path + required: true + type: string + - name: body + in: body + required: true + schema: + $ref: '#/definitions/AppPublicServiceCreateMessageBody' + tags: + - app + /v1alpha/namespaces/{namespaceId}/apps/{appId}/conversations/{conversationId}/messages/{messageUid}: + delete: + summary: Delete a message + operationId: AppPublicService_DeleteMessage + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/v1alphaDeleteMessageResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpcStatus' + parameters: + - name: namespaceId + description: namespace id + in: path + required: true + type: string + - name: appId + description: app id + in: path + required: true + type: string + - name: conversationId + description: conversation id + in: path + required: true + type: string + - name: messageUid + description: message uid + in: path + required: true + type: string + tags: + - app + put: + summary: Update a message + operationId: AppPublicService_UpdateMessage + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/v1alphaUpdateMessageResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpcStatus' + parameters: + - name: namespaceId + description: namespace id + in: path + required: true + type: string + - name: appId + description: app id + in: path + required: true + type: string + - name: conversationId + description: conversation id + in: path + required: true + type: string + - name: messageUid + description: message uid + in: path + required: true + type: string + - name: body + in: body + required: true + schema: + $ref: '#/definitions/AppPublicServiceUpdateMessageBody' + tags: + - app +definitions: + AppPublicServiceCreateAppBody: + type: object + properties: + name: + type: string + description: The app name. + description: + type: string + description: The app description. + tags: + type: array + items: + type: string + description: The app tags. + description: CreateAppRequest represents a request to create a app. + required: + - name + AppPublicServiceCreateConversationBody: + type: object + properties: + conversationId: + type: string + title: conversation id. only allow kebab case + title: CreateConversationRequest is used to create a new conversation + required: + - conversationId + AppPublicServiceCreateMessageBody: + type: object + properties: + content: + type: string + title: message content + role: + type: string + title: message role + type: + title: message type + allOf: + - $ref: '#/definitions/MessageMessageType' + title: CreateMessageRequest is used to create a new message + required: + - content + - role + - type + AppPublicServiceUpdateAppBody: + type: object + properties: + description: + type: string + description: The app description. + tags: + type: array + items: + type: string + description: The app tags. + description: UpdateAppRequest represents a request to update a app. + AppPublicServiceUpdateConversationBody: + type: object + properties: + newConversationId: + type: string + title: new conversation id + title: UpdateConversationRequest is used to update a conversation + required: + - newConversationId + AppPublicServiceUpdateMessageBody: + type: object + properties: + content: + type: string + title: new message content + title: UpdateMessageRequest is used to update a message + required: + - content + MessageMessageType: + type: string + enum: + - MESSAGE_TYPE_TEXT + description: '- MESSAGE_TYPE_TEXT: text' + title: message type + protobufAny: + type: object + properties: + '@type': + type: string + additionalProperties: {} + rpcStatus: + type: object + properties: + code: + type: integer + format: int32 + message: + type: string + details: + type: array + items: + type: object + $ref: '#/definitions/protobufAny' + v1alphaApp: + type: object + properties: + appId: + type: string + description: The app id. + name: + type: string + description: The app name. + description: + type: string + description: The app description. + createTime: + type: string + format: date-time + description: The creation time of the app. + readOnly: true + updateTime: + type: string + format: date-time + description: The last update time of the app. + readOnly: true + ownerName: + type: string + description: The owner/namespace of the app. + readOnly: true + tags: + type: array + items: + type: string + description: The app tags. + description: App represents a app. + required: + - appId + - name + v1alphaConversation: + type: object + properties: + uid: + type: string + title: unique identifier of the conversation created by the system + readOnly: true + namespaceId: + type: string + title: namespace id + appId: + type: string + title: app id + id: + type: string + title: conversation id/name + createTime: + type: string + format: date-time + title: creation time of the conversation + readOnly: true + updateTime: + type: string + format: date-time + title: update time of the conversation + readOnly: true + title: Conversation represents a chat conversation + required: + - namespaceId + - appId + - id + v1alphaCreateAppResponse: + type: object + properties: + app: + description: The created app. + readOnly: true + allOf: + - $ref: '#/definitions/v1alphaApp' + description: CreateAppResponse represents a response for creating a app. + v1alphaCreateConversationResponse: + type: object + properties: + conversation: + title: conversation + readOnly: true + allOf: + - $ref: '#/definitions/v1alphaConversation' + title: CreateConversationResponse returns the created conversation + v1alphaCreateMessageResponse: + type: object + properties: + message: + title: message + allOf: + - $ref: '#/definitions/v1alphaMessage' + title: CreateMessageResponse returns the created message + v1alphaDeleteAppResponse: + type: object + description: DeleteAppResponse represents a response for deleting a app. + v1alphaDeleteConversationResponse: + type: object + title: DeleteConversationResponse is empty as no content needs to be returned + v1alphaDeleteMessageResponse: + type: object + title: DeleteMessageResponse is empty as no content needs to be returned + v1alphaListAppsResponse: + type: object + properties: + apps: + type: array + items: + type: object + $ref: '#/definitions/v1alphaApp' + description: The apps container. + readOnly: true + description: GetAppsResponse represents a response for getting all apps from users. + v1alphaListConversationsResponse: + type: object + properties: + conversations: + type: array + items: + type: object + $ref: '#/definitions/v1alphaConversation' + title: conversations + readOnly: true + nextPageToken: + type: string + title: next page token + readOnly: true + totalSize: + type: integer + format: int32 + title: total size + readOnly: true + title: ListConversationsResponse returns a list of conversations + v1alphaListMessagesResponse: + type: object + properties: + messages: + type: array + items: + type: object + $ref: '#/definitions/v1alphaMessage' + title: messages + readOnly: true + nextPageToken: + type: string + title: next page token + readOnly: true + totalSize: + type: integer + format: int32 + title: total size + readOnly: true + title: ListMessagesResponse returns a list of messages + v1alphaMessage: + type: object + properties: + uid: + type: string + title: message uid + readOnly: true + appUid: + type: string + title: app uid + readOnly: true + conversationUid: + type: string + title: conversation uid + readOnly: true + content: + type: string + title: message content + role: + type: string + title: message role e.g., "user" or "assistant" + type: + title: message type + allOf: + - $ref: '#/definitions/MessageMessageType' + createTime: + type: string + format: date-time + title: creation time of the message + readOnly: true + updateTime: + type: string + format: date-time + title: update time of the message + readOnly: true + title: Message represents a single message in a conversation + required: + - content + - role + - type + v1alphaUpdateAppResponse: + type: object + properties: + app: + description: The updated app. + readOnly: true + allOf: + - $ref: '#/definitions/v1alphaApp' + description: UpdateAppResponse represents a response for updating a app. + v1alphaUpdateConversationResponse: + type: object + properties: + conversation: + title: conversation + readOnly: true + allOf: + - $ref: '#/definitions/v1alphaConversation' + title: UpdateConversationResponse returns the updated conversation + v1alphaUpdateMessageResponse: + type: object + properties: + message: + title: message + readOnly: true + allOf: + - $ref: '#/definitions/v1alphaMessage' + title: UpdateMessageResponse returns the updated message +securityDefinitions: + Bearer: + type: apiKey + description: Enter the token with the `Bearer ` prefix, e.g. `Bearer abcde12345` + name: Authorization + in: header + x-default: Bearer instill_sk_*** +security: + - Bearer: [] +externalDocs: + description: More about Instill AI + url: https://www.instill.tech/docs