Skip to content

Commit b9fc96c

Browse files
glecarosMaryGaoweidongxu-microsoft
authored
Adding definitions for the Chat API (#26038)
* Adding definitions for the Chat API * renamed dir * adding placeholder docs to make generators happy * python options * ts config * Adding auth. Marking props as optional. * more fixes * adding client.tsp * more optional stuff. * templated interface * adding route * updated generic argument type * warnings * rollback package.json * adding examples + tspconfig update * prettier * updating based on spec * Updated namespace. * rename * Updating documentation for models and operations. Removing references out-of-scope features. * typo * Adding autorest generation. * fixes * more openapi fixes * feedback * updating example * updating docs * updating js package name * using RpcOperation * rollback to using Foundations.Operation * updating example * updated template parameter names. * regenerated openapi * removing usage of azure-core + removing api-version param. * adding oauth * feedback * Update specification/machinelearning/Azure.AI.ChatProtocol/tspconfig.yaml * Update specification/machinelearning/Azure.AI.ChatProtocol/tspconfig.yaml * java config * Updating route. Wire to use camelCase. * missing field * path * path * Revert "path" This reverts commit f663ecc. * adding back route param * Adding message kind definition * renaming model * removing template parameters to work around emitter issue. * updating sample * updates * discriminator for streaming deltas. * update samples * typo * forcing ChatRole to be public. --------- Co-authored-by: Mary Gao <[email protected]> Co-authored-by: Weidong Xu <[email protected]>
1 parent 2d044b8 commit b9fc96c

File tree

13 files changed

+940
-0
lines changed

13 files changed

+940
-0
lines changed

‎specification/machinelearning/Azure.AI.ChatProtocol/client.tsp‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
import "@azure-tools/typespec-client-generator-core";
2+
3+
import "./main.tsp";
4+
5+
using Azure.ClientGenerator.Core;
6+
7+
@@access(Azure.AI.ChatProtocol.Chat.createStreaming, Access.internal, "csharp");
8+
@@access(Azure.AI.ChatProtocol.ChatRole, Access.public, "csharp");

‎specification/machinelearning/Azure.AI.ChatProtocol/examples/2023-10-01-preview/create.json‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
{
2+
"operationId": "Chat_Create",
3+
"title": "Creates a chat completion for the provided prompt using streaming.",
4+
"parameters": {
5+
"endpoint": "{endpoint}",
6+
"operationRoute": "chat",
7+
"body": {
8+
"messages": [
9+
{
10+
"kind": "text",
11+
"content": "Tell me a joke",
12+
"role": "user"
13+
}
14+
],
15+
"stream": false
16+
}
17+
},
18+
"responses": {
19+
"200": {
20+
"body": {
21+
"choices": [
22+
{
23+
"index": 0,
24+
"message": {
25+
"kind": "text",
26+
"content": "Why did the tomato turn red?\nBecause it saw the salad dressing!",
27+
"role": "assistant",
28+
"sessionState": {
29+
"active_skill": "QnA"
30+
}
31+
},
32+
"context": {
33+
"function_call": "none"
34+
},
35+
"sessionState": {
36+
"session_cookie": "d2d1b2c3-4a5b-6c7d-8e9f-0a1b2c3d4e5f"
37+
},
38+
"finishReason": "stop"
39+
}
40+
]
41+
}
42+
}
43+
}
44+
}

‎specification/machinelearning/Azure.AI.ChatProtocol/examples/2023-10-01-preview/create_streaming.json‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
{
2+
"operationId": "Chat_CreateStreaming",
3+
"title": "Creates a chat completion for the provided prompt using streaming.",
4+
"parameters": {
5+
"endpoint": "{endpoint}",
6+
"operationRoute": "chat",
7+
"body": {
8+
"messages": [
9+
{
10+
"kind": "text",
11+
"content": "Tell me a joke",
12+
"role": "user"
13+
}
14+
],
15+
"stream": true
16+
}
17+
},
18+
"responses": {
19+
"200": {
20+
"body": {
21+
"choices": [
22+
{
23+
"index": 0,
24+
"delta": {
25+
"kind": "text",
26+
"content": "Why did the tomato turn red?\nBecause it saw the salad dressing!",
27+
"role": "assistant",
28+
"sessionState": {
29+
"active_skill": "QnA"
30+
}
31+
},
32+
"context": {
33+
"function_call": "none"
34+
},
35+
"sessionState": {
36+
"session_cookie": "d2d1b2c3-4a5b-6c7d-8e9f-0a1b2c3d4e5f"
37+
},
38+
"finishReason": "stop"
39+
}
40+
]
41+
}
42+
}
43+
}
44+
}

‎specification/machinelearning/Azure.AI.ChatProtocol/main.tsp‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
import "@typespec/rest";
2+
import "@typespec/http";
3+
import "@typespec/versioning";
4+
5+
import "./operations.tsp";
6+
7+
using TypeSpec.Http;
8+
using TypeSpec.Versioning;
9+
10+
#suppress "@azure-tools/typespec-azure-core/casing-style" "Using the AI acronym similar to what was done for OpenAI"
11+
@doc("Azure APIs for the Azure Chat protocol.")
12+
@service({
13+
title: "Azure ML Chat",
14+
})
15+
@useAuth(
16+
ApiKeyAuth<ApiKeyLocation.header, "api-key"> | OAuth2Auth<[
17+
{
18+
type: OAuth2FlowType.implicit,
19+
authorizationUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
20+
scopes: [],
21+
}
22+
]>
23+
)
24+
@server(
25+
"{endpoint}",
26+
"Azure Chat Protocol APIs",
27+
{
28+
endpoint: string,
29+
}
30+
)
31+
@versioned(APIVersion)
32+
namespace Azure.AI.ChatProtocol;
33+
34+
#suppress "@azure-tools/typespec-azure-core/documentation-required" "https://github.com/Azure/typespec-azure/issues/3107"
35+
enum APIVersion {
36+
v20231001Preview: "2023-10-01-preview",
37+
}

‎specification/machinelearning/Azure.AI.ChatProtocol/models/blocking.tsp‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
import "./common.tsp";
2+
3+
namespace Azure.AI.ChatProtocol;
4+
5+
@doc("The representation of a single generated completion.")
6+
model ChatChoice {
7+
@doc("The index of the of the chat choice, relative to the other choices in the same completion.")
8+
index: safeint;
9+
10+
@doc("The chat message for a given chat completion.")
11+
message: ChatMessage;
12+
13+
...StateProperty;
14+
...ContextProperty;
15+
16+
@doc("The reason this chat completion completed its generation.")
17+
finishReason: FinishReason;
18+
}
19+
@doc("Representation of the response to a chat completion request.")
20+
model ChatCompletion {
21+
@doc("The collection of generated completions.")
22+
choices: ChatChoice[];
23+
}
24+
25+
@doc("The configuration for a chat completion request.")
26+
model ChatCompletionOptions {
27+
@doc("The collection of context messages associated with this completion request.")
28+
messages: ChatMessage[];
29+
30+
@doc("Indicates whether the completion is a streaming or non-streaming completion.")
31+
stream: false;
32+
33+
...StateProperty;
34+
...ContextProperty;
35+
}

‎specification/machinelearning/Azure.AI.ChatProtocol/models/common.tsp‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
import "@typespec/http";
2+
3+
namespace Azure.AI.ChatProtocol;
4+
5+
using TypeSpec.Http;
6+
7+
@doc("Representation of the reason why a chat session has finished processing.")
8+
enum FinishReason {
9+
@doc("Completion ended normally.")
10+
stopped: "stop",
11+
12+
@doc("The completion exhausted available tokens before generation could complete.")
13+
tokenLimitReached: "length",
14+
}
15+
16+
@doc("A representation of the intended purpose of a message.")
17+
enum ChatRole {
18+
@doc("The role that provides input to the completion.")
19+
user: "user",
20+
21+
@doc("The role that instructs or configures the behavior of the assistant.")
22+
system: "system",
23+
24+
@doc("The role that provides responses to the system-instructed, user-prompted input.")
25+
assistant: "assistant",
26+
}
27+
28+
@doc("A property that represents backend-specific context or arguments.")
29+
model ContextProperty {
30+
#suppress "@azure-tools/typespec-azure-core/bad-record-type" "Protocol defines the type as Record<any>"
31+
@doc("""
32+
Context allows the chat app to receive extra parameters from the client, such as temperature, functions, or
33+
customer_info. These parameters are specific to the chat app and not understood by the generic clients.
34+
""")
35+
context?: Record<unknown>;
36+
}
37+
38+
@doc("A property that represents backend-specific information for the tracking of a session.")
39+
model StateProperty {
40+
#suppress "@azure-tools/typespec-azure-core/no-unknown" "The protocol defines these as any (object/scalar) for now"
41+
@doc("""
42+
Field that allows the chat app to store and retrieve data, the structure of such data is dependant on the backend
43+
being used. The client must send back the data in this field unchanged in subsequent requests, until the chat app
44+
sends a new one. The data in this field can be used to implement stateful services, such as remembering previous
45+
conversations or user preferences.
46+
""")
47+
sessionState?: unknown;
48+
}
49+
50+
@doc("Identifies the type of a message.")
51+
enum MessageKind {
52+
@doc("The message context is text.")
53+
text: "text",
54+
}
55+
56+
@doc("A single, role-attributed message within a chat completion interaction.")
57+
@discriminator("kind")
58+
model ChatMessage {
59+
@doc("The type of the message. If not specified, the message is assumed to be text.")
60+
kind: MessageKind;
61+
62+
@doc("The role associated with the message.")
63+
role: ChatRole;
64+
65+
...StateProperty;
66+
}
67+
68+
@doc("A single, role-attributed text message within a chat completion interaction.")
69+
model TextChatMessage extends ChatMessage {
70+
@doc("The type of the message.")
71+
kind: MessageKind.text;
72+
73+
@doc("The text associated with the message.")
74+
content: string;
75+
}
76+
77+
@doc("Parameter that describes the route of the operation to be performed.")
78+
model OperationRouteParam {
79+
@doc("The route where the endpoint exposes the chat operations.")
80+
@path
81+
operationRoute: string = "chat";
82+
}

‎specification/machinelearning/Azure.AI.ChatProtocol/models/streaming.tsp‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
import "./common.tsp";
2+
3+
namespace Azure.AI.ChatProtocol;
4+
5+
@doc("The representation of a delta message received in a streaming completion.")
6+
@discriminator("kind")
7+
model ChatMessageDelta {
8+
@doc("The type of the message. If not specified, the message is assumed to be text.")
9+
kind: MessageKind;
10+
11+
@doc("The role associated with the message.")
12+
role?: ChatRole;
13+
14+
...StateProperty;
15+
}
16+
17+
@doc("The representation of a delta text message received in a streaming completion.")
18+
model TextChatMessageDelta extends ChatMessageDelta {
19+
@doc("The type of the message.")
20+
kind: MessageKind.text;
21+
22+
@doc("An incremental part of the text associated with the message.")
23+
content?: string;
24+
}
25+
26+
@doc("The representation of an incremental choice received in a streaming completion.")
27+
model ChoiceDelta {
28+
@doc("The index of the of the chat choice, relative to the other choices in the same completion.")
29+
index: safeint;
30+
31+
@doc("The partial message received for this choice.")
32+
delta: ChatMessageDelta;
33+
34+
...StateProperty;
35+
...ContextProperty;
36+
37+
@doc("The reason this chat completion completed its generation.")
38+
finishReason?: FinishReason;
39+
}
40+
41+
@doc("A single response to a streaming completion request.")
42+
model ChatCompletionChunk {
43+
@doc("The collection of choice deltas received in this chunk.")
44+
choices: ChoiceDelta[];
45+
}
46+
47+
@doc("The configuration for a streaming chat completion request.")
48+
model StreamingChatCompletionOptions {
49+
@doc("The collection of context messages associated with this completion request.")
50+
messages: ChatMessage[];
51+
52+
@doc("Indicates whether the completion is a streaming or non-streaming completion.")
53+
stream: true;
54+
55+
...StateProperty;
56+
...ContextProperty;
57+
}

‎specification/machinelearning/Azure.AI.ChatProtocol/operations.tsp‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
import "@typespec/http";
2+
3+
import "./models/common.tsp";
4+
import "./models/blocking.tsp";
5+
import "./models/streaming.tsp";
6+
7+
namespace Azure.AI.ChatProtocol;
8+
9+
using TypeSpec.Http;
10+
11+
interface Chat {
12+
/* This operation returns a stream of objects in jsonl format. */
13+
#suppress "@azure-tools/typespec-azure-core/use-standard-operations" "Defining the operation in an Azure independent fashion"
14+
#suppress "@azure-tools/typespec-azure-core/operation-missing-api-version" "API version is not supported by the back end"
15+
@doc("Creates a new streaming chat completion.")
16+
@sharedRoute
17+
createStreaming(
18+
...StreamingChatCompletionOptions,
19+
...OperationRouteParam,
20+
): ChatCompletionChunk;
21+
22+
#suppress "@azure-tools/typespec-azure-core/use-standard-operations" "Defining the operation in an Azure independent fashion"
23+
#suppress "@azure-tools/typespec-azure-core/operation-missing-api-version" "API version is not supported by the back end"
24+
@doc("Creates a new chat completion.")
25+
@sharedRoute
26+
create(...ChatCompletionOptions, ...OperationRouteParam): ChatCompletion;
27+
}

‎specification/machinelearning/Azure.AI.ChatProtocol/tspconfig.yaml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
parameters:
2+
"service-dir":
3+
default: "sdk/machinelearning"
4+
emit:
5+
- "@azure-tools/typespec-autorest"
6+
# - "@typespec/openapi3"
7+
linter:
8+
extends:
9+
- "@azure-tools/typespec-azure-core/all"
10+
options:
11+
"@azure-tools/typespec-autorest":
12+
emitter-output-dir: "{project-root}/../"
13+
output-file: "{azure-resource-provider-folder}/Azure.AI.ChatProtocol/{version-status}/{version}/generated.json"
14+
azure-resource-provider-folder: "data-plane"
15+
examples-directory: examples
16+
omit-unreachable-types: true
17+
"@azure-tools/typespec-csharp":
18+
package-dir: "Azure.AI.ChatProtocol"
19+
namespace: "Azure.AI.ChatProtocol"
20+
clear-output-folder: true
21+
model-namespace: false
22+
"@azure-tools/typespec-python":
23+
package-dir: "azure-ai-chatprotocol"
24+
package-name: "{package-dir}"
25+
package-mode: dataplane
26+
"@azure-tools/typespec-ts":
27+
package-dir: "ai-chat-protocol"
28+
isModularLibrary: true
29+
packageDetails:
30+
name: "@azure/ai-chat-protocol"
31+
"@azure-tools/typespec-java":
32+
package-dir: "azure-ai-chatprotocol"
33+
namespace: "com.azure.ai.chatprotocol"

0 commit comments

Comments
 (0)