genai-service.yaml

openapi: 3.0.3
info:
  title: AI Event Concepter - GenAI Service
  description: |
    GenAI Service for the AI Event Concepter platform. Handles AI-powered content generation,
    document processing, RAG pipeline, and intelligent event concept development.
    
    This service provides:
    - Document ingestion and processing (PDF, Word, text files)
    - RAG (Retrieval-Augmented Generation) pipeline using LangChain + Weaviate
    - Interactive chat interface for concept development
    - AI-powered content generation (themes, agendas, speaker suggestions)
    - Context-aware recommendations based on uploaded documents
  version: 1.0.0
  contact:
    name: AI Event Concepter Team
    email: ge56jal@mytum.de
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:8083
    description: Development server (GenAI Service)

paths:
  /health:
    get:
      operationId: getGenAIServiceHealth
      summary: Health check
      description: Check if the GenAI Service is running
      tags:
        - Health
      x-openapi-router-controller: controllers.health_controller
      security: []
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "UP"
                  timestamp:
                    type: string
                    format: date-time
                  service:
                    type: string
                    example: "genai-service"
                  models:
                    type: object
                    properties:
                      llm:
                        type: string
                        example: "gpt-4"
                      embedding:
                        type: string
                        example: "text-embedding-ada-002"
                  vectorStore:
                    type: object
                    properties:
                      status:
                        type: string
                        example: "connected"
                      collections:
                        type: integer

  /api/genai/chat/initialize:
    post:
      operationId: initializeChatForConcept
      summary: Initialize chat for new concept
      description: Create the first welcome message when a user creates a new concept, personalized with user and concept details
      tags:
        - Chat Interface
      x-openapi-router-controller: controllers.chat_controller
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - conceptId
                - userId
              properties:
                conceptId:
                  type: string
                  format: uuid
                  description: The newly created concept ID
                userId:
                  type: string
                  format: uuid
                  description: User ID for personalization
                conceptTitle:
                  type: string
                  example: "Tech Innovation Summit 2024"
                userPreferences:
                  $ref: '#/components/schemas/UserPreferences'
      responses:
        '200':
          description: Welcome message generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Hi John! I'm excited to help you develop your 'Tech Innovation Summit 2024' concept. Based on your preferences for hybrid events in the technology sector, I can suggest speakers, create agendas, and help refine your event. What would you like to work on first?"
                  suggestions:
                    type: array
                    items:
                      type: string
                    example:
                      - "Generate an initial agenda"
                      - "Suggest keynote speakers"
                      - "Upload relevant documents"
                      - "Define target audience"
                  conversationId:
                    type: string
                    format: uuid
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/genai/chat:
    post:
      operationId: chatWithAIAssistant
      summary: Chat with AI assistant
      description: Send a message to the AI assistant for concept development and receive intelligent responses with optional concept suggestions
      tags:
        - Chat Interface
      x-openapi-router-controller: controllers.chat_controller
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
      responses:
        '200':
          description: AI response generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/genai/documents:
    post:
      operationId: uploadAndProcessDocuments
      summary: Upload and process documents
      description: Upload documents for AI analysis and RAG processing
      tags:
        - Document Processing
      x-openapi-router-controller: controllers.document_controller
      security:
        - bearerAuth: []
      parameters:
        - name: conceptId
          in: query
          required: true
          description: Associated concept ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - files
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Documents to upload (PDF, DOC, DOCX, TXT)
      responses:
        '200':
          description: Documents uploaded and processing started
          content:
            application/json:
              schema:
                type: object
                properties:
                  processedDocuments:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProcessedDocument'
        '400':
          description: Invalid file format or request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/genai/concepts/{conceptId}/documents:
    get:
      operationId: getDocumentsForConcept
      summary: Get documents for concept
      description: Retrieve all processed documents associated with a concept
      tags:
        - Document Processing
      x-openapi-router-controller: controllers.document_controller
      security:
        - bearerAuth: []
      parameters:
        - name: conceptId
          in: path
          required: true
          description: Concept ID
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          description: Filter by processing status
          schema:
            type: string
            enum: [PROCESSING, COMPLETED, FAILED]
      responses:
        '200':
          description: Documents retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  documents:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProcessedDocument'
                  totalCount:
                    type: integer
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/genai/documents/{documentId}:
    delete:
      operationId: deleteDocument
      summary: Delete document
      description: Delete a specific document from a concept and remove it from the knowledge base
      tags:
        - Document Processing
      x-openapi-router-controller: controllers.document_controller
      security:
        - bearerAuth: []
      parameters:
        - name: documentId
          in: path
          required: true
          description: Document ID to delete
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Document deleted successfully
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Document not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden - not document owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    ChatRequest:
      type: object
      required:
        - message
        - concept
      properties:
        message:
          type: string
          example: "Can you suggest some innovative workshop formats for our tech summit?"
        concept:
          type: object
          description: The complete concept object for context
          properties:
            id:
              type: string
              format: uuid
            title:
              type: string
            description:
              type: string
            status:
              type: string
              enum: [DRAFT, IN_PROGRESS, COMPLETED, ARCHIVED]
            eventDetails:
              type: object
            agenda:
              type: array
              items:
                type: object
            speakers:
              type: array
              items:
                type: object

        conversationId:
          type: string
          format: uuid
          description: Conversation thread ID
        userPreferences:
          $ref: '#/components/schemas/UserPreferences'
          description: User preferences to personalize AI responses
        context:
          type: object
          properties:
            previousMessages:
              type: array
              items:
                type: object
                properties:
                  role:
                    type: string
                    enum: [user, assistant]
                  content:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
            includeDocuments:
              type: boolean
              default: true
              description: Include document context in response
            maxTokens:
              type: integer
              default: 1000
              minimum: 100
              maximum: 4000

    ChatResponse:
      type: object
      properties:
        response:
          type: string
          description: AI assistant response
        suggestions:
          type: array
          items:
            type: string
          description: Follow-up suggestions
        followUpQuestions:
          type: array
          items:
            type: string
          description: Recommended questions to ask next
        conceptSuggestion:
          type: object
          description: "Complete concept suggestion that user can accept"
          properties:
            title:
              type: string
            description:
              type: string
            eventDetails:
              type: object
              properties:
                theme:
                  type: string
                format:
                  type: string
                  enum: [PHYSICAL, VIRTUAL, HYBRID]
                capacity:
                  type: integer
                duration:
                  type: string
                startDate:
                  type: string
                  format: date
                endDate:
                  type: string
                  format: date
                targetAudience:
                  type: string
                objectives:
                  type: array
                  items:
                    type: string
                location:
                  type: string
            agenda:
              type: array
              items:
                type: object
                properties:
                  time:
                    type: string
                  title:
                    type: string
                  description:
                    type: string
                  type:
                    type: string
                    enum: [KEYNOTE, WORKSHOP, PANEL, NETWORKING, BREAK, LUNCH]
                  speaker:
                    type: string
                  duration:
                    type: integer
            speakers:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  expertise:
                    type: string
                  suggestedTopic:
                    type: string
                  bio:
                    type: string
            pricing:
              type: object
              properties:
                currency:
                  type: string
                earlyBird:
                  type: number
                regular:
                  type: number
                vip:
                  type: number
                student:
                  type: number
                group:
                  type: number
            notes:
              type: string
            reasoning:
              type: string
            confidence:
              type: number
        conceptUpdates:
          type: object
          description: Suggested partial updates to the existing concept
          properties:
            suggestions:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  currentValue:
                    type: string
                  suggestedValue:
                    type: string
                  reasoning:
                    type: string
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
          description: Document sources used in response
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: Confidence score for the response
        tokens:
          type: object
          properties:
            prompt:
              type: integer
            response:
              type: integer
            total:
              type: integer

    ProcessedDocument:
      type: object
      properties:
        id:
          type: string
          format: uuid
        filename:
          type: string
        type:
          type: string
          enum: [INDUSTRY_REPORT, BRAND_DECK, PAST_EVENT_DEBRIEF, GUIDELINES, OTHER]
        status:
          type: string
          enum: [PROCESSING, COMPLETED, FAILED]
        s3Location:
          type: string
          description: S3 bucket path where the document is stored
          example: "s3://concepter-documents/user123/doc456.pdf"
        uploadedAt:
          type: string
          format: date-time
        processedAt:
          type: string
          format: date-time

    Source:
      type: object
      properties:
        documentId:
          type: string
          format: uuid
        filename:
          type: string
        pageNumber:
          type: integer
        section:
          type: string
        confidence:
          type: number

    UserPreferences:
      type: object
      properties:
        preferredEventFormat:
          type: string
          enum: [PHYSICAL, VIRTUAL, HYBRID]
          example: "HYBRID"
        industry:
          type: string
          example: "Technology"
        language:
          type: string
          example: "en"
        timezone:
          type: string
          example: "Europe/Berlin"

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: "VALIDATION_ERROR"
        message:
          type: string
          example: "Invalid input data provided"
        timestamp:
          type: string
          format: date-time
        path:
          type: string
          example: "/api/users/profile"
        status:
          type: integer
          example: 400
        details:
          type: array
          items:
            type: string
          example: ["firstName must not be blank"]

tags:
  - name: Health
    description: Health check and service status
  - name: Chat Interface
    description: Interactive AI chat for concept development
  - name: Document Processing
    description: Document upload, processing, and RAG integration