best_engine_ai_helper.config module

config — cheap, deterministic resolution of the chosen model tags.

This module answers a single question for downstream consumers (md2star and the rest of the AI Helpers suite): “which local model tag should I use right now?” It never probes hardware and never pulls anything — that expensive, machine- dependent work belongs to the recommend / pull flow. Here we only read, in a fixed precedence, what has already been decided:

  1. an explicit environment override (BEST_LLM_TEXT / BEST_LLM_VISION, with the legacy SPREZZATURE_LLM_* spellings accepted as aliases),

  2. the persisted selection written by best-engine-ai-helper pull to ~/.best-engine-ai-helper/config.json (see pull.write_env()),

  3. a conservative built-in default (DEFAULT_TEXT_MODEL / DEFAULT_VISION_MODEL) so the call always returns a usable tag, even on a machine that has never run detection.

Because the resolvers are pure reads with a guaranteed fallback, they are safe to call at import time, in CI (where no config file and no Ollama exist), and inside unit tests — the result is deterministic and never raises.

Author

Warith Harchaoui <warithmetics@deraison.ai>

best_engine_ai_helper.config.backend()[source]

Return the serving backend for the legacy, no-engine transport path.

Precedence: BEST_LLM_BACKEND env (or legacy SPREZZATURE_LLM_BACKEND) -> persisted config.json -> DEFAULT_BACKEND. Lower-cased, because the transport dispatches on an exact string and a sourced env file is hand-editable.

Does not apply to the engine= path, where the backend comes from the resolved engine descriptor.

Return type:

str

best_engine_ai_helper.config.base_url()[source]

Return the server base URL for the legacy, no-engine transport path.

Same precedence as backend(), with any trailing slash removed so callers can join paths without doubling it.

Return type:

str

best_engine_ai_helper.config.load_config()[source]

Return the persisted selection dict, or an empty dict if absent/unreadable.

Reads ~/.best-engine-ai-helper/config.json (written by pull.write_env()). A missing file is the normal “never ran detection” case, so it maps to {} rather than an error; a corrupt file is treated the same way so a bad write can never break a downstream caller.

Returns:

The parsed config, or {} when the file does not exist or cannot be parsed as a JSON object.

Return type:

dict

best_engine_ai_helper.config.load_preferences()[source]

Read the saved preferences, falling back to the defaults for anything unset.

A missing or unreadable file is not an error: no preferences yet is the normal state, and every value has a usable default. Returns a fresh dict, so a caller mutating the result cannot corrupt the next read.

Returns:

Every key in _PREFERENCE_DEFAULTS, saved value or default.

Return type:

dict

best_engine_ai_helper.config.resolved_models()[source]

Return both resolved tags in one call, reading the config file at most once.

Returns:

{"text": <tag>, "vision": <tag>} — the same values text_model() and vision_model() would return.

Return type:

dict

best_engine_ai_helper.config.save_preferences(values)[source]

Merge values into the saved preferences and write them back.

Only known keys are kept, and each is coerced to the type its default implies — a form posts strings, and a headroom of "0.4" that stayed a string would compare wrongly against a float for the rest of its life. A value that cannot be coerced is skipped with a warning rather than stored broken.

Parameters:

values (dict) – Preferences to set. Unknown keys are ignored.

Returns:

The full set of preferences as now saved.

Return type:

dict

best_engine_ai_helper.config.text_model()[source]

Return the model tag to use for text-only prompts (lint, summaries, …).

Precedence: BEST_LLM_TEXT env (or legacy SPREZZATURE_LLM_TEXT) -> persisted config.json -> DEFAULT_TEXT_MODEL. Never probes hardware, never raises.

Return type:

str

best_engine_ai_helper.config.vision_model()[source]

Return the model tag to use for prompts that include images (alt-text, OCR).

Precedence: BEST_LLM_VISION env (or legacy SPREZZATURE_LLM_VISION) -> persisted config.json -> DEFAULT_VISION_MODEL. Never probes hardware, never raises.

Return type:

str