Skip to content

About

Train, evaluate and publish compact models for dictionary meaning selection in English and Portuguese

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

sense-model

Train, evaluate, and publish compact models that choose a word's meaning in context. Supply a sentence, an exact target span, and dictionary definitions; receive scores, a selected candidate, or abstention. English and Portuguese share one Python API and prepared-data format. Dictionary lookup belongs to the application.

Install

Python 3.11+ and uv:

uv sync --extra train --extra export --extra dev
uv run wsd --help
uv run pytest

The lock defaults to CPU PyTorch. For GPU training use a separate environment with a CUDA PyTorch wheel appropriate for the machine (uv pip install with the PyTorch CUDA index), then install this package with training extras. Never install this project from the sibling upstream directory: both packages use wsd.

Predict

uv run wsd predict --model sign/Ettin-150m-WSD \
  --input data/fixtures/smoke.jsonl --output runs/predictions.jsonl

The first explicit model load downloads weights. Use --local-files-only to require cached files. No dictionary server, spaCy, entity linker, or account is needed once model files are cached. Literal * markers and mask tokens are rejected by the current compact prompt format; oversized prompts are refused. The checkpoint limit is 127 candidates. Single-candidate inputs still permit rejection. Empty candidate lists return no_candidates without model execution.

from wsd import Predictor, Example, Target, Candidate

text = 'She sat on the bank.'
start = text.index('bank')
example = Example(
    id='example', text=text, target=Target(start, start + 4, 'bank'),
    candidates=[Candidate('river', 'sloping land beside a body of water'),
                Candidate('finance', 'a financial institution')],
)
model = Predictor.from_pretrained('sign/Ettin-150m-WSD')
print(model.predict([example]))

Target offsets count Unicode code points and end exclusively. Node consumers must convert UTF-16 selection offsets; the Node example provides that conversion. Candidate IDs are opaque, unique strings. They never have to be WordNet IDs. none_fits is the model's explicit rejection; uncertain is threshold-based abstention. Uncalibrated scores are not confidence guarantees.

Lifecycle

uv run wsd prepare --help
uv run wsd train --help
uv run wsd teacher --help
uv run wsd evaluate --help
uv run wsd export --help
uv run wsd publish --help

See data preparation, training, evaluation, release/export, and implementation status and Portuguese training smoke receipt. Configuration examples live in configs. Small authored smoke examples are tests of software mechanics, not a benchmark.

Build and review an automatic dataset

uv sync --extra pilot --extra train --extra export --extra dev
uv run wsd config init
# Set jev.api_key in ~/.config/sense-model/config.toml.
# Set generation.lexicon_en / lexicon_pt to your dictionary JSONL paths.
cp papers.example.json papers.json
# Put PDFs in papers/ and edit papers.json to list them.
uv run wsd generate --input papers.json --samples-per-paper 10
uv run wsd label
uv run wsd annotate --import-file data/pilot/generated/labeled/samples.jsonl --open

The generator reads a JSON manifest pointing to local PDFs in papers/, processes every listed paper in order, and requests 10 samples per paper by default (5 easy, 3 medium, 2 hard). Set --samples-per-paper to change that count. JSON manifest paths resolve relative to the manifest file. The generator selects authentic paper passages with local Codex and attaches pinned dictionary meanings. The labeler calls Jev for every example, then asks Codex to independently check low/missing-confidence results or failed requests. The default CLI model is gpt-6-luna; both scripts accept an override. Local Codex uses hosted inference through your existing CLI login, not offline inference.

Review automatic proposals in dark cards, filter by confidence and disagreement, correct or approve them, and export the same JSONL format with human labels. The local server loads no WSD weights. Default workspace: .annotation/workspace.sqlite. API keys stay in private local configuration.

Read the automatic pilot plan, generation guide, labeling guide, and review guide. See the verification receipt for tested behavior and the dark-interface screenshot. The two standalone entry points are scripts/generate_dataset.py and scripts/label_dataset.py; wsd generate and wsd label call the same code. Automatic labels are silver: evaluation requires review; training on silver data requires an explicit --allow-silver. Downloaded papers and generated datasets are excluded from Git. The older manual wsd pilot collect/audit workflow and independent-review annotation mode remain available for existing datasets.

Portuguese

The starting candidate is jhu-clsp/mmBERT-small, a multilingual ModernBERT. Initialize/train its compact answer decoder with Portuguese contexts and Portuguese definitions. The same inference code accepts an artifact produced by training. Until representative training, calibration, and evaluation are done, this project does not claim a production-ready Portuguese checkpoint. A generic multilingual base is not a trained WSD model.

The package supports separate English/Portuguese artifacts and independent teacher/student tokenizers. A bilingual checkpoint is an optional experiment, not an assumption. Source language and definition language are recorded separately.

Origins and attribution

Model, decoder-pruning and answer-letter code is adapted from sign/word-sense-disambiguation, using local fork commit d1f7e107f2c072e876f031fdd5935bf496a0ef1b. The sibling fork is retained as the reference implementation. This project extracts candidate selection and provides portable datasets, training, evaluation, ONNX/Node deployment, and explicit Hub release tooling.

Original code copyright (c) 2026 Nagish Inc., MIT. See LICENSE and NOTICE. Model weights and datasets retain their own terms. The upstream English WSD checkpoint declares Apache-2.0; mmBERT-small declares MIT. Every release must document exact base/data revisions and applicable notices.

About

Train, evaluate and publish compact models for dictionary meaning selection in English and Portuguese

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages