Workflow

Base classes for Rowan workflows.

Workflow `pydantic-model`

Bases: BaseModel

Rowan workflow base model, returned by submit workflow functions.

Workflow data is not loaded by default to avoid unnecessary downloads that could impact performance. Call fetch_latest() to fetch and attach the workflow data.

Attributes:

Name	Type	Description
`name`	`str`	name of the workflow
`uuid`	`str`	UUID of the workflow
`created_at`	`datetime`	date and time the workflow was created
`updated_at`	`datetime \| None`	date and time the workflow was last updated
`started_at`	`datetime \| None`	date and time the workflow computation was started
`completed_at`	`datetime \| None`	date and time the workflow was completed
`status`	`Status`	status of the workflow
`parent_uuid`	`str`	UUID of the parent folder
`notes`	`str`	workflow notes
`starred`	`bool`	whether the workflow is starred
`public`	`bool`	whether the workflow is public
`public_until`	`datetime \| None`	date and time until which the workflow is temporarily public
`is_temporarily_public`	`bool`	whether temporary public access is currently active
`workflow_type`	`str`	type of the workflow
`data`	`dict[str, Any] \| None`	data of the workflow
`email_when_complete`	`bool`	whether to send an email when the workflow completes
`max_credits`	`int \| None`	maximum credits for the workflow
`webhook_url`	`int \| None`	URL that Rowan will POST to when the workflow completes
`submission_group_uuid`	`str \| None`	UUID shared by workflows submitted as one execution group
`elapsed`	`float \| None`	elapsed time of the workflow
`credits_charged`	`float`	number of credits charged for the workflow
`logfile`	`str`	workflow logfile

Show JSON schema:

{
  "$defs": {
    "Status": {
      "description": "Job execution status.",
      "enum": [
        0,
        1,
        2,
        3,
        4,
        5,
        6,
        7
      ],
      "title": "Status",
      "type": "integer"
    }
  },
  "description": "Rowan workflow base model, returned by submit workflow functions.\n\nWorkflow data is not loaded by default to avoid unnecessary downloads that could impact\nperformance. Call `fetch_latest()` to fetch and attach the workflow data.\n\nAttributes:\n    name: name of the workflow\n    uuid: UUID of the workflow\n    created_at: date and time the workflow was created\n    updated_at: date and time the workflow was last updated\n    started_at: date and time the workflow computation was started\n    completed_at: date and time the workflow was completed\n    status: status of the workflow\n    parent_uuid: UUID of the parent folder\n    notes: workflow notes\n    starred: whether the workflow is starred\n    public: whether the workflow is public\n    public_until: date and time until which the workflow is temporarily public\n    is_temporarily_public: whether temporary public access is currently active\n    workflow_type: type of the workflow\n    data: data of the workflow\n    email_when_complete: whether to send an email when the workflow completes\n    max_credits: maximum credits for the workflow\n    webhook_url: URL that Rowan will POST to when the workflow completes\n    submission_group_uuid: UUID shared by workflows submitted as one execution group\n    elapsed: elapsed time of the workflow\n    credits_charged: number of credits charged for the workflow\n    logfile: workflow logfile",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "uuid": {
      "title": "Uuid",
      "type": "string"
    },
    "created_at": {
      "format": "date-time",
      "title": "Created At",
      "type": "string"
    },
    "updated_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Updated At"
    },
    "started_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Started At"
    },
    "completed_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Completed At"
    },
    "object_status": {
      "$ref": "#/$defs/Status"
    },
    "parent_uuid": {
      "title": "Parent Uuid",
      "type": "string"
    },
    "notes": {
      "title": "Notes",
      "type": "string"
    },
    "starred": {
      "title": "Starred",
      "type": "boolean"
    },
    "public": {
      "title": "Public",
      "type": "boolean"
    },
    "public_until": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Public Until"
    },
    "is_temporarily_public": {
      "default": false,
      "title": "Is Temporarily Public",
      "type": "boolean"
    },
    "object_type": {
      "title": "Object Type",
      "type": "string"
    },
    "object_data": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Object Data"
    },
    "email_when_complete": {
      "title": "Email When Complete",
      "type": "boolean"
    },
    "max_credits": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Credits"
    },
    "elapsed": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Elapsed"
    },
    "credits_charged": {
      "title": "Credits Charged",
      "type": "number"
    },
    "object_logfile": {
      "title": "Object Logfile",
      "type": "string"
    },
    "compute_hardware": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Compute Hardware"
    },
    "submission_group_uuid": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Submission Group Uuid"
    }
  },
  "required": [
    "name",
    "uuid",
    "created_at",
    "object_status",
    "parent_uuid",
    "notes",
    "starred",
    "public",
    "object_type",
    "email_when_complete",
    "credits_charged",
    "object_logfile"
  ],
  "title": "Workflow",
  "type": "object"
}

Config:

populate_by_name: True

Fields:

name (str)
uuid (str)
created_at (datetime)
updated_at (datetime | None)
started_at (datetime | None)
completed_at (datetime | None)
status (Status)
parent_uuid (str)
notes (str)
starred (bool)
public (bool)
public_until (datetime | None)
is_temporarily_public (bool)
workflow_type (str)
data (dict[str, Any] | None)
email_when_complete (bool)
max_credits (int | None)
elapsed (float | None)
credits_charged (float)
logfile (str)
compute_hardware (str | None)
submission_group_uuid (str | None)

fetch_latest

fetch_latest(in_place: bool = False) -> Self

Loads workflow data from the database and updates the current instance.

Parameters:

Name	Type	Description	Default
`in_place`	`bool`	whether to update the current instance in-place	`False`

Returns:

Type	Description
`Self`	updated instance (self)

Raises:

Type	Description
`HTTPStatusError`	API request fails

update

update(name: str | None = None, parent_uuid: str | None = None, notes: str | None = None, starred: bool | None = None, email_when_complete: bool | None = None, public: bool | None = None, in_place: bool = False) -> Self

Updates a workflow in the API with new data.

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	new name for the workflow	`None`
`parent_uuid`	`str \| None`	UUID of the parent folder	`None`
`notes`	`str \| None`	description of the workflow	`None`
`starred`	`bool \| None`	whether the workflow is starred	`None`
`email_when_complete`	`bool \| None`	whether to send an email when complete	`None`
`public`	`bool \| None`	whether the workflow is public	`None`
`in_place`	`bool`	whether to update the current instance in-place	`False`

Raises:

Type	Description
`HTTPStatusError`	API request fails

temporarily_share

temporarily_share(duration_minutes: int, in_place: bool = False) -> Self

Temporarily make the workflow publicly accessible.

Temporary sharing does not change public. The returned workflow instead records the expiration in public_until and reports the active state through is_temporarily_public.

Parameters:

Name	Type	Description	Default
`duration_minutes`	`int`	number of minutes to share the workflow, up to 120	required
`in_place`	`bool`	whether to update the current instance in-place	`False`

Returns:

Type	Description
`Self`	workflow with the temporary sharing state returned by the API

Raises:

Type	Description
`HTTPStatusError`	API request fails

end_temporary_share

end_temporary_share(in_place: bool = False) -> Self

End temporary public access to the workflow.

Permanent public access through public is unaffected.

Parameters:

Name	Type	Description	Default
`in_place`	`bool`	whether to update the current instance in-place	`False`

Returns:

Type	Description
`Self`	workflow with the temporary sharing state returned by the API

Raises:

Type	Description
`HTTPStatusError`	API request fails

done

done() -> bool

Check if the workflow has finished (success, failure, or stopped).

Non-blocking check following the concurrent.futures.Future pattern.

Returns:

Type	Description
`bool`	true if workflow is no longer running

result

result(wait: bool = True, poll_interval: int = 5) -> R

Return the typed result, optionally waiting for completion.

Follows the concurrent.futures.Future.result() pattern.

Parameters:

Name	Type	Description	Default
`wait`	`bool`	block until completion; False returns the currently available data	`True`
`poll_interval`	`int`	seconds between status checks while waiting	`5`

Returns:

Type	Description
`R`	WorkflowResult subclass with typed access to results

Raises:

Type	Description
`WorkflowError`	workflow failed or was stopped. Inspect the exception's `logfile` attribute for the backend log

stream_result

stream_result(poll_interval: int = 5) -> Iterator[R]

Poll the workflow and yield results until complete.

Yields partial results at each poll interval while running, then yields the final complete result once the workflow finishes.

Parameters:

Name	Type	Description	Default
`poll_interval`	`int`	seconds between status checks	`5`

Yields:

Type	Description
`R`	WorkflowResult at each poll interval, with final complete result last

Raises:

Type	Description
`WorkflowError`	workflow fails or is stopped

wait_for_result

wait_for_result(poll_interval: int = 5) -> Self

Wait for the workflow to finish.

Deprecated

Use result instead, which waits and returns the typed result.

Returns:

Type	Description
`Self`	current instance (self)

get_status

get_status() -> stjames.Status

Gets the status of the workflow.

Returns:

Type	Description
`Status`	status of the workflow, as an instance of stjames.Status

is_finished

is_finished() -> bool

Check if the workflow is finished.

Deprecated

Use done instead.

Returns:

Type	Description
`bool`	true if the workflow status is COMPLETED_OK, FAILED, or STOPPED

stop

stop() -> None

Stops a workflow.

Raises:

Type	Description
`HTTPStatusError`	API request fails

delete

delete() -> None

Deletes the workflow.

Raises:

Type	Description
`HTTPStatusError`	API request fails

delete_data

delete_data() -> None

Deletes the workflow data from the API.

Raises:

Type	Description
`HTTPStatusError`	API request fails

dispatch_info

dispatch_info() -> DispatchInfo

Fetch estimated dispatch information for this workflow.

Returns:

Type	Description
`DispatchInfo`	estimated time, hardware, and queue info

Raises:

Type	Description
`HTTPStatusError`	API request fails

submit_draft

submit_draft() -> Self

Submit a draft workflow for execution.

Returns:

Type	Description
`Self`	updated workflow instance

Raises:

Type	Description
`WorkflowError`	workflow is not in DRAFT status
`HTTPStatusError`	API request fails

download_msa_files

download_msa_files(msa_format: MSAFormat, path: Path | str | None = None) -> None

Download MSA files for an MSA workflow.

Deprecated

Use workflow.result().download_files() instead.

download_dcd_files

download_dcd_files(replicates: list[int], name: str | None = None, path: Path | str | None = None) -> None

Downloads DCD trajectory files for specified replicates.

Deprecated

Use workflow.result().download_trajectories() instead.

Parameters:

Name	Type	Description	Default
`replicates`	`list[int]`	list of replicate indices to download	required
`name`	`str \| None`	optional custom name for the tar.gz file	`None`
`path`	`Path \| str \| None`	directory to save the file to	`None`

WorkflowResult `dataclass`

WorkflowResult(workflow_data: dict[str, Any], workflow_type: str, workflow_uuid: str, complete: bool = True)

Base class for workflow results.

Wraps the raw workflow data dict and parses it into a stjames object for typed access to nested data.

Attributes:

Name	Type	Description
`workflow_data`	`dict[str, Any]`	raw data dict from the workflow
`workflow_type`	`str`	workflow type string
`workflow_uuid`	`str`	UUID of the parent workflow (for API calls)

data `property`

data: dict[str, Any]

Raw workflow data dict for fallback access.

clear_cache

clear_cache() -> None

Clear all cached data to force re-fetching on next access.

Use this if you need to refresh lazily-loaded data (e.g., structures, calculations) from the API.

WorkflowError

WorkflowError(message: str, *, logfile: str = '')

Bases: Exception

Raised when a workflow cannot return a result.

The complete backend log is available through logfile rather than being included in the exception text. It provides diagnostic context only and is not a source of workflow result values.

Attributes:

Name	Type	Description
`message`		error summary
`logfile`		workflow log returned by the API, when available

Initialize the error with its summary and backend log.

Parameters:

Name	Type	Description	Default
`message`	`str`	error summary	required
`logfile`	`str`	workflow log returned by the API	`''`

DispatchInfo `dataclass`

DispatchInfo(to_be_dispatched: bool | None, compute_hardware: str | None, estimated_runtime_minutes: float | None)

Estimated dispatch information for a workflow.

Attributes:

Name	Type	Description
`to_be_dispatched`	`bool \| None`	whether workflow will be queued (vs starting immediately)
`compute_hardware`	`str \| None`	hardware type (CPU, H200, A100, etc.)
`estimated_runtime_minutes`	`float \| None`	estimated runtime in minutes, or None if unknown

Message `dataclass`

Message(title: str, body: str, type: str)

A workflow message (error, warning, or info).

Attributes:

Name	Type	Description
`title`	`str`	short message title
`body`	`str`	full message content
`type`	`str`	message type: 'error', 'warning', or 'info'

submit_workflow

submit_workflow(workflow_type: WORKFLOW_NAME, workflow_data: dict[str, Any] | None = None, initial_molecule: StructureInput | dict[str, Any] | None = None, initial_smiles: SMILES | None = None, name: str | None = None, folder_uuid: str | Folder | None = None, max_credits: int | None = None, webhook_url: str | None = None, is_draft: bool = False) -> Workflow[WorkflowResult]

Submits a workflow to the API.

Parameters:

Name	Type	Description	Default
`workflow_type`	`WORKFLOW_NAME`	type of workflow to submit	required
`workflow_data`	`dict[str, Any] \| None`	dictionary containing the data required to run the workflow	`None`
`initial_molecule`	`StructureInput \| dict[str, Any] \| None`	molecule object to use as the initial molecule	`None`
`initial_smiles`	`SMILES \| None`	SMILES string to use as the initial molecule	`None`
`name`	`str \| None`	name for the workflow	`None`
`folder_uuid`	`str \| Folder \| None`	UUID of the folder to store the workflow in, or a Folder object	`None`
`max_credits`	`int \| None`	maximum credits for the workflow	`None`
`webhook_url`	`str \| None`	URL that Rowan will POST to when the workflow completes	`None`
`is_draft`	`bool`	save as a draft without starting execution	`False`

Returns:

Type	Description
`Workflow[WorkflowResult]`	submitted workflow

Raises:

Type	Description
`ValueError`	neither `initial_smiles` nor a valid `initial_molecule` is provided
`HTTPStatusError`	API request fails

retrieve_workflow

retrieve_workflow(uuid: str) -> Workflow[WorkflowResult]

retrieve_workflow(uuid: str, *, result_type: type[R]) -> Workflow[R]

retrieve_workflow(uuid: str, *, result_type: type[WorkflowResult] = WorkflowResult) -> Workflow[WorkflowResult]

Retrieve a workflow from the API by UUID.

Parameters:

Name	Type	Description	Default
`uuid`	`str`	UUID of the workflow to retrieve	required
`result_type`	`type[WorkflowResult]`	expected result class for the retrieved workflow	`WorkflowResult`

Returns:

Type	Description
`Workflow[WorkflowResult]`	workflow object with the fetched data

Raises:

Type	Description
`ValueError`	workflow result does not match `result_type`
`HTTPStatusError`	API request fails

retrieve_workflows

retrieve_workflows(uuids: list[str]) -> list[Workflow[WorkflowResult]]

Retrieve a list of workflows from the API.

Parameters:

Name	Type	Description	Default
`uuids`	`list[str]`	UUIDs of the workflows to retrieve	required

Returns:

Type	Description
`list[Workflow[WorkflowResult]]`	retrieved workflows

Raises:

Type	Description
`HTTPStatusError`	API request fails

list_workflows

list_workflows(parent_uuid: str | None = None, name_contains: str | None = None, public: bool | None = None, starred: bool | None = None, status: int | None = None, workflow_type: WORKFLOW_NAME | None = None, page: int = 0, size: int = 10) -> list[Workflow[WorkflowResult]]

List workflows subject to the specified criteria.

Parameters:

Name	Type	Description	Default
`parent_uuid`	`str \| None`	UUID of the parent folder	`None`
`name_contains`	`str \| None`	substring to search for in workflow names	`None`
`public`	`bool \| None`	filter workflows by their public status	`None`
`starred`	`bool \| None`	filter workflows by their starred status	`None`
`status`	`int \| None`	filter workflows by their status	`None`
`workflow_type`	`WORKFLOW_NAME \| None`	filter workflows by their type	`None`
`page`	`int`	page number to retrieve	`0`
`size`	`int`	number of items per page	`10`

Returns:

Type	Description
`list[Workflow[WorkflowResult]]`	list of Workflow objects that match the search criteria

Raises:

Type	Description
`HTTPStatusError`	request to the API fails

batch_submit_workflow

batch_submit_workflow(workflow_type: WORKFLOW_NAME, workflow_data: dict[str, Any] | None = None, initial_molecules: list[StructureInput | dict[str, Any]] | None = None, initial_smileses: list[SMILES] | None = None, names: list[str] | None = None, folder_uuid: str | Folder | None = None, max_credits: int | None = None, webhook_url: str | None = None) -> list[Workflow[WorkflowResult]]

Submits a batch of workflows to the API.

Each workflow will be submitted with the same workflow type, workflow data, and folder UUID, but with different initial molecules and/or SMILES strings.

Parameters:

Name	Type	Description	Default
`workflow_type`	`WORKFLOW_NAME`	type of workflow to submit	required
`workflow_data`	`dict[str, Any] \| None`	dictionary containing the data required to run the workflow	`None`
`initial_molecules`	`list[StructureInput \| dict[str, Any]] \| None`	molecule objects to use as initial molecules	`None`
`initial_smileses`	`list[SMILES] \| None`	SMILES strings to use as initial molecules	`None`
`names`	`list[str] \| None`	names for the submitted workflows	`None`
`folder_uuid`	`str \| Folder \| None`	UUID of the folder to store the workflows in	`None`
`max_credits`	`int \| None`	maximum number of credits to use per workflow	`None`
`webhook_url`	`str \| None`	URL to call when each workflow completes	`None`

Returns:

Type	Description
`list[Workflow[WorkflowResult]]`	list of Workflow objects representing the submitted workflows

batch_poll_status

batch_poll_status(uuids: list[str]) -> dict[str, int]

Poll the status of a list of workflows.

Parameters:

Name	Type	Description	Default
`uuids`	`list[str]`	UUIDs of the workflows to poll	required

Returns:

Type	Description
`dict[str, int]`	counts keyed by lower-case status name, plus the total workflow count

Raises:

Type	Description
`HTTPStatusError`	API request fails

Workflow

Workflow pydantic-model

fetch_latest

update

temporarily_share

end_temporary_share

done

result

stream_result

wait_for_result

get_status

is_finished

stop

delete

delete_data

dispatch_info

submit_draft

download_msa_files

download_dcd_files

WorkflowResult dataclass

data property

clear_cache

WorkflowError

DispatchInfo dataclass

Message dataclass

submit_workflow

retrieve_workflow

retrieve_workflows

list_workflows

batch_submit_workflow

batch_poll_status

Workflow `pydantic-model`

WorkflowResult `dataclass`

data `property`

DispatchInfo `dataclass`

Message `dataclass`