swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector text:detectGroundedness API
schemes:
- https
tags:
- name: text:detectGroundedness
paths:
  /text:detectGroundedness:
    post:
      operationId: microsoftAzureTextgroundednessdetectionoperationsDetectgroundednessoptions
      summary: Microsoft Azure Detect Groundedness
      description: A synchronous API for the analysis of language model outputs to determine alignment with user-provided information or identify fictional content.
      parameters:
      - $ref: '#/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: body
        in: body
        description: The text groundedness detection request.
        required: true
        schema:
          $ref: '#/definitions/AnalyzeTextGroundednessOptions'
      responses:
        '200':
          description: The request has succeeded.
          schema:
            $ref: '#/definitions/AnalyzeTextGroundednessResult'
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/definitions/Azure.Core.Foundations.ErrorResponse'
          headers:
            x-ms-error-code:
              type: string
              description: String error code indicating what went wrong.
      x-ms-examples:
        Detect Groundedness:
          $ref: ./examples/DetectGroundedness.json
      tags:
      - text:detectGroundedness
definitions:
  AnalyzeTextGroundednessOptions:
    type: object
    description: The request of groundedness detection.
    properties:
      domain:
        type: string
        description: 'The domain of the text for analysis. Allowed values: Medical, Generic.

          This field is optional, with a default value of Generic.'
        default: Generic
        enum:
        - Generic
        - Medical
        x-ms-enum:
          name: GroundednessDomain
          modelAsString: true
          values:
          - name: Generic
            value: Generic
          - name: Medical
            value: Medical
      task:
        type: string
        description: 'The task type for the text analysis. Type of task: QnA, Summarization.

          This field is optional, with a default value of Summarization.'
        default: Summarization
        enum:
        - Summarization
        - QnA
        x-ms-enum:
          name: GroundednessTask
          modelAsString: true
          values:
          - name: Summarization
            value: Summarization
          - name: QnA
            value: QnA
      qna:
        $ref: '#/definitions/QnAOptions'
        description: 'The user''s question input in a QnA scenario.

          This field is optional, but if the task type is set to QnA, it becomes required.'
      text:
        type: string
        description: The specific text that needs to be checked.
        maxLength: 7500
      groundingSources:
        type: array
        description: 'Leverages a vast array of grounding sources to validate AI-generated text.

          Limit: Restrictions on the total amount of grounding sources that can be analyzed in a single request are 55K characters.'
        items:
          type: string
      reasoning:
        type: boolean
        description: 'A value indicating if the output includes an explanation for the identified groundedness.

          This field is optional, with a default value of false.'
      llmResource:
        $ref: '#/definitions/LLMResource'
        description: "Connection details for the LLM resource. \nThis field will be used only when the 'reasoning' field is set to true; otherwise, it will be ignored."
    required:
    - text
    - groundingSources
  Azure.Core.Foundations.ErrorResponse:
    type: object
    description: A response containing error details.
    properties:
      error:
        $ref: '#/definitions/Azure.Core.Foundations.Error'
        description: The error object.
    required:
    - error
  QnAOptions:
    type: object
    description: The request of QnA options.
    properties:
      query:
        type: string
        description: The user's question input in a QnA scenario.
        maxLength: 7500
    required:
    - query
  Azure.Core.Foundations.InnerError:
    type: object
    description: An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
    properties:
      code:
        type: string
        description: One of a server-defined set of error codes.
      innererror:
        $ref: '#/definitions/Azure.Core.Foundations.InnerError'
        description: Inner error.
  LLMResource:
    type: object
    description: Connection details for the LLM resource.
    properties:
      resourceType:
        type: string
        description: LLM resource type. The default value is AzureOpenAI.
        default: AzureOpenAI
        enum:
        - AzureOpenAI
        x-ms-enum:
          name: LLMResourceType
          modelAsString: true
          values:
          - name: AzureOpenAI
            value: AzureOpenAI
            description: Azure OpenAI resource type.
      azureOpenAIEndpoint:
        type: string
        description: Endpoint for Azure OpenAI resource.
      azureOpenAIDeploymentName:
        type: string
        description: Deployment model name.
    required:
    - azureOpenAIEndpoint
    - azureOpenAIDeploymentName
  IndexDetails:
    type: object
    description: The index details.
    properties:
      utf8:
        type: integer
        format: int64
        description: Indicate the index when encoding is UTF-8.
      utf16:
        type: integer
        format: int64
        description: Indicate the index when encoding is UTF-16.
      codePoint:
        type: integer
        format: int64
        description: Indicate the index with code point format.
    required:
    - utf8
    - utf16
    - codePoint
  AnalyzeTextGroundednessResult:
    type: object
    description: The response of groundedness detection.
    properties:
      ungroundedDetected:
        type: boolean
        description: Indicates whether the text exhibits ungroundedness.
      ungroundedPercentage:
        type: number
        format: float
        description: "Specifies the proportion of the text identified as ungrounded, \nexpressed as a decimal between 0 and 1,\nwhere 0 indicates no grounded content and 1 indicates entirely grounded content.."
      ungroundedDetails:
        type: array
        description: Provides insights into ungrounded content with specific examples and percentages.
        items:
          $ref: '#/definitions/UngroundednessDetails'
        x-ms-identifiers: []
    required:
    - ungroundedDetected
    - ungroundedPercentage
    - ungroundedDetails
  Azure.Core.Foundations.Error:
    type: object
    description: The error object.
    properties:
      code:
        type: string
        description: One of a server-defined set of error codes.
      message:
        type: string
        description: A human-readable representation of the error.
      target:
        type: string
        description: The target of the error.
      details:
        type: array
        description: An array of details about specific errors that led to this reported error.
        items:
          $ref: '#/definitions/Azure.Core.Foundations.Error'
        x-ms-identifiers: []
      innererror:
        $ref: '#/definitions/Azure.Core.Foundations.InnerError'
        description: An object containing more specific information than the current object about the error.
    required:
    - code
    - message
  UngroundednessDetails:
    type: object
    description: The detailed information about a text identified as ungroundedness.
    properties:
      text:
        type: string
        description: The grounded text.
      offset:
        $ref: '#/definitions/IndexDetails'
        description: The offset when grounded text starts.
      length:
        $ref: '#/definitions/IndexDetails'
        description: The length of the grounded text.
      reason:
        type: string
        description: 'The explanation for detected ungroundedness, enhancing understanding.

          Only when the ''reasoning'' field in the input is set to true ''reason'' field will be returned.'
    required:
    - text
    - offset
    - length
parameters:
  Azure.Core.Foundations.ApiVersionParameter:
    name: api-version
    in: query
    description: The API version to use for this operation.
    required: true
    type: string
    minLength: 1
    x-ms-parameter-location: method
    x-ms-client-name: apiVersion
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'