openapi: '3.0.3'
info:
  version: 1.0.0
  title: Twiki API
  description: API for LLM observations via Twiki
paths:
  /project:
    get:
      tags:
        - project
      summary: Get all projects
      responses:
        '200':
          description: A list of projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
    post:
      tags:
        - project
      summary: Create a new project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  pattern: '^[a-zA-Z0-9-]+$'
                  minLength: 1
                  maxLength: 255
                  example: 'My Project'
              required: ['name']
      responses:
        '201':
          description: Project created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/uuid'
                  name:
                    type: string
                    example: 'My Project'
                  created_on:
                    type: string
                    format: date-time
  /project/{projectId}:
    get:
      tags:
        - project
      summary: Get a project by ID
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
          description: The project ID
      responses:
        '200':
          description: A project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectSessions'
  /project/{projectId}/overview:
    get:
      tags:
        - project
      summary: Get an overview of a project
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
          description: The project ID
      responses:
        '200':
          description: A project overview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectOverview'

  /session:
    post:
      tags:
        - session
      summary: Create a new session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  $ref: '#/components/schemas/uuid'
                project_id:
                  $ref: '#/components/schemas/uuid'
                user:
                  type: string
                start_time:
                  type: string
                  format: date-time
                end_time:
                  type: string
                  format: date-time
              required: ['project_id', 'user', 'start_time']
      responses:
        '201':
          description: Session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
  /session/{sessionId}:
    get:
      tags:
        - session
      summary: Get a session by ID
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
          description: The session ID
      responses:
        '200':
          description: A session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionThreads'

    patch:
      tags:
        - session
      summary: Update a session by ID
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
          description: The session ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                end_time:
                  type: string
                  format: date-time
      responses:
        '200':
          description: Session updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
  /thread:
    post:
      tags:
        - thread
      summary: Create a new thread
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  $ref: '#/components/schemas/uuid'
                session_id:
                  $ref: '#/components/schemas/uuid'
                name:
                  type: string
                start_time:
                  type: string
                  format: date-time
                end_time:
                  type: string
                  format: date-time
                input:
                  type: string
                output:
                  type: string
              required: ['id', 'project_id', 'name', 'input', 'output']
      responses:
        '201':
          description: Thread created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/uuid'
  /thread/{threadId}:
    get:
      tags:
        - thread
      summary: Get a thread by ID
      parameters:
        - name: threadId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
          description: The thread ID
      responses:
        '200':
          description: A thread
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionThreads'

  /step/{stepId}:
    get:
      tags:
        - step
      summary: Get an step by ID
      parameters:
        - name: stepId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
          description: The step ID
      responses:
        '200':
          description: A step in a thread
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Step'
  /step:
    post:
      tags:
        - step
      summary: Create a new step
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  $ref: '#/components/schemas/uuid'
                thread_id:
                  $ref: '#/components/schemas/uuid'
                name:
                  type: string
                type:
                  type: string
                start_time:
                  type: string
                  format: date-time
                end_time:
                  type: string
                  format: date-time
                model_name:
                  type: string
                model_metadata:
                  type: object
                  additionalProperties: true
                input:
                  type: string
                output:
                  type: string
                input_tokens:
                  type: number
                  format: int32
                output_tokens:
                  type: number
                  format: int32
              required: ['id', 'thread_id', 'name', 'type', 'start_time']  
      responses:
        '201':
          description: Step created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Step'
components:
  schemas:
    Project:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
          pattern: '^[a-zA-Z0-9-]+$'
        created_on:
          type: string
          format: date-time
    Session:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        project_id:
          type: string
        user:
          type: string
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
    Thread:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        session_id:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        input:
          type: string
        output:
          type: string
    Step:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        run_id:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
        type:
          type: string
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        model_name:
          type: string
        model_metadata:
          type: object
          additionalProperties: true
        input_tokens:
          type: number
          format: int32
        output_tokens:
          type: number
          format: int32
    ProjectOverview:
      type: object
      properties:
        project:
          $ref: '#/components/schemas/Project'
        sessions:
          type: array
          properties:
            session_count:
              type: number
              format: int32
            average_latency:
              type: number
              format: float
            thread_count:
              type: number
              format: int32
        model_usage:
          type: array
          items:
            type: object
            properties:
              model_name:
                type: string
              date: 
                type: string
                format: date
              token_usage:
                type: number
                format: int32
              average_latency:
                type: number
                format: float
              cost:
                type: number
                format: float
    ProjectSessions:
      type: object
      properties:
        id: 
          type: string
        name:
          type: string
        created_on:
          type: string
          format: date-time
        sessions:
          type: array
          items:
            $ref: '#/components/schemas/Session'
    SessionThreads:
      type: object
      properties:
        id: 
          type: string
        name:
          type: string
        created_on:
          type: string
          format: date-time
        threads:
          type: array
          items:
            $ref: '#/components/schemas/Thread'
    ThreadSteps:
      type: object
      properties:
        id: 
          type: string
        name:
          type: string
        type:
          type: string
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        input:
          type: string
        output:
          type: string
        steps:
          type: array
          items:
            $ref: '#/components/schemas/Step'
    uuid:
      type: string
      pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
      minLength: 36
      maxLength: 36