gateway/openapi-schema.yaml

openapi: 3.1.0
info:
  title: Adaptive Model Gateway
  description: >
    Routes chat turns to a multi-adapter language model on Hugging Face and returns
    a structured UI spec alongside the text response. Paste this into the ChatGPT
    Action editor and set the server URL to your deployed gateway.
  version: 1.0.0

servers:
  - url: https://joduor-adaptive-model-gateway.hf.space

paths:
  /generate:
    post:
      operationId: generate
      summary: Run the adaptive model for the current conversation turn.
      description: >
        Sends the full conversation history to the adaptive model.
        Selects a LoRA adapter (support / analytics / form) and returns
        a prose response plus an optional ui_spec.
        When ui_spec is present, render ui_markdown verbatim in your reply.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - messages
              properties:
                messages:
                  type: array
                  description: Full conversation history, oldest first.
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum: [user, assistant, system]
                      content:
                        type: string
                mode:
                  type: string
                  enum: [support, analytics, form]
                  description: >
                    Optional explicit adapter override.
                    Omit to let the gateway choose via heuristic routing.
      responses:
        "200":
          description: Successful generation
          content:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
                    description: Plain-text model response.
                  ui_spec:
                    type: object
                    nullable: true
                    description: >
                      Structured component specification emitted by the model.
                      null when the turn needs no interactive UI.
                    properties:
                      component:
                        type: string
                        enum: [form, chart, card, table]
                      props:
                        type: object
                        additionalProperties: true
                  ui_markdown:
                    type: string
                    nullable: true
                    description: >
                      Markdown rendering of ui_spec for use in plain-text chat.
                      Include this verbatim in your reply when ui_spec is present.
                  adapter:
                    type: string
                    description: Which adapter handled this turn.
        "500":
          description: Gateway or upstream model error
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string

  /health:
    get:
      operationId: health
      summary: Health check
      responses:
        "200":
          description: Gateway is running
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  endpoint_configured:
                    type: boolean