{
    _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
                }
            }
        }
        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
                }
            }
        }
    }
    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_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.7" {
            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). Otherwise from the earliest to the latest ones (in timestamp ascending order). The default is True"
                    }
                    refresh {
                        type: boolean
                        description: "If set then scroll will be moved to the latest logs (if 'navigate_earlier' is set to True) or to the earliest (otherwise)"
                    }
                    scroll_id {
                        type: string
                        description: "Scroll ID of previous call (used for getting more results)"
                    }
                }
            }
            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"
                    }
                    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 (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 10000."
                        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"
                        type: array
                        items {
                            type: string
                            description: "List of task Task IDs"
                        }
                    }
                    samples {
                        description: "The amount of histogram points to return (0 to return all the points). Optional, the default value is 10000."
                        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)"
                    }
                }
            }
        }
    }
}