HUGGINGFACE.md

# Publishing TinyLiquid Analyst on Hugging Face (for downloads → grants/loans)

## 1. Prepare the artifact

```bash
export PYTHONPATH=$PWD
# after the training pipeline finishes (ckpt/dpo exists):
.venv/bin/python hf/export_hf.py --ckpt ckpt/dpo --out hf_repo     # safetensors + q8 + configs + modeling file
.venv/bin/python hf/export_gguf.py --ckpt ckpt/dpo --out hf_repo/tiny-liquid-q8.gguf
.venv/bin/python eval/bench.py --ckpt ckpt/dpo --out bench/metrics.json
.venv/bin/python hf/build_card.py --metrics bench/metrics.json     # model card from real metrics
```

Sanity checks before publishing:

```bash
# 1) transformers path (trust_remote_code) produces coherent text
.venv/bin/python - << 'PY'
from transformers import AutoModelForCausalLM, AutoTokenizer
tok = AutoTokenizer.from_pretrained("hf_repo")
m = AutoModelForCausalLM.from_pretrained("hf_repo", trust_remote_code=True)
m.persona_id = 1
ids = tok("<|analyst|><|user|>Verify: 'The bridge was painted in 2019 and never repainted.' Records show a 2022 repaint permit.<|assistant|>", return_tensors="pt").input_ids
print(tok.decode(m.generate(ids, max_new_tokens=80, do_sample=True)[0]))
PY

# 2) GGUF round-trips natively
.venv/bin/python -m model.gguf_runtime --gguf hf_repo/tiny-liquid-q8.gguf \
    --prompt "<|analyst|><|user|>What's your take on coincidences?<|assistant|>"
```

## 2. Publish

```bash
huggingface-cli login          # paste your HF token
.venv/bin/python hf_upload.py --repo YOURNAME/tiny-liquid-analyst
```

Then on the HF web page:
- set the **License** to `apache-2.0` (already in the model card metadata),
- add **tags**: `tiny-model`, `on-device`, `liquid-architecture`, `fact-checking`, `osint`, `gguf`,
- add a **demo** (optional): `demo/serve.py` behind a tunnel, or the HF Spaces template,
- pin the README's `YOUR-ORG` links after upload.

## 3. Grant/loan-ready framing (what reviewers look for)

- **Reproducibility**: every step in this repo is scripted (`run_*.sh`, `data/gen_*.py`,
  `hf/export_*.py`, `eval/bench.py`). Include the commit hash in your application.
- **Originality**: non-transformer liquid architecture, own tokenizer, own data pipeline, own
  SOP/agent tooling — nothing is a wrapper around another model.
- **Efficiency story**: 7.8M params, trained on an 8-core ARM laptop with no GPU, quantized to
  ~5-11 MB. That is the headline for edge-AI grants: *SOTA-scale capability per watt*.
- **Evidence**: `bench/metrics.json` (val perplexity, probe accuracy, tok/s) plus generation
  samples in the model card. Add a short technical report citing them.
- **Guardrails**: the OSINT/dark-web tooling is scoped to authorized research with hard stop
  rules — show this explicitly; it de-risks your application.
- **Community**: answer questions on the HF discussion tab, add a Spaces demo, and post
  quantization/config updates. Downloads follow usefulness, not hype.

## 4. Growth levers after v1

- Code stage (continuation pretraining on `data/code_train.bin`) — planned next.
- Bigger variant (e.g., 30-60M MoE) once a GPU or cloud budget appears.
- Multilingual tokenizer + a second persona language.
- ONNX export + onnxruntime for even faster ARM inference.