hamo-score-toolkit

EN | 中文

Client toolkit and safety scaffold for HamoAI/hamo-score-0.6b — the little model that takes a conversational pulse (AWEHB: Agency / Withdrawal / Extremity / Hostility / Boundary).

This repo is the missing half of the model: the exact prompt format, tolerant output parsing, the smoothing-and-buckets math the scores are designed to feed, and — front and center — the crisis gate that the model license (HAMO-RAIL-S §3c) requires upstream of the model in any consumer-facing deployment.

⚠️ The model is not a chatbot, not a diagnostic instrument, and not a crisis detector. This toolkit makes the safe integration pattern the easy one.

💬 Think a score is wrong? Tell us — that's the most valuable thing you can send. Open a disagreement report → (message + the model's score + the score you'd give). Every report goes into the human gold-label program that steers the next version. The reference scorer this model replaced disagrees with itself 2–6% of the time, so "the model is wrong here" is a real finding, not a nuisance.

5-minute start (ollama)

# 1. get the model (one-time)
hf download HamoAI/hamo-score-0.6b gguf/hamo-score-0.6b-v7.q8.gguf --local-dir /tmp/hamo
ollama create hamo-score-0.6b -f server/Modelfile

# 2. install the toolkit
pip install hamo-score

from hamo_score import OllamaClient, score_message, update_stress, energy_state

client = OllamaClient(model="hamo-score-0.6b")
r = score_message(client, "虽然还是有点提不起劲，不过今天把拖了两周的体检约上了",
                  history=[{"role": "assistant", "content": "这周过得怎么样？"}])

if r.crisis.triggered:          # deterministic gate ran BEFORE the model
    route_to_human(r.crisis.matched)
elif r.scores:
    print(r.scores)             # {'A': 2.5, 'W': 0.5, 'E': 0.0, 'H': 0.0, 'B': 1.0}
    stress = update_stress(r.scores, current_stress=3.0)
    print(energy_state(stress)) # 'positive' / 'negative' / 'neurotic'

That's the whole intended shape: gate → score → smooth → bucket. Scores are per-message signals; never act on a single raw score.

One-command server (Docker)

No Python integration needed — run the whole pipeline as an HTTP service:

git clone https://github.com/HamoAI/hamo-score-toolkit.git && cd hamo-score-toolkit/server
docker compose up          # downloads the GGUF (639MB, one-time), creates + warms the model

curl -s localhost:8080/score -H 'content-type: application/json' \
  -d '{"message": "最近总觉得撑不太住", "current_stress": 3.0}'
# → {"crisis": {...}, "scores": {"A":..}, "stress": 3.1, "energy_state": "positive", "latency_ms": ...}

POST /score runs gate → score → smooth → bucket; crisis-gated requests never reach the model. GET /healthz probes the model end-to-end.

Verify your deployment

A 195-question synthetic exam (teacher-labeled, zero real data) plus 10 handwritten crisis-gate cases. Run it against your own deployment and compare with the official reference band in eval/README.md:

python eval/run_exam.py    # reference (v7 bf16): JSON 100%, dim-level 83.5%, gate 10/10

Adapting it to your own population

Read docs/finetune.md — the seven-generation fine-tuning playbook, including the two generations we rejected for crisis-recall regressions and exactly why. Data red lines first, then the real LoRA recipe, checkpoint selection with a crisis-miss column, and the acceptance hard gate.

What's in the box

More docs: the integration guide (the correct wiring + the ten-point don't list), the FAQ, and the fine-tuning playbook. Runnable examples in examples/: quickstart, batch CSV scoring, and a session-monitor demo with the crisis short-circuit (both take --mock to run without a model).

Design notes worth reading before integrating: the model card's Evaluation and Limitations sections — including why the reference scorer's own self-consistency (94–98%) is the practical ceiling.

Disagree with a score? (please tell us)

This is the one contribution we ask for. Open a disagreement report →

Useful reports carry three things: the message (redact freely — we don't want identifiable text), the score the model gave, and the score you would give. Context turns and your population/language help but are optional.

Every report is triaged into the human gold-label program: where licensed practitioners disagree with the model at a rate above its own noise floor, that becomes a training-data gap for the next generation. Disagreements are how this model gets better; silent workarounds are how it stays wrong.

License

Toolkit code: Apache-2.0. Model weights: HAMO-RAIL-S 1.0 (free use with four restrictions — no standalone clinical determinations, no consequential decisions about individuals, keep independent upstream crisis handling + AI disclosure in consumer deployments, no re-identification). Using this toolkit's default pipeline satisfies the crisis-handling pattern by construction.

中文

hamo-score-0.6b 的客户端工具包与安全脚手架——给对话把脉的小模型（AWEHB 五维：行动力/退缩/极端化/敌意/边界）。

这个仓库是模型的另一半：唯一正确的提示词格式、容错解析、分数该喂进去的平滑折算与状态桶，以及放在最前面的危机闸门——模型许可证（HAMO-RAIL-S §3c）要求任何面向消费者的心理健康部署都必须在模型上游保留独立的危机处理，本工具包让「合规的接法」成为「最省事的接法」。

五分钟上手：见上方英文段——hf download 拉 GGUF → ollama create → pip install → 四行代码跑通 闸门 → 评分 → 平滑 → 状态桶 完整链路。切记：分数是逐句信号，永远不要凭单句原始分做任何决定。

一键服务器：cd server && docker compose up——自动拉 GGUF、建模型、预热，POST localhost:8080/score 直接返回 危机/五维分/压力值/状态桶，危机命中的请求永远不会碰到模型。

部署自检：python eval/run_exam.py——195 题合成考卷（教师标注，零真实数据）+ 10 条手写危机闸门用例，对照 eval/README.md 的官方参考带（v7 bf16 参考值：JSON 合法率 100%、维度级 83.5%、闸门 10/10）验证你的部署接线正确。

想微调到你自己的人群？ 读 docs/finetune.md——七代模型蒸出来的完整打法（含两代拒收与确切原因）：数据红线、真实 LoRA 配方、带危机漏检列的选点表、验收硬闸。

更多文档：集成指南（正确接线 + 十条禁令）、FAQ、微调指南；examples/ 里有可跑的批量打分与会话监测演示（带 --mock，无模型也能看管线）。

对某个评分不服？请一定告诉我们——这是我们唯一请求的贡献。 提一条分歧报告 →：给出「消息（可自由脱敏）+ 模型给的分 + 你认为该给的分」三样即可。每一条都会进入人类金标计划分诊：凡持牌从业者与模型的分歧率高过模型自身的噪声底噪，那就是下一代的训练数据缺口。被替换的那个参照评分器自己重打同一句都有 2–6% 不一致——所以「这里模型判错了」是真发现，不是打扰。

许可证：工具包代码 Apache-2.0；模型权重 HAMO-RAIL-S 1.0（自由使用附四条限制，用本工具包默认管线即天然满足危机处理条款）。