_description: "Provides support for defining Projects containing Tasks, Models and Dataset Versions."
_definitions {
    multi_field_pattern_data {
        type: object
        properties {
            pattern {
                description: "Pattern string (regex)"
                type: string
            }
            fields {
                description: "List of field names"
                type: array
                items { type: string }
            }
        }
    }
    project {
        type: object
        properties {
            id {
                description: "Project id"
                type: string
            }
            name {
                description: "Project name"
                type: string
            }
            description {
                description: "Project description"
                type: string
            }
            user {
                description: "Associated user id"
                type: string
            }
            company {
                description: "Company id"
                type: string
            }
            created {
                description: "Creation time"
                type: string
                format: "date-time"
            }
            tags {
                type: array
                description: "User-defined tags"
                items { type: string }
            }
            system_tags {
                type: array
                description: "System tags. This field is reserved for system use, please don't use it."
                items {type: string}
            }
            default_output_destination {
                description: "The default output destination URL for new tasks under this project"
                type: string
            }
            last_update {
                description: """Last project update time. Reflects the last time the project metadata was changed or a task in this project has changed status"""
                type: string
                format: "date-time"
            }
        }
    }
    stats_status_count {
        type: object
        properties {
            total_runtime {
                description: "Total run time of all tasks in project (in seconds)"
                type: integer
            }
            status_count {
                description: "Status counts"
                type: object
                properties {
                    created {
                        description: "Number of 'created' tasks in project"
                        type: integer
                    }
                    queued {
                        description: "Number of 'queued' tasks in project"
                        type: integer
                    }
                    in_progress {
                        description: "Number of 'in_progress' tasks in project"
                        type: integer
                    }
                    stopped {
                        description: "Number of 'stopped' tasks in project"
                        type: integer
                    }
                    published {
                        description: "Number of 'published' tasks in project"
                        type: integer
                    }
                    closed {
                        description: "Number of 'closed' tasks in project"
                        type: integer
                    }
                    failed {
                        description: "Number of 'failed' tasks in project"
                        type: integer
                    }
                    unknown {
                        description: "Number of 'unknown' tasks in project"
                        type: integer
                    }
                }
            }
        }
    }
    stats  {
        type: object
        properties {
            active {
                description: "Stats for active tasks"
                "$ref": "#/definitions/stats_status_count"
            }
            archived {
                description: "Stats for archived tasks"
                "$ref": "#/definitions/stats_status_count"
            }
        }
    }
    projects_get_all_response_single {
        // copy-paste from project definition
        type: object
        properties {
            id {
                description: "Project id"
                type: string
            }
            name {
                description: "Project name"
                type: string
            }
            description {
                description: "Project description"
                type: string
            }
            user {
                description: "Associated user id"
                type: string
            }
            company {
                description: "Company id"
                type: string
            }
            created {
                description: "Creation time"
                type: string
                format: "date-time"
            }
            tags {
                type: array
                description: "User-defined tags"
                items { type: string }
            }
            system_tags {
                type: array
                description: "System tags. This field is reserved for system use, please don't use it."
                items {type: string}
            }
            default_output_destination {
                description: "The default output destination URL for new tasks under this project"
                type: string
            }
            // extra properties
            stats: {
                description: "Additional project stats"
                "$ref": "#/definitions/stats"
            }
        }
    }
    metric_variant_result {
        type: object
        properties {
            metric {
                description: "Metric name"
                type: string
            }
            metric_hash {
                description: """Metric name hash. Used instead of the metric name when categorizing
                last metrics events in task objects."""
                type: string
            }
            variant {
                description: "Variant name"
                type: string
            }
            variant_hash {
                description: """Variant name hash. Used instead of the variant name when categorizing
                last metrics events in task objects."""
                type: string
            }
        }
    }
    tags_request {
        type: object
        properties {
            include_system {
                description: "If set to 'true' then the list of the system tags is also returned. The default value is 'false'"
                type: boolean
                default: false
            }
            projects {
                description: "The list of projects under which the tags are searched. If not passed or empty then all the projects are searched"
                type: array
                items { type: string }
            }
            filter {
                description: "Filter on entities to collect tags from"
                type: object
                properties {
                    tags {
                        description: "The list of tag values to filter by. Use 'null' value to specify empty tags. Use '__Snot' value to specify that the following value should be excluded"
                        type: array
                        items {type: string}
                    }
                    system_tags {
                        description: "The list of system tag values to filter by. Use 'null' value to specify empty system tags. Use '__Snot' value to specify that the following value should be excluded"
                        type: array
                        items {type: string}
                    }
                }
            }
        }
    }
    tags_response {
        type: object
        properties {
            tags {
                description: "The list of unique tag values"
                type: array
                items {type: string}
            }
            system_tags {
                description: "The list of unique system tag values. Returned only if 'include_system' is set to 'true' in the request"
                type: array
                items {type: string}
            }
        }
    }
}

create {
    "2.1" {
        description: "Create a new project"
        request {
            type: object
            required :[
                name
                description
            ]
            properties {
                name {
                    description: "Project name Unique within the company."
                    type: string
                }
                description {
                    description: "Project description. "
                    type: string
                }
                tags {
                    type: array
                    description: "User-defined tags"
                    items { type: string }
                }
                system_tags {
                    type: array
                    description: "System tags. This field is reserved for system use, please don't use it."
                    items {type: string}
                }
                default_output_destination  {
                    description: "The default output destination URL for new tasks under this project"
                    type: string
                }
            }
        }
        response {
            type: object
            properties {
                id {
                    description: "Project id"
                    type: string
                }
            }
        }
    }
}
get_by_id {
    "2.1" {
        description: ""
        request {
            type: object
            required: [ project ]
            properties {
                project {
                    description: "Project id"
                    type: string
                }
            }
        }
        response {
            type: object
            properties {
                project {
                    description: "Project info"
                    "$ref": "#/definitions/project"
                }
            }
        }
    }
}
get_all {
    "2.1" {
        description: "Get all the company's projects and all public projects"
        request {
            type: object
            properties {
                id {
                    description: "List of IDs to filter by"
                    type: array
                    items { type: string }
                }
                name {
                    description: "Get only projects whose name matches this pattern (python regular expression syntax)"
                    type: string
                }
                description {
                    description: "Get only projects whose description matches this pattern (python regular expression syntax)"
                    type: string
                }
                tags {
                    description: "User-defined tags list used to filter results. Prepend '-' to tag name to indicate exclusion"
                    type: array
                    items { type: string }
                }
                system_tags {
                    description: "System tags list used to filter results. Prepend '-' to system tag name to indicate exclusion"
                    type: array
                    items { type: string }
                }
                order_by {
                    description: "List of field names to order by. When search_text is used, '@text_score' can be used as a field representing the text score of returned documents. Use '-' prefix to specify descending order. Optional, recommended when using page"
                    type: array
                    items { type: string }
                }
                page {
                    description: "Page number, returns a specific page out of the resulting list of dataviews"
                    type: integer
                    minimum: 0
                }
                page_size {
                    description: "Page size, specifies the number of results returned in each page (last page may contain fewer results)"
                    type: integer
                    minimum: 1
                }
                search_text {
                    description: "Free text search query"
                    type: string
                }
                only_fields {
                    description: "List of document's field names (nesting is supported using '.', e.g. execution.model_labels). If provided, this list defines the query's projection (only these fields will be returned for each result entry)"
                    type: array
                    items { type: string }
                }
                _all_ {
                    description: "Multi-field pattern condition (all fields match pattern)"
                    "$ref": "#/definitions/multi_field_pattern_data"
                }
                _any_ {
                    description: "Multi-field pattern condition (any field matches pattern)"
                    "$ref": "#/definitions/multi_field_pattern_data"
                }
            }
        }
        response {
            type: object
            properties {
                projects {
                    description: "Projects list"
                    type: array
                    items { "$ref": "#/definitions/projects_get_all_response_single" }

                }
            }
        }
    }
}
get_all_ex {
    internal: true
    "2.1": ${get_all."2.1"} {
        request {
            properties {
                include_stats {
                    description: "If true, include project statistic in response."
                    type: boolean
                    default: false
                }
                stats_for_state {
                    description: "Report stats include only statistics for tasks in the specified state. If Null is provided, stats for all task states will be returned."
                    type: string
                    enum: [ active, archived ]
                    default: active
                }
            }
        }
    }
}
update {
    "2.1" {
        description: "Update project information"
        request {
            type: object
            required: [ project ]
            properties {
                project {
                    description: "Project id"
                    type: string
                }
                name {
                    description: "Project name. Unique within the company."
                    type: string
                }
                description {
                    description: "Project description. "
                    type: string
                }
                description {
                    description: "Project description"
                    type: string
                }
                tags {
                    type: array
                    description: "User-defined tags"
                    items { type: string }
                }
                system_tags {
                    type: array
                    description: "System tags. This field is reserved for system use, please don't use it."
                    items {type: string}
                }
                default_output_destination {
                    description: "The default output destination URL for new tasks under this project"
                    type: string
                }
            }
        }
        response {
            type: object
            properties {
                updated {
                    description: "Number of projects updated (0 or 1)"
                    type: integer
                    enum: [ 0, 1 ]
                }
                fields {
                    description: "Updated fields names and values"
                    type: object
                    additionalProperties: true
                }
            }
        }
    }
}
delete {
    "2.1" {
        description: "Deletes a project"
        request {
            type: object
            required: [ project ]
            properties {
                project {
                    description: "Project id"
                    type: string
                }
                force {
                    description: """If not true, fails if project has tasks.
                    If true, and project has tasks, they will be unassigned"""
                    type: boolean
                    default: false
                }

            }
        }
        response {
            type: object
            properties {
                deleted {
                    description: "Number of projects deleted (0 or 1)"
                    type: integer
                }
                disassociated_tasks {
                    description: "Number of tasks disassociated from the deleted project"
                    type: integer
                }
            }
        }
    }
}
get_unique_metric_variants {
    "2.1" {
        description: """Get all metric/variant pairs reported for tasks in a specific project.
        If no project is specified, metrics/variant paris reported for all tasks will be returned.
        If the project does not exist, an empty list will be returned."""
        request {
            type: object
            properties {
                project {
                    description: "Project ID"
                    type: string
                }
            }
        }
        response {
            type: object
            properties {
                metrics {
                    description: "A list of metric variants reported for tasks in this project"
                    type: array
                    items { "$ref": "#/definitions/metric_variant_result" }
                }
            }
        }
    }
}
get_hyper_parameters {
    "2.2" {
        description: """Get a list of all hyper parameter names used in tasks within the given project."""
        request {
            type: object
            properties {
                project {
                    description: "Project ID"
                    type: string
                }
                page {
                    description: "Page number"
                    default: 0
                    type: integer
                }
                page_size {
                    description: "Page size"
                    default: 500
                    type: integer
                }
            }
        }
        response {
            type: object
            properties {
                parameters {
                    description: "A list of hyper parameter names"
                    type: array
                    items {type: string}
                }
                remaining {
                    description: "Remaining results"
                    type: integer
                }
                total {
                    description: "Total number of results"
                    type: integer
                }
            }
        }
    }
}
get_task_tags {
    "2.8" {
        description: "Get user and system tags used for the tasks under the specified projects"
        request = ${_definitions.tags_request}
        response = ${_definitions.tags_response}
    }
}
get_model_tags {
    "2.8" {
        description: "Get user and system tags used for the models under the specified projects"
        request = ${_definitions.tags_request}
        response = ${_definitions.tags_response}
    }
}