Hub Privacy & Upload Options

Every praisonai-train Hub push is private by default — opt in to publish, tune the commit, tags, and save method

Every Hub push from praisonai-train is private by default. Set hf_private: false in config.yaml to publish.

Diagram

Quick Start

Publish to a public repo — opt out of the private default with one key.

yaml

# config.yaml
model_name: unsloth/gemma-2-2b-it-bnb-4bit
hf_model_name: me/my-model         # namespaced, always
huggingface_save: true             # push after training
hf_private: false                  # opt-in to publish publicly
commit_message: "v0.1 from praisonai-train"
tags: ["praisonai", "gemma-2"]

bash

praisonai train

Omit hf_private entirely and the repo is created private — the safe default.

Config keys

Every key that shapes a Hub push, read from _hub.py::hub_push_kwargs and the trainer’s KNOWN_KEYS.

Key	Type	Default	Description
`hf_private`	bool	`true`	Push as a private repo, fail-closed. Publish only on `false, no, 0, off, n`; keep private on `true, yes, 1, on, y` (or unset). Any other value stays private and prints a warning.
`save_method`	string	`"merged_16bit"`	Passed to Unsloth’s `push_to_hub_merged`. Previously hardcoded to `merged_16bit` at every push site.
`commit_message`	string	—	Optional commit message on the Hub. Only sent when set.
`tags`	list[string]	—	Optional tags on the Hub repo. Only sent when set.
`hf_model_name`	string	required	Hub repo id (e.g. `me/my-model`) — see the safety note below.
`hf_token`	string	—	Config-level Hugging Face token. Overridden by the `HF_TOKEN` env var and a cached login. Also the download credential for gated base models.

Accepted values for `hf_private`

hf_private fails closed: only the publish set opts out, and anything unrecognised stays private.

text

Publish (private = false):   false   no   0   off   n
Keep private (private = true): true   yes  1   on   y     (also None / unset)
Anything else:               warn, keep PRIVATE

Any value outside those two sets — "private", "enabled", 5, "", "maybe", [] — keeps the repo private and prints:

text

WARNING: hf_private='enabled' is not a yes/no value; keeping the repository PRIVATE. Use hf_private: false to publish.

Authentication

A write-scoped token, from an env var, a cached login, or config — any works.

bash

export HF_TOKEN=hf_...
# or
huggingface-cli login

Or set it in config.yaml as hf_token — the config-level twin of the env var:

yaml

# config.yaml
hf_token: "hf_xxx"

Precedence: HF_TOKEN env var wins, then a cached huggingface-cli login, then hf_token from config.

Source	Key	When it wins
Env var	`HF_TOKEN` / `HUGGING_FACE_HUB_TOKEN`	Always, if set
Cached login	`huggingface-cli login`	If no env var
Config	`hf_token`	If neither of the above

The token must have write scope, and the repo must be under your own username or an org you can write to.

Error translation

A rejected push turns into a one-line fix, not a stack trace — now shared by all three push sites (LLM, vision, and upload-vision) via _hub.py::raise_hf_push_error.

Status	Message keyword	What to do
401	“rejected the credentials”	Run `huggingface-cli login`, or `export HF_TOKEN=…` with write scope
403	“refused write access”	Repo must be under your username / an org you can write to; token needs write scope
other	“upload to ‘<repo>’ failed”	Raw upstream error preserved after the actionable prefix

Safety note on `hf_model_name`

Always use the namespaced form me/model, never a bare name.

praisonai-train deletes a local stale output directory of that name before an upload (_hub.py::clean_local_repo_dir), but a namespaced repo id like me/model is never treated as a path to delete — even if ./me/model exists locally. A bare name with no / is treated as a local directory and removed.

Best Practices

Leave hf_private unset for private repos

The default is private. Only add hf_private: false when you deliberately want a public repo — and double-check the dataset was public too.

Always namespace hf_model_name

Use me/model, never a bare model. A namespaced id is a Hub target and is never deleted as a local path.

Set a write token once

Run huggingface-cli login (cached tokens count) or export HF_TOKEN=hf_... with write scope before the run — preflight fails fast if it’s missing.

Add commit_message and tags for traceability

commit_message and tags are only sent when set — use them to label each upload on the Hub.

Export a trained model

Publish an already-trained model to HF, GGUF, or Ollama without re-training.

Keep an Ollama export local

Stop after ollama create with --no-push or ollama_push: false.

Train

Full fine-tuning flow and config.yaml reference.

Preference Tuning

Fine-tune with DPO, ORPO, or KTO preference pairs.

Unsloth Surface

Gated model access, PEFT selectors, offline merge, and vLLM rollouts.