This library provides several versions of the Rhetorical Structure (RST) parser for multiple languages. Below, you will find instructions on how to set up and run the parser either locally or using Docker.

• Performance
• Installation & Quick Start
• Visualizing the RST Tree
• Advanced Usage
• Docker Setup
• Citation

The parser achieves strong end-to-end performance across various standard RST corpora.

Supported languages (all): English (eng), Czech (ces), German (deu), Basque (eus), Persian (fas), French (fra), Dutch (nld), Brazilian Portuguese (por), Russian (rus), Spanish (spa), and Chinese (zho).

This guide covers the most common use case: running the parser locally.

Install isanlp from GitHub and isanlp_rst from PyPI:

pip uninstall isanlp -y && pip install git+https://github.com/iinemo/isanlp.git
pip install isanlp_rst

The following example initializes and runs the parser.

from isanlp_rst.parser import Parser

# Define the version of the model you want to use
version = 'gumrrg'  # Choose from {'gumrrg', 'rstdt', 'rstreebank'}

# Initialize the parser
parser = Parser(hf_model_name='tchewik/isanlp_rst_v3', 
                hf_model_version=version, 
                cuda_device=0) # Use -1 for CPU

text = """
On Saturday, in the ninth edition of the T20 Men's Cricket World Cup, Team India won against South Africa by seven runs. 
The final match was played at the Kensington Oval Stadium in Barbados. This marks India's second win in the T20 World Cup, 
which was co-hosted by the West Indies and the USA between June 2 and June 29.

After winning the toss, India decided to bat first and scored 176 runs for the loss of seven wickets. 
Virat Kohli top-scored with 76 runs, followed by Axar Patel with 47 runs. Hardik Pandya took three wickets, 
and Jasprit Bumrah took two wickets.
"""

# Parse the text to obtain the RST tree
res = parser(text) # res['rst'] contains the binary discourse tree

# Inspect the structure of the root node
print(vars(res['rst'][0]))

To use the multilingual UniRST model, you can specify the required relation inventory with relinventory='lang.code.dataset', as listed in the UniRST performance table. The default inventory for UniRST is eng.rst.rstdt.

parser = Parser(hf_model_name='tchewik/isanlp_rst_v3',
                hf_model_version='unirst',
                cuda_device=0,
                relinventory='eng.erst.gum')

The parser returns an RST tree with a recursive structure. Each node (Discourse Unit) contains:

{
 'id': 21,
 'left': (id=14, start=1, end=323),  # Left child node
 'right': (id=20, start=324, end=570), # Right child node
 'relation': 'elaboration',           # Rhetorical relation
 'nuclearity': 'NS',                 # Nucleus-Satellite status
 'entropy': 0.92,                    # Entropy of the split
 'start': 1,                         # Start character offset
 'end': 570,                         # End character offset
 'text': "On Saturday, ... took two wickets."
}

You can easily visualize the output in several ways.

First, export the parsed tree to the standard .rs3 format.

res['rst'][0].to_rs3('filename.rs3')

You can open filename.rs3 in external tools like RSTTool or rstWeb for editing.

Render the tree directly in your notebook.

import io, contextlib
import isanlp_rst

# Suppress the HTML string from being printed
buf = io.StringIO()
with contextlib.redirect_stdout(buf):
    isanlp_rst.render("filename.rs3")

# If you’re in Google Colab, use colab=True to sync the cell height
# isanlp_rst.render("filename.rs3", colab=True)

To export the visualization, you'll first need to install Playwright:

pip install playwright
playwright install chromium

Then, you can export the .rs3 file:

import isanlp_rst

# Export to PNG
isanlp_rst.to_png("filename.rs3", "filename.png")

# Export to PDF
isanlp_rst.to_pdf("filename.rs3", "filename.pdf")

You can pass custom segments instead of raw text:

my_edus = [
    "On Saturday, Team India won against South Africa.",
    "The final match was played in Barbados."
]

res = parser.from_edus(my_edus)

When parsing many documents, the resulting DiscourseUnit trees can consume significant memory, as each node stores its corresponding text span.

You can use res['rst'][0].clear_textfields() to recursively remove all text from the tree, leaving only the structure (IDs, relations, and character offsets). This makes the tree object lightweight for storage (e.g., pickling).

Later, you can use .fill_textfields(full_text) to repopulate the tree using the original text.

Important: Do not use the .to_rs3() method on a tree with cleared text fields.

You can run the parser as a service using Docker. This is currently available for tags: rstdt, gumrrg, rstreebank.

1. Run the Docker container:

   # Pull and run the 'rstreebank' model on port 3335
   docker run --rm -p 3335:3333 --name rst_rrt tchewik/isanlp_rst:3.0-rstreebank

2. Connect with the isanlp client: (Note: isanlp_rst is not required for the client)

   pip install git+https://github.com/iinemo/isanlp.git

   from isanlp import PipelineCommon
   from isanlp.processor_remote import ProcessorRemote
   
   # Connect to the running container
   address_rst = ('127.0.0.1', 3335)
   
   ppl = PipelineCommon([
       (ProcessorRemote(address_rst[0], address_rst[1], 'default'),
        ['text'],
        {'rst': 'rst'})
   ])
   
   res = ppl(text)
   # res['rst'] will contain the binary discourse tree

If you use the IsaNLP RST Parser in your research, please cite our work:

• For rstdt, gumrrg, and rstreebank models:

  @inproceedings{chistova-2024-bilingual,
   title = "Bilingual Rhetorical Structure Parsing with Large Parallel Annotations",
   author = "Chistova, Elena",
   booktitle = "Findings of the Association for Computational Linguistics ACL 2024",
   month = aug,
   year = "2024",
   address = "Bangkok, Thailand and virtual meeting",
   publisher = "Association for Computational Linguistics",
   url = "https://aclanthology.org/2024.findings-acl.577",
   pages = "9689--9706"
  }
  

• For the unirst model:

  @inproceedings{chistova-2025-bridging,
    title = "Bridging Discourse Treebanks with a Unified Rhetorical Structure Parser",
    author = "Chistova, Elena",
    booktitle = "Proceedings of the 6th Workshop on Computational Approaches to Discourse, Context and Document-Level Inferences (CODI 2025)",
    month = nov,
    year = "2025",
    address = "Suzhou, China",
    publisher = "Association for Computational Linguistics",
    url = "https://aclanthology.org/2025.codi-1.17/",
    pages = "197--208"
   }