TypeScript/Deno Model Parsing Demo

This directory contains a minimal, standalone TypeScript demonstration that loads the trained DeBERTa-Biaffine dependency parser model directly using ONNX Runtime.

The parser takes a raw sentence and returns:

1. Part-of-Speech tags (Universal POS)
2. Dependency Heads (index of parent token, where 0 is ROOT)
3. Dependency Relations (DepRel)
4. Morphological Features (Feats in alphabetical CoNLL-U format)

All word-level tokenization rules (such as contraction splitting) are implemented in pure TypeScript, matching the Python/Rust pipelines exactly to prevent train-serve skew.

---

File Structure

• parser.ts: Main class implementation (DebertaBiaffineParser). Handles the regex word-tokenizer, ONNX inference (onnxruntime-node), tokenization (@huggingface/transformers), and greedy decoding logic. Fully commented in English.
• download.ts: Interactive downloader utility. Retrieves model files directly from Hugging Face and saves them to a local models/ directory with a progress indicator.
• demo.ts: Command-line script to parse input sentences. Automatically detects local downloaded models and supports custom paths/sentences.
• README.md: This documentation file.

---

1. Download Model (download.ts)

Before running the parser, you need to download a model bundle. Run the interactive download script:

deno run --allow-net --allow-write --allow-read download.ts

The script will ask you to select a default repository (e.g. ghotriw/...-xsmall or ghotriw/...-small) or enter a custom Hugging Face repository (format: username/repo). All required files (config.json, vocabs.json, tokenizer.json, model.onnx) will be downloaded to models/<model-name>/.

---

2. Parse Sentence (demo.ts)

Once a model is downloaded, you can test it on a sentence. demo.ts will search for local model folders automatically.

First Run (requires downloading and caching tokenizers from Hugging Face):

deno run --allow-env --allow-read --allow-net --allow-write --allow-ffi demo.ts "He spilled the beans."

Subsequent Runs (fully offline with minimal permissions):

Once the tokenizer configurations are cached locally, you can run the parser without network and write permissions:

deno run --allow-env --allow-read --allow-ffi demo.ts "He spilled the beans."

Customizing the Model:

You can specify a model directory path explicitly using the --model (or -m) flag:

deno run --allow-env --allow-read --allow-ffi demo.ts --model models/deberta-v3-xsmall-biaffine-dep-pos-feats-en-ewt-gum-norm "She kicked the bucket."

---

Model Limitations & Input Length

• Context Window (512 Subwords): The underlying DeBERTa-v3 encoder has a hard positional limit of 512 subwords (tokens).
• Word Packing: In our model architecture, words are tokenized into subwords and packed into a flat sequence. Since English words contain ~1.3 to 1.5 subwords on average, a sentence can have up to ~300-380 words before hitting the 512 subword limit.
• Handling Overflow: If a sentence exceeds this limit, the model will not crash. However, words located beyond the 512th subword position will be truncated internally, resulting in poor parsing accuracy for the end of the sentence.
• Best Practice: Always split large paragraphs or blocks of text into individual sentences (e.g., using a sentence-splitter library) before passing them to the parser.

---

Example Output

Using model directory: "models/deberta-v3-xsmall-biaffine-dep-pos-feats-en-ewt-gum-norm"
Sentence to parse:    "He spilled the beans."
--------------------------------------------------------------------------------
Loading model and tokenizer (downloads config on first run)...
Model initialized successfully!

Parsing...

Dependency Parsing Results:

ID  Word            UPOS        Head      DepRel          Morphological Features
====================================================================================================
1   He              PRON        2         nsubj           Case=Nom|Gender=Masc|Number=Sing|Person=3|PronType=Prs
2   spilled         VERB        0         root            Mood=Ind|Number=Sing|Person=3|Tense=Past|VerbForm=Fin
3   the             DET         4         det             Definite=Def|PronType=Art
4   beans           NOUN        2         obj             Number=Plur
5   .               PUNCT       2         punct           _