Metadata-Version: 2.4
Name: renard-pipeline
Version: 0.7.1
Summary: Relationships Extraction from NARrative Documents
Project-URL: Homepage, https://github.com/CompNet/Renard
Project-URL: Documentation, https://compnet.github.io/Renard/
Project-URL: Repository, https://github.com/CompNet/Renard
Author-email: Arthur Amalvy <arthur.amalvy@univ-avignon.fr>
License: GPL-3.0-only
License-File: LICENSE
Requires-Python: <3.13,>=3.9
Requires-Dist: accelerate>=1.10.1
Requires-Dist: datasets>=4.0.0
Requires-Dist: grimbert>=0.1.5
Requires-Dist: matplotlib>=3.9
Requires-Dist: more-itertools>=10.7
Requires-Dist: nameparser>=1.1.3
Requires-Dist: networkx>=3.2
Requires-Dist: nltk>=3.9.1
Requires-Dist: protobuf>=6.33.2
Requires-Dist: pytest>=8.4.1
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: tibert>=0.5.2
Requires-Dist: tiktoken>=0.12.0
Requires-Dist: torch>=2.7.0
Requires-Dist: tqdm>=4.67.1
Requires-Dist: transformers>=4.57.1
Provides-Extra: cpu
Requires-Dist: torch>=2.7.1; extra == 'cpu'
Provides-Extra: cuda128
Requires-Dist: torch>=2.7.1; extra == 'cuda128'
Provides-Extra: rocm63
Requires-Dist: pytorch-triton-rocm>=3.1.0; extra == 'rocm63'
Requires-Dist: torch>=2.7.1; extra == 'rocm63'
Provides-Extra: rocm64
Requires-Dist: pytorch-triton-rocm>=3.1.0; extra == 'rocm64'
Requires-Dist: torch>=2.7.1; extra == 'rocm64'
Provides-Extra: ui
Requires-Dist: gradio>=4.44.1; extra == 'ui'
Requires-Dist: pyvis>=0.3.2; extra == 'ui'
Description-Content-Type: text/markdown

# Renard

[![DOI](https://joss.theoj.org/papers/10.21105/joss.06574/status.svg)](https://doi.org/10.21105/joss.06574)

<img src="https://compnet.github.io/Renard/_images/renard.svg" align="right" alt="the Renard logo" width="240">

Renard (Relationship Extraction from NARrative Documents) is a modular library for creating and using custom character networks extraction pipelines. Renard can extract dynamic as well as static character networks. Renard is modular, in the sense that you can easily create a custom extraction pipeline that fits your needs.


# Installation

Currently, Renard supports Python>=3.9,<=3.12. You can install the
latest version using pip:

> pip install renard-pipeline

If you have a GPU, there are accelerated versions for Nvidia CUDA and
AMD ROCm:

> pip install renard-pipeline[cuda128]
> pip install renard-pipeline[rocm63]


# Documentation

Documentation, including installation instructions, can be found at https://compnet.github.io/Renard/

If you need local documentation, it can be generated using `Sphinx`. From the `docs` directory, `make html` should create documentation under `docs/_build/html`. 


# Interactive Demo

You can check the [interactive demo of Renard at HuggingFace](https://huggingface.co/spaces/compnet-renard/renard-demo). The UI used for the demo is currently in development and will be available directly in Renard in the next version.


# Tutorial

Renard's central concept is the `Pipeline`.A `Pipeline` is a list of `PipelineStep` that are run sequentially in order to extract a character graph from a document. Here is a simple example:

```python
from renard.pipeline import Pipeline
from renard.pipeline.tokenization import NLTKTokenizer
from renard.pipeline.ner import NLTKNamedEntityRecognizer
from renard.pipeline.character_unification import GraphRulesCharacterUnifier
from renard.pipeline.graph_extraction import CoOccurrencesGraphExtractor

with open("./my_doc.txt") as f:
	text = f.read()

pipeline = Pipeline(
	[
		NLTKTokenizer(),
		NLTKNamedEntityRecognizer(),
		GraphRulesCharacterUnifier(min_appearance=10),
		CoOccurrencesGraphExtractor(co_occurrences_dist=25)
	]
)

out = pipeline(text)
```

For more information, see `renard_tutorial.py`, which is a tutorial in the `jupytext` format. You can open it as a notebook in Jupyter Notebook (or export it as a notebook with `jupytext --to ipynb renard-tutorial.py`).


# Contributing

see [the "Contributing" section of the documentation](https://compnet.github.io/Renard/contributing.html).

## Running tests 

`Renard` uses `pytest` for testing. To launch tests, use the following command : 

> uv run python -m pytest tests

Alternatively, the project Makefile has a test target:

> make test

Expensive tests are disabled by default. These can be run by setting the environment variable `RENARD_TEST_SLOW` to `1`.



# Renard UI

Since version 0.7, Renard has a web interface powered by gradio. First, install the additional dependencies:

> uv sync --group ui

Then, simply run:

> make ui

And open your browser at http://127.0.0.1:7860


# How to cite

If you use Renard in your research project, please cite it as follows:

```bibtex
@Article{Amalvy2024,
  doi	       = {10.21105/joss.06574},
  year	       = {2024},
  publisher    = {The Open Journal},
  volume       = {9},
  number       = {98},
  pages	       = {6574},
  author       = {Amalvy, A. and Labatut, V. and Dufour, R.},
  title	       = {Renard: A Modular Pipeline for Extracting Character
                  Networks from Narrative Texts},
  journal      = {Journal of Open Source Software},
} 
```

We would be happy to hear about your usage of Renard, so don't hesitate to reach out!
