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:
an explicit environment override (
BEST_LLM_TEXT/BEST_LLM_VISION, with the legacySPREZZATURE_LLM_*spellings accepted as aliases),the persisted selection written by
best-engine-ai-helper pullto~/.best-engine-ai-helper/config.json(seepull.write_env()),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.
- best_engine_ai_helper.config.backend()[source]
Return the serving backend for the legacy, no-engine transport path.
Precedence:
BEST_LLM_BACKENDenv (or legacySPREZZATURE_LLM_BACKEND) -> persistedconfig.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:
- 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:
- 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 bypull.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:
- 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:
- 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 valuestext_model()andvision_model()would return.- Return type:
- 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
headroomof"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.
- best_engine_ai_helper.config.text_model()[source]
Return the model tag to use for text-only prompts (lint, summaries, …).
Precedence:
BEST_LLM_TEXTenv (or legacySPREZZATURE_LLM_TEXT) -> persistedconfig.json->DEFAULT_TEXT_MODEL. Never probes hardware, never raises.- Return type: