docs/publishing.md

# Publishing Guide

This checklist keeps the repository usable as both a Python package and a Hugging Face
artifact.

## Local Checks

```bash
python -m pip install -e ".[dev,examples,publish]"
python -m ruff check .
python -m ruff format --check .
python -m pytest
python -m compileall -q src scripts
time-anchor-infer --no-impact
python -m build
```

Run the plotting example when `matplotlib` is installed:

```bash
time-anchor-sine-test
```

## Hugging Face Model Hub

The current Hugging Face CLI is `hf`.

```bash
hf auth login
hf repo create K-Iwa/time-anchor-modernbert-32m --repo-type model --exist-ok
```

For a model-only repository, upload the checkpoint files:

```bash
hf upload K-Iwa/time-anchor-modernbert-32m models/time-anchor-modernbert-32m . --repo-type model
```

Users can then load it with:

```python
from time_anchor import TimeAnchorPipeline

pipeline = TimeAnchorPipeline.from_pretrained("K-Iwa/time-anchor-modernbert-32m")
```

For a combined code/model repository, upload the full project:

```bash
hf repo create K-Iwa/time-anchor --repo-type model --exist-ok
hf upload K-Iwa/time-anchor . . --repo-type model --exclude output --exclude dist --exclude .venv
```

Users should load the nested checkpoint with:

```python
from time_anchor import TimeAnchorPipeline

pipeline = TimeAnchorPipeline.from_pretrained(
    "K-Iwa/time-anchor",
    subfolder="models/time-anchor-modernbert-32m",
)
```

Use `hf upload-large-folder` instead of `hf upload` if the upload is interrupted often or
the checkpoint directory grows substantially.

## Python Package Distribution

The Python package distribution is intentionally lightweight. `MANIFEST.in` includes
source, documentation, license files, and the small example CSV. Model weights and
generated outputs are not part of the package distribution; publish model weights on
Hugging Face Hub instead of PyPI.

Check the generated files before uploading:

```bash
python -m build
python -m twine check dist/*
```

## GitHub or Source Release

```bash
git init
git add .
git commit -m "Prepare Time-Anchor for public release"
```

Before publishing source-only mirrors, decide whether the checkpoint should be included.
If model weights are included, keep Git LFS enabled for `*.safetensors`.

## Release Hygiene

- Confirm that `output/` only contains generated files and is not committed.
- Keep `examples/sample_data.csv` small.
- Update the README examples if the checkpoint folder or default target column changes.
- Add benchmark or evaluation notes before advertising quantitative quality claims.