Tasks¶

TasksClient¶

Accessed via client.tasks.

pyawe.client.TasksClient ¶

TasksClient(http: _HttpSession)

Methods for the /tasks resource.

list ¶

list(workflow_id: UUID | str | None = None) -> builtins.list[Task]

List tasks, optionally filtered by workflow.

Parameters:

Name	Type	Description	Default
`workflow_id`	`UUID \| str \| None`	When supplied, returns only tasks within this workflow.	`None`

Returns:

Type	Description
`list[Task]`	List of :class:`~pyawe.models.Task` objects.

Raises:

Type	Description
`AweAuthError`	If not authenticated.

list_mine ¶

list_mine(role_ids: list[UUID | str] | None = None) -> builtins.list[TaskWithContext]

Return tasks assigned to the authenticated user or their team roles.

Parameters:

Name	Type	Description	Default
`role_ids`	`list[UUID \| str] \| None`	Team role UUIDs to include alongside direct assignments.	`None`

Returns:

Type	Description
`list[TaskWithContext]`	List of :class:`~pyawe.models.TaskWithContext` objects, each enriched
`list[TaskWithContext]`	with workflow and job names.

Raises:

Type	Description
`AweAuthError`	If not authenticated.

create ¶

create(name: str, workflow_id: UUID | str, *, is_template: bool | None = None, description: str | None = None, status: Status | str | None = None, schedule_status: ScheduleStatus | str | None = None, rework_task_id: UUID | str | None = None, is_start: bool | None = None, is_end: bool | None = None, task_type: TaskType | str | None = None, effort: int | None = None, priority: str | None = None, due_time: datetime | None = None) -> Task

Create a task within a workflow.

Parameters:

Name	Type	Description	Default
`name`	`str`	Task name.	required
`workflow_id`	`UUID \| str`	UUID of the containing workflow.	required
`is_template`	`bool \| None`	Mark as a template task.	`None`
`description`	`str \| None`	Optional description.	`None`
`status`	`Status \| str \| None`	Initial status (default `"Not Started"`).	`None`
`schedule_status`	`ScheduleStatus \| str \| None`	Initial schedule status (default `"N/A"`).	`None`
`rework_task_id`	`UUID \| str \| None`	UUID of the task this one reworks, if any.	`None`
`is_start`	`bool \| None`	Designate as the workflow start task.	`None`
`is_end`	`bool \| None`	Designate as the workflow end task.	`None`
`task_type`	`TaskType \| str \| None`	`"standard"` (default), `"decision"`, `"automated"`, `"loop_block"`, or `"checkpoint"`.	`None`
`effort`	`int \| None`	Unitless effort estimate (e.g. story points).	`None`
`priority`	`str \| None`	`"none"` (default), `"low"`, `"medium"`, `"high"`, or `"critical"`.	`None`
`due_time`	`datetime \| None`	Optional point in time the task is due.	`None`

Returns:

Type	Description
`Task`	The newly created :class:`~pyawe.models.Task`.

Raises:

Type	Description
`AweAuthError`	If not authenticated.
`AweValidationError`	On a 400 response.

get ¶

get(task_id: UUID | str) -> Task

Fetch a single task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required

Returns:

Type	Description
`Task`	class:`~pyawe.models.Task`.

Raises:

Type	Description
`AweNotFoundError`	If the task does not exist.
`AweAuthError`	If not authenticated.

update ¶

update(task_id: UUID | str, *, name: str | None = None, is_template: bool | None = None, description: str | None = None, status: Status | str | None = None, schedule_status: ScheduleStatus | str | None = None, rework_task_id: UUID | str | None = None, is_start: bool | None = None, is_end: bool | None = None, task_type: TaskType | str | None = None, assigned_to: Any = _UNSET, decision_input_port: Any = _UNSET, is_locked: bool | None = None, canvas_x: float | None = None, canvas_y: float | None = None, effort: Any = _UNSET, priority: str | None = None, due_time: Any = _UNSET, branch_name: Any = _UNSET, port_namespace: Any = _UNSET) -> Task

Update a task; only supplied fields are changed.

assigned_to, decision_input_port, effort, due_time, branch_name, and port_namespace are tri-state fields:

Omitted (default): field is left unchanged.
None: clears the current value.
A value: sets the field.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task to update.	required
`name`	`str \| None`	New name.	`None`
`is_template`	`bool \| None`	Template flag.	`None`
`description`	`str \| None`	New description.	`None`
`status`	`Status \| str \| None`	New status. Completed/cancelled tasks cannot be transitioned. Setting to `"In Progress"` stamps `start_time`; setting to `"Complete"` stamps `end_time`.	`None`
`schedule_status`	`ScheduleStatus \| str \| None`	New schedule status.	`None`
`rework_task_id`	`UUID \| str \| None`	Rework back-link.	`None`
`is_start`	`bool \| None`	Start task flag.	`None`
`is_end`	`bool \| None`	End task flag.	`None`
`task_type`	`TaskType \| str \| None`	Task type string.	`None`
`assigned_to`	`Any`	User ID string, `None` to clear, or omit to leave unchanged.	`_UNSET`
`decision_input_port`	`Any`	Input port name for auto-decide, `None` to clear, or omit to leave unchanged.	`_UNSET`
`is_locked`	`bool \| None`	Lock or unlock structural edits (requires owner/leader/admin).	`None`
`canvas_x`	`float \| None`	Canvas X position from the workflow editor.	`None`
`canvas_y`	`float \| None`	Canvas Y position from the workflow editor.	`None`
`effort`	`Any`	Unitless effort estimate, `None` to clear, or omit to leave unchanged.	`_UNSET`
`priority`	`str \| None`	`"none"`, `"low"`, `"medium"`, `"high"`, or `"critical"`.	`None`
`due_time`	`Any`	Due time, `None` to clear, or omit to leave unchanged.	`_UNSET`
`branch_name`	`Any`	Git branch name, `None` to clear, or omit to leave unchanged.	`_UNSET`
`port_namespace`	`Any`	Checkpoint port namespace override (`^[a-z][a-z0-9_]*$`), `None` to clear (falls back to `t{task_number}`), or omit to leave unchanged.	`_UNSET`

Returns:

Type	Description
`Task`	The updated :class:`~pyawe.models.Task`.

Raises:

Type	Description
`AweNotFoundError`	If the task does not exist.
`AweValidationError`	If the status transition is invalid.
`AweAuthError`	If not authenticated.

delete ¶

delete(task_id: UUID | str) -> None

Delete a task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task to delete.	required

Raises:

Type	Description
`AweNotFoundError`	If the task does not exist.
`AweAuthError`	If not authenticated.

decide ¶

decide(task_id: UUID | str, branch_label: str) -> Task

Resolve a decision task by choosing an outgoing branch.

Sets the task status to "Complete", records decision_outcome, activates the chosen successor, and cancels tasks on rejected branches.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of a decision task.	required
`branch_label`	`str`	Label of the branch to follow. Must match an outgoing link's `branch_label`.	required

Returns:

Type	Description
`Task`	The decided :class:`~pyawe.models.Task`.

Raises:

Type	Description
`AweValidationError`	If the task is not a decision task, is already complete, or the branch label is not found.
`AweNotFoundError`	If the task does not exist.
`AweAuthError`	If not authenticated.

clear_rework ¶

clear_rework(task_id: UUID | str) -> Task

Remove the rework back-link from a task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required

Returns:

Type	Description
`Task`	The updated :class:`~pyawe.models.Task`.

Raises:

Type	Description
`AweNotFoundError`	If the task does not exist.
`AweAuthError`	If not authenticated.

request_rework ¶

request_rework(task_id: UUID | str) -> Task

Manually trigger a rework of task_id.

Spawns a fresh clone of the subgraph between the task's configured rework_task_id and the task itself, rewires the clone chain in place of the original, and marks the original task "Reworked". The original target/intermediate tasks are never touched.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task that judged rework was needed (the "source" task; must already have `rework_task_id` set).	required

Returns:

Type	Description
`Task`	The reworked (now `"Reworked"`-status) :class:`~pyawe.models.Task`.

Raises:

Type	Description
`AweNotFoundError`	If the task does not exist.
`AweValidationError`	If the task has no `rework_task_id` configured.
`AweAuthError`	If not authenticated.

TaskLinksClient¶

Accessed via client.task_links.

pyawe.client.TaskLinksClient ¶

TaskLinksClient(http: _HttpSession)

Methods for task link management (/task-links and /tasks/{id}/…).

create ¶

create(from_task_id: UUID | str, to_task_id: UUID | str, *, branch_label: str | None = None) -> TaskLink

Create a directed link between two tasks.

Parameters:

Name	Type	Description	Default
`from_task_id`	`UUID \| str`	UUID of the upstream task.	required
`to_task_id`	`UUID \| str`	UUID of the downstream task.	required
`branch_label`	`str \| None`	Required when the upstream task is a decision task.	`None`

Returns:

Type	Description
`TaskLink`	The created :class:`~pyawe.models.TaskLink`.

Raises:

Type	Description
`AweAuthError`	If not authenticated.
`AweValidationError`	On a 400 response.

delete ¶

delete(from_task_id: UUID | str, to_task_id: UUID | str) -> None

Delete the link between two tasks.

Parameters:

Name	Type	Description	Default
`from_task_id`	`UUID \| str`	UUID of the upstream task.	required
`to_task_id`	`UUID \| str`	UUID of the downstream task.	required

Raises:

Type	Description
`AweNotFoundError`	If the link does not exist.
`AweAuthError`	If not authenticated.

get_next ¶

get_next(task_id: UUID | str) -> list[Task]

Return the immediate successor tasks of task_id.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required

Returns:

Type	Description
`list[Task]`	List of :class:`~pyawe.models.Task` objects.

Raises:

Type	Description
`AweNotFoundError`	If the task does not exist.
`AweAuthError`	If not authenticated.

get_previous ¶

get_previous(task_id: UUID | str) -> list[Task]

Return the immediate predecessor tasks of task_id.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required

Returns:

Type	Description
`list[Task]`	List of :class:`~pyawe.models.Task` objects.

Raises:

Type	Description
`AweNotFoundError`	If the task does not exist.
`AweAuthError`	If not authenticated.

get_outgoing ¶

get_outgoing(task_id: UUID | str) -> list[TaskLink]

Return all outgoing links from task_id.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required

Returns:

Type	Description
`list[TaskLink]`	List of :class:`~pyawe.models.TaskLink` objects.

Raises:

Type	Description
`AweNotFoundError`	If the task does not exist.
`AweAuthError`	If not authenticated.

update_bindings ¶

update_bindings(from_task_id: UUID | str, to_task_id: UUID | str, bindings: list[DataBinding]) -> TaskLink

Replace the data bindings on a task link edge.

Bindings are applied by the propagator when the upstream task completes, copying output values to the downstream task's inputs.

Parameters:

Name	Type	Description	Default
`from_task_id`	`UUID \| str`	UUID of the upstream task.	required
`to_task_id`	`UUID \| str`	UUID of the downstream task.	required
`bindings`	`list[DataBinding]`	New list of :class:`~pyawe.models.DataBinding` objects.	required

Returns:

Type	Description
`TaskLink`	The updated :class:`~pyawe.models.TaskLink`.

Raises:

Type	Description
`AweNotFoundError`	If the link does not exist.
`AweAuthError`	If not authenticated.

TaskPortsClient¶

Accessed via client.task_ports.

pyawe.client.TaskPortsClient ¶

TaskPortsClient(http: _HttpSession)

Methods for task port spec and value management (/tasks/{id}/ports, etc.).

get_workflow_ports ¶

get_workflow_ports(workflow_id: UUID | str) -> list[TaskPortSpec]

Return all port specs for every task in a workflow.

Parameters:

Name	Type	Description	Default
`workflow_id`	`UUID \| str`	UUID of the workflow.	required

Returns:

Type	Description
`list[TaskPortSpec]`	List of :class:`~pyawe.models.TaskPortSpec` objects.

Raises:

Type	Description
`AweAuthError`	If not authenticated.

list_specs ¶

list_specs(task_id: UUID | str) -> list[TaskPortSpec]

Return all port specs (inputs and outputs) for a task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required

Returns:

Type	Description
`list[TaskPortSpec]`	List of :class:`~pyawe.models.TaskPortSpec` objects.

Raises:

Type	Description
`AweAuthError`	If not authenticated.

create_spec ¶

create_spec(task_id: UUID | str, direction: str, name: str, value_type: str, *, required: bool | None = None, description: str | None = None, default_value: Any | None = None, sort_order: int | None = None) -> TaskPortSpec

Add a port spec to a task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required
`direction`	`str`	`"input"` or `"output"`.	required
`name`	`str`	Port name (unique within direction on the task).	required
`value_type`	`str`	`"string"`, `"number"`, `"boolean"`, `"json"`, `"file"`, or `"dam_asset"`.	required
`required`	`bool \| None`	Whether this input is required (default `False`; ignored for outputs).	`None`
`description`	`str \| None`	Human-readable description.	`None`
`default_value`	`Any \| None`	JSON default applied at instantiation for optional inputs.	`None`
`sort_order`	`int \| None`	Display order.	`None`

Returns:

Type	Description
`TaskPortSpec`	The created :class:`~pyawe.models.TaskPortSpec`.

Raises:

Type	Description
`AweAuthError`	If not authenticated.
`AweValidationError`	On a 400 response.

update_spec ¶

update_spec(task_id: UUID | str, port_id: UUID | str, *, name: str | None = None, value_type: str | None = None, required: bool | None = None, description: str | None = None, default_value: Any | None = None, sort_order: int | None = None) -> TaskPortSpec

Update a port spec; only supplied fields are changed.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required
`port_id`	`UUID \| str`	UUID of the port spec.	required
`name`	`str \| None`	New port name.	`None`
`value_type`	`str \| None`	New value type.	`None`
`required`	`bool \| None`	Required flag.	`None`
`description`	`str \| None`	New description.	`None`
`default_value`	`Any \| None`	New default value.	`None`
`sort_order`	`int \| None`	New sort order.	`None`

Returns:

Type	Description
`TaskPortSpec`	The updated :class:`~pyawe.models.TaskPortSpec`.

Raises:

Type	Description
`AweNotFoundError`	If the port spec does not exist.
`AweAuthError`	If not authenticated.

delete_spec ¶

delete_spec(task_id: UUID | str, port_id: UUID | str) -> None

Delete a port spec.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required
`port_id`	`UUID \| str`	UUID of the port spec.	required

Raises:

Type	Description
`AweNotFoundError`	If the port spec does not exist.
`AweAuthError`	If not authenticated.

get_inputs ¶

get_inputs(task_id: UUID | str) -> TaskPortValues

Return input port specs and current values for a task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required

Returns:

Type	Description
`TaskPortValues`	class:`~pyawe.models.TaskPortValues` with `direction == "input"` specs.

Raises:

Type	Description
`AweAuthError`	If not authenticated.

patch_inputs ¶

patch_inputs(task_id: UUID | str, values: dict[str, Any]) -> TaskPortValues

Partially update the input values of a task.

Only the keys present in values are written; others are left unchanged.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required
`values`	`dict[str, Any]`	Mapping of `{port_name: value}` pairs to set.	required

Returns:

Name	Type	Description
`Updated`	`TaskPortValues`	class:`~pyawe.models.TaskPortValues`.

Raises:

Type	Description
`AweNotFoundError`	If the task does not exist.
`AweAuthError`	If not authenticated.

get_outputs ¶

get_outputs(task_id: UUID | str) -> TaskPortValues

Return output port specs and current values for a task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required

Returns:

Type	Description
`TaskPortValues`	class:`~pyawe.models.TaskPortValues` with `direction == "output"` specs.

Raises:

Type	Description
`AweAuthError`	If not authenticated.

patch_outputs ¶

patch_outputs(task_id: UUID | str, values: dict[str, Any]) -> Task

Partially update the output values of a task (runner use).

Only the keys present in values are written; others are left unchanged. Typically called by the automated runner after a task completes.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required
`values`	`dict[str, Any]`	Mapping of `{port_name: value}` pairs to set.	required

Returns:

Name	Type	Description
`Updated`	`Task`	class:`~pyawe.models.Task`.

Raises:

Type	Description
`AweNotFoundError`	If the task does not exist.
`AweAuthError`	If not authenticated.

TaskScriptsClient¶

Accessed via client.task_scripts.

pyawe.client.TaskScriptsClient ¶

TaskScriptsClient(http: _HttpSession)

Methods for automated task script management (/tasks/{id}/script).

get ¶

get(task_id: UUID | str) -> TaskScript

Fetch the script attached to a task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required

Returns:

Type	Description
`TaskScript`	class:`~pyawe.models.TaskScript`.

Raises:

Type	Description
`AweNotFoundError`	If no script is attached.
`AweAuthError`	If not authenticated.

upsert ¶

upsert(task_id: UUID | str, *, script_type: str | None = None, endpoint: str | None = None, script_body: str | None = None, timeout_secs: int | None = None, retry_limit: int | None = None, execution_profile_id: UUID | str | None = None, connection_id: UUID | str | None = None) -> TaskScript

Create or fully replace the script on a task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required
`script_type`	`str \| None`	`"webhook"` (default), `"shell"`, `"python"`, `"mcp_tool"`, or `"email"`.	`None`
`endpoint`	`str \| None`	Webhook URL; required when `script_type == "webhook"`.	`None`
`script_body`	`str \| None`	Script source; required for `"shell"`, `"python"`, and `"mcp_tool"` types. Must be absent for `"email"`.	`None`
`timeout_secs`	`int \| None`	Execution timeout in seconds.	`None`
`retry_limit`	`int \| None`	Maximum number of retry attempts.	`None`
`execution_profile_id`	`UUID \| str \| None`	Execution profile for Kubernetes dispatch (`"shell"` and `"python"` only).	`None`
`connection_id`	`UUID \| str \| None`	Connection profile to resolve auth from at run time. Required (must reference an `smtp` connection) when `script_type == "email"`.	`None`

Returns:

Type	Description
`TaskScript`	The upserted :class:`~pyawe.models.TaskScript`.

Raises:

Type	Description
`AweNotFoundError`	If the task does not exist.
`AweAuthError`	If not authenticated.

delete ¶

delete(task_id: UUID | str) -> None

Remove the script from a task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required

Raises:

Type	Description
`AweNotFoundError`	If no script is attached.
`AweAuthError`	If not authenticated.

TaskRunsClient¶

Accessed via client.task_runs.

pyawe.client.TaskRunsClient ¶

TaskRunsClient(http: _HttpSession)

Methods for automated task execution history (/tasks/{id}/runs).

list ¶

list(task_id: UUID | str) -> builtins.list[TaskRun]

Return all execution run records for a task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required

Returns:

Type	Description
`list[TaskRun]`	List of :class:`~pyawe.models.TaskRun` objects, newest first.

Raises:

Type	Description
`AweAuthError`	If not authenticated.

create ¶

create(task_id: UUID | str, outcome: str, started_at: datetime, completed_at: datetime, *, run_id: UUID | str | None = None, runner_id: str | None = None, input_json: Any | None = None, output_json: Any | None = None, error_message: str | None = None, branch_name: str | None = None) -> TaskRun

Record a completed execution run.

This endpoint is called by the runner after executing an automated task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required
`outcome`	`str`	`"Success"`, `"Failure"`, or `"Timeout"`.	required
`started_at`	`datetime`	When execution began.	required
`completed_at`	`datetime`	When execution ended (or timed out).	required
`run_id`	`UUID \| str \| None`	Optional client-supplied UUID for idempotent recording.	`None`
`runner_id`	`str \| None`	Identifier of the runner that executed the task.	`None`
`input_json`	`Any \| None`	Snapshot of the dispatch payload.	`None`
`output_json`	`Any \| None`	Structured output produced by the task.	`None`
`error_message`	`str \| None`	Error details when `outcome != "Success"`.	`None`
`branch_name`	`str \| None`	Git branch extracted from the run's output (`mcp_tool` scripts declaring `branch_output_field`). When present on a successful run, the task's `branch_name` is updated to this value.	`None`

Returns:

Type	Description
`TaskRun`	The recorded :class:`~pyawe.models.TaskRun`.

Raises:

Type	Description
`AweNotFoundError`	If the task does not exist.
`AweAuthError`	If not authenticated.

get ¶

get(task_id: UUID | str, run_id: UUID | str) -> TaskRun

Fetch a single execution run record.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required
`run_id`	`UUID \| str`	UUID of the run.	required

Returns:

Type	Description
`TaskRun`	class:`~pyawe.models.TaskRun`.

Raises:

Type	Description
`AweNotFoundError`	If the run does not exist.
`AweAuthError`	If not authenticated.

TaskTeamRolesClient¶

Accessed via client.task_team_roles.

pyawe.client.TaskTeamRolesClient ¶

TaskTeamRolesClient(http: _HttpSession)

Methods for task team-role assignment (/tasks/{id}/team-roles).

list ¶

list(task_id: UUID | str) -> builtins.list[TaskTeamRole]

Return all team-role assignments for a task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required

Returns:

Type	Description
`list[TaskTeamRole]`	List of :class:`~pyawe.models.TaskTeamRole` objects.

Raises:

Type	Description
`AweAuthError`	If not authenticated.

assign ¶

assign(task_id: UUID | str, team_role_id: UUID | str) -> TaskTeamRole

Assign a team role to a task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required
`team_role_id`	`UUID \| str`	UUID of the team role.	required

Returns:

Type	Description
`TaskTeamRole`	The created :class:`~pyawe.models.TaskTeamRole`.

Raises:

Type	Description
`AweNotFoundError`	If the task does not exist.
`AweAuthError`	If not authenticated.

remove ¶

remove(task_id: UUID | str, team_role_id: UUID | str) -> None

Remove a team-role assignment from a task.

Parameters:

Name	Type	Description	Default
`task_id`	`UUID \| str`	UUID of the task.	required
`team_role_id`	`UUID \| str`	UUID of the team role assignment to remove.	required

Raises:

Type	Description
`AweNotFoundError`	If the assignment does not exist.
`AweAuthError`	If not authenticated.