openapi: 3.1.0
info:
  title: AIDidact API
  version: 1.0.0
  description: API contract for the AIDidact AI-powered microlearning ecosystem.
servers:
  - url: https://api.aididact.example.com
paths:
  /v1/auth/register:
    post:
      summary: Register a learner
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterLearnerRequest'
      responses:
        '201':
          description: Registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LearnerRegistrationResponse'
  /v1/learners/{learnerId}/profile:
    get:
      summary: Get learner profile
      parameters:
        - $ref: '#/components/parameters/LearnerId'
      responses:
        '200':
          description: Learner profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LearnerProfile'
    patch:
      summary: Update learner goals or preferences
      parameters:
        - $ref: '#/components/parameters/LearnerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLearnerProfileRequest'
      responses:
        '200':
          description: Updated
  /v1/learners/{learnerId}/diagnostic-assessment:
    post:
      summary: Submit readiness assessment
      parameters:
        - $ref: '#/components/parameters/LearnerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiagnosticSubmission'
      responses:
        '202':
          description: Accepted
  /v1/modules:
    get:
      summary: List modules
      responses:
        '200':
          description: Module list
  /v1/modules/{moduleId}:
    get:
      summary: Get module detail
      parameters:
        - $ref: '#/components/parameters/ModuleId'
      responses:
        '200':
          description: Module detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleDetail'
  /v1/learners/{learnerId}/recommendations:
    get:
      summary: Get ranked module recommendations
      parameters:
        - $ref: '#/components/parameters/LearnerId'
      responses:
        '200':
          description: Recommendations
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecommendationItem'
  /v1/enrollments:
    post:
      summary: Enroll learner in module
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [learnerId, moduleId]
              properties:
                learnerId:
                  type: string
                  format: uuid
                moduleId:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Enrolled
  /v1/interactions:
    post:
      summary: Ingest interaction event
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InteractionEvent'
      responses:
        '202':
          description: Accepted
  /v1/assessments/{assessmentId}/attempts:
    post:
      summary: Create unique assessment attempt
      parameters:
        - $ref: '#/components/parameters/AssessmentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [learnerId]
              properties:
                learnerId:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Attempt created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssessmentAttempt'
  /v1/assessments/attempts/{attemptId}/responses:
    post:
      summary: Submit responses
      parameters:
        - $ref: '#/components/parameters/AttemptId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssessmentResponseSubmission'
      responses:
        '202':
          description: Accepted for grading
  /v1/assessments/attempts/{attemptId}:
    get:
      summary: Get assessment result
      parameters:
        - $ref: '#/components/parameters/AttemptId'
      responses:
        '200':
          description: Result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssessmentAttemptResult'
  /v1/learners/{learnerId}/dashboard:
    get:
      summary: Get learner dashboard
      parameters:
        - $ref: '#/components/parameters/LearnerId'
      responses:
        '200':
          description: Dashboard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LearnerDashboard'
components:
  parameters:
    LearnerId:
      in: path
      name: learnerId
      required: true
      schema:
        type: string
        format: uuid
    ModuleId:
      in: path
      name: moduleId
      required: true
      schema:
        type: string
        format: uuid
    AssessmentId:
      in: path
      name: assessmentId
      required: true
      schema:
        type: string
        format: uuid
    AttemptId:
      in: path
      name: attemptId
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    RegisterLearnerRequest:
      type: object
      required: [email, firstName, lastName, timezone, educationalLevel, goals, priorLearning]
      properties:
        email:
          type: string
          format: email
        firstName:
          type: string
        lastName:
          type: string
        timezone:
          type: string
        educationalLevel:
          type: string
        priorLearning:
          type: array
          items:
            $ref: '#/components/schemas/PriorLearningItem'
        goals:
          type: array
          items:
            $ref: '#/components/schemas/LearnerGoal'
        preferences:
          $ref: '#/components/schemas/LearnerPreferences'
    LearnerRegistrationResponse:
      type: object
      properties:
        learnerId:
          type: string
          format: uuid
        nextStep:
          type: string
    PriorLearningItem:
      type: object
      properties:
        learningType:
          type: string
          enum: [formal, non_formal, informal]
        title:
          type: string
        provider:
          type: string
        description:
          type: string
    LearnerGoal:
      type: object
      properties:
        goalHorizon:
          type: string
          enum: [short_term, long_term]
        goalText:
          type: string
        targetDate:
          type: string
          format: date
    LearnerPreferences:
      type: object
      properties:
        preferredModalities:
          type: array
          items:
            type: string
        preferredSessionLengthMinutes:
          type: integer
    DiagnosticSubmission:
      type: object
      properties:
        responses:
          type: array
          items:
            type: object
            additionalProperties: true
    LearnerProfile:
      type: object
      properties:
        learnerId:
          type: string
          format: uuid
        readinessLevel:
          type: string
        readinessScore:
          type: number
        masteryMap:
          type: object
          additionalProperties: true
    UpdateLearnerProfileRequest:
      type: object
      properties:
        goals:
          type: array
          items:
            $ref: '#/components/schemas/LearnerGoal'
        preferences:
          $ref: '#/components/schemas/LearnerPreferences'
    ModuleDetail:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
        objectives:
          type: array
          items:
            type: object
            additionalProperties: true
        units:
          type: array
          items:
            type: object
            additionalProperties: true
        completionCriteria:
          type: object
          additionalProperties: true
    RecommendationItem:
      type: object
      properties:
        moduleId:
          type: string
          format: uuid
        rank:
          type: integer
        score:
          type: number
        reasons:
          type: array
          items:
            type: string
    InteractionEvent:
      type: object
      properties:
        learnerId:
          type: string
          format: uuid
        moduleId:
          type: string
          format: uuid
        unitId:
          type: string
          format: uuid
        activityId:
          type: string
          format: uuid
        eventType:
          type: string
        eventTimestamp:
          type: string
          format: date-time
        durationMs:
          type: integer
        payload:
          type: object
          additionalProperties: true
    AssessmentAttempt:
      type: object
      properties:
        attemptId:
          type: string
          format: uuid
        assessmentId:
          type: string
          format: uuid
        timeLimitMinutes:
          type: integer
        items:
          type: array
          items:
            type: object
            additionalProperties: true
    AssessmentResponseSubmission:
      type: object
      properties:
        responses:
          type: array
          items:
            type: object
            additionalProperties: true
    AssessmentAttemptResult:
      type: object
      properties:
        attemptId:
          type: string
          format: uuid
        score:
          type: number
        passStatus:
          type: string
        integrityStatus:
          type: string
        humanReviewRequired:
          type: boolean
    LearnerDashboard:
      type: object
      properties:
        learnerId:
          type: string
          format: uuid
        timeOnTaskMinutes7d:
          type: number
        dropoutRisk:
          type: number
        successProbability:
          type: number
        adaptiveFeedback:
          type: array
          items:
            type: string