CLI Manual

Command-line interface for accessing Pending AI's retrosynthesis service.

Getting Started

Usage of the Pending AI CLI requires

• an account for the Pending AI Platform and

• a locally installed Python version >=3.9.

The Pending AI CLI is available from the Python Package Index, the official third-party software repository for Python and can thus be easily installed using the package management system pip:

pip install pendingai

Successful installation can be verified with

pendingai --version

which is expected to output the name and version of the Pending AI CLI.

Authentication

Using the Pending AI services via the CLI requires an authenticated session. The pendingai auth command provides several subcommands to manage your authentication status.

Logging In

To initiate the login process, use the login subcommand:

pendingai auth login

This command uses device authorization, which will automatically open a web browser window. Follow the prompts in your browser to enter your Pending AI Platform credentials and authorize the CLI session.

For any account problems, contact Pending AI via email at [email protected].

Checking Session Status

You can check the status of your current authenticated session, including details like the associated user and expiry time:

pendingai auth status

Refreshing a Session

Authenticated sessions have a limited lifetime for security reasons. If your session is close to expiring or has already expired, you can attempt to refresh it without needing to fully log in again:

pendingai auth refresh

This will extend the lifetime of your current session if it's still valid for refreshing.

Retrieving the Access Token

Successful authentication stores an access token locally on your machine. You can retrieve the current access token using:

pendingai auth token

The access token retrieved via pendingai auth token can be used as a Bearer token for direct API access by including it in the Authorization header of each API request (e.g., Authorization: Bearer <your_token>).

Logging Out

To end your authenticated session and remove the locally cached authentication details, use the logout subcommand:

pendingai auth logout

This ensures that your credentials are no longer stored by the CLI on the current machine.

Exploring Available Generative Models

An overview of Pending AI's generative models and their characteristics can be found here. Please note that your account might have access to select models only. Reach out to our support at [email protected] if you want discuss your generative model options.

Before generating molecules, you might want to know which generative models are available to your account. Each model has a unique ID that can be provided to the generator sample command to select a model.

To list all available models, use the models command:

pendingai generator models

The output will be a table listing the available models, their version, and their current status. Only models with an Online status can be used for sampling.

Example Output:

┌─────────────────────────────────┬────────────────────────────┬───────────────┬─────────┐
│ ID                              │ Name                       │ Version       │ Status  │
├─────────────────────────────────┼────────────────────────────┼───────────────┼─────────┤
│ mod_2XF0UlNC3yWGLVhklkoYAS3vky0 │ diverse small transformer  │ 0.0.0-alpha.0 │ Online  │
│ mod_2XF0Y4tJrHbHxpWwppyfJFAiHJM │ docking tiny transformer   │ 0.0.0-alpha.0 │ Online  │
│ mod_2XEGInBPVsqDsW25vSvaNRcIfxs │ docking small transformer  │ 0.0.0-alpha.0 │ Online  │
│ mod_2XEGInBPVsqDsW25vSvaNRcIfxc │ docking medium transformer │ 0.0.0-alpha.0 │ Offline │
└─────────────────────────────────┴────────────────────────────┴───────────────┴─────────┘

You can also get this list in a machine-readable format using the --json flag.

Guide: Sampling Molecules

To sample molecules from a generative model, use the sample command. You can specify the number of molecules to generate and the model to use.

1. Basic Sampling

To generate 1,000 molecules using any available online model and save them to a file named samples.smi:

pendingai generator sample --num-samples 1000 --output-file "samples.smi"

If an output file is not specified with --output-file, the results will be saved to a default file that follows the pattern endingai_generator_sample_XXX.smi with XXX starting at 001 and being incremented in steps of 1.

2. Targeted Sampling with a Specific Model

To generate 5,000 molecules specifically from the diverse small transformer model (using its ID from the models command), run:

pendingai generator sample --model "mod_2XF0UlNC3yWGLVhklkoYAS3vky0" --num-samples 5000 --output-file "samples.smi"

If you don't specify a model, the service will pick any model is available to your account and is online to generate the samples. It is highly recommended to always specify a model ID so that the generated molecules are suitable to the requirements of your specific task.

3. Appending to an Existing File

If you want to add more samples to an existing file without being prompted to overwrite it, use the --append flag:

pendingai generator sample --num-samples 2500 --output-file "samples.smi" --append

Molecule Sampling Parameters

The following parameters can be used with the pendingai generator sample command:

• -o, --output-file <FILE>

  • Specifies the file path for storing the output SMILES molecules.

  • If not provided, it defaults to pendingai_generator_sample_XXX.smi in the current directory.

• -n, --num-samples <INTEGER>

  • The number of molecules you want to generate.

  • Must be an integer between 1 and 1,000,000.

  • Defaults to 500 if not specified.

• -m, --model <TEXT>

  • The unique ID of the model you want to use for sampling.

  • Use the pendingai generator models command to find available model IDs.

  • If not specified, the system will use any available online generator model.

• -a, --append

  • A flag to indicate that the generated molecules should be appended to the output file if it already exists.

  • This also suppresses the prompt that asks for confirmation before overwriting a file.