`deeporigin.drug_discovery.pocket_finder`¶

PocketFinder -- find binding pockets via synchronous or asynchronous execution.

Sync usage (blocking, returns pockets directly)::

pf = PocketFinder(protein)
pf.run(quote=True)   # populates pf.estimate; pf.status == "Quoted"
pockets = pf.run()   # blocking; calls get_results(); populates pf.cost

Async usage (persisted execution, watch in notebook)::

pf = PocketFinder(protein)
pf.start()            # submits async; sets pf.id and pf.status
await pf.watch()      # live Jupyter updates (or pf.sync() in a loop)
pockets = pf.get_results()

Attributes¶

Classes¶

PocketFinder ¶

Bases: Execution, SyncExecutableMixin, AsyncExecutableMixin, NotebookWatchMixin

Find binding pockets in a protein structure.

The execution request body includes sync (true = blocking, false = immediate DTO). :meth:run sets "sync": true and blocks until the run finishes. :meth:start sets "sync": false in inputs (non-blocking); start returns immediately with an execution DTO that you can poll with :meth:sync (or watch with :meth:watch / :meth:watch_async in Jupyter). Track async jobs with :meth:sync, :meth:from_id, and :meth:list.

Attributes:

Name	Type	Description
`protein`	`Protein`	The protein to analyse.
`pocket_count`	`int`	Maximum number of pockets to detect.
`pocket_min_size`	`int`	Minimum pocket volume in cubic Angstroms.

Attributes¶

app `instance-attribute` ¶

app: str | None = None

approve_amount `instance-attribute` ¶

approve_amount: int | None = None

client `instance-attribute` ¶

client: DeepOriginClient = client

completed_at `instance-attribute` ¶

completed_at: str | None = None

cost `property` ¶

cost: float | None

Actual cost in dollars, set after execution completes.

This property cannot be set manually.

created_at `instance-attribute` ¶

created_at: str | None = None

created_by `instance-attribute` ¶

created_by: str | None = None

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.

pocket_count `property` ¶

pocket_count: int

Maximum number of pockets to detect.

pocket_min_size `property` ¶

pocket_min_size: int

Minimum pocket volume in cubic Angstroms.

progress `instance-attribute` ¶

progress: dict | None = None

protein `property` ¶

protein: Protein

The protein to analyse.

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.

session `instance-attribute` ¶

session: str | None = None

started_at `instance-attribute` ¶

started_at: str | None = None

status `instance-attribute` ¶

status: PlatformStatus | None = None

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

tool_key: str = TOOL_KEYS_AND_VERSIONS["pocket_finder"][
    "tool_key"
]

tool_version `instance-attribute` ¶

tool_version = tool_version

Functions¶

cancel ¶

cancel() -> None

Cancel a running or queued execution.

Raises:

Type	Description
`ValueError`	If the job has no execution ID.
`ValueError`	If the job is not in a cancellable state.

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, then applies the returned DTO via :meth:update_from_dto so status, :attr:cost, and :attr:dto reflect the platform response. For direct (blocking) tools the response is typically terminal (Succeeded); for async tools it may be Created or Running — call :meth:sync until the job finishes.

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 a PocketFinder from a tools execution DTO.

Rehydrates protein, pocket_count, and pocket_min_size from userInputs (falling back to inputs for older payloads). The protein is loaded with Protein.from_id(..., download=False) and remote_path_override from the stored input, matching :meth:_make_payload / :meth:Docking.from_dto.

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 `PocketFinder` with `id`, pricing fields, and domain inputs set.

Raises:

Type	Description
`ValueError`	If `protein.id` is missing from stored inputs.

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(
    dto: dict[str, Any] | None = None,
) -> list[Pocket]

Load pockets for this execution from the data platform or jobOutputs.

Tries :meth:~deeporigin.drug_discovery.structures.pocket.Pocket.from_result first. On failure, parses jobOutputs.pockets from dto, or from client.executions.get when dto is omitted (for example after :meth:~deeporigin.drug_discovery.execution.Execution.from_id).

Parameters:

Name	Type	Description	Default
`dto`	`dict[str, Any] \| None`	Optional execution payload (`executions.create` / `executions.get`). Passing it avoids an extra GET when the data platform path fails but the sync response included `jobOutputs`.	`None`

Returns:

Type	Description
`list[Pocket]`	List of `Pocket` objects for this execution.

Raises:

Type	Description
`ValueError`	If :attr:`id` is unset.
`DeepOriginException`	If no pockets could be loaded from the data platform or `jobOutputs`.

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`).

run ¶

run(
    *,
    quote: bool = False,
    approve_amount: int | None = None
) -> list[Pocket] | None

Execute pocket finding synchronously (blocking).

Submits one synchronous tools execution (sync=True) and returns the detected pockets via :meth:get_results. The server blocks until the run completes; use :meth:start for async, persisted execution.

Pass quote=True (or approve_amount=0) to request a cost estimate only. In that case the platform returns a Quoted DTO, the instance is updated with estimate and status="Quoted", and None is returned.

Parameters:

Name	Type	Description	Default
`quote`	`bool`	Shorthand for `approve_amount=0`.	`False`
`approve_amount`	`int \| None`	Spend cap forwarded to the platform as `approveAmount`.	`None`

Returns:

Type	Description
`list[Pocket] \| None`	List of `Pocket` objects, or `None` when the platform responds
`list[Pocket] \| None`	with `Quoted` status.

Raises:

Type	Description
`DeepOriginException`	If no pockets could be loaded from the data platform or `jobOutputs`.

show ¶

show() -> None

Display the current execution in Jupyter using the execution card HTML view.

If no platform execution ID exists yet, shows the same card with a short notice instead of raising (see :meth:~deeporigin.platform.execution_display.ExecutionDisplay.from_pending).

start ¶

start(
    *,
    quote: bool = False,
    approve_amount: int | None = None,
    **kwargs
) -> None

Submit a persisted async execution to the platform.

Only valid when status is None (no execution exists yet). All other statuses raise immediately to prevent re-submission.

Pass quote=True or approve_amount=0 to request a cost estimate without running. If the platform returns a Quoted DTO the instance is left in that state — call :meth:~deeporigin.drug_discovery.execution.Execution.confirm explicitly to proceed.

Parameters:

Name	Type	Description	Default
`quote`	`bool`	Shorthand for `approve_amount=0`. Takes precedence when both `quote` and `approve_amount` are provided.	`False`
`approve_amount`	`int \| None`	Spend cap passed to the platform as `approveAmount`. `0` requests a quote only. `None` omits the field (platform runs immediately).	`None`
`**kwargs`		Forwarded verbatim to `_start_impl`.	`{}`

Raises:

Type	Description
`ValueError`	If the current status is not `None`.

stop_watching ¶

stop_watching() -> None

Cancel an in-flight :meth:watch_async loop if one is running.

Safe to call when no watch is active. Does not cancel the caller's current task when invoked from inside :meth:watch_async.

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`.

watch `async` ¶

watch(*, interval: float = 5.0) -> Task

Schedule :meth:watch_async and return the :class:asyncio.Task immediately.

In Jupyter, awaiting this coroutine finishes in one event-loop turn, so the cell returns while the display keeps updating in the background (similar to legacy Job.watch()). Use this when you need to run other cells while the job runs::

task = await abfe.watch()

To block until the job finishes, use :meth:watch_async instead::

await abfe.watch_async()

Parameters:

Name	Type	Description	Default
`interval`	`float`	Seconds between polls; passed to :meth:`watch_async`.	`5.0`

Returns:

Type	Description
`Task`	The task running :meth:`watch_async`. Cancel it with
`Task`	meth:`stop_watching` or `task.cancel()`.

watch_async `async` ¶

watch_async(*, interval: float = 5.0) -> None

Poll the platform and update a Jupyter display until a terminal state.

In notebooks use top-level await abfe.watch_async(). In scripts use asyncio.run(abfe.watch_async()).

Parameters:

Name	Type	Description	Default
`interval`	`float`	Seconds between polls after a successful update.	`5.0`

Raises:

Type	Description
`ValueError`	If `id` is None, or execution data is missing when required.

deeporigin.drug_discovery.pocket_finder¶

Attributes¶

Classes¶

PocketFinder ¶

Attributes¶

app instance-attribute ¶

approve_amount instance-attribute ¶

client instance-attribute ¶

completed_at instance-attribute ¶

cost property ¶

created_at instance-attribute ¶

created_by instance-attribute ¶

dto property ¶

estimate property ¶

id property ¶

name property writable ¶

pocket_count property ¶

pocket_min_size property ¶

progress instance-attribute ¶

protein property ¶

runtime property ¶

session instance-attribute ¶

started_at instance-attribute ¶

status instance-attribute ¶

tool_key class-attribute instance-attribute ¶

tool_version instance-attribute ¶

Functions¶

cancel ¶

confirm ¶

duplicate ¶

from_dto classmethod ¶

from_id classmethod ¶

get_results ¶

get_user_logs ¶

list classmethod ¶

run ¶

show ¶

start ¶

stop_watching ¶

sync ¶

update_from_dto ¶

watch async ¶

watch_async async ¶

`deeporigin.drug_discovery.pocket_finder`¶

app `instance-attribute` ¶

approve_amount `instance-attribute` ¶

client `instance-attribute` ¶

completed_at `instance-attribute` ¶

cost `property` ¶

created_at `instance-attribute` ¶

created_by `instance-attribute` ¶

dto `property` ¶

estimate `property` ¶

id `property` ¶

name `property` `writable` ¶

pocket_count `property` ¶

pocket_min_size `property` ¶

progress `instance-attribute` ¶

protein `property` ¶

runtime `property` ¶

session `instance-attribute` ¶

started_at `instance-attribute` ¶

status `instance-attribute` ¶

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

tool_version `instance-attribute` ¶

from_dto `classmethod` ¶

from_id `classmethod` ¶

list `classmethod` ¶

watch `async` ¶

watch_async `async` ¶