Merge branch 'main' of https://github.com/manubot/rootstock into root…

…stock-2024-07-29

.github/workflows/ai-revision.yaml

@@ -16,17 +16,25 @@ on:
         description: 'Language model'
         required: true
         type: string
-        default: 'text-davinci-003'
+        default: 'gpt-3.5-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-gpt35'
 
 jobs:
   ai-revise:
     name: AI Revise
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
     defaults:
       run:
         shell: bash --login {0}
@@ -51,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 }}'

.github/workflows/manubot.yaml

@@ -85,7 +85,9 @@ jobs:
           activate-environment: manubot
           environment-file: build/environment.yml
           auto-activate-base: false
+          miniforge-variant: Mambaforge
           miniforge-version: 'latest'
+          use-mamba: true
       - name: Install Spellcheck
         if: env.SPELLCHECK == 'true'
         run: bash ci/install-spellcheck.sh

USAGE.md

@@ -322,6 +322,8 @@ metadata:
   csl: https://github.com/citation-style-language/styles/raw/906cd6d43d0c136190ecfbb12f6af0ca794e3c5b/peerj.csl
 ```
 
+Instructions for generating additional manuscript output formats such as DOCX can be found in [`build/README.md`](build/README.md).
+
 ## Spellchecking
 
 When the `SPELLCHECK` environment variable is `true`, the pandoc [spellcheck filter](https://github.com/pandoc/lua-filters/tree/master/spellcheck) is run.
@@ -331,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
 
@@ -370,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

build/README.md

@@ -7,8 +7,19 @@ However, setting the `BUILD_PDF` environment variable to `false` will suppress P
 For example, run local builds using the command `BUILD_PDF=false bash build/build.sh`.
 
 To build a DOCX file of the manuscript, set the `BUILD_DOCX` environment variable to `true`.
-For example, use the command `BUILD_DOCX=true bash build/build.sh`.
-To export DOCX for all CI builds, set an environment variable (see docs for [GitHub Actions](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables)).
+For example, use the command `BUILD_DOCX=true bash build/build.sh` locally.
+To export DOCX for all CI builds, set an environment variable in the CI configuration file.
+For GitHub Actions, set the variable in `.github\workflows\manubot.yaml` (see [docs](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables)):
+
+```yaml
+name: Manubot
+env:
+  BUILD_DOCX: true
+```
+
+To generate a single DOCX output of the latest manuscript with GitHub Actions, click the "Actions" tab at the top of the repository.
+Select the "Manubot" workflow, then the "Run workflow" button and check "generate DOCX output" before clicking the green "Run workflow" button.
+
 Currently, equation numbers via `pandoc-eqnos` are not supported for DOCX output.
 
 Format conversion is done using [Pandoc](https://pandoc.org/MANUAL.html).
@@ -20,12 +31,17 @@ To change the options, either edit the YAML files directly or add additional `--
 
 Note: currently, **Windows is not supported**.
 
-Install the [conda](https://conda.io) environment specified in [`environment.yml`](environment.yml) by running the following commands
+The Manubot environment is managed with [conda](https://conda.io).
+If you do not have `conda` installed, we recommend using the Miniforge3 (includes `conda`) or Mambaforge (includes `conda` and `mamba`) installers from [miniforge](https://github.com/conda-forge/miniforge).
+Install the environment from [`environment.yml`](environment.yml) by running one of following commands
 (from the repository's root directory):
 
 ```sh
-# Install the environment
+# Install the environment using conda
 conda env create --file build/environment.yml
+
+# Install the environment using mamba (faster)
+mamba env create --file build/environment.yml
 ```
 
 If the `manubot` environment is already installed, but needs to be updated to reflect changes to `environment.yml`, use one of the following options:
@@ -38,6 +54,9 @@ conda env update --file build/environment.yml
 # Slower than option 1, but guarantees a fresh environment.
 conda env remove --name manubot
 conda env create --file build/environment.yml
+
+# option 3: reinstall the manubot environment faster using mamba.
+mamba env create --force --file build/environment.yml
 ```
 
 Activate with `conda activate manubot` (assumes `conda` version of [at least](https://github.com/conda/conda/blob/9d759d8edeb86569c25f6eb82053f09581013a2a/CHANGELOG.md#440-2017-12-20) 4.4).

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

ci/ai-revision-config.yaml

@@ -0,0 +1,8 @@
+files:
+  ignore:
+    - front\-matter
+    - back\-matter
+  matchings:
+    - files:
+        - .*\.md$
+      prompt: default

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:

setup.bash

@@ -15,7 +15,7 @@ echo "OWNER and REPO refer to the details of your manuscript repo location:"
 echo "i.e. https://github.com/OWNER/REPO."
 echo
 echo "Options:"
-echo "  -o --owner   GitHub user or organisation name."
+echo "  -o --owner   GitHub user or organization name."
 echo "  -r --repo    Name of the repository for your new manuscript."
 echo "  -y --yes     Non-interactive mode. Continue script without asking for confirmation that the repo exists."
 echo "  -s --ssh     Use SSH to authenticate GitHub account. HTTPS is used by default."
@@ -104,7 +104,7 @@ if [ -z "${OWNER}" ] || [ -z "${REPO}" ]; then
   echo "First, we need to specify where to create the GitHub repo for your manuscript."
   echo
   echo "The URL will take this format: https://github.com/OWNER/REPO."
-  echo "OWNER is your username or organisation"
+  echo "OWNER is your username or organization"
   echo "REPO is the name of your repository"
   echo
   read -r -p "Type in the OWNER now:" input
@@ -188,13 +188,13 @@ fi
 case $AUTH in
   0)
   echo
-  echo "Seting origin URL using its https web address"
+  echo "Setting origin URL using its https web address"
   echo
   git remote set-url origin https://github.com/${OWNER}/${REPO}.git
   ;;
   1)
   echo
-  echo "Seting origin URL using SSH"
+  echo "Setting origin URL using SSH"
   echo
   git remote set-url origin [email protected]:$OWNER/$REPO.git
   ;;