A Python library to simplify handling causality in natural language: extraction, training extraction models, unified datasets, and storing/querying results as causal graphs.

What is this?

causalatee covers the full lifecycle of working with causality in text:

• Datasets — causality corpora, converted into one consistent HuggingFace-compatible schema across three standardized tasks:
  • Causality Detection — does a sentence express a causal relation at all?
  • Causal Candidate Extraction — which spans in a sentence are causes/effects?
  • Causality Identification — given two marked spans, does a causal relation hold between them?
• causalatee.models — batch-callable typing.Protocol interfaces (Detection, CandidateExtraction, PairwiseIdentification, Identification, Extraction) that any conforming model (rule-based, HuggingFace, or otherwise) satisfies with zero inheritance, plus compose_extraction to build an end-to-end extractor from the three sub-tasks.
• causalatee.graph — a typed Graph/Node/Edge interface with several interchangeable backends: an eager CauseNet loader, CGF (a compact, memory-mappable on-disk format), a CausalBank Cause-Effect Graph loader, and SQLGraph, a generic mutable graph you build yourself via add_node/add_edge.
• causalatee.mining — a streaming, concurrency-aware pipeline (source -> flat_map -> filter -> map -> map -> reduce) that turns a corpus of raw documents into an aggregated causal graph, without materializing the corpus in memory.
• causalatee.nn / causalatee.integrations — a biaffine span-grid extraction head, and ready-made HuggingFace Pipeline / PyTorch Lightning integrations for the three tasks above.

See causalatee.webis.de for the full documentation, including the dataset inventory, task/model reference, and runnable example notebooks.

Installation

pip install causalatee

Optional extras pull in dependencies for specific pieces: huggingface (fine-tuning/inference pipelines), baselines (dependency-parse baselines), mining (the corpus-mining pipeline), and docs (building this documentation locally).

Quick start

Every converted dataset is a standard HuggingFace dataset, indexed by task:

from datasets import load_dataset

dataset = load_dataset("thagen/CausalNewsCorpus", "causality identification")

See the Datasets page for the full list, and the Examples notebooks for fine-tuning a model, building a causal graph, and mining one from a raw corpus.

Development

pip install -e ".[tests]"
ruff check .
mypy -p causalatee
pytest

Building the Documentation

pip install -e ".[docs]"
mkdocs serve       # live-reloading local server
mkdocs build       # static site written to site/