Core Reference

Core reference still in progress.

Workflow

class orchestra.workflow.Step(**kwargs)[source]

Steps represent nodes on a workflow execution graph.

slug

str

Unique identifier for the step.

name

str

Human-readable name for the step.

description

str

A longer description of the step.

worker_type

orchestra.workflow.Step.WorkerType

Indicates whether the policy is for a human or machine.

creation_depends_on

[str]

Slugs for steps on which this step’s creation depends.

submission_depends_on

[str]

Slugs for steps on which this step’s submission depends.

function

function

Function to execute during step. Should be present only for machine tasks

required_certifications

[str]

Slugs for certifications required for a worker to pick up tasks based on this step.

class WorkerType[source]

Specifies whether step is performed by human or machine

class orchestra.workflow.Workflow(**kwargs)[source]

Workflows represent execution graphs of human and machine steps.

slug

str

Unique identifier for the workflow.

name

str

Human-readable name for the workflow.

description

str

A longer description of the workflow.

steps

dict

Steps comprising the workflow.

add_step(step)[source]

Add step to the workflow.

Parameters:

step (orchestra.workflow.Step) – The step to be added.

Returns:

None

Raises:
  • orchestra.core.errors.InvalidSlugValue

    Step slug should have fewer than 200 characters.

  • orchestra.core.errors.SlugUniquenessError

    Step slug has already been used in this workflow.

get_human_steps()[source]

Return steps from the workflow with a human worker_type.

Parameters:None
Returns:steps

Steps from the workflow with a human worker_type..

Return type:[orchestra.workflow.Step]
get_step(slug)[source]

Return the specified step from the workflow.

Parameters:slug (str) – The slug of the desired step.
Returns:step

The specified step from the workflow.

Return type:orchestra.workflow.Step
get_step_slugs()[source]

Return all step slugs for the workflow.

Parameters:None
Returns:slugs

List of step slugs for the workflow.

Return type:[str]
get_steps()[source]

Return all steps for the workflow.

Parameters:None
Returns:steps

List of steps for the workflow.

Return type:[orchestra.workflow.Step]
orchestra.workflow.get_default_policy(worker_type, policy_name)[source]

Return the default value for a specified policy.

Parameters:
Returns:

default_policy

A dict containing the default policy for the worker type and policy name specified.

Return type:

dict

orchestra.workflow.get_step_choices()[source]

Return step data formatted as choices for a model field.

Parameters:None
Returns:step_choices

A tuple of tuples containing each step slug and human-readable name.

Return type:tuple
orchestra.workflow.get_workflow_by_slug(slug)[source]

Return the workflow specified by slug.

Parameters:slug (str) – The slug of the desired workflow.
Returns:workflow

The corresponding workflow object.

Return type:orchestra.workflow.Workflow
orchestra.workflow.get_workflow_choices()[source]

Return workflow data formatted as choices for a model field.

Parameters:None
Returns:workflow_choices

A tuple of tuples containing each workflow slug and human-readable name.

Return type:tuple
orchestra.workflow.get_workflows()[source]

Return all stored workflows.

Parameters:None
Returns:workflows

A dict of all workflows keyed by slug.

Return type:[orchestra.workflow.Workflow]

Models

class orchestra.models.Certification(*args, **kwargs)[source]

Certifications allow workers to perform different types of tasks.

slug

str

Unique identifier for the certification.

name

str

Human-readable name for the certification.

description

str

A longer description of the certification.

required_certifications

[orchestra.models.Certification]

Prerequisite certifications for possessing this one.

class orchestra.models.Project(*args, **kwargs)[source]

A project is a collection of tasks representing a workflow.

status

orchestra.models.Project.Status

Represents whether the project is being actively worked on.

workflow_slug

str

Identifies the workflow that the project represents.

start_datetime

datetime.datetime

The time the project was created.

priority

int

Represents the relative priority of the project.

task_class

int

Represents whether the project is a worker training exercise or a deliverable project.

review_document_url

str

The URL for the review document to be passed between workers and reviwers for the project’s tasks.

slack_group_id

str

The project’s internal Slack group ID if Slack integration is enabled.

class orchestra.models.Task(*args, **kwargs)[source]

A task is a cohesive unit of work representing a workflow step.

step_slug

str

Identifies the step that the project represents.

project

orchestra.models.Project

The project to which the task belongs.

status

orchestra.models.Task.Status

Represents the task’s stage within its lifecycle.

class orchestra.models.TaskAssignment(*args, **kwargs)[source]

A task assignment is a worker’s assignment for a given task.

start_datetime

datetime.datetime

The time the project was created.

worker

orchestra.models.Worker

The worker to whom the given task is assigned.

task

orchestra.models.Task

The given task for the task assignment.

status

orchestra.models.Project.Status

Represents whether the assignment is currently being worked on.

assignment_counter

int

Identifies the level of the assignment in the given task’s review hierarchy (i.e., 0 represents an entry-level worker, 1 represents the task’s first reviewer, etc.).

in_progress_task_data

str

A JSON blob containing the worker’s input data for the task assignment.

snapshots

str

A JSON blob containing saved snapshots of previous data from the task assignment.

Constraints:

task and assignment_counter are taken to be unique_together.

Task assignments for machine-type tasks cannot have a worker, while those for human-type tasks must have one.

class orchestra.models.Worker(*args, **kwargs)[source]

Workers are human experts within the Orchestra ecosystem.

user

django.contrib.auth.models.User

Django user whom the worker represents.

start_datetime

datetime.datetime

The time the worker was created.

slack_username

str

The worker’s Slack username if Slack integration is enabled.

class orchestra.models.WorkerCertification(*args, **kwargs)[source]

A WorkerCertification maps a worker to a certification they possess.

certification

orchestra.models.Certification

Certification belonging to the corresponding worker.

worker

orchestra.models.Worker

Worker possessing the given certification.

task_class

orchestra.models.WorkerCertification.TaskClass

Represents whether the worker is in training for the given certification or prepared to work on real tasks.

role

orchestra.models.WorkerCertification.Role

Represents whather the worker is an entry-level or review worker for the given certification.

Constraints:

certification, worker, task_class, and role are taken to be unique_together.

Worker must possess an entry-level WorkerCertification before obtaining a reviewer one.

Task Lifecycle

orchestra.utils.task_lifecycle.assign_task(worker_id, task_id)[source]

Return a given task after assigning or reassigning it to the specified worker.

Parameters:
  • worker_id (int) – The ID of the worker to be assigned.
  • task_id (int) – The ID of the task to be assigned.
Returns:

task

The newly assigned task.

Return type:

orchestra.models.Task

Raises:
  • orchestra.core.errors.TaskAssignmentError

    The specified worker is already assigned to the given task or the task status is not compatible with new assignment.

  • orchestra.core.errors.WorkerCertificationError

    The specified worker is not certified for the given task.

orchestra.utils.task_lifecycle.create_subsequent_tasks(project)[source]

Create tasks for a given project whose dependencies have been completed.

Parameters:project (orchestra.models.Project) – The project for which to create tasks.
Returns:project

The modified project object.

Return type:orchestra.models.Project
orchestra.utils.task_lifecycle.end_project(project_id)[source]

Mark the specified project and its component tasks as aborted.

Parameters:project_id (int) – The ID of the project to abort.
Returns:None
orchestra.utils.task_lifecycle.get_new_task_assignment(worker, task_status)[source]

Check if new task assignment is available for the provided worker and task status; if so, assign the task to the worker and return the assignment.

Parameters:
  • worker (orchestra.models.Worker) – The worker submitting the task.
  • task_status (orchestra.models.Task.Status) – The status of the desired new task assignment.
Returns:

assignment

The newly created task assignment.

Return type:

orchestra.models.TaskAssignment

Raises:
  • orchestra.core.errors.WorkerCertificationError

    No human tasks are available for the given task status except those for which the worker is not certified.

  • orchestra.core.errors.NoTaskAvailable

    No human tasks are available for the given task status.

orchestra.utils.task_lifecycle.get_next_task_status(task, snapshot_type)[source]

Given current task status and snapshot type provide new task status. If the second level reviewer rejects a task then initial reviewer cannot reject it further down, but must fix and submit the task.

Parameters:
  • task (orchestra.models.Task) – The specified task object.
  • task_status (orchestra.models.TaskAssignment.SnapshotType) – The action to take upon task submission (e.g., SUBMIT, ACCEPT, REJECT).
Returns:

next_status

The next status of task, once the snapshot_type action has been completed.

Return type:

orchestra.models.Task.Status

Raises:

orchestra.core.errors.IllegalTaskSubmission

The snapshot_type action cannot be taken for the task in its current status.

orchestra.utils.task_lifecycle.get_task_assignment_details(task_assignment)[source]

Return various information about the specified task assignment.

Parameters:task_assignment (orchestra.models.TaskAssignment) – The specified task assignment.
Returns:task_assignment_details

Information about the specified task assignment.

Return type:dict
orchestra.utils.task_lifecycle.get_task_details(task_id)[source]

Return various information about the specified task.

Parameters:task_id (int) – The ID of the desired task.
Returns:task_details – Information about the specified task.
Return type:dict
orchestra.utils.task_lifecycle.get_task_overview_for_worker(task_id, worker)[source]

Get information about task and its assignment for worker.

Parameters:
  • task_id (int) – The ID of the desired task object.
  • worker (orchestra.models.Worker) – The specified worker object.
Returns:

task_assignment_details

Information about task and its assignment for worker.

Return type:

dict

orchestra.utils.task_lifecycle.previously_completed_task_data(task)[source]

Returns a dict mapping task prerequisites onto their latest task assignment information. The dict is of the form: {‘previous-slug’: {task_assignment_data}, ...}

Parameters:task (orchestra.models.Task) – The specified task object.
Returns:prerequisites

A dict mapping task prerequisites onto their latest task assignment information..

Return type:dict
orchestra.utils.task_lifecycle.save_task(task_id, task_data, worker)[source]

Save the latest data to the database for a task assignment, overwriting previously saved data.

Parameters:
  • task_id (int) – The ID of the task to save.
  • task_data (str) – A JSON blob of task data to commit to the database.
  • worker (orchestra.models.Worker) – The worker saving the task.
Returns:

None

Raises:

orchestra.core.errors.TaskAssignmentError

The provided worker is not assigned to the given task or the assignment is in a non-processing state.

orchestra.utils.task_lifecycle.submit_task(task_id, task_data, snapshot_type, worker, work_time_seconds)[source]

Returns a dict mapping task prerequisites onto their latest task assignment information. The dict is of the form: {‘previous-slug’: {task_assignment_data}, ...}

Parameters:
  • task_id (int) – The ID of the task to submit.
  • task_data (str) – A JSON blob of task data to submit.
  • snapshot_type (orchestra.models.TaskAssignment.SnapshotType) – The action to take upon task submission (e.g., SUBMIT, ACCEPT, REJECT).
  • worker (orchestra.models.Worker) – The worker submitting the task.
  • work_time_seconds (int) – The time taken by the worker on the latest iteration of their task assignment.
Returns:

task

The modified task object.

Return type:

orchestra.models.Task

Raises:
  • orchestra.core.errors.IllegalTaskSubmission

    Submission prerequisites for the task are incomplete or the assignment is in a non-processing state.

  • orchestra.core.errors.TaskAssignmentError

    Worker belongs to more than one assignment for the given task.

  • orchestra.core.errors.TaskStatusError

    Task has already been completed.

orchestra.utils.task_lifecycle.task_history_details(task_id)[source]

Return assignment details for a specified task.

Parameters:task_id (int) – The ID of the desired task object.
Returns:details

A dictionary containing the current task assignment and an in-order list of related task assignments.

Return type:dict
orchestra.utils.task_lifecycle.tasks_assigned_to_worker(worker)[source]

Get all the tasks associated with worker.

Parameters:worker (orchestra.models.Worker) – The specified worker object.
Returns:tasks_assigned

A dict with information about the worker’s tasks, used in displaying the Orchestra dashboard.

Return type:dict

Copy data to a specified task assignment and mark it as processing.

Parameters:
  • task (orchestra.models.Task) – The task whose assignments will be updated.
  • assignment_counter (int) – The index of the assignment to be updated.
  • data (str) – A JSON blob containing data to add to the assignment.
Returns:

None

orchestra.utils.task_lifecycle.worker_assigned_to_max_tasks(worker)[source]

Check whether worker is assigned to the maximum number of tasks.

Parameters:worker (orchestra.models.Worker) – The specified worker object.
Returns:assigned_to_max_tasks

True if worker is assigned to the maximum number of tasks.

Return type:bool
orchestra.utils.task_lifecycle.worker_assigned_to_rejected_task(worker)[source]

Check whether worker is assigned to a task that has been rejected.

Parameters:worker (orchestra.models.Worker) – The specified worker object.
Returns:assigned_to_rejected_task

True if worker is assigned to a task that has been rejected.

Return type:bool
orchestra.utils.task_lifecycle.worker_has_reviewer_status(worker, task_class=1)[source]

Check whether worker is a reviewer for any certification for a given task class.

Parameters:
  • worker (orchestra.models.Worker) – The specified worker object.
  • task_class (orchestra.models.WorkerCertification.TaskClass) – The specified task class.
Returns:

has_reviwer_status

True if worker is a reviewer for any certification for a given task class.

Return type:

bool

orchestra.utils.task_properties.all_workers(task)[source]

Return all workers for a given task.

Parameters:task (orchestra.models.Task) – The specified task object.
Returns:all_workers

A list of all workers involved with task.

Return type:[orchestra.models.Worker]
orchestra.utils.task_properties.assignment_history(task)[source]

Return all assignments for task ordered by assignment_counter.

Parameters:task (orchestra.models.Task) – The specified task object.
Returns:assignment_history

All assignments for task ordered by assignment_counter.

Return type:[orchestra.models.TaskAssignment]
orchestra.utils.task_properties.current_assignment(task)[source]

Return the in-progress assignment for task.

Parameters:task (orchestra.models.Task) – The specified task object.
Returns:current_assignment

The in-progress assignment for task.

Return type:orchestra.models.TaskAssignment
orchestra.utils.task_properties.is_worker_assigned_to_task(worker, task)[source]

Check if specified worker is assigned to the given task.

Parameters:
Returns:

worker_assigned_to_task

True if worker has existing assignment for the given task.

Return type:

bool