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

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.

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)[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.

Returns:

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

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'