Core Reference¶
Core reference still in progress.
Contents
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
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
-
-
orchestra.workflow.
get_default_policy
(worker_type, policy_name)[source]¶ Return the default value for a specified policy.
Parameters: - worker_type (orchestra.workflow.Step.WorkerType) – Indicates whether the policy is for a human or machine.
- policy_name (str) – The specified policy identifier.
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
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: 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: 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: 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: - worker (orchestra.models.Worker) – The specified worker object.
- task (orchestra.models.Task) – The given task object.
Returns: worker_assigned_to_task –
True if worker has existing assignment for the given task.
Return type: bool