From ca0f229100f8cd1a32c7b70ea833e4fcb9b74230 Mon Sep 17 00:00:00 2001 From: Arthur Date: Thu, 10 Sep 2026 17:46:41 +0200 Subject: [PATCH] docs: how to keep oMLX's grammar support through a reinstall --- docs/admin-guide.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/admin-guide.md b/docs/admin-guide.md index 61668275..ce2ea8f6 100644 --- a/docs/admin-guide.md +++ b/docs/admin-guide.md @@ -422,6 +422,33 @@ brew untrust jundot/omlx Trusted taps are recorded in `~/.homebrew/trust.json` (or under `$XDG_CONFIG_HOME/homebrew/` if you set it). On Homebrew 5 and older there is no trust gate and the step is skipped. +**Maintaining oMLX by hand.** famstack installs it with `--with-grammar`, which +brings in xgrammar. That is what makes the model return structured JSON, and +document classification depends on it: without xgrammar, filing still happens +but every document arrives with no tags, no correspondent and no summary. + +Upgrading is safe. Homebrew records the options a formula was built with and +reuses them, so `brew upgrade omlx` keeps grammar. You can check what yours was +built with: + +```bash +grep -o '"--with-grammar"' /opt/homebrew/Cellar/omlx/*/INSTALL_RECEIPT.json +``` + +Uninstalling is what loses it, because that receipt goes with it. If you ever +remove and reinstall oMLX yourself, pass the flag again: + +```bash +brew install omlx --with-grammar +``` + +Two failures worth recognising. `brew` refusing to load the formula at all +means the tap is no longer trusted, so trust it again as above. And a +`bad interpreter: .../bin/python3.11: no such file or directory` from the +`omlx` command means its virtualenv broke, usually after a Python upgrade; +`brew reinstall omlx` rebuilds it. `stack up ai` reports a missing oMLX +rather than starting and failing a health check with no stated cause. + Why native instead of Docker? Metal GPU acceleration does not pass through Docker on macOS cleanly. Roughly 10x performance difference. Docker for orchestrated services, native for the GPU work. Once up, voice messages in chat get transcribed automatically and the document classifier starts using the LLM.