Skip to content

Commit

Permalink
ai-revision docs: section mapping & prompt types
Browse files Browse the repository at this point in the history
miltondp authored Dec 13, 2023
1 parent 48c7d75 commit 078af3a
Showing 2 changed files with 22 additions and 2 deletions.
6 changes: 6 additions & 0 deletions .github/workflows/ai-revision.yaml
Original file line number Diff line number Diff line change
@@ -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/
18 changes: 16 additions & 2 deletions USAGE.md
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit 078af3a

Please sign in to comment.