ths-apimatic-sdk-sdk 1.0.0

data/lib/thought_spot_public_rest_api/controllers/ai_controller.rb

@@ -0,0 +1,550 @@
+# thought_spot_public_rest_api
+#
+# This file was automatically generated by
+# APIMATIC v3.0 ( https://www.apimatic.io ).
+
+module ThoughtSpotPublicRestApi
+  # AiController
+  class AiController < BaseController
+    # <span class="since-beta-tag">Beta</span> <span
+    # class="since-beta-tag">Version: 10.13.0.cl or later</span>
+    # #### Endpoint URL
+    # @param [CreateAgentConversationRequest] body Required parameter: TODO:
+    # type description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def create_agent_conversation(body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/api/rest/2.0/ai/agent/conversation/create',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('bearerAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(AgentConversation.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Operation failed',
+                                 ErrorResponseException)
+                    .local_error('500',
+                                 'Operation failed',
+                                 ErrorResponseException))
+        .execute
+    end
+
+    # <span class="since-beta-tag">Beta</span> <span
+    # class="since-beta-tag">Version: 10.4.0.cl or later</span>
+    # Creates a Conversation object to start an AI-driven conversation based on
+    # a specific data model.
+    # Requires at least view access to the metadata object specified in the
+    # request.
+    # #### Usage guidelines
+    # This API requires the `metadata_identifier` parameter to define the
+    # context for the conversation.
+    # You can also specify the tokens to initiate the conversation as shown in
+    # this example:
+    # `"tokens": "[tea],[sales],[type]"`
+    # If the API request is successful, ThoughtSpot returns the ID of the
+    # conversation.
+    # > ###### Note:
+    # > * This endpoint is currently in Beta. Breaking changes may be introduced
+    # before the endpoint is made Generally Available.
+    # > * This endpoint requires Spotter - please contact ThoughtSpot support to
+    # enable Spotter on your cluster.
+    # #### Endpoint URL
+    # @param [CreateConversationRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def create_conversation(body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/api/rest/2.0/ai/conversation/create',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('bearerAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(Conversation.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Operation failed',
+                                 ErrorResponseException)
+                    .local_error('500',
+                                 'Operation failed',
+                                 ErrorResponseException))
+        .execute
+    end
+
+    # <span class="since-beta-tag">Beta</span> <span
+    # class="since-beta-tag">Version: 10.15.0.cl or later</span>
+    # Provides relevant data source recommendations for a user-submitted natural
+    # language query.
+    # To use this API, the user must have at least view-level access to the
+    # underlying metadata entities referenced in the response.
+    # #### Usage guidelines
+    # The request must include a `query` string via the request body.
+    # The returned results include metadata such as:
+    # - `confidence`: a float indicating the model's confidence in the relevance
+    # of each recommendation
+    # - `details`: includes `data_source_identifier`, `data_source_name`, and
+    # `description` of each recommended data source
+    # - `reasoning`: rationale provided by the LLM to explain why each data
+    # source was recommended
+    # If the API request is successful, ThoughtSpot returns a ranked list of
+    # data sources, each annotated with relevant reasoning.
+    # > ###### Note:
+    # > * This endpoint is currently in Beta. Breaking changes may be introduced
+    # before it is made Generally Available.
+    # > * This endpoint requires Spotter — please contact ThoughtSpot Support to
+    # enable Spotter on your cluster.
+    # #### Endpoint URL
+    # @param [GetDataSourceSuggestionsRequest] body Required parameter: TODO:
+    # type description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def get_data_source_suggestions(body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/api/rest/2.0/ai/data-source-suggestions',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('bearerAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(EurekaDataSourceSuggestionResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Operation failed',
+                                 ErrorResponseException)
+                    .local_error('500',
+                                 'Operation failed',
+                                 ErrorResponseException))
+        .execute
+    end
+
+    # <span class="since-beta-tag">Beta</span> <span
+    # class="since-beta-tag">Version: 10.15.0.cl or later</span>
+    # This API allows users to retrieve existing natural language (NL)
+    # instructions for a specific data-model. These instructions guide the AI
+    # system in understanding data context and generating more accurate
+    # responses when processing natural language queries.
+    # #### Usage guidelines
+    # To retrieve NL instructions for a data-model, the request must include:
+    # - `data_source_identifier`: The unique ID of the data-model to retrieve NL
+    # instructions
+    # The API returns a response object with:
+    # - `nl_instructions_info`: An array of instruction objects, each
+    # containing:
+    #   - `instructions`: Array of text instructions for natural language
+    # processing
+    #   - `scope`: The scope of the instruction (`GLOBAL`). It can be extended
+    # to data-model-user scope in future.
+    # #### Instructions Scope
+    # - **GLOBAL**: Instructions that apply globally across the system on the
+    # given data-model (currently only global instructions are supported)
+    # > ###### Note:
+    # > * To use this API, the user needs atleast view access on the data-model
+    # and they must use corresponding org related bearerToken where the
+    # data-model exists.
+    # > * This endpoint is currently in Beta. Breaking changes may be introduced
+    # before the endpoint is made Generally Available.
+    # > * Available from version 10.15.0.cl and later.
+    # > * This endpoint requires Spotter — please contact ThoughtSpot Support to
+    # enable Spotter on your cluster.
+    # > * Use this API to view currently configured instructions before
+    # modifying them with `setNLInstructions`.
+    # #### Endpoint URL
+    # @param [GetNlInstructionsRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def get_nl_instructions(body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/api/rest/2.0/ai/instructions/get',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('bearerAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(EurekaGetNlInstructionsResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Operation failed',
+                                 ErrorResponseException)
+                    .local_error('500',
+                                 'Operation failed',
+                                 ErrorResponseException))
+        .execute
+    end
+
+    # <span class="since-beta-tag">Beta</span> <span
+    # class="since-beta-tag">Version: 10.13.0.cl or later</span>
+    # Breaks down a user-submitted query into a series of analytical
+    # sub-questions using relevant contextual metadata.
+    # To use this API, the user must have at least view-level access to the
+    # referenced metadata objects.
+    # #### Usage guidelines
+    # To accurately generate relevant questions, the request must include at
+    # least one of the following metadata identifiers within `metadata_context`
+    # : `conversation_identifier`, `answer_identifiers`,
+    # `liveboard_identifiers`, or `data_source_identifiers`.
+    # You can further enhance the quality and precision of breakdown by
+    # providing additional `ai_context` such as:
+    # - `content`: User provided content like text data, csv data as a string
+    # message to provide context & potentially improve the quality of the
+    # response.
+    # - `instructions`: User specific text instructions sent to AI system for
+    # processing the query.
+    # Additional optional parameters include:
+    # - `limit_relevant_questions`: Controls the maximum number of relevant
+    # questions returned. Defaults to 5 if not specified.
+    # - `bypass_cache`: If set to true, forces fresh computation instead of
+    # returning cached results.
+    # If the API request is successful, ThoughtSpot returns a list of relevant
+    # analytical queries, each aligned with the user's original question. Each
+    # returned question includes the query string, along with the identifier and
+    # name of the corresponding data source.
+    # > ###### Note:
+    # > * This endpoint is currently in Beta. Breaking changes may be introduced
+    # before the endpoint is made Generally Available.
+    # > * This endpoint requires Spotter - please contact ThoughtSpot support to
+    # enable Spotter on your cluster.
+    # #### Endpoint URL
+    # @param [GetRelevantQuestionsRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def get_relevant_questions(body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/api/rest/2.0/ai/relevant-questions/',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('bearerAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(EurekaGetRelevantQuestionsResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Operation failed',
+                                 ErrorResponseException)
+                    .local_error('500',
+                                 'Operation failed',
+                                 ErrorResponseException))
+        .execute
+    end
+
+    # <span class="since-beta-tag">Beta</span> <span
+    # class="since-beta-tag">Version: 10.7.0.cl or later</span>
+    # #### Endpoint URL
+    # @param [QueryGetDecomposedQueryRequest] body Required parameter: TODO:
+    # type description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def query_get_decomposed_query(body)
+      warn 'Endpoint query_get_decomposed_query in AiController is deprecated'
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/api/rest/2.0/ai/analytical-questions',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('bearerAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(EurekaDecomposeQueryResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Operation failed',
+                                 ErrorResponseException)
+                    .local_error('500',
+                                 'Operation failed',
+                                 ErrorResponseException))
+        .execute
+    end
+
+    # <span class="since-beta-tag">Beta</span> <span
+    # class="since-beta-tag">Version: 10.15.0.cl or later</span>
+    # This API allows users to initiate or continue an agent (Spotter)
+    # conversation by submitting one or more natural language messages.
+    # To use this API, the user must have access to the relevant conversational
+    # session (via conversation_identifier) and submit at least one message.
+    # #### Usage guidelines
+    # To initiate or continue a conversation, the request must include:
+    # - `conversation_identifier`: a unique session ID for continuity and
+    # message tracking
+    # - `messages`: an array of one or more text messages, each with a value and
+    # type
+    # The API returns a array of object with a type, message, and metadata.
+    # - `type`: Type of the message — text, answer, or error.
+    # - `message`: Main content of the response.
+    # - `metadata`: Additional info depending on the message type.
+    # > ###### Note:
+    # > * This endpoint is currently in Beta. Breaking changes may be introduced
+    # before the endpoint is made Generally Available.
+    # > * This endpoint requires Spotter - please contact ThoughtSpot support to
+    # enable Spotter on your cluster.
+    # #### Endpoint URL
+    # @param [String] conversation_identifier Required parameter: Unique
+    # identifier for the conversation (used to track context)
+    # @param [SendAgentMessageRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def send_agent_message(conversation_identifier,
+                           body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/api/rest/2.0/ai/agent/{conversation_identifier}/converse',
+                                     Server::DEFAULT)
+                   .template_param(new_parameter(conversation_identifier, key: 'conversation_identifier')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('bearerAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:json_deserialize))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Operation failed',
+                                 ErrorResponseException)
+                    .local_error('500',
+                                 'Operation failed',
+                                 ErrorResponseException))
+        .execute
+    end
+
+    # <span class="since-beta-tag">Beta</span> <span
+    # class="since-beta-tag">Version: 10.13.0.cl or later</span>
+    # This API allows users to initiate or continue an agent (Spotter)
+    # conversation by submitting one or more natural language messages.
+    # To use this API, the user must have access to the relevant conversational
+    # session (via conversation_identifier) and submit at least one message.
+    # #### Usage guidelines
+    # To initiate or continue a conversation, the request must include:
+    # - `conversation_identifier`: a unique session ID for continuity and
+    # message tracking
+    # - `messages`: an array of one or more text messages, each with a value and
+    # type
+    # Additionally, user can specify what tool can be included
+    # `conversation_settings` parameter, which supports:
+    # - `enable_contextual_change_analysis` (default: false)
+    # - `enable_natural_language_answer_generation` (default: true)
+    # - `enable_reasoning` (default: false)
+    # If the request is valid, the API returns a stream of messages in real
+    # time, including:
+    # - `ack`: confirms receipt of the request
+    # - `text / text-chunk`: content chunks, optionally formatted (e.g.,
+    # markdown)
+    # - `answer`: the final structured response with metadata and analytics
+    # - `error`: if a failure occurs
+    # - `notification`: notification messages for operation being performed
+    # > ###### Note:
+    # > * This endpoint is currently in Beta. Breaking changes may be introduced
+    # before the endpoint is made Generally Available.
+    # > * This endpoint requires Spotter - please contact ThoughtSpot support to
+    # enable Spotter on your cluster.
+    # > * The streaming protocol uses Server-Sent Events (SSE)
+    # #### Endpoint URL
+    # @param [SendAgentMessageStreamingRequest] body Required parameter: TODO:
+    # type description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def send_agent_message_streaming(body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/api/rest/2.0/ai/agent/converse/sse',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('bearerAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(SendAgentMessageResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Operation failed',
+                                 ErrorResponseException)
+                    .local_error('500',
+                                 'Operation failed',
+                                 ErrorResponseException))
+        .execute
+    end
+
+    # <span class="since-beta-tag">Beta</span> <span
+    # class="since-beta-tag">Version: 10.4.0.cl or later</span>
+    # Allows sending a follow-up message to an ongoing conversation within the
+    # context of the metadata model.
+    # Requires at least view access to the metadata object specified in the
+    # request.
+    # #### Usage guidelines
+    # The API requires you to specify the `conversation_identifier` in the
+    # request path, and a `metadata_identifier` and `message` string in the
+    # request body.
+    # If the API request is successful, ThoughtSpot returns the session ID,
+    # tokens used in the conversation, and visualization type.
+    # > ###### Note:
+    # > * This endpoint is currently in Beta. Breaking changes may be introduced
+    # before the endpoint is made Generally Available.
+    # > * This endpoint requires Spotter - please contact ThoughtSpot support to
+    # enable Spotter on your cluster.
+    # #### Endpoint URL
+    # @param [String] conversation_identifier Required parameter: Unique
+    # identifier of the conversation.
+    # @param [SendMessageRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def send_message(conversation_identifier,
+                     body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/api/rest/2.0/ai/conversation/{conversation_identifier}/converse',
+                                     Server::DEFAULT)
+                   .template_param(new_parameter(conversation_identifier, key: 'conversation_identifier')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('bearerAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(ResponseMessage.method(:from_hash))
+                    .is_api_response(true)
+                    .is_response_array(true)
+                    .local_error('400',
+                                 'Operation failed',
+                                 ErrorResponseException)
+                    .local_error('500',
+                                 'Operation failed',
+                                 ErrorResponseException))
+        .execute
+    end
+
+    # <span class="since-beta-tag">Beta</span> <span
+    # class="since-beta-tag">Version: 10.15.0.cl or later</span>
+    # This API allows users to set natural language (NL) instructions for a
+    # specific data-model to improve AI-generated answers and query processing.
+    # These instructions help guide the AI system to better understand the data
+    # context and provide more accurate responses.
+    # #### Usage guidelines
+    # To set NL instructions for a data-model, the request must include:
+    # - `data_source_identifier`: The unique ID of the data-model for which to
+    # set NL instructions
+    # - `nl_instructions_info`: An array of instruction objects, each
+    # containing:
+    #   - `instructions`: Array of text instructions for the LLM
+    #   - `scope`: The scope of the instruction (`GLOBAL`). Currently only
+    # `GLOBAL` is supported. It can be extended to data-model-user scope in
+    # future.
+    # The API returns a response object with:
+    # - `success`: Boolean indicating whether the operation was successful
+    # #### Instructions Scope
+    # - **GLOBAL**: Instructions that apply globally for that data-model across
+    # the system
+    # > ###### Note:
+    # > * To use this API, the user needs either edit access or
+    # SPOTTER_COACHING_PRIVILEGE on the data-model and they must use
+    # corresponding org related bearerToken where the data-model exists.
+    # > * This endpoint is currently in Beta. Breaking changes may be introduced
+    # before the endpoint is made Generally Available.
+    # > * Available from version 10.15.0.cl and later.
+    # > * This endpoint requires Spotter — please contact ThoughtSpot Support to
+    # enable Spotter on your cluster.
+    # > * Instructions help improve the accuracy and relevance of AI-generated
+    # responses for the specified data-model.
+    # #### Endpoint URL
+    # @param [SetNlInstructionsRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def set_nl_instructions(body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/api/rest/2.0/ai/instructions/set',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('bearerAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(EurekaSetNlInstructionsResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Operation failed',
+                                 ErrorResponseException)
+                    .local_error('500',
+                                 'Operation failed',
+                                 ErrorResponseException))
+        .execute
+    end
+
+    # <span class="since-beta-tag">Beta</span> <span
+    # class="since-beta-tag">Version: 10.4.0.cl or later</span>
+    # Processes a natural language query and returns an AI-generated response
+    # based on a specified data model.
+    # Requires at least view access to the metadata object specified in the
+    # request.
+    # > ###### Note:
+    # > * This endpoint is currently in Beta. Breaking changes may be introduced
+    # before the endpoint is made Generally Available.
+    # > * This endpoint requires Spotter - please contact ThoughtSpot support to
+    # enable Spotter on your cluster.
+    # #### Endpoint URL
+    # @param [SingleAnswerRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def single_answer(body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/api/rest/2.0/ai/answer/create',
+                                     Server::DEFAULT)
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('bearerAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(ResponseMessage.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 'Operation failed',
+                                 ErrorResponseException)
+                    .local_error('500',
+                                 'Operation failed',
+                                 ErrorResponseException))
+        .execute
+    end
+  end
+end