feat: add AI assistance to the VLA Builder

docs/spec/vla-manager-api.yaml

@@ -70,6 +70,46 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+  /assistant/vla:
+    post:
+      tags: [Assistant]
+      summary: Prepare a VLA draft from the template catalog
+      description: >-
+        Uses the supplied builder context and available templates to prepare
+        an unsaved VLA draft. Requirements contain catalog template IDs and
+        variable models only; the endpoint never persists a VLA or template.
+      operationId: assistVLA
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssistantVLARequest'
+      responses:
+        '200':
+          description: Catalog-backed VLA draft.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AssistantVLAResponse'
+        '422':
+          description: Empty or invalid assistant request.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationError'
+        '502':
+          description: Assistant returned an invalid response.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: Assistant service is not configured or unavailable.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
   /template:
     get:
       tags: [Templates]
@@ -394,16 +434,131 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+  /vla/{id}/evaluate:
+    parameters:
+      - $ref: '#/components/parameters/idParam'
+    post:
+      tags: [VLA]
+      summary: Try a VLA out on sample data
+      description: >-
+        Runs every requirement in the VLA's `quality` array over `data` with
+        DVA Processing's `/evaluate`, as `/evaluate/from-template` runs a
+        single one.  Nothing is attested: this is for checking a VLA before
+        it is used in an exchange.  A requirement the data fails, or one the
+        engine could not run, is a result with `success` false (and `error`
+        set in the latter case), so this stays a `200`.
+      operationId: evaluateVLA
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VLAEvaluationRequest'
+      responses:
+        '200':
+          description: >-
+            One result per requirement, in the order the requirements appear
+            in the VLA's `quality` array; a VLA without requirements yields
+            an empty array.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/EvaluationResult'
+        '404':
+          description: No VLA with the given ID exists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '422':
+          description: Invalid request body.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationError'
+        '503':
+          description: >-
+            DVA Processing could not be reached (`EVALUATION_UNAVAILABLE`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /evaluate/from-template:
+    post:
+      tags: [Templates]
+      summary: Run a template over sample data
+      description: >-
+        Renders the template with the supplied model – after checking the
+        model against the template's variable schema – and has DVA
+        Processing's `/evaluate` run the resulting requirement over `data`.
+        The request and the `EvaluationResult` are those of DVA Processing's
+        own `/evaluate/from-template`; processing's status and result are
+        returned as they are, so a requirement the data fails is a `200`
+        with `success: false`, and one the engine could not run is a `500`
+        carrying the result's `error`.
+      operationId: evaluateFromTemplate
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/EvaluationFromTemplateRequest'
+      responses:
+        '200':
+          description: The requirement was evaluated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EvaluationResult'
+        '400':
+          description: >-
+            The model does not match the template's variable schema
+            (`INVALID_TEMPLATE_INPUT`), or the template could not be
+            rendered.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: No template with the given ID exists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '422':
+          description: Invalid request body.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationError'
+        '500':
+          description: The evaluation engine could not run the requirement.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EvaluationResult'
+        '503':
+          description: >-
+            DVA Processing could not be reached (`EVALUATION_UNAVAILABLE`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
   /vla/from-templates:
     post:
       tags: [VLA]
       summary: Create a VLA from templates
       description: >-
         Creates a VLA by rendering a list of VLA templates with supplied
         models.
-        Each entry in `qualityTemplates` is rendered and the resulting quality
+        Each entry in `qualityTemplates` is checked as
+        `POST /template/{id}/validate` would check it – the model must match
+        the template's variable schema, the template must render, and DVA
+        Processing must accept the rendered logic – and the resulting quality
         requirements are merged into the VLA’s `quality` array before
-        persistence.
+        persistence. If any entry fails, nothing is persisted.
       operationId: createVLAFromTemplates
       requestBody:
         required: true
@@ -419,7 +574,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/Id'
         '400':
-          description: Failed to render one of the templates.
+          description: >-
+            One of the requirements is invalid: its model does not match the
+            template's variable schema, the template could not be rendered,
+            or DVA Processing rejected the rendered logic. `type` is
+            `INVALID_REQUIREMENT` and `title` names the requirement and why.
           content:
             application/json:
               schema:
@@ -436,6 +595,14 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ValidationError'
+        '503':
+          description: >-
+            DVA Processing could not be reached to validate a requirement, so
+            the VLA was not created. `type` is `VALIDATION_UNAVAILABLE`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
   /livez:
     get:
       tags: [Health]
@@ -749,9 +916,17 @@ components:
                 enum: [user, assistant]
               content:
                 type: string
+                maxLength: 8000
         currentTemplate:
           type: object
           additionalProperties: true
+        proposal:
+          description: >-
+            The assistant's previous proposal, so that a follow-up request
+            can have it adjusted rather than regenerated from scratch.
+          type: object
+          nullable: true
+          additionalProperties: true
     AssistantResponse:
       type: object
       required: [message]
@@ -764,11 +939,168 @@ components:
             - $ref: '#/components/schemas/TemplateCreate'
           nullable: true
         examples:
+          description: >-
+            Example input documents, as `passing` and `failing` arrays, that
+            the proposal is tested with.
+          type: object
+          nullable: true
+          additionalProperties: true
+        exampleModel:
+          description: The variable values the examples were written for.
+          type: object
+          nullable: true
+          additionalProperties: true
+        selfTest:
+          $ref: '#/components/schemas/TemplateSelfTest'
+    TemplateSelfTest:
+      type: object
+      description: >-
+        How a proposal fared when rendered with `exampleModel` and run by DVA
+        Processing over its own examples, before being returned. A proposal
+        that failed is sent back to the assistant once with the problems, so
+        `attempts` is 2 when a correction was asked for.
+      required: [status, problems, attempts]
+      additionalProperties: false
+      properties:
+        status:
+          type: string
+          enum: [passed, failed, unavailable, skipped]
+          description: >-
+            `unavailable` when DVA Processing could not be reached, so the
+            proposal is untested; `skipped` when there was no proposal.
+        problems:
+          type: array
+          items:
+            type: string
+        attempts:
+          type: integer
+          minimum: 1
+          maximum: 2
+    AssistantVLARequest:
+      type: object
+      required: [message]
+      additionalProperties: false
+      properties:
+        message:
+          type: string
+          minLength: 1
+          maxLength: 4000
+        conversation:
+          type: array
+          maxItems: 20
+          items:
+            type: object
+            required: [role, content]
+            additionalProperties: false
+            properties:
+              role:
+                type: string
+                enum: [user, assistant]
+              content:
+                type: string
+                maxLength: 8000
+        builderContext:
+          $ref: '#/components/schemas/BuilderContext'
+    BuilderContext:
+      type: object
+      additionalProperties: false
+      properties:
+        metadata:
+          type: object
+          additionalProperties: true
+        sampleData:
+          nullable: true
+        selectedPath:
+          type: string
+          nullable: true
+        fragments:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        draft:
+          description: >-
+            The assistant's previous draft (requirements and missing
+            templates), so that a follow-up such as a recheck after creating
+            templates can complete it rather than start over.
           type: object
           nullable: true
           additionalProperties: true
+    AssistantVLAResponse:
+      type: object
+      required: [message, requirements, missingTemplates]
+      additionalProperties: false
+      properties:
+        message:
+          type: string
+        metadata:
+          type: object
+          nullable: true
+          additionalProperties: true
+        requirements:
+          type: array
+          items:
+            type: object
+            required: [templateId, model, reason]
+            additionalProperties: false
+            properties:
+              templateId:
+                type: string
+                format: uuid
+              model:
+                type: object
+                additionalProperties: true
+              reason:
+                type: string
+        missingTemplates:
+          description: >-
+            One entry per template the author still has to create before the
+            draft can cover every requested rule.
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+            properties:
+              name:
+                type: string
+                description: Short title for the template to create.
+              reason:
+                type: string
+                description: >-
+                  The rule the template must express, precise enough to
+                  write the template from.
+              templateId:
+                type: string
+                description: >-
+                  Set when a catalog template was chosen but could not be
+                  filled in completely.
     QualityEngine:
       $ref: ./components.yaml#/schemas/QualityEngine
+    EvaluationResult:
+      $ref: ./components.yaml#/schemas/EvaluationResult
+    VLAEvaluationRequest:
+      type: object
+      description: The sample data to try a VLA out on.
+      required: [data]
+      additionalProperties: false
+      properties:
+        data:
+          description: The sample data to run the VLA's requirements over.
+    EvaluationFromTemplateRequest:
+      type: object
+      description: >-
+        The same request as DVA Processing's `/evaluate/from-template`,
+        with the DVA's `...ID` spelling.
+      required: [templateID, templateModel, data]
+      additionalProperties: false
+      properties:
+        templateID:
+          type: string
+          format: uuid
+        templateModel:
+          $ref: '#/components/schemas/TemplateModel'
+        data:
+          description: The sample data to run the requirement over.
     Health:
       $ref: ./components.yaml#/schemas/Health
     CriterionType: