README.md

---
license: mit
base_model: microsoft/mdeberta-v3-base
tags:
- causal-extraction
- causality
- cause-effect
- span-extraction
- causal-news-corpus
- multilingual
language:
- en
- es
- fr
- de
- pt
- tr
- ru
- ar
- zh
- ja
---

# causal-span-pointer-mdeberta

A **span-pointer** causal extraction model: given a sentence it predicts the
**cause**, **effect** and **signal** spans as start/end pointers, decoded under
ordering/non-overlap constraints with beam search (top-2 relations per sentence).
Fine-tuned from [`microsoft/mdeberta-v3-base`](https://huggingface.co/microsoft/mdeberta-v3-base)
on the [Causal News Corpus](https://github.com/tanfiona/CausalNewsCorpus) Subtask-2
(CC0). Architecture reimplemented from the CNC baseline (MIT).

## Benchmark (Causal News Corpus Subtask 2)

Official scorer (`evaluation/subtask2`: FairEval + best-combination alignment), V2 dev:

```
Overall  F1 0.689   (span extraction; with the causal gate + beam dedup)
  Cause    F1 0.72  |  Effect  F1 0.69  |  Signal  F1 0.65
  Multi-relation sentences: F1 0.50  (beam top-2 decoding)
  Causal gate: accuracy 0.85 (precision 0.86, recall 0.87) on CNC dev

Context (same official scorer):
  Organizer baseline (2023, dev)     0.627   <- this model beats it
  1Cademy (2022 winner, test)        0.542
  BoschAI (2023 winner, test)        0.728

Trained on English CNC Subtask-2 (relations=all) + 1451 non-causal negatives for the
gate, mDeBERTa-v3, lr 3e-5, 10 epochs. Multilingual at inference (script-aware
segmentation). Augmented data was tried and hurt, so it is unused.
```

**This beats the organizer's 0.627 dev baseline** and the 2022 shared-task winner
(0.542, test); it trails the 2023 winner (0.728, test). Same scorer, same dev set.

## Usage

This is a custom architecture, so inference goes through the `causal_span_model`
package (not `AutoModel`):

```python
from huggingface_hub import snapshot_download
from causal_span_model.pointer.submission import load_pointer, predict_sentence

local_dir = snapshot_download("Berk/causal-span-pointer-mdeberta")
model, tokenizer = load_pointer(local_dir)
print(predict_sentence(model, tokenizer, "Heavy rainfall caused severe flooding."))
# ['<ARG0>Heavy rainfall</ARG0> <SIG0>caused</SIG0> <ARG1>severe flooding</ARG1> .', ...]
```

`<ARG0>` = cause, `<ARG1>` = effect, `<SIG0>` = signal. The prediction is a list of
tagged relation strings (up to two per sentence).

### Multilingual

Trained on English spans, but multilingual at inference (mDeBERTa encoder +
script-aware segmentation). Use `predict_relations`, which returns character-exact
spans in any script:

```python
from causal_span_model.pointer.infer import predict_relations

predict_relations(model, tokenizer, "暴雨导致该地区发生严重洪灾。")
# [{'cause': '暴雨', 'effect': '该地区发生严重洪灾', 'signal': '导致'}]
predict_relations(model, tokenizer, "Las fuertes lluvias provocaron inundaciones.")
# [{'cause': 'Las fuertes lluvias', 'effect': 'inundaciones', 'signal': 'provocaron'}]
```

Verified on es/fr/de/pt/tr/ru/ar and CJK (zh/ja).

## Notes

- It is NOT compatible with a generic token-classification ONNX consumer -- it
  needs its own start/end + beam-search decoder (provided by the package).
- It has a built-in **causal gate** (a causal/non-causal head, ~0.85 accuracy on
  CNC dev): `predict_relations` returns `[]` on text it judges non-causal, so it
  is safe to run on arbitrary input. Beam duplicates are collapsed to one relation
  per distinct cause->effect.

## License

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