Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,138 @@
+---
+license: apache-2.0
+library_name: transformers.js
+language:
+  - en
+  - ja
+  - zh
+  - ko
+  - th
+tags:
+  - coreference
+  - multilingual
+  - onnx
+  - onnxruntime-web
+  - transformers.js
+pipeline_tag: token-classification
+---
+
+# Infon multilingual coreference pointer
+
+Multilingual coreference resolution: detects mentions and links them
+into clusters across **English, Japanese, Korean, Thai, and Chinese**.
+Designed for browser inference via ONNX, replacing the English-only
+fastcoref baseline for multilingual workloads.
+
+## Quick start (JavaScript)
+
+```bash
+npm install @cp500/infon-coref onnxruntime-web
+```
+
+```ts
+import { InfonCorefModel } from '@cp500/infon-coref';
+
+const model = await InfonCorefModel.fromHub('cp500/infon-coref-pointer', {
+  precision: 'fp16',     // 235 MB (default) — vs 470 MB for fp32
+  device: 'auto',        // tries WebGPU, falls back to WASM
+});
+
+const result = await model.resolve(
+  'Toyota announced a partnership with Panasonic. ' +
+  'The Japanese automaker said the deal is worth $250M.'
+);
+
+for (const cluster of result.clusters) {
+  console.log(cluster.map(i => result.mentions[i].text).join(' = '));
+  // Toyota = The Japanese automaker
+}
+```
+
+The JS client source is mirrored under [`js/`](./tree/main/js) in this
+repo for self-contained installs:
+
+```bash
+npm install ./js
+```
+
+## Quick start (Python / PyTorch)
+
+```python
+import torch
+from transformers import AutoModel, AutoTokenizer
+# Architecture lives in scripts/train_coref_pointer.py / coref_onnx_experiment.py
+# (the training repo). Loading the heads is a 4-line check:
+heads = torch.load("heads.pt", map_location="cpu", weights_only=True)
+backbone = AutoModel.from_pretrained("./backbone/")
+tokenizer = AutoTokenizer.from_pretrained("./backbone/")
+```
+
+## Architecture
+
+```
+text ─▶ tokenize ─▶ MiniLM-L12 backbone ─▶ ┬─▶ last_hidden_state ─┐
+                                            └─▶ bio_logits (T,3)    │
+                                                       │             │
+                                                       ▼             │
+                                              decode BIO spans       │
+                                                       │             │
+                                                       ▼             │
+                                          mention_scorer ◀───────────┘
+                                                  │
+                                                  ▼
+                                            pair_scores (P,)
+                                                  │
+                                                  ▼
+                                          per-mention argmax
+                                                  │
+                                                  ▼
+                                          coreference clusters
+```
+
+Two ONNX graphs:
+
+- `onnx/coref_backbone_bio.onnx` — XLM-R-distilled MiniLM-L12 (H=384,
+  12 layers, 117M params) plus a 3-class BIO mention-detection head.
+- `onnx/coref_mention_scorer.onnx` — vectorised mention pooling
+  (boundary tokens + segment-mean) and a pairwise antecedent scorer.
+  DUMMY antecedent is concatenated at index 0 so `pair_j == 0` means
+  "no antecedent."
+
+## Evaluation
+
+Best checkpoint (selected on combined `(ptr_acc + bio_f1) / 2`):
+
+| Language | Pointer acc | BIO F1 | Val mentions |
+|----------|-------------|--------|--------------|
+| en | 0.805 | 0.809 | 1827 |
+| ja | 0.823 | 0.794 | 1601 |
+| ko | 0.824 | 0.814 | 1702 |
+| th | 0.820 | 0.906 | 1495 |
+| zh | 0.829 | 0.872 | 1589 |
+
+**Aggregate**: pointer accuracy 0.820, BIO F1 0.815,
+combined score 0.817.
+
+Trained on
+[cp500/infon-coref-multilingual](https://huggingface.co/datasets/cp500/infon-coref-multilingual).
+
+### Known limits
+
+- BIO precision degrades after epoch 0 if training continues with the
+  default joint-loss schedule (pointer head saturates and the
+  optimizer pushes BIO toward recall). The deployed checkpoint is
+  from epoch 0 to keep BIO precision and pointer accuracy balanced.
+  A fix using separate optimizers per head is on the roadmap.
+- Trained only on the 5 listed languages. Other XLM-R-supported
+  languages may work via zero-shot transfer; verify on your domain.
+- Synthetic training data follows news-article register; out-of-domain
+  text (chat, code comments, formal contracts) may underperform.
+
+## Backbone
+
+`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` — public Apache-2.0 distillation of XLM-R-base.
+Tokenizer copied here for offline-installable parity.
+
+## License
+
+Apache 2.0 for both weights and code.