> For the complete documentation index, see [llms.txt](https://docs.pending.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pending.ai/api-reference/pai-generator.md).

# PAI Generator

Access Pending AI's high-throughput Molecule Generator models

Pending AI's Molecule Generator capability is designed to yield high-throughput novel and diverse molecule sampling ideal for expanding into untouched chemical spaces rapidly. The service provides a simple integration for dedicated AI inference with one of Pending AI's innovative generative models.

See the **capability** page for more information:

{% content-ref url="/pages/wK2lO6QAKZOEG9j5xLRv" %}
[Generative AI](https://docs.pending.ai/capabilities/generative-ai.md)
{% endcontent-ref %}

***

## Workflow Summary

Access to Pending AI's Molecule Generator models simplifies the workflow in drug discovery pipelines for branching into different chemical spaces for targeted or broad molecular distributions. Request a [**sample**](https://docs.pending.ai/api-reference/pai-generator/sampling-structures.md) of up to 500 molecules from a generative [**model**](https://docs.pending.ai/api-reference/pai-generator/generative-models.md) when specifying an `id`, or create a [**sample batch**](https://docs.pending.ai/api-reference/pai-generator/sample-batches.md) of up to 100,000 molecules to build a large compound library in one request.

* **`POST /samples`** generates up to 500 molecules and waits for them. Send the `Prefer: respond-async` header to get the sample back at once with status `pending` (`202`), then poll `GET /samples/{sample_id}` until it is `completed` or `failed`.
* **`POST /sample-batches`** takes up to 100,000 molecules and returns at once. The batch is split into chunks of up to 500 molecules that are generated in the background. Poll `GET /sample-batches/{batch_id}` until its `status` is `completed` or `failed`, then page through `GET /sample-batches/{batch_id}/samples` to collect the molecules.

```mermaid
stateDiagram-v2
  a: Inspect Molecule Generator Models
  b: Request a Sample or a Sample Batch from a Model
  ScreeningCampaign: Screening Campaign
  SubspaceClustering: Subspace Clustering
  state ScreeningCampaign {
    c: Collect Molecules for a Compound Library
    d: Screen Molecules for Synthetic Accessibility
    e: Filter for Optimal Drug-Likeness and Target Affinity
    c --> d
    d --> e
  }
  state SubspaceClustering {
    f: Collect Unique Molecules of Interest
    g: Cluster Molecules using any Algorithm
    f --> g
  }
  b --> ScreeningCampaign
  b --> SubspaceClustering
  SubspaceClustering --> ScreeningCampaign : Identify clusters with optimal synthetic accessibility
  [*] --> a
  [*] --> b

```

See the available [Guides](https://docs.pending.ai/developer-tools/guides.md) for more implementation possibilities when integrating with existing drug discovery pipelines.

***

## Frequently Asked Questions

<details>

<summary>Q: How do I decide which model to use?</summary>

A: Refer to the [**capability**](https://docs.pending.ai/capabilities/generative-ai.md) page for a detailed breakdown of each model's strengths. Consider the optimal model based on the primary metric for the intended purpose. Otherwise, any model is generally favourable for sampling drug-like novel and diverse molecules.

</details>

<details>

<summary>Q: How many molecules can I generate in one request?</summary>

A: A sample (`POST /samples`) holds at most 500 molecules. A sample batch (`POST /sample-batches`) holds up to 100,000, generated in chunks of up to 500. There is no limit to how many samples or batches you can create, other than your team's plan allowance.

</details>

<details>

<summary>Q: Why is my sample still <code>pending</code>?</summary>

A: A sample is `pending` until a model takes it, then `processing` while molecules are generated, then `completed` or `failed`. A model that isn't running is started by the next sample, which takes about 10-15 seconds, so a sample that stays `pending` for a few seconds is usually waiting for its model to start.

</details>

<details>

<summary>Q: What does each model status mean?</summary>

A: `GET /models/{model_id}/status` returns one of:

* `online`: the model is running and samples at once.
* `idle`: no instance of the model is running. The next sample starts one, which takes about 10-15 seconds.
* `offline`: the model is offline and not reachable.
* `timeout`: the request timed out while waiting for the model.
* `error`: an error occurred while trying to reach the model.

</details>

<details>

<summary>Q: Why was my request refused with <code>402</code>?</summary>

A: Generated molecules count against your team's plan. A `POST /samples` or `POST /sample-batches` request is refused whole with `402 Payment Required` if your team has no plan, or can't generate that many molecules this billing period. When the allowance is the reason, the message says how many molecules can still be generated. See [Accounts, teams and billing](https://github.com/pendingai/gitbook/tree/main/getting-started/accounts-and-billing.md) for how allowances and overage work.

</details>

<details>

<summary>Q: Can there be duplicate SMILES returned when sampling?</summary>

A: Within a given sample request no duplicates are returned. It should be considered that when generating molecules from the same model the chemical space captured by the AI embedding architecture is not infinite and there is always a possibility (although highly unlikely).

</details>
