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 <warith.harchaoui@deraison.ai>

best_engine_ai_helper.config.load_config()

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.resolved_models()

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.text_model()

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()

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