Tools API.¶

The DeepOriginClient can be used to access the tools API using:

from deeporigin.platform.client import DeepOriginClient

client = DeepOriginClient()

Then, the following methods can be used, for example:

tools = client.executions.list()

src.platform.executions.Executions ¶

Executions API wrapper.

Provides access to tool execution-related endpoints through the DeepOriginClient.

Functions¶

cancel ¶

cancel(execution_id: str) -> None

Cancel a tool execution.

Parameters:

Name	Type	Description	Default
`execution_id`	`str`	The execution ID to cancel.	required

Returns:

Type	Description
`None`	None. If the execution is already in a terminal state, returns early.

confirm ¶

confirm(
    execution_id: str,
    *,
    timeout: float | None = None,
    retry: bool = True
) -> None

Confirm a tool execution.

Parameters:

Name	Type	Description	Default
`execution_id`	`str`	The execution ID to confirm.	required
`timeout`	`float \| None`	Optional HTTP timeout in seconds for this request. When `None`, the client's default timeout applies.	`None`
`retry`	`bool`	When `True` (default), use the client's retry policy for transient failures. Set `False` for a single attempt.	`True`

Returns:

Type	Description
`None`	None.

create ¶

create(
    *,
    tool_key: str,
    tool_version: str,
    data: dict,
    timeout: float | None = None
) -> dict

Create (run) an execution of a tool with a specific version.

Parameters:

Name	Type	Description	Default
`tool_key`	`str`	Key of the tool to run.	required
`tool_version`	`str`	Version of the tool to run.	required
`data`	`dict`	Data transfer object (DTO) containing tool execution parameters. This is typically generated by the `make_payload` function. If "clusterId" is not present, it will be set to the default cluster ID.	required
`timeout`	`float \| None`	HTTP timeout in seconds for this request. If None, uses `TOOL_EXECUTION_POST_TIMEOUT_SECONDS` (600s), since quoting and synchronous execution creation can exceed the client's default short timeout (e.g. molprops, protonation, system-prep).	`None`

Returns:

Type	Description
`dict`	Dictionary containing the execution response from the API.

Raises:

Type	Description
`Exception`	If the tool execution fails, with error details printed.

from_data_platform ¶

from_data_platform(data_platform_execution_id: str) -> dict

Get an execution from the data-platform API by its execution identifier.

This identifier is not the same as the tools-service execution_id used by :meth:get.

Parameters:

Name	Type	Description	Default
`data_platform_execution_id`	`str`	Data-platform execution ID (e.g. from search UIs).	required

Returns:

Type	Description
`dict`	Dictionary containing the execution record from the data platform.

get ¶

get(execution_id: str) -> dict

Get a tool execution by execution ID.

Parameters:

Name	Type	Description	Default
`execution_id`	`str`	The execution ID to fetch.	required

Returns:

Type	Description
`dict`	Dictionary containing the tool execution data.

list ¶

list(
    *,
    page: int | None = None,
    page_size: int | None = None,
    order: str | None = None,
    tool_key: str | None = None,
    session: str | None = None,
    project_id: str | None = None,
    created_after: datetime | str | None = None,
    fetch_all_pages: bool = False
) -> dict

List tool executions with pagination and filtering.

Parameters:

Name	Type	Description	Default
`page`	`int \| None`	Page number of the pagination (default 0). Ignored when `fetch_all_pages` is `True`.	`None`
`page_size`	`int \| None`	Page size of the pagination (max 10,000). When `fetch_all_pages` is `True` and this is `None`, uses `1000`.	`None`
`order`	`str \| None`	Order of the pagination, e.g., "executionId? asc", "completedAt? desc".	`None`
`tool_key`	`str \| None`	Tool key to filter by.	`None`
`session`	`str \| None`	Session identifier to filter by. Returns only executions tagged with this session on creation (see `executions.create` where `payload["session"] = self._c._session`). Without this, the endpoint returns all executions the caller can see, not just ones from the caller's own client.	`None`
`project_id`	`str \| None`	When set, restrict to executions whose root-level `projectId` matches (same field as in the tools execution DTO; may be omitted or null on rows that are not project-scoped).	`None`
`created_after`	`datetime \| str \| None`	When set, restrict to rows with `createdAt` strictly after this instant. Passed to the tools-service list filter as `createdAt: {"$gt": "<iso-8601>"}` (MikroORM operator on the entity `createdAt` column). Use a timezone-aware :class:`~datetime.datetime` or an ISO string such as `2026-05-07T15:13:25.254Z`.	`None`
`fetch_all_pages`	`bool`	When `True`, follow pagination until every row for the filter is collected, merge `data` in page order, and return `{"data": [...], "count": <total>}`. When `False`, performs a single request using `page` / `page_size`.	`False`

Returns:

Type	Description
`dict`	Dictionary containing paginated execution data (or all rows when
`dict`	`fetch_all_pages` is `True`).

search ¶

search(
    *,
    project_id: str | None = None,
    tool_key: list[str] | str | None = None,
    status: str | None = None,
    extra_props: list[dict[str, Any]] | None = None,
    limit: int | None = None,
    offset: int | None = None,
    select: list[str] | None = None,
    with_total_count: bool = False,
    compute_job_id: str | None = None
) -> dict

Search executions via the data-platform endpoint.

Unlike :meth:list (tools-service DTO with camelCase projectId; use list(project_id=...) to filter there), this method hits POST /data-platform/{org}/executions/search which:

exposes project_id as a first-class column and applies it as a server-side filter when provided,
returns rows with snake_case columns (tool_key, started_at, project_id, ...) and tags (app + session) / compute_metadata (userInputs, ...) as nested objects,
supports the standard data-platform {"props": [...]} filter grammar with eq / neq / in / ... ops.

Parameters:

Name	Type	Description	Default
`project_id`	`str \| None`	Scope to this project. Strongly recommended — without it the response spans every execution the caller can see.	`None`
`tool_key`	`list[str] \| str \| None`	Equality filter on `tool_key` (e.g. `"deeporigin.bulk-docking"`).	`None`
`status`	`str \| None`	Equality filter on `status` (e.g. `"Completed"`, `"Failed"`, `"Running"`).	`None`
`extra_props`	`list[dict[str, Any]] \| None`	Additional filter props appended to the built-in ones. Each prop is a dict with `{"column": str, "op": str, "value": Any}`.	`None`
`limit`	`int \| None`	Max rows to return.	`None`
`offset`	`int \| None`	Skip offset.	`None`
`select`	`list[str] \| None`	Columns to select; all columns by default.	`None`
`with_total_count`	`bool`	When True, the server returns a total count alongside the page (may be slower).	`False`

Returns:

Type	Description
`dict`	The raw response dict, typically `{"data": [...], "meta": {...}}`.

wait ¶

wait(
    executions: str | list[str],
    *,
    poll_interval: float = 5.0,
    timeout: float | None = None
) -> list[dict]

Block until every given execution reaches a terminal state.

Periodically polls the platform via :meth:get for each execution whose status is not yet in :data:~deeporigin.platform.constants.TERMINAL_STATES, sleeping poll_interval seconds between polling cycles. Once all executions have terminated (or timeout elapses), returns the latest DTOs in the same order as the input.

Parameters:

Name	Type	Description	Default
`executions`	`str \| list[str]`	A single execution ID string, or a list of execution ID strings to wait on.	required
`poll_interval`	`float`	Seconds to sleep between polling cycles. Must be positive. Defaults to `5.0`.	`5.0`
`timeout`	`float \| None`	Maximum total seconds to wait. If `None` (default), waits indefinitely. When set and exceeded before all executions terminate, raises :class:`TimeoutError`.	`None`

Returns:

Type	Description
`list[dict]`	Latest execution DTOs (one per input), each in a terminal state.

Raises:

Type	Description
`ValueError`	If `executions` is empty, `poll_interval` is not positive, or any execution ID is an empty string.
`TimeoutError`	If `timeout` is set and elapses before every execution reaches a terminal state.