---
name: hugging-bay-teach
description: Released. Fine-tune (teach) a small open model on the user's own examples, on the user's own machine, with Hugging Bay's `hbay teach`. Use when someone says "fine-tune a model for…", "teach a model to…", "train a specialist for payments risk / ticket triage / invoice fields…", or "help me get started with fine-tuning". Everything runs locally; the examples never leave the machine, and the result is measured on the user's own locked exam cases. Not for one-off questions or for rules that can simply be written down.
---

# Teach a specialist with `hbay teach`

> **Teach released 14 October 2026.** Mac app 0.1.4 includes the Teach tab; the public Teach engine wheel is 0.1.1. Teaching (the fine-tune) runs locally on the user's machine through the Mac app or `hbay-teach`. Teach on Mac requires Apple silicon and macOS 14+. Mac memory thresholds: Qwen2.5-0.5B-Instruct 8 GB, Qwen3-1.7B 16 GB, Qwen3-4B 32 GB. The 0.5B threshold has MLX measurements; the 1.7B and 4B thresholds are estimates. The engine checks the selected base against the machine's memory before teaching. The engine is not on PyPI, and its source repository is private.

Teach turns one job, described in a sentence, plus the user's examples into a **named specialist**: a LoRA adapter on a verified open base model that passed the user's own exam, runs only on their machine, answers through a local OpenAI-compatible API, and comes with signed papers.

## When Teach fits, and when it doesn't

- **Fits:** the person makes the same kind of call again and again (triage, risk review, pulling fields out of documents, tagging, replies in a house style) and has a few hundred past examples, or will correct drafted ones. No rulebook is needed: the specialist learns from their past decisions.
- **Doesn't fit:** a one-off question; fewer than about 200 examples (use saved instructions); or rules that are crisp and already written down. Then a capable model given the written policy is usually the better tool.
- **Status:** Teach is live for local use on supported Macs. Install the released engine before starting a run.
- **Before you start:** the hosted read-only tools `list_teach_bases` (which base models can be taught, with size, licence and evidence status) and `get_teach_template` (starter templates with synthetic data) need no account. These tools only list bases and hand out synthetic starters; they do not train a model. The teaching itself runs locally on the user's machine.

## If you only have the hosted tools

A remote-only agent can list bases and return a synthetic starter template. Its hosted part ends there. Tell the user: "To teach the model, install Mac app 0.1.4 and open its Teach tab, or install the `hbay-teach` engine on your own machine with the exact published commands below. The fine-tune runs there, not on this hosted service."

Give the user the [Mac app download](https://huggingbay.xyz/desktop) or the install commands below. Continue the local workflow only if local tools are already connected on the user's machine. Otherwise ask the user to run the local steps themselves; do not claim that a hosted tool started training or that this remote environment is their machine. Their example files stay on their machine.

## Ground rules (never bend these)

- **The examples never leave this machine.** Don't paste rows into chat, a web tool, a cloud model, or any URL. Use only the local `hbay` MCP tools or the local `hbay-teach` command. Setup downloads the engine wheel and Python dependencies; teaching downloads a verified base model from huggingbay.xyz. Example rows stay local.
- **Scores are always "on your N locked cases".** Never say a specialist is "94% accurate" without "on your 124 locked cases". Never compare with a cloud model unless the person explicitly agrees that the exam questions will be sent to that provider.
- **Never hide a bad result.** If the scorecard says it got worse, lead with that, the failing categories, and the three choices: fix the examples and teach again, teach more gently, or discard.
- **Grading happens on the person's machine, never in chat.** The cases to grade are shown only locally: in the Mac app's Teach tab, or by the person running `hbay-teach grade recipe.yaml --show` in their own terminal. You record only the verdicts they tell you (case id + right/wrong, or their corrected answer). Never ask them to paste a case into chat, and never read the cases yourself.
- **Tools return counts, not rows.** `check_examples` and the scorecard give totals, health and miss categories; the rows themselves stay in the job folder. Don't open the job folder's data files.
- **Pause for the person** at two points only: grading ("Teach it your standards") and keeping a version. Don't grade or keep on their behalf.
- It assists decisions. For actions that affect customers, say: keep a person in the loop.

## Install first

Download [Mac app 0.1.4](https://huggingbay.xyz/desktop), open the **Teach** tab and use its engine installation steps. Or run these exact commands in Terminal:

```sh
# Apple silicon Mac, macOS 14+; native Python 3.12 is required.
# If Python 3.12 is missing: brew install python@3.12
TEACH_DIR="$HOME/Library/Application Support/xyz.huggingbay.desktop/teach"
python3.12 -m venv "$TEACH_DIR/runtime"
"$TEACH_DIR/runtime/bin/python3" -m pip install \
  'mlx-lm==0.32.0' \
  'hbay-teach[xlsx] @ https://storage.googleapis.com/hb-desktop-releases-barneyserver/teach/0.1.1/hbay_teach-0.1.1-py3-none-any.whl#sha256=f10b3137efad10821c033ae18db2ed16cc4a2d5b199a2d405873ecccdac25451'
"$TEACH_DIR/runtime/bin/python3" -m hbay_teach.preflight --backend mlx
"$TEACH_DIR/runtime/bin/hbay-teach" --version
# Expect preflight ok:true, then hbay-teach 0.1.1. Return to Teach and click Check installation.
```

The wheel URL and SHA-256 are pinned above; do not substitute `pip install hbay-teach` or a private repository checkout. Python 3.12 must run natively on Apple silicon. `mlx-lm==0.32.0` is required.

For the Terminal steps below, activate that environment so its `hbay-teach` command is on PATH:

```sh
source "$TEACH_DIR/runtime/bin/activate"
```

`hbay-teach` is the installed engine entry point for the `hbay teach` workflow. The Mac app uses the same local engine. Local MCP tools are an option only when already connected; the wheel does not install the separate native `hbay` CLI.

## The steps

Prefer the local MCP tools when they're connected (`hbay mcp`); otherwise run the same steps with the CLI. Every command prints JSON lines; read the last line's `say` field to the person.

| Step | MCP tool | CLI |
|---|---|---|
| 1. Plan: write the recipe, check this machine can teach | `plan_teach` | `hbay-teach plan "<job in one sentence>" --data <file>` |
| 2. Examples: clean, mask personal data, health score | `check_examples` | `hbay-teach check recipe.yaml` |
| 3. Exam: the untouched model sits the locked cases | `run_exam` | `hbay-teach exam recipe.yaml` |
| 3b. Standards: the person grades 8–12 least-sure cases | `grade_case` | the person runs `hbay-teach grade recipe.yaml --show`, then `grade recipe.yaml <id> right\|wrong [--answer …]` |
| 4. Teach (background, low priority) | `teach` (alias `fine_tune`) | `hbay-teach run recipe.yaml --detach` |
| 5. Progress and the scorecard | `teach_status` | `hbay-teach status recipe.yaml` |
| 6. Keep (person decides) or discard | `keep_specialist` / `discard_specialist` | `hbay-teach keep recipe.yaml` / `discard` |
| 7. Serve on localhost | `serve_specialist` | `hbay-teach serve recipe.yaml` |

### No data yet?

Start from a template with **synthetic** sample data (`hbay-teach template init payment-risk ./payments`) so the person can try the flow. Run time depends on the model and machine. Or draft 30–60 seed examples from their one-sentence job, write them to a CSV with a `draft` column set to `yes`, and ask the person to correct them before step 2. The papers will say "agent-drafted, person-corrected", and the scorecard says "on your graded cases".

### Reading the results

- **Health below 60:** teaching won't start. Read the first tip out loud ("Only 9% of your examples are 'Needs review'. Add more…").
- **Fewer than ~200 examples:** suggest saved instructions instead, or add examples.
- **This machine can't teach that base:** offer the smaller base the tool suggests, or running `hbay-teach` on a bigger machine they own. Hosted training is not offered.
- **Scorecard:** say it in wrong calls first ("Wrong calls on your 124 locked cases: 48 → 7"), then the score, then must-pass cases and the general check. Offer the miss clusters as "add about 20 examples like these".

## Example

> "I want to fine-tune a model for payments risk review. Help me get started."

1. Ask for their examples file (or offer the synthetic payment-risk template). Ask which column holds the decision.
2. `plan_teach` → confirm the base and that the machine can teach it.
3. `check_examples` → report "1,240 look good · 31 held aside (why) · 252 emails and card numbers masked · health 82/100".
4. `run_exam` → "The untouched model got 76 of 124 right on your locked cases." Ask the person to open the cases to grade on their own machine (the Mac app's Teach tab, or `hbay-teach grade recipe.yaml --show` in their terminal). Each is labelled "first guess — untouched model". Don't run `--show` yourself or paste cases into chat. Record each verdict they tell you with `grade_case` (id + right/wrong). Stop once the standard is clear.
5. `teach` → report progress from `teach_status` every few minutes (the climbing score is a real exam sample).
6. Show the scorecard. Ask whether to keep it and what to name it.
7. `serve_specialist` → give them the one-line curl to call it.