@dynatrace-sdk/client-davis-copilot

Overview

This API allows you to interact with Davis CoPilot Generative AI. The API is in preview and is subject to the Dynatrace preview conditions.

Refer to the feature documentation to get familiar with the key concepts.

Installation

npm install @dynatrace-sdk/client-davis-copilot

Getting help

• Visit SDK for Typescript guide in the Dynatrace Developer
• Ask a question in the Dynatrace Community

License

This SDK is distributed under the Apache License, Version 2.0, see LICENSE for more information.

API reference

Full API reference for the latest version of the SDK is also available at the Dynatrace Developer.

publicClient

import { publicClient } from '@dynatrace-sdk/client-davis-copilot';

documentSearch

Search for relevant documents.

Required scope: davis-copilot:document-search:execute

Allows to query documents (Dashboards, Notebooks, ...) relevant for your input. The payload is a JSON dictionary provided from the response. Please review the examples for the correct payload formatting.

Parameters:

• texts: List of search strings.
• collections: List of document collections to search in.
• exclude (Optional): List of document ids to exclude from the search.

Please note, this endpoint is in preview and is subject to the Dynatrace preview conditions, as linked in the overview.

Parameters

| Name | Type | | --- | --- | |config.body*required|DocumentSearchRequest|

Returns

| Return type | Status code | Description | |---|---|---| |DocumentSearchResponse|200|List of documents with their relevance scores|

Throws

| Error Type | Error Message | |---|---| |ClientErrorResponseError|| |InternalErrorResponseError||

import { publicClient } from "@dynatrace-sdk/client-davis-copilot";

const data = await publicClient.documentSearch({
  body: {
    texts: ["search-string 1,search-string 2,DQL1,DQL2"],
    collections: [
      "documentCollection 1,documentCollection 2,documentCollection 3",
    ],
  },
});

dql2nl

Explain a DQL (Dynatrace Query Language) query in natural language.

Required scope: davis-copilot:dql2nl:execute

Get an explanation for DQL queries. Note that only valid queries are handled. The payload is a JSON dictionary with the following key. Please review the examples for the correct payload formatting.

Parameters:

• dql: Dql query to explain.

Please note, this endpoint is in preview and is subject to the Dynatrace preview conditions, as linked in the overview.

Parameters

| Name | Type | | --- | --- | |config.body*required|Dql2NlRequest|

Returns

| Return type | Status code | Description | |---|---|---| |Dql2NlResponse|200|Answer from Dql2Nl skill|

Throws

| Error Type | Error Message | |---|---| |ClientErrorResponseError|| |InternalErrorResponseError||

import { publicClient } from "@dynatrace-sdk/client-davis-copilot";

const data = await publicClient.dql2nl({
  body: {
    dql: 'fetch logs, from:now()-1h, samplingRatio:100| fields timestamp, severity, logfile, message, container| limit 10| filterOut severity == "NONE" or severity == "INFO"| sort timestamp desc',
  },
});

dql2nlFeedback

Provide feedback for a DQL (Dynatrace Query Language) explanation.

Required scope: davis-copilot:dql2nl:execute

Allows to provide feedback to a dql2nl response. The payload is a JSON dictionary combining feedback and information from the dql2nl response. Please review the examples for the correct payload formatting.

Parameters:

• messageToken: Message token as provided by dql2nl:explain.
• origin: Application name of the caller.
• feedback: Feedback dictionary.
  • type: Type of the feedback: "positive" or "negative".
  • text: Natural language feedback text.
  • category (Optional): One out of "misunderstood", "incorrect", "incomplete", "error", "other".
  • improvement (Optional):
    • text: Suggestion to improve the answer
    • confirmation: true to verify that the improvement suggestion is valid, false otherwise
• userQuery (Optional): Message prompt as sent to the dql2nl:explain endpoint.
• *queryExplanation (Optional): Response as received from the dql2nl:explain endpoint.

Please note, this endpoint is in preview and is subject to the Dynatrace preview conditions, as linked in the overview.

Parameters

| Name | Type | | --- | --- | |config.body*required|Dql2NlFeedbackRequest|

Returns

| Return type | Status code | Description | |---|---|---| |void|202|Feedback successfully submitted|

Throws

| Error Type | Error Message | |---|---| |ClientErrorResponseError|| |InternalErrorResponseError||

import { publicClient } from "@dynatrace-sdk/client-davis-copilot";

const data = await publicClient.dql2nlFeedback({
  body: {
    messageToken: "...",
    origin: "Notebooks DQL to NL feedback",
    feedback: {
      type: "positive",
      improvement: {
        text: "The DQL statement should have shown me metadata for the logs source.",
        confirmation: false,
      },
    },
    userQuery: "describe logs",
  },
});

listAvailableSkills

List all available skills.

Returns a list of available skills. The availability depends whether Davis-CoPilot has been enabled for your tenant and if the used token has the required scopes.

Please note, this endpoint is in preview and is subject to the Dynatrace preview conditions, as linked in the overview.

Returns

| Return type | Status code | Description | |---|---|---| |AvailableSkillsResponse|200|All skills available to the user.|

Throws

| Error Type | Error Message | |---|---| |ClientErrorResponseError|Client Error.| |InternalErrorResponseError|Internal server Error.|

import { publicClient } from "@dynatrace-sdk/client-davis-copilot";

const data = await publicClient.listAvailableSkills();

nl2dql

Generate a DQL (Dynatrace Query Language) query from natural language.

Required scope: davis-copilot:nl2dql:execute

Create a DQL query from natural language input. The payload is a JSON dictionary with the following keys. Please review the examples for the correct payload formatting.

Parameters:

• text: Natural language input to create a DQL query.

Please note, this endpoint is in preview and is subject to the Dynatrace preview conditions, as linked in the overview.

Parameters

| Name | Type | | --- | --- | |config.body*required|Nl2DqlRequest|

Returns

| Return type | Status code | Description | |---|---|---| |Nl2DqlResponse|200|Answer from Nl2Dql skill|

Throws

| Error Type | Error Message | |---|---| |ClientErrorResponseError|| |InternalErrorResponseError||

import { publicClient } from "@dynatrace-sdk/client-davis-copilot";

const data = await publicClient.nl2dql({
  body: {
    text: "Generate a query which shows the latest 10 log lines",
  },
});

nl2dqlFeedback

Provide feedback on DQL (Dynatrace Query Language) result created from natural language.

Required scope: davis-copilot:nl2dql:execute

Allows to provide feedback to a nl2dql response. The payload is a JSON dictionary combining feedback and information from the nl2dql response. Please review the examples for the correct payload formatting.

Parameters:

• messageToken: Message token as provided by nl2dql:explain.
• origin: Application name of the caller.
• feedback: Feedback dictionary.
  • type: Type of the feedback: "positive" or "negative".
  • text: Natural language feedback text.
  • category (Optional): One out of "misunderstood", "incorrect", "incomplete", "error", "other".
  • improvement (Optional):
    • text: Suggestion to improve the answer
    • confirmation: true to verify that the improvement suggestion is valid, false otherwise
• userQuery (Optional): Message prompt as sent to the nl2dql:generate endpoint.
• *generatedDql (Optional): Response as received from the nl2dql:generate endpoint.

Please note, this endpoint is in preview and is subject to the Dynatrace preview conditions, as linked in the overview.

Parameters

| Name | Type | | --- | --- | |config.body*required|Nl2DqlFeedbackRequest|

Returns

| Return type | Status code | Description | |---|---|---| |void|202|Feedback successfully submitted|

Throws

| Error Type | Error Message | |---|---| |ClientErrorResponseError|| |InternalErrorResponseError||

import { publicClient } from "@dynatrace-sdk/client-davis-copilot";

const data = await publicClient.nl2dqlFeedback({
  body: {
    messageToken: "...",
    origin: "Notebooks DQL to NL feedback",
    feedback: {
      type: "positive",
      improvement: {
        text: "The DQL statement should have shown me metadata for the logs source.",
        confirmation: false,
      },
    },
    userQuery: "Show me the latest 100 logs.",
  },
});

recommenderConversation

Retrieve a message from a recommender conversation.

Required scope: davis-copilot:conversations:execute

Allows clients to send messages to the Davis CoPilot recommender and receive responses. The endpoint can handle both, streaming and non-streaming requests.

Streaming/Non-Streaming mode

The mode is is configured via the HTTP Header Accept:

• Non-Streaming Accept: application/json
• Streaming: Accept: application/x-ndjson

Payload Options

The payload is a JSON dictionary with the following top level keys. Please review the examples for the correct payload formatting.

Parameters:

• text: Message to the AI service. The response is a reply to this input.
• state (Optional): Information containing a conversation between user and ai to be continued. If not supplied, a new conversation is started. A state object is obtained from the response of a previous call to the conversations:message endpoint. So the client is responsible for storing and providing the state.
• context (Optional): Additional information to provide context to the requests.
  • document-retrieval (Optional): "dynatrace" for using the Dynatrace documentation as context (default), "disabled" for using no document-based context. In the background document-retrieval uses the input text to perform a semantic search to find relevant to augment the context of the conversation.
  • supplementary (Optional): Custom context to be provided for the request. Note that unlike to the text, the supplementary is not anonymized.
  • instruction (Optional): Additional instructions regarding formatting and output structure (e.g. "- Answer in bullet points", "Output the answer as JSON")

Please note, this endpoint is in preview and is subject to the Dynatrace preview conditions, as linked in the overview.

Parameters

| Name | Type | | --- | --- | |config.body*required|ConversationRequest|

Returns

| Return type | Status code | Description | |---|---|---| |ErrorEvent|200|Answer from recommender skill.

The response is a streaming response consisting of the following possible tokens: Start, Progress, Tokens, Notification, Content, End, Error. Please select the individual types to view the specific response format. A usual token stream follows the sequence: Start, Progress, Tokens, ... End. |

Throws

| Error Type | Error Message | |---|---| |ClientErrorResponseError|| |InternalErrorResponseError|Service unavailable|

import { publicClient } from "@dynatrace-sdk/client-davis-copilot";

const data = await publicClient.recommenderConversation({
  acceptType: "application/json",
  body: { text: "How can I instrument my java service?" },
});

recommenderFeedback

Provide feedback for a recommender conversation.

Required scope: davis-copilot:conversations:execute

Allows to provide feedback to a conversational recommender response. The payload is a JSON dictionary combining feedback and information from the conversational recommender response. Please review the examples for the correct payload formatting.

Parameters:

• messageToken: Message token as provided by conversation:message.
• origin: Application name of the caller.
• feedback: Feedback dictionary.
  • type: Type of the feedback: "positive" or "negative".
  • text: Natural language feedback text.
• userPrompt (Optional): Message prompt as sent to the conversation:message endpoint.
• copilotResponse (Optional): Response as received from the conversation:message endpoint.
• sources (Optional): List of sources as received from the conversation:message endpoint.

Please note, this endpoint is in preview and is subject to the Dynatrace preview conditions, as linked in the overview.

Parameters

| Name | Type | | --- | --- | |config.body*required|ConversationFeedbackRequest|

Returns

| Return type | Status code | Description | |---|---|---| |void|202|Feedback successfully submitted|

Throws

| Error Type | Error Message | |---|---| |ClientErrorResponseError|| |InternalErrorResponseError||

import { publicClient } from "@dynatrace-sdk/client-davis-copilot";

const data = await publicClient.recommenderFeedback({
  body: {
    messageToken: "...",
    origin: "...",
    feedback: {
      type: "positive",
      improvement: {
        text: "The DQL statement should have shown me metadata for the logs source.",
        confirmation: false,
      },
    },
  },
});

Types

AvailableSkillsResponse

| Name | Type | | --- | --- | |skills|Array<"conversation" | "nl2dql" | "dql2nl" | "documentSearch">|

ClientErrorResponse

| Name | Type | | --- | --- | |error*required|ClientErrorResponseObject|

ClientErrorResponseObject

| Name | Type | | --- | --- | |code*required|number| |message*required|string|

ContentEvent

| Name | Type | | --- | --- | |data|object| |event|"start" | "progress" | "notification" | "tokens" | "content" | "end" | "error"|

ConversationContext

| Name | Type | | --- | --- | |type*required|"supplementary" | "document-retrieval" | "instruction"| |value*required|string|

ConversationFeedback

| Name | Type | Description | | --- | --- | --- | |category|string|Must be one of [ "misunderstood", "incorrect", "incomplete", "error", "other" ] | |improvement|ConversationImprovedSummary| | |text|string| | |type*required|"positive" | "negative"| |

ConversationFeedbackRequest

| Name | Type | | --- | --- | |copilotResponse|string| |feedback*required|ConversationFeedback| |messageToken*required|string| |origin*required|string| |sources|Array<string>| |userPrompt|string|

ConversationImprovedSummary

| Name | Type | | --- | --- | |confirmation*required|boolean| |text*required|string|

ConversationRequest

| Name | Type | Description | | --- | --- | --- | |annotations|ConversationRequestAnnotations|Specify the annotation information which will be used to add extra context to the request, e.g. Origin app. Annotation key and value are restricted to be at most 128 characters and at most 10 annotations are accepted. This information is not masked. | |context|Array<ConversationContext>|Specify the information sources which will be used to process the request. Empty or null will default to the standard Davis CoPilot documentation search. | |state|State| | |text*required|string| |

ConversationRequestAnnotations

Specify the annotation information which will be used to add extra context to the request, e.g. Origin app. Annotation key and value are restricted to be at most 128 characters and at most 10 annotations are accepted. This information is not masked.

type: Record<string, AnnotationItem | undefined>

ConversationResponse

| Name | Type | | --- | --- | |messageToken*required|string| |metadata*required|MetadataWithSource| |state*required|State| |status*required|"SUCCESSFUL" | "SUCCESSFUL_WITH_WARNINGS" | "FAILED"| |text*required|string|

DocumentMetadata

| Name | Type | Description | | --- | --- | --- | |description|string|Users description of the document | |externalId|string| | |id|string| | |name|string| | |type|string|Type of document (notebook or dashboard) | |version|string|Starting at 1, every modification of the document to either metadata or content increases the version number |

DocumentSearchRequest

| Name | Type | Description | | --- | --- | --- | |collections*required|Array<string>|The name of the document collections corresponding to the names in the vectorstore. | |exclude|null | Array<string>|Must be a uuid hash matching a document (for now, no patterns/wildcards) | |texts*required|Array<string>| |

DocumentSearchResponse

| Name | Type | Description | | --- | --- | --- | |messageToken*required|string|Must be a random uuid hash to identify the response | |results*required|Array<ScoredDocument>| | |status*required|"SUCCESSFUL" | "SUCCESSFUL_WITH_WARNINGS" | "FAILED"| |

Dql2NlFeedback

| Name | Type | Description | | --- | --- | --- | |category|string|Must be one of [ "misunderstood", "incorrect", "incomplete", "error", "other" ] | |improvement|Dql2NlImprovedSummary| | |text|string| | |type*required|"positive" | "negative"| |

Dql2NlFeedbackRequest

| Name | Type | | --- | --- | |feedback*required|Dql2NlFeedback| |messageToken*required|string| |origin*required|string| |queryExplanation|string| |userQuery*required|string|

Dql2NlImprovedSummary

| Name | Type | | --- | --- | |confirmation*required|boolean| |text*required|string|

Dql2NlRequest

| Name | Type | | --- | --- | |dql*required|string|

Dql2NlResponse

| Name | Type | | --- | --- | |explanation*required|string| |messageToken*required|string| |metadata|Metadata| |status*required|"SUCCESSFUL" | "SUCCESSFUL_WITH_WARNINGS" | "FAILED"| |summary*required|string|

EndEvent

The EndEvent is sent by the server to indicate the end of the conversation. It is comparable to the non-streaming response, containing the full answer comprised of all tokens, the sources of the answer, and the state of the conversation that can be used for continuation.

| Name | Type | | --- | --- | |data|EndEventData| |event|"start" | "progress" | "notification" | "tokens" | "content" | "end" | "error"|

EndEventData

| Name | Type | | --- | --- | |answer|string| |sources|Array<SourceDocument>| |state|State|

ErrorEvent

The ErrorEvent is sent by the server to indicate an error and that the conversation cannot be continued. This means the stream is closed and the client should not expect any further events. It contains the code of the error representing the equivalent HTTP code and human readable message.

| Name | Type | | --- | --- | |data|ErrorMessage| |event|"start" | "progress" | "notification" | "tokens" | "content" | "end" | "error"|

ErrorMessage

| Name | Type | | --- | --- | |code*required|number| |message*required|string|

InternalErrorResponse

| Name | Type | | --- | --- | |error*required|InternalErrorResponseObject|

InternalErrorResponseObject

| Name | Type | | --- | --- | |code*required|number| |message*required|string|

Metadata

| Name | Type | | --- | --- | |notifications|Array<Notification>|

MetadataWithSource

| Name | Type | | --- | --- | |notifications|Array<Notification>| |sources|Array<SourceDocument>|

Nl2DqlFeedback

| Name | Type | Description | | --- | --- | --- | |category|string|Must be one of [ "misunderstood", "incorrect", "incomplete", "error", "other" ] | |improvement|Nl2DqlImprovedSummary| | |text|string| | |type*required|"positive" | "negative"| |

Nl2DqlFeedbackRequest

| Name | Type | | --- | --- | |feedback*required|Nl2DqlFeedback| |generatedDql|string| |messageToken*required|string| |origin*required|string| |userQuery*required|string|

Nl2DqlImprovedSummary

| Name | Type | | --- | --- | |confirmation*required|boolean| |text*required|string|

Nl2DqlRequest

| Name | Type | | --- | --- | |text*required|string|

Nl2DqlResponse

| Name | Type | | --- | --- | |dql*required|string| |messageToken*required|string| |metadata|Metadata| |status*required|"SUCCESSFUL" | "SUCCESSFUL_WITH_WARNINGS" | "FAILED"|

Notification

| Name | Type | | --- | --- | |message|string| |notificationType|string| |severity|string|

NotificationEvent

The NotificationEvent is sent by the server in case something do not fully go as planned. It contains the severity of the notification (e.g. Warning), the type of issue, and a message.

| Name | Type | | --- | --- | |data|Notification| |event|"start" | "progress" | "notification" | "tokens" | "content" | "end" | "error"|

ProgressEvent

The ProgressEvent is sent by the server to the client to indicate progress. It contains at the type of progress and a message to be displayed to the user.

| Name | Type | | --- | --- | |data|ProgressEventData| |event|"start" | "progress" | "notification" | "tokens" | "content" | "end" | "error"|

ProgressEventData

| Name | Type | | --- | --- | |message|string| |type|string|

ScoredDocument

| Name | Type | | --- | --- | |documentId*required|string| |documentMetadata*required|DocumentMetadata| |relevanceScore*required|number|

SourceDocument

| Name | Type | | --- | --- | |title|string| |type|string| |url|string|

StartEvent

The StartEvent is the first event sent by the server to the client. It contains a messageToken that is used to identify the conversation.

| Name | Type | | --- | --- | |data|StartEventData| |event|"start" | "progress" | "notification" | "tokens" | "content" | "end" | "error"|

StartEventData

| Name | Type | | --- | --- | |messageToken|string|

State

| Name | Type | | --- | --- | |conversationId|string| |history|Array<object>| |skillName|string| |version|string|

TokensEvent

The TokensEvent contains the tokens streamed from the server to the client during the conversation. It may contain multiple tokens.

| Name | Type | | --- | --- | |data|TokensEventData| |event|"start" | "progress" | "notification" | "tokens" | "content" | "end" | "error"|

TokensEventData

| Name | Type | | --- | --- | |tokens|Array<string>|

Enums

ConversationContextType

Enum keys

DocumentRetrieval | Instruction | Supplementary

ConversationFeedbackType

Enum keys

Negative | Positive

Dql2NlFeedbackType

Enum keys

Negative | Positive

EventType

Enum keys

Content | End | Error | Notification | Progress | Start | Tokens

Nl2DqlFeedbackType

Enum keys

Negative | Positive

SkillType

Enum keys

Conversation | DocumentSearch | Dql2nl | Nl2dql

Status

Enum keys

Failed | Successful | SuccessfulWithWarnings