best_engine_ai_helper.cli module

cli — the command line of best-engine-ai-helper, built with click.

One command line, one module: best-engine-ai-helper (registered in pyproject.toml) is the only CLI this package ships. An argparse twin used to mirror it command for command, which doubled every option and every test for no behaviour anybody could observe; it was removed in 1.9.0 and click became a core dependency rather than an opt-in extra.

Commands:

detect Print detected hardware as JSON. recommend Print ranked model candidates for this hardware. resolve Turn a usage brief into a machine-specific engine file. report Recommend engine(s) for a task, as Markdown or JSON. usages Browse and resolve the sev7n usage catalog. catalog show Print the merged model catalog as a table. catalog update Refresh the catalog cache; –arena adds Arena ratings. hardware show Print the merged hardware chip table. hardware update Record this machine’s chip and memory into the cache. pull Pull the best model and run Ralph validation gates. storage Plan capacity: disk, and what fits in memory together. providers Which cloud providers are usable right now, and why not. doctor Compare what was resolved against what the daemon serves. validate Run Ralph gates on the already-configured model. gui Launch the minimal browser GUI. env Print the env block for ~/.zshrc or sourcing. activity Summarize the local activity/cost ledger. lightweight status Can this machine stream layers, and should it? lightweight plan What a too-large model would cost here, ranked. lightweight prepare Download and split a checkpoint before the first call. imagine plan Which text-to-image model this machine can run, and how fast. imagine generate Generate one image locally, to a PNG file. serve Serve the OpenAI-compatible API (point any OpenAI SDK at it).

Author

Warith Harchaoui <warithmetics@deraison.ai>

best_engine_ai_helper.cli.airllm_group()

Layer streaming: run a model that does NOT fit in this machine’s memory.

A transformer never needs every layer resident at once. Keep one layer in memory, stream the rest off disk, and the memory a model needs stops scaling with its parameter count — a 70B model runs in about 4 GB instead of 141. The runtime is this package’s own; the technique was demonstrated by airllm (github.com/lyogavin/airllm, Apache-2.0).

The cost is time: every token re-reads the whole checkpoint from storage, so the unit is seconds per token. These are batch jobs — an overnight evaluation, one hard question, a quality reference for a smaller local model. Not a chat window.

Return type:

None

best_engine_ai_helper.cli.catalog_group()

Manage the model catalog.

Return type:

None

best_engine_ai_helper.cli.catalog_show()

Print the merged model catalog as a table.

Return type:

None

best_engine_ai_helper.cli.env_cmd()

Print the env block ready for ~/.zshrc or sourcing.

Reads the written env.sh from ~/.best-engine-ai-helper/env.sh and prints it to stdout. If the file does not exist, suggests running pull first.

Return type:

None

best_engine_ai_helper.cli.hardware_group()

Manage the hardware chip table.

Return type:

None

best_engine_ai_helper.cli.hardware_show()

Print the merged hardware chip table.

Return type:

None

best_engine_ai_helper.cli.hardware_update()

Record this machine’s chip and memory into the hardware cache.

There is no public specs API covering every GPU and Apple Silicon chip, so a refresh captures ground truth for the machine it runs on: the detected chip, its memory pool, and the Ollama-usable share after the OS reservation. The row is upserted into ~/.best-engine-ai-helper/hardware_cache.yaml (keyed on chip + memory tier); the bundled seed is never modified.

Return type:

None

best_engine_ai_helper.cli.imagine_group()

Text-to-image: the third kind of model this package chooses.

A diffusion model is three or four networks taking turns — text encoders, a denoiser, a VAE — so its footprint depends on whether they are all resident or handed to diffusers’ component offload, and its speed is steps times denoiser passes rather than tokens per second. These commands report both, and generate runs one.

Return type:

None

best_engine_ai_helper.cli.main()

Console entry point (best-engine-ai-helper, registered in pyproject.toml).

Click’s own invocation only special-cases ClickException/Abort (and a broken pipe); a plain library exception (a connection failure, a missing ollama binary, …) would otherwise propagate as a raw Python traceback instead of a clean CLI error. This wraps the whole invocation and translates that last case into a one-line stderr message + exit 1 – click’s own control flow (usage errors, –help, an explicit sys.exit(1) in a subcommand) already raises SystemExit, a BaseException this does not catch, so it passes through untouched.

Return type:

None

best_engine_ai_helper.cli.usages_group()

Browse and resolve the sev7n usage catalog (task profiles + families).

Return type:

None

best_engine_ai_helper.cli.usages_list()

List every usage profile and family (names, not models).

Return type:

None

best_engine_ai_helper.cli.validate_cmd()

Run Ralph gates on the already-configured model.

Reads BEST_LLM_TEXT / BEST_LLM_VISION from the environment (sourced from env.sh) and validates both gates. Useful after a manual ollama pull or after an OS update changes GPU availability.

Return type:

None