best_engine_ai_helper.pull module

pull — Ollama model pull/remove helpers and env-file writer.

Wraps the ollama pull and ollama rm subprocess calls and provides write_env, which writes the validated model selection to a shell-sourceable env.sh and a machine-readable config.json under ~/.best-engine-ai-helper/.

Author

Warith Harchaoui <warithmetics@deraison.ai>

best_engine_ai_helper.pull.context_length(tag, base_url=None, *, timeout=5.0)[source]

The context window this daemon reports for tag, read rather than assumed.

Not one of the 31 local catalogue rows declares a context_length, and none of them should: the number belongs to a particular quantisation of a particular checkpoint, so a figure typed into models.yaml would be a claim about a file nobody here has opened. The paid half gets it for free because the price source publishes it; the local half has no such source.

It does have something better. A pulled model’s GGUF metadata carries the real figure, and Ollama hands it over on /api/show under a key named after the architecture — gemma3.context_length, llama.context_length — which is why this looks for the suffix rather than a fixed key. So the number is measured on the machine that holds the weights, exactly like decode speed is, and models you do not have report nothing at all instead of a plausible guess.

Parameters:

tag (str) – Model tag as the daemon knows it, e.g. gemma3:12b.
base_url (str or None) – Daemon URL; SPREZZATURE_LLM_BASE_URL or localhost by default.
timeout (float) – Seconds to wait. Longer than installed_tags()’s because this runs after a pull rather than inside resolution, and /api/show has to read the checkpoint header.

Returns:

The window in tokens, or None when the daemon is absent, the model is not pulled, or its metadata declares no context length. All three are ordinary, and none of them is worth a guess.

Return type:

int or None

Examples

A daemon that is not there is not an error:

>>> context_length("gemma3:12b", "http://127.0.0.1:1") is None
True

best_engine_ai_helper.pull.installed_tags(base_url=None, *, timeout=1.5)[source]

Which model tags this Ollama daemon can serve right now.

Best-effort by construction: a daemon that is not running is the common case during resolution, not an error, and an empty set simply means “cannot tell” to every caller.

Parameters:

base_url (str or None) – Daemon URL; SPREZZATURE_LLM_BASE_URL or localhost by default.
timeout (float) – Seconds to wait. Short on purpose: this runs inside resolution, which must stay fast on a machine with no daemon at all.

Returns:

Tags as the daemon reports them, plus their :latest-stripped form so gemma3:12b matches whether or not the suffix is spelled out.

Return type:

set of str

Examples

>>> isinstance(installed_tags("http://127.0.0.1:1"), set)
True

best_engine_ai_helper.pull.ollama_pull(tag, *, timeout=600, out=None)[source]

Pull a model via ollama pull and stream progress to stdout.

Ollama streams progress lines to stderr by default; this function merges stderr into stdout so the caller sees a unified stream.

Parameters:

tag (str) – Ollama model tag, e.g. "qwen3-vl:8b" or "qwen3-vl:72b".
timeout (int) – Maximum seconds to wait for the pull to complete. A 72B model at Q4_K_M (~52 GB) can take 30+ minutes on a slow connection; the default of 600 seconds (10 minutes) is generous for fast links.
out (IO[str] or None) – Stream to write progress lines to. Defaults to sys.stdout.

Returns:

True if ollama pull exited with code 0; False otherwise.

Return type:

bool

Raises:

FileNotFoundError – If the ollama binary is not on PATH.
subprocess.TimeoutExpired – If the pull is still running after timeout seconds. The process is killed before this is raised.

Examples

>>> # ollama_pull("qwen3-vl:8b")  # requires ollama running
>>> True  # placeholder so doctest passes without Ollama
True

best_engine_ai_helper.pull.ollama_rm(tag, *, timeout=60)[source]

Remove a pulled model via ollama rm.

Used by the pull-and-validate loop to free disk space when a model fails the Ralph gates, before trying the next candidate.

Parameters:

tag (str) – Ollama model tag to remove.
timeout (int) – Maximum seconds to wait. ollama rm is a local filesystem delete (no network, unlike ollama_pull()), so 60s is generous; a hung daemon or a locked model file would otherwise block the pull-and- validate loop forever with no way out.

Returns:

True if ollama rm exited with code 0; False if it exited nonzero or timed out (the process is killed before returning in that case).

Return type:

bool

Examples

>>> # ollama_rm("qwen3-vl:8b")  # requires ollama running
>>> True  # placeholder
True

best_engine_ai_helper.pull.write_env(text_model, vision_model, backend, base_url, *, user_dir=None)[source]

Write the validated model selection to env.sh and config.json.

Both files are written atomically: env.sh is shell-sourceable and suitable for .envrc (direnv); config.json is for programmatic consumers. The directory is created if it does not exist.

Parameters:

text_model (str) – Ollama tag for text-only tasks (BEST_LLM_TEXT).
vision_model (str) – Ollama tag for vision tasks (BEST_LLM_VISION).
backend (str) – Backend name: "ollama", "openai", or "langchain".
base_url (str) – Base URL of the inference server.
user_dir (Path or None) – Override the default ~/.best-engine-ai-helper/ directory. Used in tests to avoid touching the real user home directory.

Returns:

Absolute path to the written env.sh file.

Return type:

Path

Examples

>>> import tempfile, pathlib
>>> with tempfile.TemporaryDirectory() as td:
...     p = write_env("qwen3-vl:8b", "qwen3-vl:8b", "ollama",
...                   "http://localhost:11434", user_dir=pathlib.Path(td))
...     p.name
'env.sh'