CLI

Documentation for the Pending AI platform CLI

Overview

Our platform CLI tool allows integrating the different Pending AI services directly from your terminal. The documentation for different commands are described below and interface with the offered APIs with the convenience of wrapper logic provided for authentication and other access requirements:

Authentication

Access to the Pending AI platform requires privileged access for the listed services. Creating cached sessions via the CLI is made possible via the pendingai auth commands.

pendingai auth login      # Create a new session
pendingai auth refresh    # Refresh session access

`pendingai`

The main entry point for the Pending AI platform CLI. Leverage the different capabilities offered via an authenticated session using pendingai auth --help for more information (or see above). Ensure you have an active subscription with the different services.

Synopsis

pendingai [OPTIONS] COMMAND [ARGS] ...

Commands:

docs: Open the Pending AI documentation in your web browser.
auth: Authenticate with the Pending AI platform.
retro: Interface with the PAI Retro service.
generator: Interface with the PAI Generator service.

Options

Option (Short)

Option (Long)

Description

Default

--version

Show the application version and exit.

n/a

--help

Show this message and exit.

n/a

`pendingai docs`

Open the Pending AI documentation in your default web browser. You will be redirected shortly from your terminal to the web page.

Synopsis

pendingai docs

`pendingai auth`

Manage your authenticated session with the Pending AI platform. Access to certain products is restricted by account permissions. The session created will require you to login and routinely refresh the session access.

For changes to your account such as starting a new subscription, ensure you re-login to a new session. Permissions will be refreshed from the cached access information which may cause issues.

Synopsis

pendingai auth [OPTIONS] COMMAND [ARGS] ...

Commands:

login: Login to your Pending AI account.
logout: Logout of your Pending AI account.
refresh: Refresh an authenticated session.
status: Show active session information.
token: Get the access token of the current session.

Options

Option (Short)

Option (Long)

Description

Default

--help

Show this message and exit.

n/a

Login to your Pending AI account. You will be prompted with a login 6-digit code to enter when redirected to your web browser. From there you can login or create a new account. Once logged in, return to your terminal with a newly authenticated session - information will cached on your device to allow for repeated CLI commands.

Synopsis

pendingai auth login

`pendingai auth logout`

Logout of your Pending AI account. The cached session information will be deleted. Any future use of the CLI will require you to call pendingai login to continue.

Synopsis

pendingai auth logout

`pendingai auth refresh`

Refresh an authenticated session. Cached session information expires after 24 hours in which you must refresh access for the session. If the session can no longer be refreshed, you will need to call pendingai login to create a new session.

Synopsis

pendingai auth refresh

`pendingai auth status`

Show active session information. If you have multiple accounts, you will be able to see which account you are currently using for the session and the remaining time before your session expires.

Synopsis

pendingai auth status

`pendingai auth token`

Get the access token of the current session. The access token is used when interfacing with the Pending AI platform API containing your user information.

Our API documentation allows you to test the different requests from your browser. This command allows you to easily copy the session token for testing authenticated API requests from the documentation.

Synopsis

pendingai auth token

`pendingai retro`

Interface with the PAI Retro service. Build high-throughput screening pipelines to perform low and high-throughput Retrosynthesis to find new and diverse reaction pathways and assess the synthetic accessibility of structures.

Synopsis

pendingai retro [OPTIONS] COMMAND [ARGS] ...

Commands:

engines: List available retrosynthesis engines.
libraries: List available building block libraries.
job: A set of commands supporting submitting and exploring individual Retrosynthesis jobs.
batch: A set of commands supporting large molecule library screening Retrosynthesis jobs.

Options

Option (Short)

Option (Long)

Description

Default

--help

Show this message and exit.

n/a

`pendingai retro engines`

List available retrosynthesis engines. An engine provides the underlying architecture and functional procedure used for building complex multi-step synthetic routes. It is required when submitting molecules for retrosynthesis to specific an engine id parameter.

Synopsis

pendingai retro engines [OPTIONS]

Options

Option (Short)

Option (Long)

Description

Default

--json

Render output as JSON.

false

--help

Show this message and exit.

n/a

`pendingai retro libraries`

List available building block libraries. Building block libraries are collections of structures used to facilitate terminating different reaction trees with purchasable information. It is required when submitting molecules for retrosynthesis to specific a list of library id parameters.

Synopsis

pendingai retro libraries [OPTIONS]

Options

Option (Short)

Option (Long)

Description

Default

--json

Render output as JSON.

false

--help

Show this message and exit.

n/a

`pendingai retro job`

A set of commands supporting submitting and exploring individual Retrosynthesis jobs.

Synopsis

pendingai retro job [OPTIONS] COMMAND [ARGS]...

Commands:

submit: Submit a job to a retrosynthesis engine.
status: Get the status of a retrosynthesis job.
result: Retrieve results for one or more jobs.
list: Retrieve a list of retrosynthesis jobs.
delete: Delete a retrosynthesis job.
routes: Visualise generated routes from the Pending AI UI.
depict: Visualise generated route from local HTML pages.

Options

Option (Short)

Option (Long)

Description

Default

--help

Show this message and exit.

n/a

`pendingai retro job submit`

Submit a single query molecule SMILES retrosynthesis job. Provide additional optional parameters to control the synthesis process. More information about these parameters is available in the PAI Retro documentation.

To provide multiple values for a <LIST> option, it should be provide in the following format --option [VALUE] --option [VALUE].

Synopsis

pendingai retro job submit [OPTIONS] SMILES

Arguments

<SMILES>: A single query molecule in SMILES format to be submitted for retrosynthesis.

Options

Option (Short)

Option (Long)

Description

Default

--engine <TEXT>

The engine id to perform retrosynthesis on.

Most recently active available engine.

--library <LIST>

All library id's to be used for retrosynthesis.

All available building block libraries.

--num-routes <INTEGER>

Maximum number of routes to generate [1-50].

20

--time-limit <INTEGER>

Maximum processing time in seconds [60-600].

300

--reaction-limit <INTEGER>

Maximum number of times a reaction can appear in generated routes [1-20].

3

--block-limit <INTEGER>

Maximum number of times a building block molecule can appear in generated routes [1-20].

3

--json

Render output as JSON.

false

--help

Show this message and exit.

n/a

`pendingai retro job status`

Get the status of a retrosynthesis job.

Synopsis

pendingai retro job status [OPTIONS] [JOB_ID]

Arguments

<JOB_ID>: An id for a retrosynthesis job.

Options

Option (Short)

Option (Long)

Description

Default

--json

Render output as JSON.

false

--help

Show this message and exit.

n/a

`pendingai retro job result`

Retrieve results for one or more retrosynthesis jobs by a single id or line-delimited file of multiple job id values. Results return back a collection of JSON routes per query molecule. More information about the response model is available here.

This command is slower than batch-based screening as it retrieves results individually. For simple molecule screening of synthetic accessibility, it is recommended to use batched Retrosynthesis.

Synopsis

pendingai retro job result [OPTIONS] [JOB_ID]

Arguments

<JOB_ID>: An id for a retrosynthesis job.

Options

Option (Short)

Option (Long)

Description

Default

-o

--output-file <FILE>

Output filepath for writing results.

Auto-generated file in your local directory.

-i

--input-file <FILE>

Optional input filepath of line-delimited job id values.

n/a

--help

Show this message and exit.

n/a

`pendingai retro job list`

Retrieve a list of retrosynthesis jobs. A paged view is made available to retrieve jobs across individual result pages. Filtering results is made available with --status.

Synopsis

pendingai retro job list [OPTIONS]

Options

Option (Short)

Option (Long)

Description

Default

--page <INTEGER>

Page number being fetched.

1

--page-size <INTEGER>

Number of results per page [1-25].

25

--status <TEXT>

Optional filter for status: completed, failed, submitted, processing.

n/a

--json

Render output as JSON.

false

--help

Show this message and exit.

n/a

`pendingai retro job delete`

Delete a retrosynthesis job. The results will no longer be available and the action cannot be undone.

Synopsis

pendingai retro job delete [OPTIONS] [JOB_ID]

Arguments

<JOB_ID>: An id for a retrosynthesis job.

Options

Option (Short)

Option (Long)

Description

Default

--json

Render output as JSON.

false

--help

Show this message and exit.

n/a

`pendingai retro job routes`

Visualise generated routes in the Pending AI UI. You will be redirected to your web browser.

Synopsis

pendingai retro job routes [JOB_ID]

Arguments

<JOB_ID>: An id for a retrosynthesis job.

`pendingai retro job depict`

Visualise generated routes in the locally generated HTML pages. Results will be retrieved and HTML pages will be generated containing visualisations for each route. Note that the depictions can take up significant storage space if retrieved in large batches.

Synopsis

pendingai retro job depict [OPTIONS] [JOB_ID]

Arguments

[JOB_ID]: An id for a retrosynthesis job.

Options

Option (Short)

Option (Long)

Description

Default

-o

--output-dir <DIRECTORY>

Directory to save generated HTML depiction files.

Auto-generated directory in your local directory.

-i

--input-file <FILE>

Optional input filepath of line-delimited job id values.

n/a

--help

Show this message and exit.

n/a

`pendingai retro batch`

A set of commands supporting large molecule library screening Retrosynthesis jobs.

Synopsis

pendingai retro batch [OPTIONS] COMMAND [ARGS]...

Commands:

submit: Submit a batch of retrosynthesis jobs.
status: Check the processing status of a batch.
result: Retrieve results for all jobs in a batch.
list: List all submitted retrosynthesis batches.
delete: Delete a completed batch of jobs.

Options

Option (Short)

Option (Long)

Description

Default

--help

Show this message and exit.

n/a

`pendingai retro batch submit`

Submit multiple retrosynthesis jobs as a single batch. Parameters that are provided will be shared across all retrosynthesis jobs in the batch. Any duplicate SMILES will also be removed to avoid running the same job multiple times.

To provide multiple values for a <LIST> option, it should be provide in the following format --option [VALUE] --option [VALUE].

Synopsis

pendingai retro batch submit [OPTIONS] SMILES_FILE

Arguments

<SMILES_FILE>: An input filepath containing line-delimited molecules belonging to the batch.

Options

Option (Short)

Option (Long)

Description

Default

--engine <TEXT>

The engine id to perform retrosynthesis on.

Most recently active available engine.

--library <LIST>

All library id's to be used for retrosynthesis.

All available building block libraries.

--num-routes <INTEGER>

Maximum number of routes to generate [1-50].

20

--time-limit <INTEGER>

Maximum processing time in seconds [60-600].

300

--reaction-limit <INTEGER>

Maximum number of times a reaction can appear in generated routes [1-20].

3

--block-limit <INTEGER>

Maximum number of times a building block molecule can appear in generated routes [1-20].

3

--help

Show this message and exit.

n/a

`pendingai retro batch status`

Check the status of a retrosynthesis batch. The batch is considered complete once all of its jobs have finished processing.

Synopsis

pendingai retro batch status BATCH_ID

Arguments

<BATCH_ID>: An id for a retrosynthesis batch.

`pendingai retro batch result`

Retrieve results for all retrosynthesis jobs in a batch. The batch returns a different result summary compared to pendingai retro job result containing a summary of the screening results for all targets in the batch. See the documentation for more information about the response data.

Note: Results can be retrieved while the batch is in progress with jobs yet to be processed with completed=false.

Synopsis

pendingai retro batch result [OPTIONS] BATCH_ID

Arguments

<BATCH_ID>: An id for a retrosynthesis batch.

Options

Option (Short)

Option (Long)

Description

Default

-o

--output-file <FILE>

Output filepath for writing results.

Auto-generated file in your local directory.

--summarise

Return a summary statistic to assess the overall result of the batch.

false

--help

Show this message and exit.

n/a

`pendingai retro batch list`

List all submitted batches in a paginated format.

Synopsis

pendingai retro batch list [OPTIONS]

Options

Option (Short)

Option (Long)

Description

Default

--before <TEXT>

An optional batch id value to retrieve those created before it.

n/a

--after <TEXT>

An optional batch id value to retrieve those created after it.

n/a

-s

--size <INTEGER>

Number of results returned by the list [1-100].

50

--help

Show this message and exit.

n/a

`pendingai retro batch delete`

Delete a batch and all of its attached retrosynthesis jobs.

Synopsis

pendingai retro batch delete BATCH_ID

Arguments

<BATCH_ID>: An id for a retrosynthesis batch.

`pendingai generator`

Interface with the PAI Generator service. Use Generative AI models for sample novel and diverse drug-like molecules to explore new chemical spaces efficiently and quickly.

Synopsis

pendingai generator [OPTIONS] COMMAND [ARGS] ...

Description

Commands:

models: List the available Generative AI models for sampling molecules.
sample: Generate samples of molecules from a model.

Options

Option (Short)

Option (Long)

Description

Default

--help

Show this message and exit.

n/a

`pendingai generator models`

List the available Generative AI models for sampling molecules. The model id must be specified when sampling from a particular model. The returned data from the service can be limited to the first --limit results of paged data to avoid waiting for the server to respond.

Synopsis

pendingai generator models [OPTIONS]

Options

Option (Short)

Option (Long)

Description

Default

-l

--limit <INTEGER>

Limit the number of returned models.

100

--json

Render output as JSON.

false

--help

Show this message and exit.

n/a

`pendingai generator sample`

Generate samples of molecules from a model. Output from the CLI is directed to a file for convenience. You can specify an output file and append to an existing one. Specify the particular model for sampling if necessary.

Note: When the --model option is not provided, the first available model will be used.

Synopsis

pendingai generator sample [OPTIONS]

Options

Option (Short)

Option (Long)

Description

Default

-o

--output-file <FILE>

Output filepath to store sampled SMILES.

pendingai_...smi

-n

--num-samples <INTEGER>

Number of samples to generate [1-1000000].

500

-m

--model <TEXT>

Model id to use for sampling.

n/a

-a

--append

Append to the output file without prompting.

false

--help

Show this message and exit.

n/a