`deeporigin.drug_discovery.execution`¶

Base class for jobs-centric execution objects (Docking, ABFE, etc.).

Use :meth:Execution.sync to refresh any instance that already has an execution id (including sync-only tools and objects built from from_dto).

Quote mode (sync vs async)¶

quote() creates a persisted tools execution with approveAmount=0. The payload is built by :meth:Execution._make_payload and must match the path you will use after :meth:Execution.confirm:

quote(mode="async") — same shape as a later async :meth:~deeporigin.drug_discovery.execution_mixins.AsyncExecutableMixin.start (after confirm).
quote(mode="sync") — same shape as a blocking :meth:~deeporigin.drug_discovery.execution_mixins.SyncExecutableMixin.run.

confirm() only sends executionId to the platform; it cannot change inputs or switch sync/async. The SDK stores _quoted_mode so start() rejects a sync-mode quote and run() can reject an async-mode quote (see each tool).

Base class for the jobs-centric API.

Provides Execution -- a base class with read-only @property descriptors for system-managed fields, platform id, and confirm() for tools executions, lifecycle state management, :attr:Execution.runtime from DTO timestamps, plus from_id() / :meth:Execution.list delegate to :meth:Execution.from_dto. :meth:Execution.sync refreshes an instance from executions.get (any execution class, including sync-only or objects built from a stale DTO). :meth:Execution.update_from_dto applies the same fields to an existing instance (for example after executions.create). The base from_dto hydrates tools execution fields from the DTO; concrete types override it, call super().from_dto(), then restore domain-specific state from userInputs. Subclasses also expose immutable input fields as read-only properties and compose with mixins (SyncExecutableMixin, AsyncExecutableMixin) to build concrete execution types like PocketFinder, Docking, and ABFE.

Quoting is handled directly by run() and start() via quote=True (sugar for approve_amount=0) or an explicit approve_amount. When the platform returns a Quoted DTO the instance is left in that state -- no automatic confirmation is performed.

Attributes¶

QuoteMode `module-attribute` ¶

QuoteMode = Literal['sync', 'async']

Classes¶

Execution ¶

Base class for all execution types in the jobs-centric API.

System-managed fields estimate and cost are exposed as read-only properties. Platform execution id and confirm() live on this class for tool-backed jobs. Subclasses implement :meth:_make_payload to build create payloads; they receive sync: bool and approve_amount directly.

Rehydration: :meth:from_dto on this base class performs shared tools DTO hydration (executionId, pricing, lifecycle fields, _dto). Concrete subclasses must override :meth:from_dto, call super().from_dto(), then attach domain-specific state from userInputs (see :class:~deeporigin.drug_discovery.docking.Docking and :class:~deeporigin.drug_discovery.pocket_finder.PocketFinder). Calling :meth:from_id or :meth:list on :class:Execution itself raises NotImplementedError (no tool_key on the bare base class).

To align with the platform after a job was updated elsewhere (for example the web UI) or to poll status, call :meth:sync whenever :attr:id is set; it is not limited to async subclasses.

Attributes:

Name	Type	Description
`estimate`	`float \| None`	Cost estimate in dollars, populated from the DTO quotation result.
`cost`	`float \| None`	Actual cost in dollars, set after execution completes.
`id`	`str \| None`	Platform execution id when set (read-only :class:`property`; backed by `_id`).
`dto`	`dict[str, Any] \| None`	Last tools execution DTO from the platform, if any (read-only `property`; backed by `_dto`).
`name`	`str \| None`	Optional user label; writable until execution `id` is set, then read-only (`property`; backed by `_name`).
`runtime`	`float \| None`	Elapsed seconds from DTO `startedAt` to `completedAt` or now; see property.
`tool_key`	`str`	Platform tool key identifying this execution type (class attribute on concrete subclasses; may be updated from the DTO in :meth:`update_from_dto`).
`tool_version`	`str`	Version string for the tool (updated from the DTO like `tool_key`).
`_id`	`str \| None`	Internal storage for the execution UUID; use :attr:`id` for reads. Subclasses and tests may assign before the property is wired from the platform.
`_dto`	`dict[str, Any] \| None`	Internal storage for the raw execution dict; use :attr:`dto` for reads.
`_name`	`str \| None`	Internal storage for the display name; use :attr:`name` and its setter.

Attributes¶

client `instance-attribute` ¶

client: DeepOriginClient = client

cost `property` ¶

cost: float | None

Actual cost in dollars, set after execution completes.

This property cannot be set manually.

dto `property` ¶

dto: dict[str, Any] | None

Last tools execution DTO from the platform, if any.

estimate `property` ¶

estimate: float | None

Cost estimate in dollars, populated when the platform returns a quotation.

Set after run(quote=True), start(quote=True), or any call with approve_amount=0. None until a quotation result is received. This property cannot be set manually.

id `property` ¶

id: str | None

Platform execution ID when set (read-only).

name `property` `writable` ¶

name: str | None

Optional user-defined label for this execution.

May be set or changed only while id is unset. After an execution ID exists, name is read-only.

runtime `property` ¶

runtime: float | None

Seconds from DTO startedAt to completedAt or current UTC time.

Uses :attr:dto (same shape as client.executions.get). When completedAt is present, it is the end time; otherwise the end time is datetime.now(timezone.utc). Returns None if there is no DTO or startedAt is missing or empty.

tool_key `class-attribute` `instance-attribute` ¶

tool_key: str = ''

Functions¶

confirm ¶

confirm() -> None

Confirm a quoted tools execution on the platform.

Requires :attr:id and status equal to "Quoted". Uses :meth:~deeporigin.platform.executions.Executions.confirm with :data:~deeporigin.utils.constants.TOOL_EXECUTION_POST_TIMEOUT_SECONDS (10 minutes) and retry=False.

Raises:

Type	Description
`ValueError`	If there is no platform execution id or status is not `"Quoted"`.

duplicate ¶

duplicate(
    *, client: DeepOriginClient | None = None
) -> Self

Create a fresh copy with the same configuration but no execution state.

Useful after from_id() to re-run the same calculation. The returned instance has no id, status, estimate, or cost — it is ready for run() / start().

Parameters:

Name	Type	Description	Default
`client`	`DeepOriginClient \| None`	Optional API client for the new instance. Falls back to the current instance's client.	`None`

Returns:

Type	Description
`Self`	A new instance sharing the same domain-specific configuration.

from_dto `classmethod` ¶

from_dto(
    dto: dict[str, Any],
    *,
    client: DeepOriginClient | None = None
) -> Self

Construct an instance from an execution DTO returned by the platform API.

Creates a bare instance via object.__new__ (bypassing __init__) and populates common tools execution fields (including :attr:name from the DTO name field) via :meth:update_from_dto. If the instance defines _init_after_from_dto (e.g. :class:~deeporigin.drug_discovery.notebook_watch_mixin.NotebookWatchMixin), it is called after common fields are set. Subclasses should call super().from_dto() then rehydrate domain-specific fields from instance._dto["userInputs"].

Parameters:

Name	Type	Description	Default
`dto`	`dict[str, Any]`	Execution payload (same shape as `client.executions.get`).	required
`client`	`DeepOriginClient \| None`	Optional API client. Uses the default if not provided.	`None`

Returns:

Type	Description
`Self`	A partially-hydrated instance with common fields populated.

Raises:

Type	Description
`NotImplementedError`	If `cls` has no `tool_key` (bare :class:`Execution`).
`ValueError`	If the DTO `tool.key` does not match `cls.tool_key`.

from_id `classmethod` ¶

from_id(
    id: str, *, client: DeepOriginClient | None = None
) -> Self

Construct an instance from an existing platform execution ID.

Fetches the execution DTO via client.executions.get and delegates to :meth:from_dto. Concrete subclasses override :meth:from_dto to attach domain state from userInputs.

Parameters:

Name	Type	Description	Default
`id`	`str`	Platform execution ID.	required
`client`	`DeepOriginClient \| None`	Optional API client. Uses the default if not provided.	`None`

Returns:

Type	Description
`Self`	A partially-hydrated instance with common fields populated.

Raises:

Type	Description
`NotImplementedError`	If `cls` has no `tool_key` (bare :class:`Execution`).

get_results ¶

get_results(**kwargs: Any) -> Any

Fetch results for this execution from the data platform.

Thin wrapper around :meth:deeporigin.platform.results.Results.get scoped to this execution's compute_job_id. Subclasses that need result-type-specific filtering (e.g. poses, prepared systems) should override this method and call the appropriate Results wrapper directly rather than teaching this base method about those filters.

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	Forwarded verbatim to :meth:`~deeporigin.platform.results.Results.get` (typically `filter_dict`, `limit`, `select`).	`{}`

Returns:

Type	Description
`Any`	Result-explorer response dict with `data` and `meta` keys.

Raises:

Type	Description
`ValueError`	If the execution has no ID yet.

get_user_logs ¶

get_user_logs(
    *,
    limit: int | None = None,
    offset: int | None = None,
    select: list[str] | None = None,
    with_total_count: bool = False
) -> dict[str, Any] | None

Search data-platform user_logs rows for this execution.

Uses :meth:deeporigin.platform.user_logs.UserLogs.search with this execution's id (tools executionId), stored as execution_id on user_logs rows — the same string passed to :meth:get_results as compute_job_id.

When no execution id is assigned yet, returns None without calling the API.

Parameters:

Name	Type	Description	Default
`limit`	`int \| None`	Max rows to return (forwarded to `UserLogs.search`).	`None`
`offset`	`int \| None`	Skip offset (forwarded).	`None`
`select`	`list[str] \| None`	Columns to select (forwarded).	`None`
`with_total_count`	`bool`	Request total count from the server (forwarded).	`False`

Returns:

Type	Description
`dict[str, Any] \| None`	The search response dict (typically `data` / `meta`), or
`dict[str, Any] \| None`	`None` if this instance has no execution id yet.

list `classmethod` ¶

list(
    *,
    client: DeepOriginClient | None = None,
    status: list[str] | None = None
) -> list[Self]

List executions of this tool type from the platform.

Calls client.executions.list(fetch_all_pages=True, tool_key=...), then builds instances via :meth:from_dto. Optional status filters hydrated instances by instance.status.

Parameters:

Name	Type	Description	Default
`client`	`DeepOriginClient \| None`	Optional API client. Uses the default if not provided.	`None`
`status`	`list[str] \| None`	Optional list of statuses to keep (membership test).	`None`

Returns:

Type	Description
`list[Self]`	Instances of this class, one per matching execution.

Raises:

Type	Description
`NotImplementedError`	If `cls` has no `tool_key` (bare :class:`Execution`).

sync ¶

sync() -> None

Fetch the latest tools execution from the platform and refresh fields.

Calls client.executions.get for :attr:id and applies the response with :meth:update_from_dto. Use when the job may have changed outside this process (for example after submission from the web UI), to poll lifecycle state, or to refresh an instance built from an older DTO. Available on sync-only and async execution types alike.

If executions.get returns a falsy value, this instance is left unchanged.

Raises:

Type	Description
`ValueError`	If this instance has no execution id yet.
`NotImplementedError`	If `type(self).tool_key` is empty (bare :class:`Execution`).
`ValueError`	If the returned DTO `tool.key` does not match this class (see :meth:`update_from_dto`).

update_from_dto ¶

update_from_dto(dto: dict[str, Any]) -> None

Apply tools execution fields from dto onto this instance.

Updates id, pricing, lifecycle fields, and _dto the same way as :meth:from_dto for a newly created instance. Use after a live executions.create / sync() response to refresh state without constructing a new object (domain inputs on self are unchanged).

Parameters:

Name	Type	Description	Default
`dto`	`dict[str, Any]`	Execution payload (same shape as `client.executions.get`).	required

Raises:

Type	Description
`NotImplementedError`	If `type(self)` has no `tool_key` (bare :class:`Execution`).
`ValueError`	If the DTO `tool.key` does not match `tool_key`.

deeporigin.drug_discovery.execution¶

Quote mode (sync vs async)¶

Attributes¶

QuoteMode module-attribute ¶

Classes¶

Execution ¶

Attributes¶

client instance-attribute ¶

cost property ¶

dto property ¶

estimate property ¶

id property ¶

name property writable ¶

runtime property ¶

tool_key class-attribute instance-attribute ¶

Functions¶

confirm ¶

duplicate ¶

from_dto classmethod ¶

from_id classmethod ¶

get_results ¶

get_user_logs ¶

list classmethod ¶

sync ¶

update_from_dto ¶

`deeporigin.drug_discovery.execution`¶

QuoteMode `module-attribute` ¶

client `instance-attribute` ¶

cost `property` ¶

dto `property` ¶

estimate `property` ¶

id `property` ¶

name `property` `writable` ¶

runtime `property` ¶

tool_key `class-attribute` `instance-attribute` ¶

from_dto `classmethod` ¶

from_id `classmethod` ¶

list `classmethod` ¶