uiceds · ctessum · Sep 10, 2024 · Sep 28, 2023 · Dec 13, 2023 · Jan 19, 2024
diff --git a/.appveyor.yml b/.appveyor.yml
@@ -20,7 +20,7 @@ only_commits:
     - ci/install.sh
     - content/
 
-image: ubuntu
+image: ubuntu2204
 services:
   - docker
 

diff --git a/.github/workflows/ai-revision.yaml b/.github/workflows/ai-revision.yaml
@@ -16,12 +16,17 @@ on:
         description: 'Language model'
         required: true
         type: string
-        default: 'text-davinci-003'
+        default: 'gpt-4-turbo'
+      custom_prompt:
+        description: 'Custom prompt'
+        required: false
+        type: string
+        default: ''
       branch_name:
         description: 'Output branch'
         required: true
         type: string
-        default: 'ai-revision-davinci'
+        default: 'ai-revision-gpt4turbo'
 
 jobs:
   ai-revise:
@@ -35,11 +40,11 @@ jobs:
         shell: bash --login {0}
     steps:
       - name: Checkout Repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with: 
           ref: ${{ inputs.branch }} 
       - name: Install environment
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
              python-version: '3.11'
       - name: Install Manubot AI revision dependencies
@@ -54,11 +59,12 @@ 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/
+        run: manubot ai-revision --content-directory content/ --config-directory ci/
       - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v4
+        uses: peter-evans/create-pull-request@v6
         with:
           commit-message: 'revise using AI model\n\nUsing the OpenAI model ${{ inputs.model }}'
           title: 'AI-based revision using ${{ inputs.model }}'

diff --git a/.github/workflows/manubot.yaml b/.github/workflows/manubot.yaml
@@ -50,7 +50,7 @@ jobs:
         shell: bash --login {0}
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           # fetch entire commit history to support get_rootstock_commit
           fetch-depth: 0
@@ -72,14 +72,14 @@ jobs:
           echo "DEFAULT_BRANCH_REF=refs/heads/$DEFAULT_BRANCH" >> $GITHUB_ENV
           echo "DEFAULT_BRANCH=$DEFAULT_BRANCH"
       - name: Cache
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: ci/cache
           key: ci-cache-${{ github.ref }}
           restore-keys: |
             ci-cache-${{ env.DEFAULT_BRANCH_REF }}
       - name: Install Environment
-        uses: conda-incubator/setup-miniconda@v2
+        uses: conda-incubator/setup-miniconda@v3
         with:
           activate-environment: manubot
           environment-file: build/environment.yml
@@ -93,7 +93,7 @@ jobs:
       - name: Build Manuscript
         run: bash build/build.sh
       - name: Upload Artifacts
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: manuscript-${{ github.run_id }}-${{ env.TRIGGERING_SHA_7 }}
           path: output

diff --git a/USAGE.md b/USAGE.md
@@ -333,29 +333,15 @@ 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 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/).
-
-You need to change your repository settings to 1) provide a secret with name `OPENAI_API_KEY` containing your OpenAI API token, and 2) allow workflows to create pull requests.
-For 1), go to the settings page and, within "Secrets and variables," select "Actions."
-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`.
-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.
-Internally, the workflow uses the tool [Manubot AI Editor](https://github.com/manubot/manubot-ai-editor) to revise the manuscript.
-For more advanced users, the behavior of the Manubot AI Editor or the parameters used for the language model can be changed using environment variables.
-These variables can be changed in the workflow file (`ai-revision.yaml`).
-
-It is important to note that using language models in scientific writing is a matter of debate among researchers and journal editors.
-Therefore, it's advisable to follow the guidelines that journals and the research community propose.
-For example, the *Nature* journal has published [rules about using language models in scholarly writing](https://www.nature.com/articles/d41586-023-00191-1), such as not listing the tools as authors and documenting how they were used.
-Since a Manubot-based manuscript uses GitHub, one approach consists of linking the AI-generated pull request, which will transparently show the changes suggested by the AI tool.
+Manubot features a powerful integrated _AI Editor_ that can proofread and revise your manuscript.
+It can fix lower-level issues such as spelling and grammar errors, but can also make higher-level improvements like simplifying sentence structure, increasing clarity, refining writing style, and more.
+You can also customize how it revises your writing in different sections of your manuscript.
+
+Running the AI Editor is _fully in your control_.
+It will only run if you manually trigger the workflow [`ai-revision`](.github/workflows/ai-revision.yaml).
+The workflow will generate a pull request with suggested revisions for you to review and either accept or reject.
+
+For _full documentation and support_, see the separate [`manubot-ai-editor` repo](https://github.com/manubot/manubot-ai-editor) and [our manuscript](https://doi.org/10.1093/jamia/ocae139).
 
 ## Manubot feedback
 
@@ -372,12 +358,12 @@ DOI: [10.1371/journal.pcbi.1007128](https://doi.org/10.1371/journal.pcbi.1007128
 
 The Manubot version of this manuscript is available at <https://greenelab.github.io/meta-review/>.
 
-To cite the Manubot AI Editor or for more information on its design, see `@doi:10.1101/2023.01.21.525030`:
+To cite the Manubot AI Editor or for more information on its design, see `@doi:10.1093/jamia/ocae139`:
 
-> **A publishing infrastructure for AI-assisted academic authoring**<br>
+> **A publishing infrastructure for Artificial Intelligence (AI)-assisted academic authoring**<br>
 Milton Pividori, Casey S. Greene<br>
-*bioRxiv* (2023) <https://doi.org/grpf8m><br>
-DOI: [10.1101/2023.01.21.525030](https://doi.org/10.1101/2023.01.21.525030)
+*Journal of the American Medical Informatics Association* (2024) <https://doi.org/gtw9d3><br>
+DOI: [10.1093/jamia/ocae139](https://doi.org/10.1093/jamia/ocae139)
 
 
 ## Acknowledgments

diff --git a/build/environment.yml b/build/environment.yml
@@ -21,7 +21,7 @@ dependencies:
   - pip:
     - cffi==1.15.0
     - errorhandler==2.0.1
-    - git+https://github.com/manubot/manubot@d4242ffa4194e4a13a68c5f6466feff559d3f9d5
+    - git+https://github.com/manubot/manubot@2914d720dfe02d2bda8781f8f784bc14d461e2e3
     - isbnlib==3.10.10
     - opentimestamps-client==0.7.1
     - opentimestamps==0.4.3

diff --git a/ci/ai-revision-config.yaml b/ci/ai-revision-config.yaml
@@ -0,0 +1,8 @@
+files:
+  ignore:
+    - front\-matter
+    - back\-matter
+  matchings:
+    - files:
+        - .*\.md$
+      prompt: default
diff --git a/ci/ai-revision-prompts.yaml b/ci/ai-revision-prompts.yaml
@@ -0,0 +1,44 @@
+prompts:
+  abstract: |
+    You are a scientist with copy-editing skills who will help in improving the text of a manuscript. Revise the following abstract of this manuscript so that it has a clear sentence structure and fits in a single paragraph. The revision should follow a context-content-conclusion (C-C-C) scheme, as follows: 1) The context portion communicates to the reader what gap the paper will fill. The first sentence orients the reader by introducing the broader field in which the manuscript's research is situated. Then, the context is narrowed until it lands on the open question that the research answers. A successful context section distinguishes the research's contributions from the current state-of-the-art, communicating what is missing in the current literature (i.e., the specific gap) and why that matters (i.e. the connection between the specific gap and the broader context). 2) The content portion (e.g. "here we") first describes the novel method or approach that was used to fill the gap, then presents an executive summary of results. 3) The conclusion portion interprets the results to answer the question that was posed at the end of the context portion. There may be a second part to the conclusion portion that highlights how this conclusion moves the broader field forward (e.g. "broader significance").
+
+    Input paragraph: {{ content }}
+
+    Revised paragraph: 
+
+  introduction: |
+    You are a scientist with copy-editing skills tasked with refining the text of a scientific manuscript. Your goal is to revise the following paragraph from the Introduction section to enhance clarity, reduce jargon, and maintain a scholarly tone. The revision should adhere to Markdown formatting and follow a Context-Content-Conclusion (C-C-C) structure. This structure begins by setting the stage with one or two sentences (Context), progresses through what is known from the literature (Content), and concludes by highlighting an aspect of the knowledge gap the manuscript addresses (Conclusion). Your revision should: 1) preserve the original information as much as possible, with minimal changes to the text, 2) ensure most references to scientific articles are kept exactly as they appear in the original text; these references are crucial for academic integrity and may appear with the format "[@TYPE:ID]" such as "[@pmid:33931583; @doi:10.1101/2021.10.21.21265225; @pmid:31036433]", and 4) the revised paragraph must encapsulate the entire revision, following the C-C-C structure, within a single, cohesive paragraph.
+
+    Input paragraph: {{ content }}
+
+    Revised paragraph:
+
+  results: |
+    You are a scientist with copy-editing skills tasked with refining the text of a scientific manuscript. Your goal is to revise the following paragraph from the Results section to enhance clarity, reduce jargon, maintain a scholarly tone, adhere to Markdown formatting and follow a Context-Content-Conclusion (C-C-C) structure. This structure begins with a sentence or two that set up the question that the paragraph answers (Context) (such as the following: "To verify that there are no artifacts...," "What is the test-retest reliability of our measure?," or "We next tested whether Ca2+ flux through L-type Ca2+ channels was involved"), the middle of the paragraph presents data and logic that pertain to the question (Content), and the paragraph ends with a sentence that answers the question (Conclusion). Your revision should: 1) ensure that the paragraph has the following structure: it starts with a sentence or two that set up the question that the paragraph answers (such as the following: "To verify that there are no artifacts...," "What is the test-retest reliability of our measure?," or "We next tested whether Ca2+ flux through L-type Ca2+ channels was involved."), the middle of the paragraph presents data and logic that pertain to the question, and the paragraph ends with a sentence that answers the question. Your revision should: 1) preserve the original information as much as possible, with minimal changes to the text, 2) ensure most references to scientific articles are kept exactly as they appear in the original text; these references are crucial for academic integrity and may appear with the format "[@TYPE:ID]" such as "[@pmid:33931583; @doi:10.1101/2021.10.21.21265225; @pmid:31036433]", and 4) the revised paragraph must encapsulate the entire revision, following the C-C-C structure, within a single, cohesive paragraph.
+
+    Input paragraph: {{ content }}
+
+    Revised paragraph:
+
+  discussion: |
+    You are a scientist with copy-editing skills tasked with refining the text of a scientific manuscript. Your goal is to revise the following paragraph from the Discussion section to enhance clarity, reduce jargon, maintain a scholarly tone, and adhere to Markdown formatting and follow a Context-Content-Conclusion (C-C-C) structure. This structure starts by describing an area of weakness or strength of the paper (Context), then evaluates the strength or weakness by linking it to the relevant literature (Content), and it often concludes by describing a clever, informal way of perceiving the contribution or by discussing future directions that can extend the contribution. Your revision should: 1) preserve the original information as much as possible, with minimal changes to the text, 2) ensure most references to scientific articles are kept exactly as they appear in the original text; these references are crucial for academic integrity and may appear with the format "[@TYPE:ID]" such as "[@pmid:33931583; @doi:10.1101/2021.10.21.21265225; @pmid:31036433]", and 4) the revised paragraph must encapsulate the entire revision, following the C-C-C structure, within a single, cohesive paragraph.
+
+    Input paragraph: {{ content }}
+
+    Revised paragraph:
+
+  methods: |
+    You are a scientist with copy-editing skills tasked with refining the text of a scientific manuscript. Your goal is to revise the following paragraph from the Methods section to enhance clarity, reduce jargon, maintain a scholarly tone, and adhere to Markdown formatting. Your revision should: 1) preserve the original information as much as possible, with minimal changes to the text, 2) preserve technical details such as mathematical expressions, 3) ensure that equations (which could be numbered) are preserved and correctly defined, 4) preserve references to numbered equations, and 5) ensure most references to scientific articles are kept exactly as they appear in the original text; these references are crucial for academic integrity and may appear with the format "[@TYPE:ID]" such as "[@pmid:33931583; @doi:10.1101/2021.10.21.21265225; @pmid:31036433]".
+
+    Input paragraph: {{ content }}
+
+    Revised paragraph:
+
+  default: |
+    Proofread the following paragraph that is part of a scientific manuscript.
+    Keep all Markdown formatting, citations to other articles, mathematical
+    expressions, and equations.
+
+    Input paragraph: {{ content }}
+
+    Proofread paragraph: