{
    _description : "Provides an API for running tasks to report events collected by the system."
    _definitions {
        metrics_scalar_event {
            description: "Used for reporting scalar metrics during training task"
            type: object
            required: [ task, type ]
            properties {
                timestamp {
                    description: "Epoch milliseconds UTC, will be set by the server if not set."
                    type: number
                }
                type {
                    description: "training_stats_vector"
                    const: "training_stats_scalar"
                }
                task {
                    description: "Task ID (required)"
                    type: string
                }
                iter {
                    description: "Iteration"
                    type: integer
                }
                metric  {
                    description: "Metric name, e.g. 'count', 'loss', 'accuracy'"
                    type: string
                }
                variant {
                    description: "E.g. 'class_1', 'total', 'average"
                    type: string
                }
                value {
                    description: ""
                    type: number
                }
            }
        }
        metrics_vector_event {
            description: "Used for reporting vector metrics during training task"
            type: object
            required: [ task ]
            properties {
                timestamp {
                    description: "Epoch milliseconds UTC, will be set by the server if not set."
                    type: number
                }
                type {
                    description: "training_stats_vector"
                    const: "training_stats_vector"
                }
                task {
                    description: "Task ID (required)"
                    type: string
                }
                iter {
                    description: "Iteration"
                    type: integer
                }
                metric {
                    description: "Metric name, e.g. 'count', 'loss', 'accuracy'"
                    type: string
                }
                variant {
                    description: "E.g. 'class_1', 'total', 'average"
                    type: string
                }
                values {
                    description: "vector of float values"
                    type: array
                    items { type: number }
                }
            }
        }
        metrics_image_event {
            description: "An image or video was dumped to storage for debugging"
            type: object
            required: [ task, type ]
            properties {
                timestamp {
                    description: "Epoch milliseconds UTC, will be set by the server if not set."
                    type: number
                }
                type {
                    description: ""
                    const: "training_debug_image"
                }
                task {
                    description: "Task ID (required)"
                    type: string
                }
                iter {
                    description: "Iteration"
                    type: integer
                }
                metric {
                    description: "Metric name, e.g. 'count', 'loss', 'accuracy'"
                    type: string
                }
                variant {
                    description: "E.g. 'class_1', 'total', 'average"
                    type: string
                }
                key {
                    description: "File key"
                    type: string
                }
                url {
                    description: "File URL"
                    type: string
                }
            }
        }
        metrics_plot_event {
            description: """ An entire plot (not single datapoint) and it's layout.
            Used for plotting ROC curves, confidence matrices, etc. when evaluating the net."""
            type: object
            required: [ task, type ]
            properties {
                timestamp {
                    description: "Epoch milliseconds UTC, will be set by the server if not set."
                    type: number
                }
                type {
                    description: "'plot'"
                    const: "plot"
                }
                task {
                    description: "Task ID (required)"
                    type: string
                }
                iter {
                    description: "Iteration"
                    type: integer
                }
                metric {
                    description: "Metric name, e.g. 'count', 'loss', 'accuracy'"
                    type: string
                }
                variant {
                    description: "E.g. 'class_1', 'total', 'average"
                    type: string
                }
                plot_str {
                    description: """An entire plot (not single datapoint) and it's layout.
                    Used for plotting ROC curves, confidence matrices, etc. when evaluating the net.
                    """
                    type: string
                }
                skip_validation {
                    description: "If set then plot_str is not checked for a valid json. The default is False"
                    type: boolean
                }
            }
        }
        scalar_key_enum {
            type: string
            enum: [
                iter
                timestamp
                iso_time
            ]
        }
        log_level_enum {
            type: string
            enum: [
                notset
                debug
                verbose
                info
                warn
                warning
                error
                fatal
                critical
            ]
        }
        event_type_enum {
            type: string
            enum: [
                training_stats_scalar
                training_stats_vector
                training_debug_image
                plot
                log
            ]
        }
        task_metric {
            type: object
            required: [task, metric]
            properties {
                task {
                    description: "Task ID"
                    type: string
                }
                metric {
                    description: "Metric name"
                    type: string
                }
            }
        }
        task_log_event {
            description: """A log event associated with a task."""
            type: object
            required: [ task, type ]
            properties {
                timestamp {
                    description: "Epoch milliseconds UTC, will be set by the server if not set."
                    type: number
                }
                type {
                    description: "'log'"
                    const: "log"
                }
                task {
                    description: "Task ID (required)"
                    type: string
                }
                level {
                    description: "Log level."
                    "$ref": "#/definitions/log_level_enum"
                }
                worker {
                    description: "Name of machine running the task."
                    type: string
                }
                msg {
                    description: "Log message."
                    type: string
                }
            }
        }
        debug_image_sample_reposnse {
            type: object
            properties {
                scroll_id {
                    type: string
                    description: "Scroll ID to pass to the next calls to get_debug_image_sample or next_debug_image_sample"
                }
                event {
                    type: object
                    description: "Debug image event"
                }
                min_iteration {
                    type: integer
                    description: "minimal valid iteration for the variant"
                }
                max_iteration {
                    type: integer
                    description: "maximal valid iteration for the variant"
                }
            }
        }
    }
    add {
        "2.1" {
            description: "Adds a single event"
            request {
                type: object
                anyOf: [
                    { "$ref": "#/definitions/metrics_scalar_event" }
                    { "$ref": "#/definitions/metrics_vector_event" }
                    { "$ref": "#/definitions/metrics_image_event" }
                    { "$ref": "#/definitions/metrics_plot_event" }
                    { "$ref": "#/definitions/task_log_event" }
                ]
            }
            response {
                type: object
                additionalProperties: true
            }
        }
    }
    add_batch {
        "2.1" {
            description: "Adds a batch of events in a single call (json-lines format, stream-friendly)"
            batch_request: {
                action: add
                version: 1.5
            }
            response {
                type: object
                properties {
                    added { type: integer }
                    errors { type: integer }
                    errors_info { type: object }
                }
            }
        }
    }
    delete_for_task {
        "2.1" {
            description: "Delete all task event. *This cannot be undone!*"
            request {
                type: object
                required: [
                    task
                ]
                properties {
                    task {
                        type: string
                        description: "Task ID"
                    }
                    allow_locked {
                        type: boolean
                        description: "Allow deleting events even if the task is locked"
                        default: false
                    }
                }
            }
            response {
                type: object
                properties {
                    deleted {
                        type: boolean
                        description: "Number of deleted events"
                    }
                }
            }
        }
    }
    debug_images {
        "2.1" {
            description: "Get all debug images of a task"
            request {
                type: object
                required: [
                    task
                ]
                properties {
                    task {
                        type: string
                        description: "Task ID"
                    }
                    iters {
                        type: integer
                        description: "Max number of latest iterations for which to return debug images"
                    }
                    scroll_id {
                        type: string
                        description: "Scroll ID of previous call (used for getting more results)"
                    }
                }
            }
            response {
                type: object
                properties {
                    task {
                        type: string
                        description: "Task ID"
                    }
                    images {
                        type: array
                        items { type: object }
                        description: "Images list"
                    }
                    returned {
                        type: integer
                        description: "Number of results returned"
                    }
                    total {
                        type: number
                        description: "Total number of results available for this query"
                    }
                    scroll_id {
                        type: string
                        description: "Scroll ID for getting more results"
                    }
                }
            }
        }
        "2.7" {
            description: "Get the debug image events for the requested amount of iterations per each task's metric"
            request {
                type: object
                required: [
                    metrics
                ]
                properties {
                    metrics {
                        type: array
                        items { "$ref": "#/definitions/task_metric" }
                        description: "List metrics for which the envents will be retreived"
                    }
                    iters {
                        type: integer
                        description: "Max number of latest iterations for which to return debug images"
                    }
                    navigate_earlier {
                        type: boolean
                        description: "If set then events are retreived from latest iterations to earliest ones. Otherwise from earliest iterations to the latest. The default is True"
                    }
                    refresh {
                        type: boolean
                        description: "If set then scroll will be moved to the latest iterations. The default is False"
                    }
                    scroll_id {
                        type: string
                        description: "Scroll ID of previous call (used for getting more results)"
                    }
                }
            }
            response {
                type: object
                properties {
                    metrics {
                        type: array
                        items: { type: object }
                        description: "Debug image events grouped by task metrics and iterations"
                    }
                    scroll_id {
                        type: string
                        description: "Scroll ID for getting more results"
                    }
                }
            }
        }
    }
    get_debug_image_sample {
        "2.12": {
            description: "Return the debug image per metric and variant for the provided iteration"
            request {
                type: object
                required: [task, metric, variant]
                properties {
                    task {
                        description: "Task ID"
                        type: string
                    }
                    metric {
                        description: "Metric name"
                        type: string
                    }
                    variant {
                        description: "Metric variant"
                        type: string
                    }
                    iteration {
                        description: "The iteration to bring debug image from. If not specified then the latest reported image is retrieved"
                        type: integer
                    }
                    refresh {
                        description: "If set then scroll state will be refreshed to reflect the latest changes in the debug images"
                        type: boolean
                    }
                    scroll_id {
                        type: string
                        description: "Scroll ID from the previous call to get_debug_image_sample or empty"
                    }
                }
            }
            response {"$ref": "#/definitions/debug_image_sample_reposnse"}
        }
    }
    next_debug_image_sample {
        "2.12": {
            description: "Get the image for the next variant for the same iteration or for the next iteration"
            request {
                type: object
                required: [task, scroll_id]
                properties {
                    task {
                        description: "Task ID"
                        type: string
                    }
                    scroll_id {
                        type: string
                        description: "Scroll ID from the previous call to get_debug_image_sample"
                    }
                    navigate_earlier {
                        type: boolean
                        description: """If set then get the either previous variant event from the current iteration or (if does not exist) the last variant event from the previous iteration.
                        Otherwise next variant event from the current iteration or first variant event from the next iteration"""
                    }
                }
            }
            response {"$ref": "#/definitions/debug_image_sample_reposnse"}
        }
    }
    get_task_metrics{
        "2.7": {
            description: "For each task, get a list of metrics for which the requested event type was reported"
            request {
                type: object
                required: [
                    tasks
                ]
                properties {
                    tasks {
                        type: array
                        items { type: string }
                        description: "Task IDs"
                    }
                    event_type {
                        "description": "Event type"
                        "$ref": "#/definitions/event_type_enum"
                    }
                }
            }
            response {
                type: object
                properties {
                    metrics {
                        type: array
                        items { type: object }
                        description: "List of task with their metrics"
                    }
                }
            }
        }
    }
    get_task_log {
        "1.5" {
            description: "Get all 'log' events for this task"
            request {
                type: object
                required: [
                    task
                ]
                properties {
                    task {
                        type: string
                        description: "Task ID"
                    }
                    order {
                        type: string
                        description: "Timestamp order in which log events will be returned (defaults to ascending)"
                        enum: [
                            asc
                            desc
                        ]
                    }
                    scroll_id {
                        type: string
                        description: ""
                    }
                    batch_size {
                        type: integer
                        description: ""
                    }
                }
            }
            response {
                type: object
                properties {
                    events {
                        type: array
                        # TODO: items: log event
                        items { type: object }
                    }
                    returned { type: integer }
                    total { type: integer }
                    scroll_id { type: string }
                }
            }
        }
        "1.7" {
            description: "Get all 'log' events for this task"
            request {
                type: object
                required: [
                    task
                ]
                properties {
                    task {
                        type: string
                        description: "Task ID"
                    }
                    order {
                        type: string
                        description: "Timestamp order in which log events will be returned (defaults to ascending)"
                        enum: [
                            asc
                            desc
                        ]
                    }
                    from {
                        type: string
                        description: "Where will the log entries be taken from (default to the head of the log)"
                        enum: [
                            head
                            tail
                        ]
                    }
                    scroll_id {
                        type: string
                        description: ""
                    }
                    batch_size {
                        type: integer
                        description: ""
                    }
                }
            }
            response {
                type: object
                properties {
                    events {
                        type: array
                        # TODO: items: log event
                        items { type: object }
                        description: "Log items list"
                    }
                    returned {
                        type: integer
                        description: "Number of results returned"
                    }
                    total {
                        type: number
                        description: "Total number of results available for this query"
                    }
                    scroll_id {
                        type: string
                        description: "Scroll ID for getting more results"
                    }
                }
            }
        }
        "2.9" {
            description: "Get 'log' events for this task"
            request {
                type: object
                required: [
                    task
                ]
                properties {
                    task {
                        type: string
                        description: "Task ID"
                    }
                    batch_size {
                        type: integer
                        description: "The amount of log events to return"
                    }
                    navigate_earlier {
                        type: boolean
                        description: "If set then log events are retreived from the latest to the earliest ones (in timestamp descending order, unless order='asc'). Otherwise from the earliest to the latest ones (in timestamp ascending order, unless order='desc'). The default is True"
                    }
                    from_timestamp {
                        type: number
                        description: "Epoch time in UTC ms to use as the navigation start. Optional. If not provided, reference timestamp is determined by the 'navigate_earlier' parameter (if true, reference timestamp is the last timestamp and if false, reference timestamp is the first timestamp)"
                    }
                    order {
                        type: string
                        description: "If set, changes the order in which log events are returned based on the value of 'navigate_earlier'"
                        enum: [asc, desc]
                    }
                }
            }
            response {
                type: object
                properties {
                    events {
                        type: array
                        items { type: object }
                        description: "Log items list"
                    }
                    returned {
                        type: integer
                        description: "Number of log events returned"
                    }
                    total {
                        type: number
                        description: "Total number of log events available for this query"
                    }
                }
            }
        }
    }
    get_task_events {
        "2.1" {
            description: "Scroll through task events, sorted by timestamp"
            request {
                type: object
                required: [
                    task
                ]
                properties {
                    task {
                        type: string
                        description: "Task ID"
                    }
                    order {
                        type:string
                        description: "'asc' (default) or 'desc'."
                        enum: [
                            asc
                            desc
                        ]
                    }
                    scroll_id {
                        type: string
                        description: "Pass this value on next call to get next page"
                    }
                    batch_size {
                        type: integer
                        description: "Number of events to return each time (default 500)"
                    }
                    event_type {
                        type: string
                        description: "Return only events of this type"
                    }
                }
            }
            response {
                type: object
                properties {
                    events {
                        type: array
                        items { type: object }
                        description: "Events list"
                    }
                    returned {
                        type: integer
                        description: "Number of results returned"
                    }
                    total {
                        type: number
                        description: "Total number of results available for this query"
                    }
                    scroll_id {
                        type: string
                        description: "Scroll ID for getting more results"
                    }
                }
            }
        }
    }

    download_task_log {
        "2.1" {
            description: "Get an attachment containing the task's log"
            request {
                type: object
                required: [
                    task
                ]
                properties {
                    task {
                        description: "Task ID"
                        type: string
                    }
                    line_type {
                        description: "Line format type"
                        type: string
                        enum: [
                            json
                            text
                        ]
                    }
                    line_format {
                        type: string
                        description: "Line string format. Used if the line type is 'text'"
                        default: "{asctime} {worker} {level} {msg}"
                    }
                }
            }
            response {
                type: string
            }
        }
    }
    get_task_plots {
        "2.1" {
            description: "Get all 'plot' events for this task"
            request {
                type: object
                required: [
                    task
                ]
                properties {
                    task {
                        type: string
                        description: "Task ID"
                    }
                    iters {
                        type: integer
                        description: "Max number of latest iterations for which to return debug images"
                    }
                    scroll_id {
                        type: string
                        description: "Scroll ID of previous call (used for getting more results)"
                    }
                }
            }
            response {
                type: object
                properties {
                    plots {
                        type: array
                        items {
                            type: object
                        }
                        description: "Plots list"
                    }
                    returned {
                        type: integer
                        description: "Number of results returned"
                    }
                    total {
                        type: number
                        description: "Total number of results available for this query"
                    }
                    scroll_id {
                        type: string
                        description: "Scroll ID for getting more results"
                    }
                }
            }
        }
    }
    get_multi_task_plots {
        "2.1" {
            description: "Get 'plot' events for the given tasks"
            request {
                type: object
                required: [
                    tasks
                ]
                properties {
                    tasks {
                        description: "List of task IDs"
                        type: array
                        items {
                            type: string
                            description: "Task ID"
                        }
                    }
                    iters {
                        type: integer
                        description: "Max number of latest iterations for which to return debug images"
                    }
                    scroll_id {
                        type: string
                        description: "Scroll ID of previous call (used for getting more results)"
                    }
                }
            }
            response {
                type: object
                properties {
                    plots {
                        type: object
                        description: "Plots mapping (keyed by task name)"
                    }
                    returned {
                        type: integer
                        description: "Number of results returned"
                    }
                    total {
                        type: number
                        description: "Total number of results available for this query"
                    }
                    scroll_id {
                        type: string
                        description: "Scroll ID for getting more results"
                    }
                }
            }
        }
    }
    get_vector_metrics_and_variants {
        "2.1" {
            description: ""
            request {
                type: object
                required: [
                    task
                ]
                properties {
                    task {
                        type: string
                        description: "Task ID"
                    }
                }
            }
            response {
                type: object
                properties {
                    metrics {
                        description: ""
                        type: array
                        items: { type: object }
                        # TODO: items: ???
                    }
                }
            }
        }
    }
    vector_metrics_iter_histogram {
        "2.1" {
            description: "Get histogram data of all the scalar metrics and variants in the task"
            request {
                type: object
                required: [
                    task
                    metric
                    variant
                ]
                properties {
                    task {
                        type: string
                        description: "Task ID"
                    }
                    metric {
                        type: string
                        description: ""
                    }
                    variant {
                        type: string
                        description: ""
                    }
                }
            }
            response {
                type: object
                properties {
                    images {
                        type: array
                        items {
                            type: object
                        }
                    }
                }
            }
        }
    }
    scalar_metrics_iter_histogram {
        "2.1" {
            description: "Get histogram data of all the vector metrics and variants in the task"
            request {
                type: object
                required: [
                    task
                ]
                properties {
                    task {
                        type: string
                        description: "Task ID"
                    }
                    samples {
                        description: "The amount of histogram points to return (0 to return all the points). Optional, the default value is 6000."
                        type: integer
                    }
                    key {
                        description: """
                        Histogram x axis to use:
                        iter - iteration number
                        iso_time - event time as ISO formatted string
                        timestamp - event timestamp as milliseconds since epoch
                        """
                        "$ref": "#/definitions/scalar_key_enum"
                    }
                }
            }
            response {
                type: object
                properties {
                    images {
                        type: array
                        items {
                            type: object
                        }
                    }

                }
            }
        }
    }
    multi_task_scalar_metrics_iter_histogram {
        "2.1" {
            description: "Used to compare scalar stats histogram of multiple tasks"
            request {
                type: object
                required: [
                    tasks
                ]
                properties {
                    tasks {
                        description: "List of task Task IDs. Maximum amount of tasks is 10"
                        type: array
                        items {
                            type: string
                            description: "List of task Task IDs"
                        }
                    }
                    samples {
                        description: "The amount of histogram points to return. Optional, the default value is 6000"
                        type: integer
                    }
                    key {
                        description: """
                        Histogram x axis to use:
                        iter - iteration number
                        iso_time - event time as ISO formatted string
                        timestamp - event timestamp as milliseconds since epoch
                        """
                        "$ref": "#/definitions/scalar_key_enum"
                    }
                }
            }
            response {
                type: object
                // properties {}
                additionalProperties: true
            }
        }
    }
    get_task_latest_scalar_values {
        "2.1" {
            description: "Get the tasks's latest scalar values"
            request {
                type: object
                required: [
                    task
                ]
                properties {
                    task {
                        type: string
                        description: "Task ID"
                    }
                }
            }
            response {
                type: object
                properties {
                    metrics {
                        type: array
                        items {
                            type: object
                            properties {
                                name {
                                    type: string
                                    description: "Metric name"
                                }
                                variants {
                                    type: array
                                    items {
                                        type: object
                                        properties {
                                            name {
                                                type: string
                                                description: "Variant name"
                                            }
                                            last_value {
                                                type: number
                                                description: "Last reported value"
                                            }
                                            last_100_value {
                                                type: number
                                                description: "Average of 100 last reported values"
                                            }

                                        }
                                    }
                                }
                            }
                        }
                     }
                 }
            }
        }
    }
    get_scalar_metrics_and_variants {
        "2.1" {
            description: get task scalar metrics and variants
            request {
                type: object
                required: [ task ]
                properties {
                    task {
                        description: task ID
                        type: string
                    }
                }
            }
            response {
                type: object
                properties {
                    metrics {
                        type: object
                        additionalProperties: true
                    }
                }
            }
        }
    }
    get_scalar_metric_data {
        "2.1" {
            description: "get scalar metric data for task"
            request {
                type: object
                properties {
                    task {
                        type: string
                        description: task ID
                    }
                    metric {
                        type: string
                        description: type of metric
                    }
                }
            }
            response {
                type: object
                properties {
                    events {
                        description: "task scalar metric events"
                        type: array
                        items {
                            type: object
                        }
                    }
                    returned {
                        type: integer
                        description: "amount of events returned"
                    }
                    total {
                        type: integer
                        description: "amount of events in task"
                    }
                    scroll_id {
                        type: string
                        description: "Scroll ID of previous call (used for getting more results)"
                    }
                }
            }
        }
    }
}