{
    _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
                }
            }
        }
        log_level_enum {
            type: string
            enum: [
                notset
                debug
                verbose
                info
                warn
                warning
                error
                fatal
                critical
            ]
        }
        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
                }
            }
        }
    }
    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."
            batch_request: {
                action: add
                version: 1.5
            }
            response {
                type: object
                properties {
                    added { type: integer }
                    errors { type: integer }
                }
            }
        }
    }
    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"
                    }
                }
            }
            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"
                    }
                }
            }
        }
    }
    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"
                    }
                }
            }
        }
    }
    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"
                    }
                }
            }
            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"
                    }
                }
            }
            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"
                        type: array
                        items {
                            type: string
                            description: "List of task Task IDs"
                        }
                    }

                }
            }
            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)"
                    }
                }
            }
        }
    }
}