Skip to content
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.

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

[Draft] Controllable and Interactive Summarization #21787

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

wangyuantao
Copy link
Member

@wangyuantao wangyuantao commented Dec 7, 2022

Design consideration:

  1. This PR is draft and target for next api-version, not 2022-10-01-preview.
  2. In current api-version 2022-10-01-preview, client can access the new features only if the labFeatures.clientApplication is "Editor".
  3. We rely on sessionId to retrieve previous summary, because the revision history has to include document snapshots, which is too large to send via request.
  4. phrase control, phrase control suggestion, insert in the middel and interactive session are separate features that is decoupled in API.

@openapi-workflow-bot
Copy link

Hi, @wangyuantao Thanks for your PR. I am workflow bot for review process. Here are some small tips.

  • Please ensure to do self-check against checklists in first PR comment.
  • PR assignee is the person auto-assigned and responsible for your current PR reviewing and merging.
  • For specs comparison cross API versions, Use API Specs Comparison Report Generator
  • If there is CI failure(s), to fix CI error(s) is mandatory for PR merging; or you need to provide justification in PR comment for explanation. How to fix?

  • Any feedback about review process or workflow bot, pls contact swagger and tools team. vscswagger@microsoft.com

    @ghost ghost added the Cognitive Services label Dec 7, 2022
    @openapi-pipeline-app
    Copy link

    openapi-pipeline-app bot commented Dec 7, 2022

    Swagger Validation Report

    ️❌BreakingChange: 7 Errors, 0 Warnings failed [Detail]
    compared swaggers (via Oad v0.10.4)] new version base version
    analyzetext.json 2023-05-01(8c1ba26) 2023-05-01(main)
    common.json 2023-05-01(8c1ba26) 2023-05-01(main)
    Rule Message
    1045 - AddedOptionalProperty The new version has a new optional property 'summaryLength' that was not found in the old version.
    1045 - AddedOptionalProperty The new version has a new optional property 'phraseControls' that was not found in the old version.
    1045 - AddedOptionalProperty The new version has a new optional property 'sessionId' that was not found in the old version.
    1045 - AddedOptionalProperty The new version has a new optional property 'phraseControlsRecommendationOption' that was not found in the old version.
    1045 - AddedOptionalProperty The new version has a new optional property 'enableInteractiveSummarizationSession' that was not found in the old version.
    1045 - AddedOptionalProperty The new version has a new optional property 'prefix' that was not found in the old version.
    1045 - AddedOptionalProperty The new version has a new optional property 'suffix' that was not found in the old version.
    ️❌Breaking Change(Cross-Version): 18 Errors, 22 Warnings failed [Detail]
    compared swaggers (via Oad v0.10.4)] new version base version
    analyzetext.json 2023-05-01(8c1ba26) 2022-05-01(main)
    analyzetext.json 2023-05-01(8c1ba26) 2022-10-01-preview(main)
    common.json 2023-05-01(8c1ba26) 2022-05-01(main)
    common.json 2023-05-01(8c1ba26) 2022-10-01-preview(main)

    The following breaking changes are detected by comparison with the latest stable version:

    Only 30 items are listed, please refer to log for more details.

    Rule Message
    1034 - AddedRequiredProperty The new version has new required property 'entities' that was not found in the old version.
    1034 - AddedRequiredProperty The new version has new required property 'relations' that was not found in the old version.
    1034 - AddedRequiredProperty The new version has new required property 'id' that was not found in the old version.
    1034 - AddedRequiredProperty The new version has new required property 'warnings' that was not found in the old version.
    1034 - AddedRequiredProperty The new version has new required property 'entities, relations, id, warnings' that was not found in the old version.
    New: cognitiveservices/data-plane/Language/analyzetext.json#L853:11
    Old: Language/stable/2022-05-01/analyzetext.json#L779:11
    1034 - AddedRequiredProperty The new version has new required property 'entities' that was not found in the old version.
    1034 - AddedRequiredProperty The new version has new required property 'id' that was not found in the old version.
    1034 - AddedRequiredProperty The new version has new required property 'warnings' that was not found in the old version.
    1034 - AddedRequiredProperty The new version has new required property 'entities, id, warnings' that was not found in the old version.
    New: cognitiveservices/data-plane/Language/analyzetext.json#L1524:11
    Old: Language/stable/2022-05-01/analyzetext.json#L1430:11
    1034 - AddedRequiredProperty The new version has new required property 'entities' that was not found in the old version.
    1034 - AddedRequiredProperty The new version has new required property 'id' that was not found in the old version.
    1034 - AddedRequiredProperty The new version has new required property 'warnings' that was not found in the old version.
    1034 - AddedRequiredProperty The new version has new required property 'entities, id, warnings' that was not found in the old version.
    New: cognitiveservices/data-plane/Language/analyzetext.json#L1677:11
    Old: Language/stable/2022-05-01/analyzetext.json#L1559:11
    1034 - AddedRequiredProperty The new version has new required property 'redactedText' that was not found in the old version.
    1034 - AddedRequiredProperty The new version has new required property 'entities' that was not found in the old version.
    1034 - AddedRequiredProperty The new version has new required property 'id' that was not found in the old version.
    1034 - AddedRequiredProperty The new version has new required property 'warnings' that was not found in the old version.
    1034 - AddedRequiredProperty The new version has new required property 'redactedText, entities, id, warnings' that was not found in the old version.
    New: cognitiveservices/data-plane/Language/analyzetext.json#L2512:11
    Old: Language/stable/2022-05-01/analyzetext.json#L1728:11
    ⚠️ 1017 - ReferenceRedirection The '$ref' property points to different models in the old and new versions.
    New: cognitiveservices/data-plane/Language/common.json#L383:11
    Old: Language/stable/2022-05-01/analyzetext.json#L517:11
    ⚠️ 1017 - ReferenceRedirection The '$ref' property points to different models in the old and new versions.
    New: cognitiveservices/data-plane/Language/analyzetext.json#L853:11
    Old: Language/stable/2022-05-01/analyzetext.json#L779:11
    ⚠️ 1017 - ReferenceRedirection The '$ref' property points to different models in the old and new versions.
    New: cognitiveservices/data-plane/Language/common.json#L383:11
    Old: Language/stable/2022-05-01/analyzetext.json#L517:11
    ⚠️ 1017 - ReferenceRedirection The '$ref' property points to different models in the old and new versions.
    New: cognitiveservices/data-plane/Language/common.json#L383:11
    Old: Language/stable/2022-05-01/analyzetext.json#L517:11
    ⚠️ 1017 - ReferenceRedirection The '$ref' property points to different models in the old and new versions.
    New: cognitiveservices/data-plane/Language/analyzetext.json#L1524:11
    Old: Language/stable/2022-05-01/analyzetext.json#L1430:11
    ⚠️ 1017 - ReferenceRedirection The '$ref' property points to different models in the old and new versions.
    New: cognitiveservices/data-plane/Language/common.json#L383:11
    Old: Language/stable/2022-05-01/analyzetext.json#L517:11
    ⚠️ 1017 - ReferenceRedirection The '$ref' property points to different models in the old and new versions.
    New: cognitiveservices/data-plane/Language/analyzetext.json#L1555:11
    Old: Language/stable/2022-05-01/analyzetext.json#L1454:11
    ⚠️ 1017 - ReferenceRedirection The '$ref' property points to different models in the old and new versions.
    New: cognitiveservices/data-plane/Language/analyzetext.json#L1677:11
    Old: Language/stable/2022-05-01/analyzetext.json#L1559:11
    ⚠️ 1017 - ReferenceRedirection The '$ref' property points to different models in the old and new versions.
    New: cognitiveservices/data-plane/Language/common.json#L383:11
    Old: Language/stable/2022-05-01/analyzetext.json#L517:11
    ⚠️ 1017 - ReferenceRedirection The '$ref' property points to different models in the old and new versions.
    New: cognitiveservices/data-plane/Language/analyzetext.json#L2512:11
    Old: Language/stable/2022-05-01/analyzetext.json#L1728:11
    ⚠️ 1017 - ReferenceRedirection The '$ref' property points to different models in the old and new versions.
    New: cognitiveservices/data-plane/Language/common.json#L383:11
    Old: Language/stable/2022-05-01/analyzetext.json#L517:11
    ⚠️ 1017 - ReferenceRedirection The '$ref' property points to different models in the old and new versions.
    New: cognitiveservices/data-plane/Language/common.json#L383:11
    Old: Language/stable/2022-05-01/analyzetext.json#L517:11
    ️️✔️CredScan succeeded [Detail] [Expand]
    There is no credential detected.
    ️⚠️LintDiff: 0 Warnings warning [Detail]
    compared tags (via openapi-validator v2.0.0) new version base version
    release_2022-07-01-preview release_2022-07-01-preview(8c1ba26) release_2022-07-01-preview(main)

    The following errors/warnings exist before current PR submission:

    Only 30 items are listed, please refer to log for more details.

    Rule Message
    HostParametersValidation The host parameter must be called 'endpoint'.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L39
    HostParametersValidation The host parameter must be typed 'type 'string', format 'url''.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L39
    IntegerTypeMustHaveFormat The integer type does not have a format, please add it.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L2778
    IntegerTypeMustHaveFormat The integer type does not have a format, please add it.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L3209
    IntegerTypeMustHaveFormat The integer type does not have a format, please add it.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L3212
    IntegerTypeMustHaveFormat The integer type does not have a format, please add it.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L3215
    IntegerTypeMustHaveFormat The integer type does not have a format, please add it.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L3218
    ⚠️ OperationId OperationId should be of the form 'Noun_Verb'
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L49
    ⚠️ ErrorResponse Error response should contain a x-ms-error-code header.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L80
    ⚠️ AdditionalPropertiesAndProperties Don't specify additionalProperties as a sibling of properties.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L82
    ⚠️ ErrorResponse Error response should contain a x-ms-error-code header.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L146
    ⚠️ AdditionalPropertiesAndProperties Don't specify additionalProperties as a sibling of properties.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L148
    ⚠️ AdditionalPropertiesAndProperties Don't specify additionalProperties as a sibling of properties.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L148
    ⚠️ GetInOperationName 'GET' operation 'AnalyzeText_JobStatus' should use method name 'Get' or Method name start with 'List'. Note: If you have already shipped an SDK on top of this spec, fixing this warning may introduce a breaking change.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L176
    ⚠️ OperationId OperationId for get method should contain 'Get' or 'list'
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L176
    ⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L182
    ⚠️ AdditionalPropertiesAndProperties Don't specify additionalProperties as a sibling of properties.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L198
    ⚠️ AdditionalPropertiesAndProperties Don't specify additionalProperties as a sibling of properties.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L198
    ⚠️ SchemaTypeAndFormat Schema with type: integer should specify format
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L198
    ⚠️ SchemaTypeAndFormat Schema with type: integer should specify format
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L198
    ⚠️ SchemaTypeAndFormat Schema with type: integer should specify format
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L198
    ⚠️ SchemaTypeAndFormat Schema with type: integer should specify format
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L198
    ⚠️ ErrorResponse Error response should contain a x-ms-error-code header.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L202
    ⚠️ AdditionalPropertiesAndProperties Don't specify additionalProperties as a sibling of properties.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L204
    ⚠️ AdditionalPropertiesAndProperties Don't specify additionalProperties as a sibling of properties.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L204
    ⚠️ AdditionalPropertiesAndProperties Don't specify additionalProperties as a sibling of properties.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L204
    ⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L237
    ⚠️ ErrorResponse Error response should contain a x-ms-error-code header.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L250
    ⚠️ AdditionalPropertiesAndProperties Don't specify additionalProperties as a sibling of properties.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L252
    ⚠️ AdditionalPropertiesAndProperties Don't specify additionalProperties as a sibling of properties.
    Location: cognitiveservices/data-plane/Language/analyzetext.json#L252
    ️️✔️Avocado succeeded [Detail] [Expand]
    Validation passes for Avocado.
    ️️✔️ApiReadinessCheck succeeded [Detail] [Expand]
    ️️✔️~[Staging] ServiceAPIReadinessTest succeeded [Detail] [Expand]
    Validation passes for ServiceAPIReadinessTest.
    ️️✔️~[Staging] SwaggerAPIView succeeded [Detail] [Expand]
    ️️✔️~[Staging] CadlAPIView succeeded [Detail] [Expand]
    ️️✔️ModelValidation succeeded [Detail] [Expand]
    Validation passes for ModelValidation.
    ️️✔️SemanticValidation succeeded [Detail] [Expand]
    Validation passes for SemanticValidation.
    ️️✔️PoliCheck succeeded [Detail] [Expand]
    Validation passed for PoliCheck.
    ️❌PrettierCheck: 1 Errors, 0 Warnings failed [Detail]
    Rule Message
    HowToFix Code style issues found
    path: cognitiveservices/data-plane/Language/common.json
    ️️✔️SpellCheck succeeded [Detail] [Expand]
    Validation passes for SpellCheck.
    ️️✔️Lint(RPaaS) succeeded [Detail] [Expand]
    Validation passes for Lint(RPaaS).
    ️️✔️CadlValidation succeeded [Detail] [Expand]
    Validation passes for CadlValidation.
    ️️✔️PR Summary succeeded [Detail] [Expand]
    Validation passes for Summary.
    Posted by Swagger Pipeline | How to fix these errors?

    @openapi-pipeline-app
    Copy link

    openapi-pipeline-app bot commented Dec 7, 2022

    Swagger Generation Artifacts

    ️️✔️ApiDocPreview succeeded [Detail] [Expand]
    ️️✔️SDK Breaking Change Tracking succeeded [Detail] [Expand]

    Breaking Changes Tracking

    ️⚠️ azure-sdk-for-net-track2 warning [Detail]
    • ⚠️Warning [Logs] Generate from 874905ce58a21ec2e4241f018932d9e3cf5249e5. SDK Automation 14.0.0
      command	pwsh ./eng/scripts/Automation-Sdk-Init.ps1 ../azure-sdk-for-net_tmp/initInput.json ../azure-sdk-for-net_tmp/initOutput.json
      command	pwsh ./eng/scripts/Invoke-GenerateAndBuildV2.ps1 ../azure-sdk-for-net_tmp/generateInput.json ../azure-sdk-for-net_tmp/generateOutput.json
      warn	No file changes detected after generation
      warn	Skip detect changed packages
    ️⚠️ azure-sdk-for-python warning [Detail]
    • ⚠️Warning [Logs] Generate from 874905ce58a21ec2e4241f018932d9e3cf5249e5. SDK Automation 14.0.0
      command	sh scripts/automation_init.sh ../azure-sdk-for-python_tmp/initInput.json ../azure-sdk-for-python_tmp/initOutput.json
      cmderr	[automation_init.sh] WARNING: Skipping azure-nspkg as it is not installed.
      command	sh scripts/automation_generate.sh ../azure-sdk-for-python_tmp/generateInput.json ../azure-sdk-for-python_tmp/generateOutput.json
      cmderr	[automation_generate.sh] npm notice
      cmderr	[automation_generate.sh] npm notice New major version of npm available! 8.19.2 -> 9.3.1
      cmderr	[automation_generate.sh] npm notice Changelog: <https://github.com/npm/cli/releases/tag/v9.3.1>
      cmderr	[automation_generate.sh] npm notice Run `npm install -g npm@9.3.1` to update!
      cmderr	[automation_generate.sh] npm notice
      warn	No file changes detected after generation
      warn	No package detected after generation
    Posted by Swagger Pipeline | How to fix these errors?

    @openapi-pipeline-app
    Copy link

    openapi-pipeline-app bot commented Dec 7, 2022

    Swagger pipeline restarted successfully. If there is ApiView generated, it will be updated in this comment.

    @AzureRestAPISpecReview AzureRestAPISpecReview added BreakingChangeReviewRequired <valid label in PR review process>add this label when breaking change review is required NewApiVersionRequired labels Dec 7, 2022
    @openapi-workflow-bot
    Copy link

    Hi @wangyuantao, one or multiple breaking change(s) is detected in your PR. Please check out the breaking change(s), and provide business justification in the PR comment and @ PR assignee why you must have these change(s), and how external customer impact can be mitigated. Please ensure to follow breaking change policy to request breaking change review and approval before proceeding swagger PR review.
    Action: To initiate an evaluation of the breaking change, create a new intake using the template for breaking changes. Addition details on the process and office hours are on the Breaking change Wiki.
    If you want to know the production traffic statistic, please see ARM Traffic statistic.
    If you think it is false positive breaking change, please provide the reasons in the PR comment, report to Swagger Tooling Team via https://aka.ms/swaggerfeedback.
    Note: To avoid breaking change, you can refer to Shift Left Solution for detecting breaking change in early phase at your service code repository.

    @openapi-workflow-bot
    Copy link

    NewApiVersionRequired reason:

    A service’s API is a contract with customers and is represented by using the api-version query parameter. Changes such as adding an optional property to a request/response or introducing a new operation is a change to the service’s contract and therefore requires a new api-version value. This is critically important for documentation, client libraries, and customer support.

    EXAMPLE: if a customer calls a service in the public cloud using api-version=2020-07-27, the new property or operation may exist but if they call the service in a government cloud, air-gapped cloud, or Azure Stack Hub cloud using the same api-version, the property or operation may not exist. Because there is no clear relationship between the service api-version and the new property/operation, customers can’t trust the documentation and Azure customer have difficulty helping customers diagnose issues. In addition, each client library version documents the service version it supports. When an optional property or new operation is added to a service and its Swagger, new client libraries must be produced to expose this functionality to customers. Without updating the api-version, it is unclear to customers which version of a client library supports these new features.

    @wangyuantao wangyuantao changed the title [Draft] Summarization New Features [Draft] Controllable and Interactive Summarization Jan 18, 2023
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    BreakingChangeReviewRequired <valid label in PR review process>add this label when breaking change review is required Cognitive Services
    Projects
    None yet
    Development

    Successfully merging this pull request may close these issues.

    4 participants