{
    _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
                }
            }
        }
    }
    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_event {
        "2.11": {
            description: "Return the last 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 latest iteration to bring debug image from. If not specified then the latest reported image is retrieved"
                        type: integer
                    }
                }
            }
            response {
                type: object
                properties {
                    event {
                        description: "The latest debug image for the specifed iteration"
                        type: object
                    }
                }
            }
        }
    }
    get_debug_image_iterations {
        "2.11": {
            description: "Return the min and max iterations for which valid urls are present"
            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
                    }
                }
            }
            response {
                type: object
                properties {
                    min_iteration {
                        description: "Mininal iteration for which a non recycled image exists"
                        type: integer
                    }
                    max_iteration {
                        description: "Maximal iteration for which an image was reported"
                        type: integer
                    }
                }
            }
        }
    }
    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)"
                    }
                }
            }
        }
    }
}