Skip to content

[CognitiveServices] LUIS Runtime API Spec #2051

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fearthecowboy merged 10 commits into from
Dec 1, 2017
Merged

[CognitiveServices] LUIS Runtime API Spec #2051

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
ed96a5c
Add LUIS Runtime API Spec
pcostantini Nov 27, 2017
da83d01
Change AzureRegion parameter to use ExtendedRegions template
pcostantini Nov 27, 2017
84c120e
API Info Title - better description for API
pcostantini Nov 29, 2017
aa673f0
Operation Ids and Description update
pcostantini Nov 29, 2017
8a945c6
Remove x-nullable: true
pcostantini Nov 29, 2017
cefe9b4
Add description to parameters and attributes
pcostantini Nov 29, 2017
c3ea0c8
Description field for LuisResult
pcostantini Nov 29, 2017
8663698
Remove Prediction_Resolve2 operation
pcostantini Nov 30, 2017
5d0af83
Represent "q" parameter as "query" argument
pcostantini Nov 30, 2017
bb87a56
modelAsExtensible
pcostantini Nov 30, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions specification/cognitiveservices/data-plane/LUIS/Runtime/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Cognitive Services LUIS SDKs

> see https://aka.ms/autorest

Configuration for generating LUIS Runtime SDK.

``` yaml
tag: runtime_2_0
add-credentials: true
openapi-type: data-plane
```

The current release for the Runtime Endpoint is `runtime_2_0`.

# Releases

## Runtime 2.0
These settings apply only when `--tag=runtime_2_0` is specified on the command line.

``` yaml $(tag) == 'runtime_2_0'

@fearthecowboy fearthecowboy Nov 29, 2017 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Change this section to this:

``` yaml $(tag) == 'runtime_2_0'
input-file: v2.0/LUIS-Runtime.json

# remove Resolve2 from code-generation (since the POST and GET operations are functionally identical. )
directive:
  remove-operation: Prediction_Resolve2
 
```

It will suppress Resolve2 from getting code generation

input-file: v2.0/LUIS-Runtime.json
```

### Runtime 2.0 - CSharp Settings
These settings apply only when `--csharp` is specified on the command line.
``` yaml $(csharp)

@fearthecowboy fearthecowboy Nov 30, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And, let's change this (uses new feature!)

csharp:
  override-client-name: LuisRuntimeAPI
  sync-methods: None
  license-header: MICROSOFT_MIT_NO_VERSION
  azure-arm: false
  namespace: Microsoft.Azure.CognitiveServices.Language.LUIS
  output-folder: $(csharp-sdks-folder)/CognitiveServices/dataPlane/Language/LUIS-Runtime/Generated
  clear-output-folder: true

# csharp has support for modelAsExtensible now; replace modelAsString with that. 
directive:
  from: swagger-document
  where: $..['x-ms-enum']
  transform: >
    if( $['modelAsString'] ) {
      $['modelAsExtensible'] = true;
      $['modelAsString'] = false;
    }

csharp:
override-client-name: LuisRuntimeAPI
sync-methods: None
license-header: MICROSOFT_MIT_NO_VERSION
azure-arm: false
namespace: Microsoft.Azure.CognitiveServices.Language.LUIS
output-folder: $(csharp-sdks-folder)/CognitiveServices/dataPlane/Language/LUIS-Runtime/Generated
clear-output-folder: true
```
338 changes: 338 additions & 0 deletions specification/cognitiveservices/data-plane/LUIS/Runtime/v2.0/LUIS-Runtime.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,338 @@
{
"swagger": "2.0",
"info": {
"title": "LUIS Endpoint API",
"version": "v2.0"
},
"x-ms-parameterized-host": {
"hostTemplate": "{AzureRegion}.api.cognitive.microsoft.com",
"parameters": [
{
"$ref": "../../../Common/ExtendedRegions.json#/parameters/AzureRegion"

@pcostantini pcostantini Nov 27, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For GA, what is the region list that should be included?
Should the BasicRegion or ExtendedRegion sets be used instead?

@DavidLiCIG DavidLiCIG Nov 28, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If neither of these fit LUIS' profile, feel free to create your own AzureRegion definitions within the spec.

@pcostantini pcostantini Nov 29, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, still awaiting confirmation.

@fearthecowboy fearthecowboy Nov 30, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pcostantini when you've got confirmation, ping and we can merge this.

@pcostantini pcostantini Nov 30, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @fearthecowboy ,
Just got confirmation, the ExtendedRegions.json is the one to be used, so no further changes are needed.
Thanks!

}
]
},
"basePath": "/luis/v2.0/apps",
"schemes": [
"https"
],
"securityDefinitions": {
"apiKeyHeader": {
"type": "apiKey",
"name": "Ocp-Apim-Subscription-Key",
"in": "header"
}
},
"security": [
{
"apiKeyHeader": []
}
],
"paths": {
"/{appId}": {
"get": {
"description": "Gets the published endpoint predictions for the given query.",
"operationId": "Prediction_GetPredictionsFromEndpointViaGet",

@fearthecowboy fearthecowboy Nov 27, 2017 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We use operationId to represent the group/method that gets generated for the SDKs.

The format should be <method-group>_<method-name> .

Ideally, something like Predictions_List (and let the description and parameters speak for themselves)

@pcostantini pcostantini Nov 29, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated to Predictions_Resolve

"parameters": [
{
"name": "appId",
"in": "path",
"type": "string",
"required": true,
"description": "Format - guid. The application ID."
},
{
"name": "q",
"in": "query",
"description": "The query to predict.",
"required": true,
"type": "string"
},
{
"name": "timezoneOffset",
"in": "query",
"description": "The timezone offset for the location of the request.",
"type": "number"
},
{
"name": "verbose",
"in": "query",
"description": "If true will return all intents instead of just the topscoring intent.",
"type": "boolean"
},
{
"name": "spellCheck",
"in": "query",
"description": "Enable spell checking.",
"type": "boolean"
},
{
"name": "staging",
"in": "query",
"description": "Use staging endpoint.",
"type": "boolean"
}
],
"responses": {
"200": {
"description": "A JSON object containing the predictions.",

@fearthecowboy fearthecowboy Nov 28, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You shouldn't describe the payload in terms of encoding or transport, (ie, remove A JSON object containing the ) -- Give a description that describes what the output is. (What exactly is a list of predictions?)

@pcostantini pcostantini Nov 29, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated along with entity's description and their attributes

"schema": {
"$ref": "#/definitions/LuisResult"
}
},
"default": {
"description": "Error response.",
"schema": {
"$ref": "#/definitions/APIError"
}
}
},
"produces": [
"application/json"
],
"x-ms-examples": {
"Successful Get Predictions From Endpoint Via Get request": {
"$ref": "./examples/prediction/SuccessfulGetPredictionsFromEndpointViaGetRequest.json"
}
}
},
"post": {
"description": "Gets the published endpoint prediction for the given long query.",
"operationId": "Prediction_GetPredictionsFromEndpointViaPost",

@fearthecowboy fearthecowboy Nov 28, 2017 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there any fundamental differences between using the GET and POST endpoints?

again this should be Predictions_List or something. Although, you can't have two methods with the same operation id, so if they are functionally the same, call the GET one Predictions_List2 and call this one Predictions_List and we'll give you the configuration to suppress generating the code for the GET (since the SDK caller won't ever care which one it's using)

If there are fundamental differences between GET and POST , we should examine them and see what we can do.

@pcostantini pcostantini Nov 29, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK. The API allows using GET or POST, but the end-result is the same and the parameters constraints are the same too.
For the SDK generation the POST can be used instead. Do you have the configuration required to disable an operation? (Please take a look at the current C# generation @ https://github.com/southworkscom/azure-sdk-for-net/blob/cognitiveservices-luis-runtime-sdk/src/SDKs/CognitiveServices/dataPlane/Language/LUIS-Runtime/Generated/PredictionExtensions.cs#L50 )

"parameters": [
{
"name": "appId",
"in": "path",
"type": "string",
"required": true,
"description": "Format - guid. The application ID."

@fearthecowboy fearthecowboy Nov 28, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the application ID used for?

@pcostantini pcostantini Nov 29, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added description for the Luis Application ID

},
{
"name": "q",

@fearthecowboy fearthecowboy Nov 29, 2017 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the q parameters, we should probably add:

           "x-ms-client-name":"query",

in so the parameter name is query rather than q in the generated code (do this on Resolve2 as well, just for completion sake)

"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/Q"
},
"description": "The query to predict."
},
{
"name": "timezoneOffset",
"in": "query",
"description": "The timezone offset for the location of the request.",
"type": "number"
},
{
"name": "verbose",
"in": "query",
"description": "If true will return all intents instead of just the topscoring intent.",
"type": "boolean"
},
{
"name": "spellCheck",
"in": "query",
"description": "Enable spell checking.",
"type": "boolean"
},
{
"name": "staging",
"in": "query",
"description": "Use staging endpoint.",
"type": "boolean"
}
],
"consumes": [
"application/json"
],
"responses": {
"200": {
"description": "A JSON object containing the prediction.",
"schema": {
"$ref": "#/definitions/LuisResult"
}
},
"default": {
"description": "Error response.",
"schema": {
"$ref": "#/definitions/APIError"
}
}
},
"produces": [
"application/json"
],
"x-ms-examples":{
"Successful Get Predictions From Endpoint Via Post request": {
"$ref": "./examples/prediction/SuccessfulGetPredictionsFromEndpointViaPostRequest.json"
}
}
}
}
},
"definitions": {
"Q": {
"type": "string",
"example": "\"forward to frank 30 dollars through HSBC\""
},
"LuisResult": {
"type": "object",
"properties": {
"query": {
"type": "string",

@fearthecowboy fearthecowboy Nov 28, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You need description fields on all your properties.

@pcostantini pcostantini Nov 29, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added description to all parameters and attributes

"x-nullable": true
},
"topScoringIntent": {
"$ref": "#/definitions/IntentModel",
"x-nullable": true
},
"intents": {
"type": "array",
"x-nullable": true,
"items": {
"$ref": "#/definitions/IntentModel"
}
},
"entities": {
"type": "array",
"x-nullable": true,

@fearthecowboy fearthecowboy Nov 28, 2017 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a reason you're explicitly marking things x-nullable: true ?

That affects code-generation in some specific ways, but shouldn't be used so liberally without a definite reason.

Most of what you've marked here would be nullable anyway.

@pcostantini pcostantini Nov 29, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed all x-nullable: true

"items": {
"$ref": "#/definitions/EntityModel"
}
},
"compositeEntities": {
"type": "array",
"x-nullable": true,
"description": "The composite entities extracted from the utterance.",
"items": {
"$ref": "#/definitions/CompositeEntityModel"
}
}
}
},
"CompositeEntityModel": {
"description": "LUIS Composite Entity.",
"type": "object",
"properties": {
"parentType": {
"type": "string",
"description": "Type/name of parent entity."
},
"value": {
"type": "string",
"description": "Value for composite entity extracted by LUIS."
},
"children": {
"type": "array",
"items": {
"$ref": "#/definitions/CompositeChildModel"
}
}
},
"required": [
"parentType",
"value",
"children"
]
},
"CompositeChildModel": {
"description": "Child entity in LUIS composite entity.",
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type of child entity."
},
"value": {
"type": "string",
"description": "Value extracted by LUIS."
}
},
"required": [
"type",
"value"
]
},
"IntentModel": {
"description": "Intent returned from LUIS.",
"type": "object",
"properties": {
"intent": {
"type": "string"
},
"score": {
"type": "number"
}
}
},
"EntityModel": {
"description": "Entity returned from LUIS.",
"type": "object",
"properties":{
"entity": {
"type": "string"
},
"type": {
"type": "string"
},
"startIndex": {
"type": "number"

@fearthecowboy fearthecowboy Nov 28, 2017

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be a good idea to have maximum and minimum values for numbers if you can.

@pcostantini pcostantini Nov 29, 2017

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added description with their meaning. These values change based on the input. They represent a match within the input query

},
"endIndex": {
"type": "number"
}
},
"additionalProperties": {
"type": "object"
},
"required": [ "entity", "type", "startIndex", "endIndex" ]
},
"EntityWithScore": {
"allOf": [
{
"$ref": "#/definitions/EntityModel"
},
{
"type": "object",
"properties": {
"score": {
"type": "number"
}
},
"required": [
"score"
]
}
]
},
"EntityWithResolution": {
"allOf": [
{
"$ref": "#/definitions/EntityModel"
},
{
"type": "object",
"properties": {
"resolution": {
"type": "object"
}
},
"required": [
"resolution"
]
}
]
},
"APIError": {
"type": "object",
"description": "Error information returned by the API",
"properties": {
"statusCode": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
Loading