PUBLISHING.md

# Publishing this model to the Hugging Face Hub

This directory is a complete Hugging Face model repository. It holds the loadable
spaCy pipeline, the installable wheel, and the model card in `README.md`.

## Contents

| Path | What it is |
|---|---|
| `README.md` | model card, including the YAML front matter the Hub reads |
| `config.cfg`, `meta.json` | pipeline configuration and metadata |
| `tokenizer`, `vocab/` | tokeniser and vocabulary, including floret vectors |
| `tok2vec/`, `tagger/`, `morphologizer/`, `trainable_lemmatizer/`, `parser/` | trained component weights |
| `en_matilda_oe_ud-1.0.0-py3-none-any.whl` | installable package, for `pip install` |
| `.gitattributes` | LFS tracking for the binary weights |

Loading the directory directly works without installing anything:

```python
import spacy
nlp = spacy.load("model")
```

## One-time setup

```bash
pip install huggingface_hub
huggingface-cli login
```

## Creating the repository and uploading

Replace `<org>` with your Hugging Face user or organisation name.

```bash
huggingface-cli repo create en_matilda_oe_ud --type model

git lfs install
git clone https://huggingface.co/<org>/en_matilda_oe_ud hf-en_matilda_oe_ud
cp -R model/. hf-en_matilda_oe_ud/

cd hf-en_matilda_oe_ud
git add .
git commit -m "MATILDA Old English UD pipeline v1.0.0"
git push
```

`.gitattributes` already routes the weights and the wheel through Git LFS, so no
further configuration is needed.

## Checking the upload

Once the push completes, confirm that the published artefacts work end to end:

```bash
pip install https://huggingface.co/<org>/en_matilda_oe_ud/resolve/main/en_matilda_oe_ud-1.0.0-py3-none-any.whl
python -c "import spacy; print([(t.text, t.pos_, t.dep_) for t in spacy.load('en_matilda_oe_ud')('Hwæt we Gardena in geardagum þeodcyninga þrym gefrunon .')])"
```

On the Hub page, the metrics declared in the `model-index` block of the card
should appear in the sidebar, and the language should show as `ang`.

## Rebuilding the wheel

If the pipeline is retrained, regenerate the package before uploading:

```bash
python -m spacy package model/ dist/ --name matilda_oe_ud --version 1.0.0 --build wheel
```

The resulting wheel is written to `dist/en_matilda_oe_ud-1.0.0/dist/`.

## Naming

The package is `en_matilda_oe_ud` while the repository language tag is `ang`.
spaCy derives the package prefix from the pipeline's `lang`, which is `en`
because no Old English tokeniser exists in spaCy and the baseline study used the
English one. Every trained component is Old English only. The discrepancy is
recorded in the model card so that users are not misled by the prefix.