openapi: 3.0.3
info:
  title: LLM Engine API
  description: |
    <a href="/openapi/wcg/llm-engine-openapi.yaml" target="_blank" download="llm-engine-openapi.yaml"><button>Download OpenAPI Specification</button></a>

    **LLM Engine** is a service responsible to manage requests from the Witboost Computational Governance to validate resources using natural language text to sent to the LLMs.

    # Register a LLM Engine

    Once you set up the parameters necessary to connect to the APIs of an LLM, when you create a policy in Witboost, you can select the LLM Engine to use for the evaluation. 

    When you select LLM Engine, you will be able to provide the prompt written in natural language which provides the instructions to the LLM for the evaluation of the resource.
  version: "0.1"
tags:
  - name: LlmEngine
paths:
  /v1/evaluate:
    post:
      tags:
        - LlmEngine
      summary: Evaluate a resource
      description: Computes a result based on the input resource. The result will be a policy result.
      operationId: validate
      requestBody:
        description: An object containing the resource to evaluate using this executor
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InputResource"
            examples:
              dataProductResource:
                value:
                  content: "apiVersion: v1\nkind: dataproduct\ndomain: marketing\nmetadata:\n  name: my-dataproduct\n  namespace: my-namespace\n  labels:\n    app: my-app"
                  policy: "The data product domain must be defined as finance."
                  resourceType: dataproduct
                  resourceId: 123456
        required: true
      responses:
        200:
          description: Return a response containing the evaluation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PolicyResult"
              examples:
                policyResult:
                  value:
                    satisfiesPolicy: false
                    errors:
                      - The data product domain is defined as 'marketing'. The expected domain is 'finance'.
                    details:
                      suggestion: Change the domain from 'marketing' to 'finance'.
        400:
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
              examples:
                invalidInput:
                  value:
                    error: "Invalid input. The resource type should be a valid string."
        500:
          description: System problem
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SysError"
              examples:
                systemProblem:
                  value:
                    error: "Internal server error. Please try again later."
components:
  schemas:
    InputResource:
      type: object
      required:
        - content
        - policy
        - resourceId
        - resourceType
      properties:
        content:
          description: The content of the resource to be evaluated. The content can be any type of data, such as a JSON object, a string, a number, etc but always in its string representation. e.g. For a system resource, the content will be a stringified YAML descriptor.
          type: string
        policy:
          description: Policy written in natural language which will be applied by the LLM to the content of the resource.
          type: string
        resourceId:
          description: A unique Resource Identifier inside the Witboost platform.
          type: string
        resourceType:
          description: Resource type that is being sent in the content. This has to be agreed between the LLM Engine implementation and the platform's registered resource types.
          type: string
    PolicyResult:
      type: object
      required:
        - satisfiesPolicy
        - errors
      properties:
        satisfiesPolicy:
          type: boolean
          description: Whether the input resource is said to satisfy the policy or not.
        details:
          type: object
          description: A free-form field of additional information linked to the policy result. This will be visible in the Witboost UI as a JSON object.
        errors:
          type: array
          description: A list of errors explaining why the resource is not compliant to the policy.
          items:
            type: string
    ValidationError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    SysError:
      type: object
      required:
        - error
      properties:
        error:
          type: string