Engineering

Open-Sourcing hamo-score-toolkit: The Other Half of the Model

AI for Psychology, Psychology for AI.

hamo-score-toolkit: the other half of hamo-score-0.6b — gate → score → smooth → bucket, with the crisis gate standing in front of the model

Hamo has open-sourced hamo-score-toolkit: the integration half of hamo-score-0.6b. One pip install gives you the exact prompt format the model was trained on, tolerant parsing, the reference stress math, and a deterministic crisis gate that runs before the model ever sees a message. One docker compose up gives you a reference server. A 195-question self-check exam tells you whether your deployment reproduces the official numbers. The code is Apache-2.0.

999 downloads, two feelings

Twelve days ago we published the weights of hamo-score-0.6b — a 600-million-parameter model that reads one message in a wellness conversation and returns five psychological state dimensions, and never writes a reply. In its first twelve days public, it was downloaded 999 times — the counter at the time of writing.

That number produced two feelings, in roughly equal measure.

The pleased half is obvious. We released the model precisely so that researchers, clinics, and counselors could run state scoring on their own machines, and 999 downloads of a niche psychological instrument in twelve days is more of that than we expected.

The worried half is the reason this post exists. hamo-score-0.6b is a measuring instrument — not a chatbot, not a diagnostic tool, not a crisis detector, not a therapist. And like most instruments, it was designed for a mounting. In our own system it sits behind a crisis gate that short-circuits upstream, so a message the gate catches is not scored on that turn — the gate promises "hit means blocked", not "nothing gets missed" — and inside a smoothing pipeline that blends every raw reading into history before anything downstream is allowed to act. Gate → score → smooth → bucket. The weights implement exactly one of those four stages.

A bare download carries none of that. Statistically, some of those 999 pulls are researchers doing exactly what we hoped. And statistically, some are someone about to wire raw per-message scores straight into decisions, with nothing standing in front of the model — precisely the deployment the whole architecture was designed against.

The model card says all of this, in bold, near the top. But a model card is documentation, and documentation is the weakest form of architecture. The stronger move is to make the safe integration the path of least resistance. So today we're open-sourcing the other half.

The shape the scores were designed for

pip install hamo-score

A few lines of code later, you are running the pipeline shape the scores were designed for:

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:          # the deterministic gate ran BEFORE the model
    handle_crisis(r.crisis.matched)
elif r.scores:
    stress = update_stress(r.scores, current_stress=3.0)
    state = energy_state(stress)   # 'positive' / 'negative' / 'neurotic'

Each stage exists for a reason worth spelling out.

The gate comes first, and it is not a model. CrisisGate is a deterministic keyword match — Chinese and English word lists, extensible for your population — that runs on every message before scoring. When it triggers, the pipeline short-circuits: the message does not reach the model, and your code is handed the match to run through your own crisis path — surface a hotline, notify whoever is responsible. This is not a convenience feature. The model license (HAMO-RAIL-S §3c) makes an independent upstream mechanism a condition of consumer-facing mental-wellness deployments, and also requires disclosing that an AI system is in use. The toolkit's keyword gate is a starting point, not a complete screen, and deployers remain responsible for meeting both requirements. The source file states the design intent in one line: extend the word lists for your population; never replace this layer with a model. [Update, 2026-11: corrected. An earlier version of this paragraph overstated what the gate does for the license.]

The score stage uses the one true prompt. The model was trained on exactly one prompt format, with the scoring rubric baked into the weights — adding your own scoring instructions makes it worse, not better. build_prompt() emits that format with trimming guards; the parser tolerates the model's empty think-blocks and snaps output to the 0.5 grid.

Smoothing is where a signal becomes a state. The reference math blends 0.8 × history + 0.2 × message, damping per-message noise five-fold before any decision is taken, and the energy-state buckets are computed from that smoothed value — never from a single reading. If you take one integration rule from this post: scores are per-message signals. Never act on a single raw score.

A server in one command

If you'd rather not touch Python at all, the repository ships a reference HTTP deployment:

git clone https://github.com/HamoAI/hamo-score-toolkit.git && cd hamo-score-toolkit/server
docker compose up --build

That fetches the GGUF from Hugging Face (639 MB, one-time; Update, 2026-11: this is the v10h GGUF, and a first run also pulls about 2.9 GB of images, measured on linux/arm64), creates the model in ollama with the correct template and neutral sampling (temperature 0, repeat_penalty 1.0), warms it, and exposes the full pipeline as POST /score:

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

Crisis-gated requests never reach the model here either — the gate is wired into the server, not left as an exercise. GET /healthz probes the model end to end.

An exam you can give your own deployment

Here is a problem every open-weights release has and few talk about: you download the weights, you wire them up, you get numbers out — and you have no idea whether your deployment reproduces the numbers on the model card, or whether a broken chat template is silently costing you five points.

We can't ship our real exam. The held-out sets that graded every generation of this model are real, pseudonymised production conversations, and they never leave the building. So we built one that can ship:

  • A scoring section: 195 synthetic questions across ten non-crisis scenario cells — small talk, elliptical replies, somatic complaints, third-party conflict, talking back to the assistant, self-criticism, terse help-seeking, implicit severity, hostile-but-clear, long venting. Generated from a fresh seed, labeled by the qualified teacher model. Zero real data. [Update, 2026-11: this post first said the seed was disjoint from all training corpora, which was too strong. Six of the 195 messages also occur as the latest message of a v10 training row; no full prompt matches one.]
  • A gate section: 10 handwritten cases — seven crisis phrasings in Chinese and English that must trigger, and three messages that must not: two hyperboles using 死 and one plain everyday message. This section never calls the model. It checks that the word lists in your checkout are intact. It does not test that your service routes messages through the gate: send a crisis sentence to your own endpoint for that.
python eval/run_exam.py

Run it from a clone of the repository, against your own ollama endpoint (--base-url). The reference server publishes only its API port: to examine it, follow the port step in eval/README.md.

And an official reference band to compare against, measured on the v7 bf16 weights (current in 2026-09):

[Update, 2026-09: this reference was first published on the v6.1 bf16 weights, the release current when the toolkit shipped (84.0%; A 86 · W 81 · E 84 · H 91 · B 79). It has now been re-measured on v7: 83.5% on the v7 bf16 weights (MLX, temperature 0), and 83.8% on the shipped v7 q8 GGUF (llama.cpp, the Modelfile template, neutral sampling: temperature 0, top_k 0, top_p 1.0, repeat_penalty 1.0) — both inside the unchanged 81–86% band, gate 10/10. Re-running v6.1 bf16 through the same harness gives 84.2%, so v7 sits about 0.7 pt lower on this synthetic exam — the same direction as its 0.5-pt dimension dip on the 453-turn real final split (85.6% → 85.1%) after the temperature-0 relabel. At that date the reference server pulled the v7 GGUF.]

[Update, 2026-11: the table below is v7's as of 2026-09 and applies only to a v7 deployment, graded with --labels pre_v9. A correctly wired deployment of v10h, the current release, reads 86.7% on q8 (A 82–83 · W 83 · E 83 · H 95 · B 90), outside the v7 band. v10h's own band is 84–90%, each dimension ≥ 75%, A ≥ 81, JSON ≥ 99%, gate 10/10. v10h's synthetic training labels were reviewed and re-scored by human counselors engaged by Hamo; this exam has no such labels, so it is graded on v10's. Scores are not comparable across versions. Current bands are in eval/README.md.]

Metricv7 reference (current in 2026-09)v7 band
JSON validity100%≥ 99%
Dimension-level agreement (±0.5)83.5%81–86%
Per-dimensionA 85 · W 79 · E 82 · H 92 · B 79each ≥ 75%
Crisis gate10/1010/10 — hard requirement

One clarification so nobody cross-references the wrong number: the model card's headline as of 2026-09 — 85.1% dimension-level (within ±0.5) and 97.1% decision-level for the v7 bf16 weights, then the current release and the same weights this reference band was measured on — is graded on the 453-turn real held-out final (the untouched final split of the original 758-turn exam, re-split when the calibration set entered training under consent), which cannot ship. [Update, 2026-11: on the real exam, graded against the reference labels (not counselor scores), the shipped v10h q8 puts 440 of 453 turns (97.1%) in the same state bucket and reads 82.8% dimension-level; scores are not comparable across versions.] This synthetic exam is a different paper. Its job is to check your wiring, not model quality — and for that, what matters is landing inside the band, not the absolute value.

Because that's the pattern we saw coming: big deviations are almost always wiring, not the model. The eval README turns that into an ordered triage. Scores running high in your own service? If it does not use the toolkit's clients, check sampling first, by hand: repeat_penalty must be 1.0, and 1.1, ollama's default through 0.32.9, pushes this model's scores up. The toolkit's clients always send 1.0, and the exam sends its own sampling, so it cannot see this. JSON validity below 99%? Check num_predict first; the shipped value is 80. Dimension-level clearly below the band? The weights may not match the labels you passed, or the server is not running the q8 as shipped: the wrong GGUF, an unmeasured quantization, or a server that ignores request options. Gate section below 10/10? The CrisisGate word lists in your checkout have been altered: fix them before going live. That section does not test that your service routes messages through the gate: send a crisis sentence to your own endpoint for that.

The exam earned its keep before it shipped

We'd like to tell you the self-check exam is for other people's deployment mistakes. Its actual first catch was ours.

On its very first run, the gate section failed a case we were sure it would pass. Our English crisis wordlist contained "end my life" — and the test message said "ending my life". The gerund sailed straight through a gate we had already been shipping.

The fix took minutes: gerund and variant forms across the English list, all in before release, with the gerund case now pinned down permanently by the gate section of the exam. But the lesson is worth more than the fix, and it is easy to draw the wrong one.

The wrong lesson is that a keyword list has exactly the gaps it has, and you can enumerate them. You cannot. What is enumerable is the test cases, not the language. A case either covers a phrasing or it doesn't, and that you can check line by line; but the number of ways a person can rewrite "I don't want to live" has no end. "I want to die" was the lesson during the wordlist era. "ending my life" was the lesson after we had already shipped. Two instances of one class, and the class is not finite.

What the determinism actually buys is narrower and more useful than completeness: the gate fails the same way every time, so a gap is findable, reproducible, and permanently closable by a test — none of which is true of a model that fails differently on Tuesday. That is the argument for keeping this layer deterministic, and it is why the gate ships with an exam rather than with a promise. The first beneficiary was us.

What's next: the playbook, not just the parts

The toolkit covers running the scorer as-is. The next piece ships alongside this post, in the same repository: a fine-tuning guide (docs/finetune.md) for institutions that want to adapt the scorer to their own population with their own consented data: the full six-generation playbook (Update, 2026-09: seven generations now, with v7; Update, 2026-11: the guide runs through v10h) distilled from the methodology notes — including v5 and v6, the first two generations we rejected, and exactly why: on high-withdrawal turns, the Withdrawal score W fell toward 0 more often than for the incumbent, v4. Negative results are part of the recipe. Anyone repeating this work should get to skip our mistakes, not rediscover them.

If you think a score is wrong

You will disagree with this model. On some messages, so do we — and so does the reference scorer it replaced, with itself, on repeat runs.

When it happens, the repository has a score disagreement issue template: the message, the model's score, and what you think it should be. These reports do not go into a void. They feed the reviews that steer future versions. The answer key of the real held-out exam that grades every release already carries hand corrections made by the founder. Published weights and a published evaluation method made disagreement specific instead of rhetorical; the issue template makes it actionable.

Two licenses, deliberately

The toolkit code is Apache-2.0. The model weights remain under HAMO-RAIL-S 1.0. That asymmetry is the point.

The safety scaffold — the gate, the smoothing, the exam, the integration pattern — should spread with zero friction. We want it copied, forked, embedded in commercial products, translated into other stacks, with no restrictions to read and no lawyer to consult. The instrument itself carries responsibilities that its license spells out: no standalone clinical determinations, no consequential decisions about individuals, independent upstream crisis handling and AI disclosure in consumer-facing mental-wellness deployments, no re-identification. Free code around a governed instrument. That is the shape we'd want everyone shipping model weights into sensitive domains to consider.

An instrument, its mounting, and its calibration papers — as of today, all three are public.

“Publishing weights and stopping there is like handing someone a scalpel and walking away. The instrument was never the dangerous part or the safe part — the pattern around it is. So we open-sourced the pattern: the gate that runs before the model, the math that runs after it, and an exam that tells you honestly whether you've wired it right. The safe way to deploy this model is now also the laziest way. That was the whole design goal.”
— Chris Cheng, Founder and CEO of Hamo AI

Toolkit: github.com/HamoAI/hamo-score-toolkit · Apache-2.0 · Model: HamoAI/hamo-score-0.6b · HAMO-RAIL-S 1.0

Grounded in code, not slideware.

Hamo AI — making minds aware, and awake.


About Hamo AI

Hamo AI Technology Ltd. is a Canada-based artificial intelligence company building the next-generation AI-Powered Therapist Avatar System. We are developing a comprehensive AI therapy platform called “Hamo” that connects mental health professionals with clients through AI-powered therapy avatars. The ecosystem consists of three interconnected applications: Hamo Pro (therapist dashboard for creating and managing AI avatars), Hamo Client (client interface for interacting with therapy avatars), and Hamo-UME (Unified Mind Engine, backend API). The platform aims to make mental health support more accessible while maintaining professional oversight through professional therapists who create and manage the AI avatars.

Media Contact

Hamo AI Technology Ltd.
Email: socialmedia@hamo.ai
Website: www.hamo.ai
Address: 108 College St, Schwartz Reisman Campus, SUITE W640, Toronto ON M5G 0C6, Canada

Frequently Asked Questions

What is hamo-score-toolkit?

An Apache-2.0 Python toolkit and safety scaffold for the open-weights model hamo-score-0.6b. One pip install provides the exact prompt format the model was trained on, tolerant output parsing, the reference stress-smoothing math, and a deterministic CrisisGate that runs before the model ever sees a message. The same repository ships a one-command Docker reference server and a 195-question self-check exam for checking how a deployment is wired.

Why release a toolkit when the model weights are already public?

Because the weights are only half of the system. hamo-score-0.6b is a measuring instrument designed to sit behind a deterministic crisis gate and inside a smoothing pipeline — gate → score → smooth → bucket. In its first twelve days public the model was downloaded 999 times, and bare weights invite exactly the integration it was designed against: raw per-message scores driving decisions with nothing in front of the model. The toolkit makes the safe integration pattern the easiest one to build.

Does shipping a CrisisGate make hamo-score-0.6b a crisis detector?

No — the opposite. The model is not a crisis detector, and the gate exists precisely so it never has to be. The CrisisGate is deterministic keyword matching that runs upstream, before the model: when it triggers, the pipeline short-circuits and the message does not reach the scorer at all. The guarantee runs one way — 'hit means blocked', not 'nothing gets missed' — so a gate is a layer, not a promise. What a gate misses falls to the rest of the system around the model (Hamo calls it the spine) and to the responsible clinician. None of the model's scores, W (Withdrawal) included, is a crisis signal. The toolkit's keyword gate is a starting point, not a complete screen. The model license (HAMO-RAIL-S §3c) makes an independent upstream mechanism a condition of consumer-facing mental-wellness deployments, and also requires disclosing that an AI system is in use. Deployers remain responsible for meeting both.

Does the self-check exam contain real conversation data?

No. The 195 scoring questions are fully synthetic — generated from a fresh seed and labeled by the qualified teacher model — and the 10 crisis-gate cases are handwritten. The real held-out exams never leave the building. The model's training data is synthetic too, with one disclosed exception: since v6.1, 440 real conversation turns contributed by three company-internal staff members — the founder and two staff counselors — with their explicit consent, upsampled ×3 to about 8% of the corpus (Update, 2026-11: 6.5% in v10h). External client conversations never enter training, by construction.

How do I verify my own deployment?

Run python eval/run_exam.py from a clone of the repository, against your ollama endpoint, and compare with the current band in eval/README.md. The reference server publishes only its API port; that README gives the port step for examining it. (Update, 2026-11: a correctly wired deployment of v10h, the current release, reads 86.7% on q8. Its band is 84–90%, each dimension at least 75%, A at least 81, JSON validity at least 99%, gate 10/10. A pass checks wiring, not model quality.) As of 2026-09 the reference was v7's: JSON validity 100%, dimension-level agreement 83.5%, crisis gate 10/10. It was measured on the v7 bf16 weights (MLX, temperature 0); the shipped v7 q8 GGUF, run under llama.cpp with neutral sampling, lands at 83.8%, inside the 81–86% band. (Update, 2026-09: the reference has been re-measured on v7, and the 81–86% band is unchanged; the reference published when the toolkit shipped was measured on v6.1, at 84.0%.) Large deviations are almost always wiring, not the model: weights and labels that do not match, the wrong GGUF, an unmeasured quantization, or a server that ignores request options. The eval README gives an ordered triage. The exam sends the toolkit's own prompt and sampling, so check those in your own service separately: repeat_penalty must be 1.0, and 1.1 was ollama's default through 0.32.9. A failed gate section means the word lists in your checkout were altered: fix them before going live. That section does not test that your service routes messages through the gate; send a crisis sentence to your own endpoint for that.

What license is the toolkit under, and is it on PyPI?

The toolkit code is Apache-2.0. The model weights are a separate artifact under a separate license, HAMO-RAIL-S 1.0 — free commercial use with four restrictions. Two artifacts, two licenses, deliberately. Yes — install it with pip install hamo-score.