Apprentice docs: cut LLM cost without losing quality

The local path runs entirely on your Mac. Training uses mlx-lm, Apple’s ML framework for Apple silicon. Your data never leaves the laptop. Your app points OPENAI_BASE_URL at one of three endpoints: your Mac, your cluster, or managed

Prerequisites

A Mac with Apple silicon (M-series). Memory needed depends on row length. The memory check on your longest rows stops runs that exceed the safe GPU memory limit.
Native ARM Python 3.11+ (not Python running under Rosetta) and the SDK: pip install "runapprentice[local]"
A CSV of examples with input,output columns. Rows you pass with --data are treated as gold: no account or review step.

Hand it to your agent

Working in Claude Code, Codex, or Copilot CLI? Install the skill and hand over the whole path:

/plugin marketplace add singhabhishekkk/apprentice-skill
/plugin install apprentice@apprentice

codex plugin marketplace add singhabhishekkk/apprentice-skill
codex plugin add apprentice@apprentice

npx skills add singhabhishekkk/apprentice-skill --skill '*' -a github-copilot

Then paste:

Using the apprentice skill, set up the local Mac path: train from
golden.csv with `apprentice train extract --local`, then serve the
adapter with mlx_lm.server on port 8080, send one test request, and
point this project's OPENAI_BASE_URL at it with model "default_model".

The skill guides the commands and checks the run report; you stay in the loop for every step that touches your code. Prefer to run it yourself? The same two steps follow.

Train

apprentice train extract --local --data golden.csv

What happens, in order:

Preflight checks the dataset, model, and memory profile.
mlx_lm lora fine-tunes mlx-community/Qwen3.5-4B-OptiQ-4bit with a LoRA adapter on your gold rows.
The fine-tuned model is scored on a held-out slice of your gold rows it never trained on: field-level F1 against your answers, 0 to 100.
The CLI prints the score, the number of held-out rows, and the run folder. Add --json for a machine-readable report with the adapter’s SHA-256 and the mlx-lm version.

The adapter lands in ~/.apprentice/local-runs/<task>/adapter. Every run on a task uses that folder, so a new run replaces the previous adapter. Useful flags:

Flag	What it does
`--effort low\|medium\|high`	Memory profile, not a quality knob. Every tier trains the same model on the same examples; higher tiers use a bigger batch and need more memory. Default: auto-detected from unified memory. A run that would run out of GPU memory stops early and says what to change.
`--keep-awake`	Keeps the Mac awake while training runs. Closing the lid still sleeps.
`--fresh`	Ignore saved checkpoints and retrain from scratch. Training resumes from the last checkpoint by default.
`--detach`	Start the run in the background and return as soon as it is running. See below.

Long runs and watching progress

A run can take an hour. Start it in the background so a closed terminal or an agent’s command timeout cannot stop it, then watch it:

apprentice train extract --local --data golden.csv --detach --json
apprentice logs --follow extract
apprentice local-status --json extract

logs --follow shows a live bar in a terminal, plain lines at each 10% when piped or run by an agent, and JSON with --json. Stopping it does not stop training. With an API key set, each run gets its own page in the console, and the CLI prints its link. It shows the run live: progress, time left, training and held-out loss, and peak memory against the Mac’s total, sent every 30 seconds. If nothing arrives for 3 minutes, it shows “No update” until the Mac reports again. To label the run, Apprentice receives the Mac’s chip and total memory, never its name. The training log itself stays on your Mac.

One run at a time per macOS user account. A second run stops at once and names the task already running, with exit code 4 so it can retry later.
local-status states: none, running, completed, failed, stopped. stopped means the process died without saving a result. Completed runs include the score, adapter path and serve command.
Errors with --json carry error, code and retryable on stderr. Exit codes: 0 ok, 1 failed, 2 usage, 3 auth, 4 retry later.
Sleep: a sleeping Mac pauses training. --keep-awake prevents idle sleep; closing the lid still sleeps.
Task names cannot contain slashes or start with a dot. Quote names with spaces.

Serve

mlx-lm ships an OpenAI-compatible HTTP server. It needs mlx-lm 0.32.2 or later: earlier versions ignore --adapter-path and serve the base model without your fine-tune. Check, and upgrade if it prints anything older:

python -c "import mlx_lm; print(mlx_lm.__version__)"
pip install -U "runapprentice[local]>=0.4.4"

Point the server at the base model plus your trained adapter:

mlx_lm.server \
  --model mlx-community/Qwen3.5-4B-OptiQ-4bit \
  --adapter-path ~/.apprentice/local-runs/extract/adapter \
  --chat-template-args '{"enable_thinking": false}' \
  --port 8080

Replace extract with your task name. --chat-template-args '{"enable_thinking": false}' matters. Qwen3.5 writes its reasoning before the answer by default. Training and the held-out score both ran with it off, so serve it the same way, or replies start with reasoning text instead of your JSON. Send one request before you switch anything over:

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "default_model", "messages": [{"role": "user", "content": "<one input from your CSV>"}]}'

The reply’s choices[0].message.content should look like the output column of your CSV. Then point your code at it:

export OPENAI_BASE_URL=http://127.0.0.1:8080/v1

Two things in your code change with it:

Model name: send "default_model". The server applies your adapter only under that name. Any other name makes it load that model instead: the base model without your fine-tune, or a failed download for a name like gpt-5.4-mini.
Prompt: send the row’s input as a single user message, with no system prompt. That is the exact format the model trained on and was scored on.

LangChain, the OpenAI SDK, and anything else that speaks the OpenAI API work with these two changes. To roll back, restore OPENAI_BASE_URL, the model name, and the original messages, including any system prompt.

Moving the adapter off the Mac

The adapter on disk is in MLX format. Serving it with vLLM on a GPU box (see Deploy in your Kubernetes cluster) needs a format conversion step that we have not published a verified recipe for yet. Until then, treat the Mac-trained adapter as a Mac-served adapter, or retrain in Colab with the benchmark notebooks, whose adapters are vLLM-ready.

Get started

How-to guides

Concepts

Reference

MLX fine-tuning on Apple silicon

Prerequisites

Hand it to your agent

Train

Long runs and watching progress

Serve

Moving the adapter off the Mac

​Prerequisites

​Hand it to your agent

​Train

​Long runs and watching progress

​Serve

​Moving the adapter off the Mac

Prerequisites

Hand it to your agent

Train

Long runs and watching progress

Serve

Moving the adapter off the Mac