From 078af3a959b07118dc2f282357644ed96646ecab Mon Sep 17 00:00:00 2001
From: Milton Pividori <miltondp@gmail.com>
Date: Wed, 13 Dec 2023 06:29:42 -0700
Subject: [PATCH] ai-revision docs: section mapping & prompt types

merges https://github.com/manubot/rootstock/pull/496
---
 .github/workflows/ai-revision.yaml |  6 ++++++
 USAGE.md                           | 18 ++++++++++++++++--
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ai-revision.yaml b/.github/workflows/ai-revision.yaml
index 58eb0d35..db2bac5c 100644
--- a/.github/workflows/ai-revision.yaml
+++ b/.github/workflows/ai-revision.yaml
@@ -17,6 +17,11 @@ on:
         required: true
         type: string
         default: 'text-davinci-003'
+      custom_prompt:
+        description: 'Custom prompt'
+        required: false
+        type: string
+        default: ''
       branch_name:
         description: 'Output branch'
         required: true
@@ -54,6 +59,7 @@ jobs:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           AI_EDITOR_LANGUAGE_MODEL: ${{ inputs.model }}
           AI_EDITOR_FILENAMES_TO_REVISE: ${{ inputs.file_names }}
+          AI_EDITOR_CUSTOM_PROMPT: ${{ inputs.custom_prompt }}
           # More variables can be specified to control the behavior of the model:
           #  https://github.com/manubot/manubot-ai-editor/blob/main/libs/manubot_ai_editor/env_vars.py
         run: manubot ai-revision --content-directory content/
diff --git a/USAGE.md b/USAGE.md
index 5ce07a5f..de1848ec 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -334,7 +334,7 @@ Spellchecking is currently only supported for English language manuscripts.
 ## AI-assisted authoring
 
 The workflow [`ai-revision`](.github/workflows/ai-revision.yaml) is available to assist authors in writing their manuscripts.
-It uses large language models to revise the manuscript text, fixing spelling and grammar errors, and improving the sentence structure and the writing style with section-specific prompts.
+It uses large language models to revise the manuscript text, fix spelling and grammar errors, and improve the sentence structure and the writing style with section-specific prompts.
 It is manually triggered by the user (it never runs automatically), and it generates a pull request with suggested revisions.
 Then the user can review these changes and merge the pull request if they are acceptable.
 More information about this tool is available in [this manuscript](https://greenelab.github.io/manubot-gpt-manuscript/).
@@ -344,7 +344,21 @@ For 1), go to the settings page and, within "Secrets and variables," select "Act
 Next, create a repository secret with the name `OPENAI_API_KEY` and the value of the API token (you can also do this using "Organization secrets" if available).
 For 2), go to "Actions", "General", "Workflow permissions", and activate the checkbox "Allow GitHub Actions to create and approve pull requests."
 
-By default, the tool uses the model `text-davinci-003`.
+Additionally, you also need to decide which type of prompts you want to use.
+"Prompts" are the instructions given to the language model to revise your manuscript.
+Basically, you can select 1) the default set of section-specific prompts already provided by the tool, or 2) a custom prompt that you provide.
+For 1), you can check [this manuscript](https://greenelab.github.io/manubot-gpt-manuscript/) for a more detailed description of the section-specific prompts.
+These prompts are already provided, but they need to know the section of each of your Markdown files (for instance, if it is the abstract, or the introduction, etc.).
+For this, the tool will try to infer them from the file names automatically, and if this fails, the tool might not revise all of your files.
+In this case, you need to indicate the section of each file using the "section mapping" environment variable that is described [here](https://github.com/manubot/manubot-ai-editor/blob/main/libs/manubot_ai_editor/env_vars.py) (read the header of the file for more instructions).
+For 2), you can provide your own custom prompt, which will be used for all the files regardless of their section.
+For example, instead of the more complex section-specific prompts in 1), you might just want to perform simpler revision tasks.
+An example of a custom prompt is "proofread the following paragraph".
+You can provide your custom prompt when you manually trigger the workflow by using the "Custom prompt" field.
+This could be more appropriate if you are testing different prompts.
+To set a fixed prompt for all runs, read the documentation [here](https://github.com/manubot/manubot-ai-editor/blob/main/libs/manubot_ai_editor/env_vars.py) to set the "custom prompt" environment variable.
+
+By default, the tool uses the model `text-davinci-003`, but you are encouraged to check the [OpenAI documentation](https://platform.openai.com/docs/models) to see which models are available, which one is the most suitable for your manuscript, and [whether our tool supports it](https://github.com/manubot/manubot-ai-editor).
 Make sure to check the [pricing](https://openai.com/api/pricing/) of the OpenAI API.
 With $0.02 per 1000 tokens using the most powerful AI models, the cost for a revision of a standard manuscript (around 35 paragraphs) should be around $0.50.
 The workflow allows specifying the branch and file names (in the `content/` directory) to revise, the language model to use, and the output branch name.