Development

Use Python 3.12 on an Apple Silicon Mac:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-mac.txt -r requirements-docs.txt

Place the checkpoint as described in First-run model setup, then run the owned desktop lifecycle:

python desktop_app.py

For browser-only interface work, the legacy source launcher remains available:

./Start\ Confucius.command

Do not run both launchers: each uses loopback port 8765.

Tests and documentation

python -m unittest -v test_mac
python -m mkdocs build --strict

Package the app

The build is intentionally macOS/arm64-only and excludes model weights:

python -m PyInstaller --clean --noconfirm packaging/macos/ConfuciusCaptions.spec
codesign --verify --deep --strict --verbose=2 "dist/Confucius Captions.app"

desktop_app.py starts Uvicorn in a managed thread, opens the Cocoa WebKit window, requests server shutdown when the window exits, and joins the thread. FastAPI lifespan is the sole owner of MLXEngine.shutdown().