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()

To block until an execution's results are available on the data platform, use wait_for_ingestion. It is woken by change notifications, and also re-checks the execution about every 90 seconds, so it still finishes if a notification is lost. While notifications are unavailable it checks every 2 seconds instead. Hidden executions are waited on too. It returns the execution record once the execution has finished (completed, failed or cancelled), so check its status:

row = client.executions.wait_for_ingestion(execution_id, project_id=project_id)
if row["status"] != "Completed":
    ...

See the wait-for-ingestion notebook for a full example.

src.platform.executions.Executions ¶

Executions API wrapper.

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

Methods:¶

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
) -> dict[str, Any]

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
`dict[str, Any]`	Updated execution DTO from the platform (same shape as :meth:`get`).

Raises:

Type	Description
`PlatformRestrictionError`	If licensing or billing rejects confirmation.

create ¶

create(
    *,
    tool_key: str,
    tool_version: str,
    data: dict,
    timeout: float | None = None,
    visibility: ExecutionVisibility | 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). When `client.tag` is set, it is sent as `tag` unless the caller already included `tag` in `data`. When `client.billing_tag` is set, it is sent as `billing` unless the caller already included `billing` in `data`. Uses `retry=False` so a failed create (including gateway 504) is not retried; retries can otherwise duplicate long sync jobs.	`None`
`visibility`	`ExecutionVisibility \| None`	Optional activity-history visibility, `"visible"` or `"hidden"`. `"hidden"` opts the run out of user-facing activity views (it still exists, and stays visible to admin/audit/billing). Sent unless the caller already included `visibility` in `data`. Falls back to the client-level `_visibility` default when both are unset; when every source is `None` the key is omitted and the server decides. Validated whichever source supplies it. Note `data={"visibility": None}` does not suppress a client-level default -- `None` reads as "unset" at every level, so resolution falls through to it. To force one run visible on a client that defaults to hidden, pass `visibility="visible"` explicitly.	`None`

Returns:

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

Raises:

Type	Description
`ValueError`	If the resolved `visibility` -- from `data`, the argument, or the client default -- is not `"visible"` or `"hidden"`.
`PlatformRestrictionError`	If licensing or billing rejects execution. The exception preserves the platform reason, action, and response.

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.

Requests the tools-service v2.0 execution DTO (Accept: application/json;v=2.0), which includes the enhanced progressReport tree. Top-level fields such as executionId, status, userInputs, and jobOutputs match the v1 shape used elsewhere in this library.

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,
    include_hidden: bool = False
) -> 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`
`compute_job_id`	`str \| None`	Equality filter on `compute_job_id` (the tools-service execution id).	`None`
`include_hidden`	`bool`	When True, also return runs submitted with `visibility="hidden"`, which the search omits by default.	`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.
`list[dict]`	List inputs retain all results, including rejected executions.

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.
`PlatformRestrictionError`	For a single string ID, if licensing or billing rejected execution. List inputs return rejected DTOs.

wait_for_ingestion ¶

wait_for_ingestion(
    execution_id: str,
    *,
    project_id: str | None = None,
    timeout: (
        int | float
    ) = DATA_PLATFORM_INGESTION_TIMEOUT_SECONDS
) -> dict

Block until an execution's data-platform ingestion has finished.

Woken by the gateway's SSE stream rather than by polling. Data-platform holds an execution at DataIngesting until its results are ingested, so a status in :data:~deeporigin.platform.constants.TERMINAL_STATES means ingestion is done. The stream watches execution:{execution_id}; each filters.dirty frame re-reads the row via :meth:search with include_hidden=True, since client runs are submitted hidden. The row is also re-read on every connect, and each stream is opened before its read, so a completion in between is not missed.

Frames are not replayed, so while the stream is open a sweep re-reads the row whenever DATA_PLATFORM_INGESTION_SWEEP_SECONDS pass without a read. Every read pushes the sweep back, so it only fires when the stream has gone quiet. While the stream is closed, dropped or refused, the row is polled every DATA_PLATFORM_INGESTION_POLL_SECONDS instead.

A stream that closed, dropped with a network error or was refused with a retryable status is reopened after a jittered pause that doubles from SSE_RECONNECT_BACKOFF_SECONDS up to SSE_RECONNECT_MAX_BACKOFF_SECONDS. A stream that stayed open for SSE_STABLE_CONNECTION_SECONDS resets the pause. An open stream is cut off at the deadline, so a read waiting on the next heartbeat cannot carry the wait past timeout. A row re-read already in flight at the deadline uses the client's own request timeout and retries.

Parameters:

Name	Type	Description	Default
`execution_id`	`str`	Tools-service execution id (data-platform `compute_job_id`).	required
`project_id`	`str \| None`	Project the execution belongs to. Defaults to the client's `project_id`.	`None`
`timeout`	`int \| float`	Maximum total seconds to wait.	`DATA_PLATFORM_INGESTION_TIMEOUT_SECONDS`

Returns:

Type	Description
`dict`	The data-platform execution row, in a terminal state. A legacy
`dict`	`Succeeded` status is returned as `Completed`. Failed and
`dict`	cancelled executions are returned, not raised; check `status`.

Raises:

Type	Description
`ValueError`	If `execution_id` is empty or no project id is set.
`TimeoutError`	If ingestion does not finish within `timeout`.
`DeepOriginException`	If the gateway refuses the stream with a non-retryable status (e.g. 401, 403, 404); if the backend does not support `include_hidden`; or if a data-platform read fails with a non-retryable status, or with a 5xx that outlasts the client's retries.