Merge remote-tracking branch 'origin/phap/update-poet' into develop

Author: markgeejw

.gitignore

@@ -6,3 +6,4 @@
 # pixi environments
 .pixi
 *.egg-info
+.DS_Store

source/_static/tools/poet/prompt.png

@@ -23,22 +23,22 @@ A note on the *Random seed* setting: this determines the state of the random num
 Generating a sequence
 ---------------------
 
-Navigate to the tool by opening the **PoET** dropdown menu, then selecting **Generate Sequences.**
+Navigate to the tool by opening the **PoET** dropdown menu, then selecting **Generate Sequences.** You can choose the model used to run the job. We recommend using PoET-2 for most use cases.
 
-Set your parameters to control sampling behavior. In particular, **temperature**, **top-p**, and **top-k** provide the ability to focus sampling around highly likely sequences. We recommend that you use either top-p or top-k on a given job, not both.
+Step 1: Prompt Query
+^^^^^^^^^^^^^^^^^^^^^
 
-.. image:: ../../_static/tools/poet/sampling-parameters.png
-   :alt: Sampling Parameters
+Refer to `Creating a Query <./prompts.rst#creating-a-query>`_ to learn about Prompt Query.
 
-You can choose the model used to run the job. We recommend using PoET-2 for most use cases. 
 
-.. image:: ../../_static/tools/poet/choose-model.png
-   :alt: Choose Model
+Step 2: Prompt Context
+^^^^^^^^^^^^^^^^^^^^^^^
 
+**Build Custom Context**: If you want to create a custom context, please refer to `Creating a Context <./prompts.rst#creating-a-context>`_.
 
-If you have an existing prompt, you may select it. Alternatively, add your custom MSA to the **Prompt Definition** field. You can input the sequence(s) directly, or upload an existing .fa, .fasta, or .csv file.
+**Build from MSA**: If you have an existing prompt, you may select it. Alternatively, add your custom MSA to the **Prompt Definition** field. You can input the sequence(s) directly, or upload an existing .fa, .fasta, or .csv file.
 
-If you do not have an existing MSA, input your target protein and select **Single Sequence**. OpenProtein will generate an MSA using a homology search against Uniref using mmseqs2 with default settings from ColabFold, then use the MSA to create a prompt. Please note that if you select **Single Sequence** when multiple sequences are entered, sequences after the first are ignored.
+If you do not have an existing MSA, you can select **Upload MSA**. If you select **Run Homology Search Using a Seed Sequence**, OpenProtein will generate an MSA using a homology search against Uniref using mmseqs2 with default settings from ColabFold, then use the MSA to create a prompt. Please note that when multiple sequences are entered, sequences after the first are ignored.
 
 Choose the number of prompts to ensemble. Select 1 to sample a single prompt, or increase the diversity of generated outputs by ensembling over 2-15 prompts. We suggest using 3-5 prompts.
 
@@ -50,23 +50,80 @@ Set sampling method fields. We suggest you start with the default settings, then
 .. image:: ../../_static/tools/poet/sampling-methods.png
    :alt: Sampling Methods
 
-You're ready to generate a custom sequence! Select **Run.** The job may take a few minutes depending on how busy the service is, how long your sequences are, and how many sequences you want to score.
+
+Step 3: Sampling Settings
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set your parameters to control sampling behavior. In particular, **temperature**, **top-p**, and **top-k** provide the ability to focus sampling around highly likely sequences. We recommend that you use either top-p or top-k on a given job, not both. You can choose the default structure prediction model to generate the sequence structures after the job completes.
+
+.. image:: ../../_static/tools/poet/sampling-parameters.png
+   :alt: Sampling Parameters
+
+
+You're ready to generate a custom sequence! Click **Run.** The job may take a few minutes depending on how busy the service is, how long your sequences are, and how many sequences you want to score.
 
 A 400 (Bad request) error code may be due to the following:
 
-.. image:: ../../_static/tools/poet/results-table.png
-   :alt: Results Table
+.. list-table::
+   :header-rows: 1
+   :widths: 20 20
+   :align: left
+
+   * - Issue description
+     - Solution
+   * - Invalid PoET Job or Parent
+     - Re-enter prompt and try again.
+   * - Invalid prompt in PoET service
+     - Reupload prompt and try again. Refer to the article about `prompts <./prompts.rst>`_. Ensure minimum and maximum similarity parameters are not filtering out all sequences in prompt.
+   * - Invalid user input in align service
+     - Ensure you don't have
+
+       - a top_p>1
+       - a non-valid amino acid
+       - Maximum similarity < minimum similarity
+       If necessary, refer to the article on `sampling parameters <./prompts.rst#prompt-sampling-definitions>`_.
+   * - Invalid MSA (not aligned, etc)
+     - - Make sure your MSAs are aligned and rebuild MSA if necessary.
+       - If you have uploaded pre-computed MSA, confirm that formatting is correct and sequences are of equal length (use gap tokens “-”).
+       - If you are building from a seed sequence, try rebuilding the MSA
+
 
 Please contact `OpenProtein.AI support <https://www.openprotein.ai/contact>`_ if the suggested solutions don't resolve the issue.
 
 Interpreting your results
 -------------------------
 
-Your results are presented as a table, with each generated sequence being assigned a log-likelihood score. This score indicates the fitness of the generated sequence compared to the prompt. The higher the log-likelihood score, the more fit the sequence.
+The PoET history page allows you to view and access past jobs, sorted by created date, job type, and status. Clicking the job ID will take you to the results page for that job.
+
+**Results Table**
+
+Your results are presented in a table, with each generated sequence assigned a log-likelihood score. This score reflects how well the generated sequence fits the prompt: a higher score indicates a better fit.
+
+Right-click any sequence to access local fitness landscapes through the **Run Substitution Analysis** menu. You can also sort your results and export them using the **Export** button.
+
+.. image:: ../../_static/tools/poet/results-table.png
+   :alt: Results Table
+
+**Structure Prediction and Comparison**
+
+Once the structure prediction job completes, the structure viewer will appear on the right side of the page. The prediction model can be changed via the **Structure Predictor** dropdown located above the viewer. Hover over a sequence in the results table to preview and compare its structure against the query structure. The viewer also displays key metrics, including:
+
+- **pLDDT (predicted Local Distance Difference Test)**: A per-residue confidence score (commonly scaled from 0–100 or 0.0–1.0) indicating how reliable each residue's predicted position is.
+
+- **RMSD (Root Mean Square Deviation)**: A measure of structural similarity between two molecules, typically comparing backbone atoms. Lower RMSD values indicate greater structural similarity.
+
+Click a sequence to expand the structure viewer, which will overlay the results table. In this view, you can examine detailed metrics and sequence-to-prompt alignment for the selected sequence.
+
+.. image:: ../../_static/tools/poet/results-table-expanded.png
+   :alt: Sequence structure viewer
+
+**Change Reference Structure**
+
+By default, the query structure is used as the reference structure for structural comparisons. You can change it by selecting an alternative structure via the **Edit Reference Sequence** button, accessible from the results table **Settings** in the results table.
 
-Access local fitness landscapes using the substitution analysis buttons for each sequence. You can sort your results and download them using the **Export** button.
+.. image:: ../../_static/tools/poet/results-table-ref-structure.png
+   :alt: Change reference structure
 
-Note: The PoET history page allows you to view and access past jobs, sorted by created date, job type, and status. Clicking the job ID will take you to the results page for that job.
 
 Fine-tuning your results
 ------------------------

source/_static/tools/poet/results-table-expanded.png

@@ -52,7 +52,7 @@ A 400 (Bad request) error code may be due to the following:
    * - Invalid prompt in PoET service
      - Reupload prompt and try again. Refer to the article about `prompts <./prompts.rst>`_. Ensure minimum and maximum similarity parameters are not filtering out all sequences in prompt.
    * - Invalid user input in align service
-     - Ensure you don’t have
+     - Ensure you don't have
 
        - a top_p>1
        - a non-valid amino acid

source/_static/tools/poet/results-table-ref-structure.png

@@ -46,7 +46,8 @@ A 400 (Bad request) error code may be due to the following:
    * - Invalid prompt in PoET service
      - Reupload prompt and try again. Refer to the article about `prompts <./prompts.rst>`_. Ensure minimum and maximum similarity parameters are not filtering out all sequences in prompt.
    * - Invalid user input in align service
-     - Ensure you don’t have
+     - Ensure you don't have
+
        - a top_p>1
        - a non-valid amino acid
        - Maximum similarity < minimum similarity