README.md

---
license: mit
base_model: microsoft/mdeberta-v3-base
pipeline_tag: token-classification
library_name: transformers
tags:
- token-classification
- causal-extraction
- causality
- cause-effect
- multilingual
- reasongraph
language:
- multilingual
---

# causal-span-mdeberta

A multilingual BIO token classifier that tags **cause**, **effect** and **signal**
spans, fine-tuned from [`microsoft/mdeberta-v3-base`](https://huggingface.co/microsoft/mdeberta-v3-base) on the
[Causal News Corpus](https://github.com/tanfiona/CausalNewsCorpus) (CC0-1.0).
Direction is encoded in the label TYPE, so `cause -> effect` is read straight from
the tags -- reversed phrasing like "the crash resulted from brake failure" is
handled without a separate orientation lexicon.

Built for [reasongraph](https://github.com/bgokden/reasongraph) as the accurate,
model-based causal extractor.

## Labels

```
O
B-CAUSE  I-CAUSE     the cause span
B-EFFECT I-EFFECT    the effect span
B-SIGNAL I-SIGNAL    the causal connective
```

## Usage (transformers)

```python
from transformers import AutoTokenizer, AutoModelForTokenClassification
import torch

tok = AutoTokenizer.from_pretrained("Berk/causal-span-mdeberta")
model = AutoModelForTokenClassification.from_pretrained("Berk/causal-span-mdeberta").eval()

enc = tok("Heavy rainfall caused severe flooding.", return_tensors="pt")
ids = model(**enc).logits[0].argmax(-1).tolist()
toks = tok.convert_ids_to_tokens(enc["input_ids"][0])
print([(t, model.config.id2label[i]) for t, i in zip(toks, ids)])
```

An ONNX build (`onnx/model.onnx`, inputs `input_ids` + `attention_mask`, output
per-token logits) is included for fast CPU inference via onnxruntime -- this is
what reasongraph loads.

## Evaluation

Benchmarked on the Causal News Corpus (CNC) Subtask 2 dev set. This is an honest
**first-pass** model: it is **below the shared-task baseline and SOTA**. Its value
is robust multilingual zero-shot extraction, not leaderboard rank.

```
Official CNC scorer (evaluation/subtask2: best-combination alignment + FairEval), V2 dev,
with best-span decoding (one highest-confidence span per role):

  Overall  F1 0.550   (precision 0.649, recall 0.477)
  Cause    F1 0.48  |  Effect  F1 0.55  |  Signal  F1 0.63
  Multi-relation sentences: F1 0.315  (this model predicts ONE relation per sentence)

  (naive argmax decoding scores 0.475; best-span is the recommended decode and is
   what reasongraph's consumer applies -- the ONNX model is identical.)

Shared-task context (official scorer):
  1Cademy (2022 winner, test)         0.542   <- this model (0.550 dev) is above it
  Organizer baseline (2023, dev)     ~0.627   <- this model is ~8 F1 below
  BoschAI (2023 winner, test)         0.728

Honest positioning: a strong first-pass BIO tagger, competitive with the 2022 field but
below the 2023 baseline and SOTA. The baseline uses a span-pointer + beam-search +
signal-detector architecture; matching it needs that architecture. This model's real
strength is robust multilingual zero-shot extraction.

Own metrics (clean dev): strict exact-span seqeval micro F1 0.48 ; token-level F1 0.79
```

Multilingual capability comes from mDeBERTa-v3's zero-shot cross-lingual transfer;
the training spans are English only.

## Training data

Causal News Corpus V2, subtask 2 (CC0-1.0). ARG0 = cause, ARG1 = effect,
SIG* = signal. Tags can nest (a signal inside an argument) and a sentence may carry
several relations.

## Limitations

- Trained on English news text; other languages rely on zero-shot transfer and are
  less accurate, especially for distant scripts (e.g. Chinese, Arabic).
- News-domain bias; short, explicit causal statements are handled best.
- Multi-relation sentences receive one predicted causal structure.

## License

MIT (weights and code). Training data is CC0-1.0.