openapi: 3.1.0
info:
  title: Voice Assistant Teaching TTS Orchestration
  version: 0.2.0
servers:
  - url: http://127.0.0.1:8000
components:
  schemas:
    NormalizeRequest:
      type: object
      required: [text, personaId]
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 5000
        personaId:
          type: string
        speed:
          type: string
          enum: [gentle, standard, bright]
          default: standard
        toneMode:
          type: string
          enum: [companion, coach, encourage, lively]
        audioFormat:
          type: string
          enum: [wav, mp3]
          default: wav
    NormalizeResponse:
      type: object
      required: [text, voice, stylePrompt, formattedText, audioFormat, metadata]
      properties:
        text:
          type: string
        voice:
          type: string
        stylePrompt:
          type: string
        formattedText:
          type: string
        audioFormat:
          type: string
        metadata:
          type: object
    TtsJob:
      type: object
      required: [id, status]
      properties:
        id:
          type: string
        status:
          type: string
          enum: [queued, processing, success, error]
        audioUrl:
          type: string
        error:
          type: object
paths:
  /v1/health:
    get:
      summary: Health check
      responses:
        '200':
          description: OK
  /v1/personas:
    get:
      summary: List teaching personas and UI options
      responses:
        '200':
          description: OK
  /v1/tts/normalize:
    post:
      summary: Build normalized payload for shared TTS capability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NormalizeRequest'
      responses:
        '200':
          description: Normalized payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NormalizeResponse'
        '400':
          description: Bad request
  /api/tts/jobs:
    post:
      summary: Same-origin proxy for creating shared TTS jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NormalizeResponse'
      responses:
        '200':
          description: TTS job response from platform API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TtsJob'
        '202':
          description: Accepted TTS job response from platform API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TtsJob'
  /api/tts/jobs/{jobId}:
    get:
      summary: Same-origin proxy for reading shared TTS job status
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: TTS job response from platform API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TtsJob'
  /api/tts/jobs/{jobId}/audio:
    get:
      summary: Same-origin proxy for reading shared TTS job audio
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Audio response from platform API
    head:
      summary: Same-origin proxy for reading shared TTS job audio metadata
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Audio metadata response from platform API