manubot-ai-editor 0.5.0

A Manubot plugin to revise a manuscript using GPT-3

Manubot AI Editor

This package provides classes and functions for automated, AI-assisted revision of manuscripts written using Manubot. Check out the manuscript for more information.

Usage

The Manubot AI Editor can be used from the GitHub repository of a Manubot-based manuscript, from the command line, or from Python code.

Manubot-based manuscript repository

You first need to follow the steps to setup a Manubot-based manuscript. Then, follow these instructions to setup a workflow in GitHub Actions that will allow you to quickly trigger a job to revise your manuscript.

Configuring Prompts

In order to revise your manuscript, prompts must be provided to the AI model. There are two ways to do this:

• Default prompts: you can use the default prompts provided by the tool, in which case you don't need to do anything.
• Custom prompts: you can define your own prompts to apply to specific files using YAML configuration files that you include with your manuscript.

If you wish to customize the prompts on a per-file basis, see docs/custom-prompts.md for more information.

Caveats

In the current implementation, the editor can only process one paragraph at a time. This limits the contextual information the LLM receives and thus the specificity of what it can check and fix. For example, in the Discussion section of a manuscript, the first paragraph should typically summarize the findings from the Results section, while the rest of the paragraphs should follow a different structure, but the AI editor can only judge each paragraph in the same way. We plan to reduce or remove this limitation in the future.

Command line

To use the tool from the command line, you first need to install Manubot in a Python environment:

pip install --upgrade manubot[ai-rev]

You also need to export an environment variable with the OpenAI's API key:

export OPENAI_API_KEY=<your-api-key>

You can also provide other options that will change the behavior of the tool (such as revising certain files only). This file documents the list of supported environment variables that can be used. For example, to change the temperature parameter of OpenAI models, you can export the following environment variable: export AI_EDITOR_TEMPERATURE=0.50

Then, within the root directory of your Manubot-based manuscript, run the following commands (IMPORTANT: this will overwrite your original manuscript!):

manubot ai-revision --content-directory content/ --config-directory ci/

The tool will revise each paragraph of your manuscript and write back the revised files in the same directory. Finally, you can select which changes you want to keep or discard.

Before using the OpenAI API and incurring costs, you can run a test by using a dummy, local revision model:

manubot ai-revision \
  --content-directory content/ \
  --config-directory ci/ \
  --model-type DummyManuscriptRevisionModel \
  --model-kwargs add_paragraph_marks=True

When it finishes, check out your manuscript files. This will allow you to detect whether the tool is identifying paragraphs correctly. If you find a problem, please report the issue.

Python API

There is also a Python API that you can use to revise your manuscript. In this case, you don't need to also install Manubot but only this package:

pip install -U manubot-ai-editor

The Python code below shows how to use the API:

import shutil
from pathlib import Path

from manubot_ai_editor.editor import ManuscriptEditor
from manubot_ai_editor.models import GPT3CompletionModel

# create a manuscript editor object
# here content_dir points to the "content" directory of the Manubot-based
# manuscript, where Markdown files (*.md) are located
# config_dir points to where CI-related configuration, including the AI
# editor's configuration, is stored. it's optional, and if left out will
# resort to defaults.
me = ManuscriptEditor(
    content_dir="content",
    config_dir="ci"
)

# create a model to revise the manuscript
model = GPT3CompletionModel(
    title=me.title,
    keywords=me.keywords,
)

# create a temporary directory to store the revised manuscript
output_folder = (Path("tmp") / "manubot-ai-editor-output").resolve()
shutil.rmtree(output_folder, ignore_errors=True)
output_folder.mkdir(parents=True, exist_ok=True)

# then revise the manuscript
me.revise_manuscript(output_folder, model)

# the revised manuscript is now in the folder pointed by `output_folder`

# uncomment the following code if you want to write back the revised manuscript to
# the content folder
# **CAUTION**: this will overwrite the original manuscript
# for f in output_folder.glob("*"):
#     f.rename(me.content_dir / f.name)
# 
# # remove output folder
# output_folder.rmdir()

The cli_process function in this file also provides an example of how to use the API.

Current support for large language models

We currently support the following OpenAI endpoints:

• Completion
• Edits
• ChatCompletion
  • Note: this endpoint is not fully implemented yet. The current implementation uses the chat completion endpoint in a similar way as we use the completion endpoint (each paragraph is revised independently in a query). This is because new models such as gpt-3.5-turbo or gpt-4 are only available through the chat completion endpoint.