swagger: "2.0"
info:
  description: This page supports description and interaction with the API currently supported by Ruler. 
  version: "1.0.0"
  title: Ruler API Specification
consumes:
  - application/json
produces:
  - application/json

basePath: /api

tags:
  - name: Project Management
    description: manage data and models
    externalDocs:
      url: none
  - name: Labelling Interaction
    description: label and create functions
  - name: Concept
    description: update concepts and tokens
  - name: GLL (Generalized Labeling Language)
    description: get GLL keys and values
  - name: Statistics
    description: evaluate model performance.

definitions:
  Condition:
    type: object
    example: {"string": "(?:(?<=\\W)|(?<=^))(terrible)(?=\\W|$)", "token_text": "terrible", "type": 0, "case_sensitive": False}
    properties:
      string: 
        type: string
      type: 
        type: integer
        enum: [0, 1, 2, 3]
        description: The type of the condition. Available types can be fetched with a get request to \keytype
      TYPE_:
        type: string
        enum: ['TOKEN','REGEXP','CONCEPT','NER']
        description: String description of the condition type
      case_sensitive: 
        type: boolean
  Instance:
    type: object
    properties:
      Connective:
        type: integer
      CONNECTIVE_:
        type: string
        description: String explanation of the connective type
      Direction:
        type: boolean
      Label:
        type: integer
      Weight:
        type: integer
      Conditions:
        type: array
        items:
          type: object
          $ref: '#/definitions/Condition'
  Tokens:
    type: array
    items:
      $ref: '#/definitions/Condition'
  Annotation:
    type: object
    example: [
                {
                    "id":85,
                    "label":0,
                    "start_offset":85,
                    "end_offset":92,
                    "text":"a while",
                    "link": None,
                    "type":"annotation"
                }
            ]
    properties:
      end_offset:
        type: integer
      start_offset:
        type: integer


# Paths supported by the server application
paths:
  /models:
    post:
      operationId: endpoints.select_model
      tags:
        - Project Management
      summary: Select a model for this project
      parameters:
        - name: config
          description: model configuration data
          required: true
          in: body
          schema:
            type: object
            properties:
              model_name:
                type: string
      responses:
        200:
          description: OK
          schema:
            type: object
    get:
      operationId: endpoints.get_models
      tags:
        - Project Management
      summary: View available Ruler models
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              type: string   

  /models/{model_name}:
    post:
      operationId: endpoints.create_new_model
      tags:
        - Project Management
      summary: Create a new Ruler model
      parameters:
        - name: model_name
          description: Name of the new model
          in: path
          type: string
          required: true
      responses:
        200:
          description: OK
          schema:
            type: object

  /datasets:
    get:
      operationId: endpoints.get_datasets
      tags:
        - Project Management
      summary: View available datasets
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              type: string
    post:
      operationId: endpoints.select_dataset
      tags:
        - Project Management
      summary: Select a dataset for this project
      parameters:
        - name: config
          description: Information on the selected dataset
          required: true
          in: body
          schema:
            type: object
            properties:
              dataset_uuid:
                type: string
      responses:
        200:
          description: OK
          schema:
            type: object

  /datasets/{dataset_uuid}:
    post:
      operationId: endpoints.post_data
      tags:
        - Project Management
      summary: Upload a new dataset
      parameters:
        - name: dataset_uuid
          description: ID for this dataset
          in: path
          type: string
          required: true
        - name: file
          in: formData
          description: file to upload and preprocess
          required: true
          type: file
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              type: string
    get:
      operationId: endpoints.get_dataset
      tags:
        - Project Management
      summary: View files in a dataset
      parameters:
        - name: dataset_uuid
          description: ID for this dataset
          in: path
          type: string
          required: true
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              type: string

  /datasets/{dataset_uuid}/status:
    get:
      operationId: endpoints.progress
      tags:
        - Project Management
      summary: get status of dataset preparation
      parameters:
        - name: dataset_uuid
          description: ID for this dataset
          in: path
          type: string
          required: true
      responses:
        200:
          description: OK
          schema:
            type: number

  /label:
    get:
      operationId: endpoints.get_labels
      tags:
        - GLL (Generalized Labeling Language)
      summary: Get pre-defined labels
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              label:
                type: object
    post:
      operationId: endpoints.post_labels
      tags:
        - Project Management
      summary: Define labels for a task
      parameters:
        - name: labels
          in: body
          required: true
          schema:
            type: object
            properties:
              label:
                type: object
      responses:
        200:
          description: OK
          schema:
            type: object

  /connective:
    get:
      operationId: endpoints.get_connective
      tags:
        - GLL (Generalized Labeling Language)
      summary: Get pre-defined connective definition
      description: Get pre-defined connective definition for AND, OR among multiple conditions
      responses:
        200:
          description: OK
          schema:
            type: object
            additionalProperties:
              type: integer

  /keytype:
    get:
      operationId: endpoints.get_keytype
      tags:
        - GLL (Generalized Labeling Language)
      summary: Get pre-defined key types
      description: Get pre-defined key types (e.g., a highlighed token is a token, concept or named entity.
      responses:
        200:
          description: OK
          schema:
            type: object
            additionalProperties:
              type: integer

  /concept:
    get:
      operationId: endpoints.get_all_concepts
      tags:
        - Concept
      summary: Get all existing concepts
      responses:
        200:
          description: OK
          schema:
            type: object
            additionalProperties:
              type: array
    post:
      operationId: endpoints.create_concept
      tags:
        - Concept
      summary: Create a concept
      parameters:
        - name: concept
          in: body
          description: Concept to create
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
                description: The name of new concept
              tokens:
                $ref: '#/definitions/Tokens'
                description: List of tokens that belong to the new concept
      responses:
        200:
          description: OK

  /concept/{cname}:
    get:
      operationId: endpoints.get_concept
      tags:
        - Concept
      summary: Get the tokens from one concept
      parameters:
        - name: cname
          in: path
          description: Name of an exisiting concept
          type: string
          required: true
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Tokens'
            description: List of tokens and their keytypes that belong to the requested concept
    put:
      operationId: endpoints.update_concept
      tags:
        - Concept
      summary: Update tokens of existing concept
      parameters:
        - name: cname
          description: Name of a concept
          in: path
          type: string
          required: true
        - name: tokens
          in: body
          description: A list of (new and existing) tokens belonging to this concept
          required: true
          schema:
            $ref: '#/definitions/Tokens'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Tokens'
            description: List of tokens and their keytypes that belong to the updated concept
    delete:
      operationId: endpoints.delete_concept
      tags:
       - Concept
      summary: Delete an existing concept
      parameters:
        - name: cname
          description: Name of an exisiting concept
          in: path
          type: string
          required: true
      responses:
        200:
          description: OK

  /interaction:
    get:
      operationId: endpoints.next_text
      tags:
        - Labelling Interaction
      summary: Get next text to label, possibly with annotations
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              text: 
                type: string
              annotations:
                type: array
                items:
                  $ref: '#/definitions/Annotation'
              index:
                type: integer
    post:
      operationId: endpoints.submit_interaction
      tags:
        - Labelling Interaction
      summary: Submit the labeled text from the user
      parameters:
        - name: interaction
          in: body
          description: Original text, annotations, and label from the interaction
          required: true
          schema:
            type: object
            properties:
              text:
                type: string
                description: The original text
                example: "pleas subscribe on me to my channel"
              annotations:
                type: array
                items: 
                  $ref: '#/definitions/Annotation'
                description: The annotations over the text
                example: 
                  - id: 6
                    label: 0
                    start_offset: 6
                    end_offset: 21
              label:
                type: integer
                description: User selected label
                example: 1
      responses:
        200:
          description: A list of LF explanation generated from user interaction
          schema:
            type: array
            items:
              $ref: '#/definitions/Instance'
    put:
      operationId: endpoints.submit_instances
      tags:
        - Labelling Interaction
      summary: Submit the user selected LF explanation
      parameters:
        - name: lf_dicts
          in: body
          description: A list of selected LF explanation
          required: true
          schema:
            type: object
            items:
              $ref: '#/definitions/Instance'
      responses:
        200:
          description: OK

  /interaction/{idx}:
    get:
      operationId: endpoints.get_interaction_idx
      tags:
        - Labelling Interaction
      summary: Get the previous interaction from history
      parameters:
        - name: idx
          in: path
          description: The index of previous interaction
          type: integer
          required: true
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              id:
                type: integer
                description: The index of this interaction
              text:
                type: string
                description: The original text
              annotations:
                type: array
                items: 
                  $ref: '#/definitions/Annotation'
              label:
                type: integer
                description: User selected labels
              lf_exp:
                type: array
                items:
                  $ref: '#/definitions/Instance'
                description: The user selected LF explanations

  /statistics:
    get:
      operationId: endpoints.get_stats
      tags:
        - Statistics
      summary: Get the current quality statistics
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              accuracy:
                type: number
                format: float
                description: Accuracy
              precision:
                type: number
                format: float
                description: Precision
              recall:
                type: number
                format: float
                description: Recall
              f1:
                type: number
                format: float
                description: F1 score
              count:
                type: integer
                description: Count of interaction rounds
  /lr_statistics:
    get:
      operationId: endpoints.get_logreg_stats
      tags:
        - Statistics
      summary: Get the current quality statistics of an LR model trained on your labels
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              precision:
                type: number
                format: float
                description: Precision
              recall:
                type: number
                format: float
                description: Recall
              f1:
                type: number
                format: float
                description: F1 score

  /labelingfunctions:
    get:
      operationId: endpoints.get_lf_stats
      tags:
        - Statistics
      summary: Get the current LF statistics
      responses:
        200:
          description: OK
          schema:
            type: object  
    put:
      operationId: endpoints.delete_lfs
      tags:
       - Statistics
      summary: Delete a previous LF
      parameters:
        - name: lf_ids
          in: body
          description: IDs of LFs to be deleted
          schema:
            type: array
            items:
              type: string
          required: true
      responses:
        204:
          description: OK
  /labelingfunctions/{lf_id}:
    get:
      operationId: endpoints.get_lf_label_examples
      tags:
        - Statistics
      summary: Get examples of text labeled by the given labeling function
      parameters:
        - name: lf_id
          in: path
          description: The ID of the labeling function 
          type: string
          required: true
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              examples:
                type: array
                items:
                  type: object
                  properties:
                    text:
                      type: string
                      description: The text of the labeled example
                    label:
                      type: integer
                      description: The label assigned by this function
                    annotations:
                      type: array
                      items: 
                        $ref: '#/definitions/Annotation'
                      description: The annotations by this function over the text
              mistakes:
                type: array
                items:
                  type: object
                  properties:
                    text:
                      type: string
                      description: The text of the erroneous label
                    label:
                      type: integer
                      description: The erroneous label assigned by this function
                    annotations:
                      type: array
                      items: 
                        $ref: '#/definitions/Annotation'
                      description: The annotations by this function over the text

  /save:
    post:
      operationId: endpoints.save_project
      tags:
        -  Project Management
      summary: Save the interactions, labeling functions, and model to disk
      responses:
        200:
          description: OK