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

Confirm a tool execution.

Parameters:

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

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

List tool executions with pagination and filtering.

Parameters:

Name	Type	Description	Default
`page`	`int \| None`	Page number of the pagination (default 0).	`None`
`page_size`	`int \| None`	Page size of the pagination (max 10,000).	`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`

Returns:

Type	Description
`dict`	Dictionary containing paginated execution data.

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 (which hits the tools-service, has no project scoping, and returns a DTO shape missing project_id on most rows), 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": {...}}`.