best-engine-ai-helper 0.3.0__tar.gz

best_engine_ai_helper-0.3.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Warith Harchaoui
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

best_engine_ai_helper-0.3.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: best-engine-ai-helper
+Version: 0.3.0
+Summary: Pick and pull the best local LLM/VLM for the current hardware.
+Author-email: Warith Harchaoui <warith.harchaoui@gmail.com>
+License: BSD-3-Clause
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: psutil>=5.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31
+Dynamic: license-file
+
+# best-engine-ai-helper
+
+Pick and pull the best local large language model (LLM) or vision-language model (VLM) for the hardware in the current machine.
+
+The tool detects available memory (Apple Silicon unified pool, NVIDIA VRAM, or system RAM), consults a bundled model catalog, and selects the highest-scoring model that fits within a configurable safety headroom. After selection, it pulls the model via Ollama, runs two quality gates (the Ralph Loop for prose and the Ralph Eyeball Loop for vision), and writes an environment file that downstream projects source to find the chosen model.
+
+Phase 0a (this release) covers detection, catalog, scoring, and the CLI skeleton. Phase 0b adds the pull, validate, and env commands.
+
+## Requirements
+
+- Python 3.10 or later
+- [Ollama](https://ollama.com) (Phase 0b only; not needed for `detect` and `recommend`)
+- psutil, PyYAML, click, requests (installed automatically)
+
+## Install
+
+```sh
+pip install best-engine-ai-helper
+```
+
+Or from source:
+
+```sh
+git clone https://github.com/warith-harchaoui/best-engine-ai-helper
+cd best-engine-ai-helper
+pip install -e .
+```
+
+## Quick start
+
+```sh
+# See what hardware this machine has
+best-engine-ai-helper detect
+
+# See which models would be selected (no download)
+best-engine-ai-helper recommend
+
+# Recommend the best engine(s) for a task, as a report (Markdown + JSON)
+best-engine-ai-helper report --task "product descriptions and image-quality checks" --out engine
+
+# Browse the full catalog
+best-engine-ai-helper catalog show
+
+# Browse the hardware chip table
+best-engine-ai-helper hardware show
+```
+
+See [EXAMPLES.md](https://github.com/warith-harchaoui/best-engine-ai-helper/blob/main/EXAMPLES.md) for runnable recipes with expected output.
+
+## How selection works
+
+Selection weighs three factors, each made explicit in the `report` output so the
+recommendation is reproducible and can be argued with.
+
+### 1. Memory fit (will it run on the accelerator?)
+
+Available memory comes from the highest-priority probe that succeeds: Apple
+Silicon unified memory (`system_profiler`), NVIDIA VRAM (`nvidia-smi`), AMD VRAM
+(`rocm-smi`), else half of system RAM as a conservative CPU-only estimate.
+
+The usable budget is **not** the whole pool. On Apple Silicon, Metal caps GPU
+allocations at about **66%** of unified memory at or below 36 GB and about
+**75%** above it (`recommendedMaxWorkingSetSize`); past that, work spills to the
+CPU and slows sharply. An extra safety `headroom` (default **0.85**) is applied
+on top, reserving room for the OS, your own application, and KV-cache growth as
+context fills. A catalog entry's `ram_gb` is already a peak-inference estimate
+(weights plus a moderate KV cache; roughly weights ÷ 0.7, since weights are only
+about 70% of runtime memory and can approach 2× at long context). A model fits
+when that `ram_gb` is at most the budget.
+
+### 2. Task fit (is it good at the job?)
+
+A task — even a vague phrase like *"retail descriptions and image-quality
+checks"* — maps to a benchmark axis (`generalist`, `code`, `math`, `ocr`,
+`vision`) and to the model kinds it needs (text ⇒ LLM, anything visual ⇒ VLM).
+Among fitting models, the highest benchmark on that axis wins.
+
+### 3. Throughput (how fast will it generate?)
+
+Token generation is **memory-bandwidth bound**: each token reads the active
+model from memory once, so the ceiling is `bandwidth ÷ model-size`, derated to
+about 65% for KV-cache reads and overhead. `report` estimates tokens/s per
+candidate from the chip's memory bandwidth, and offers a lighter, faster
+alternative when one is nearly as strong. Bigger is not automatically better: a
+72B model that technically fits may run at a few tokens/s, while an 8–14B model
+leaves headroom and runs several times faster.
+
+When nothing fits, the tool falls back to the smallest model and says so.
+
+**Sources.** Apple Metal working-set cap (Apple developer docs / apple-specs);
+inference-memory breakdown weights + KV (15–20%) + overhead (5–10%) (local-LLM
+sizing guides); bandwidth-bound decode `tok/s ≈ bandwidth ÷ active-bytes × 0.5–0.8`
+(llama.cpp / MLX community benchmarks). The exact ratios live as documented
+constants in `score.py`.
+
+## Model catalog
+
+The bundled seed catalog (`models.yaml`) covers 13 models from the Qwen 3, Qwen 2.5, and Gemma 3 families, from 3B to 72B parameters, across Q4_K_M and Q8_0 quantizations. The catalog tracks on-disk size, estimated peak RAM, and benchmark scores from the Open LLM Leaderboard v2 and the OpenVLM Leaderboard.
+
+`catalog update` (Phase 0b) refreshes the cache from external sources: the Ollama registry API, the HuggingFace Hub API, the Open LLM Leaderboard v2 dataset, the OpenVLM Leaderboard dataset, and the [ApXML LLM directory](https://apxml.com/models?modelType=open_weight) (open-weight models with VRAM/compute needs and coding benchmarks, consulted regularly). The bundled seed is never modified by the refresh.
+
+## Hardware table
+
+`hardware.yaml` lists known GPU and Apple Silicon chip configurations with their usable memory (physical pool minus OS and driver overhead). `hardware update` (Phase 0b) refreshes NVIDIA entries from TechPowerUp.
+
+## Downstream integration
+
+After `best-engine-ai-helper pull` completes, it writes `~/.best-engine-ai-helper/env.sh`:
+
+```sh
+export BEST_LLM_TEXT=qwen3-vl:72b
+export BEST_LLM_VISION=qwen3-vl:72b
+export BEST_LLM_BACKEND=ollama
+export BEST_LLM_BASE_URL=http://localhost:11434
+```
+
+Projects that consume the selected model source this file or read the companion `config.json`.
+
+## License
+
+[BSD-3-Clause](https://github.com/warith-harchaoui/best-engine-ai-helper/blob/main/LICENSE). Copyright 2026 Warith Harchaoui.

best_engine_ai_helper-0.3.0/README.md

@@ -0,0 +1,121 @@
+# best-engine-ai-helper
+
+Pick and pull the best local large language model (LLM) or vision-language model (VLM) for the hardware in the current machine.
+
+The tool detects available memory (Apple Silicon unified pool, NVIDIA VRAM, or system RAM), consults a bundled model catalog, and selects the highest-scoring model that fits within a configurable safety headroom. After selection, it pulls the model via Ollama, runs two quality gates (the Ralph Loop for prose and the Ralph Eyeball Loop for vision), and writes an environment file that downstream projects source to find the chosen model.
+
+Phase 0a (this release) covers detection, catalog, scoring, and the CLI skeleton. Phase 0b adds the pull, validate, and env commands.
+
+## Requirements
+
+- Python 3.10 or later
+- [Ollama](https://ollama.com) (Phase 0b only; not needed for `detect` and `recommend`)
+- psutil, PyYAML, click, requests (installed automatically)
+
+## Install
+
+```sh
+pip install best-engine-ai-helper
+```
+
+Or from source:
+
+```sh
+git clone https://github.com/warith-harchaoui/best-engine-ai-helper
+cd best-engine-ai-helper
+pip install -e .
+```
+
+## Quick start
+
+```sh
+# See what hardware this machine has
+best-engine-ai-helper detect
+
+# See which models would be selected (no download)
+best-engine-ai-helper recommend
+
+# Recommend the best engine(s) for a task, as a report (Markdown + JSON)
+best-engine-ai-helper report --task "product descriptions and image-quality checks" --out engine
+
+# Browse the full catalog
+best-engine-ai-helper catalog show
+
+# Browse the hardware chip table
+best-engine-ai-helper hardware show
+```
+
+See [EXAMPLES.md](https://github.com/warith-harchaoui/best-engine-ai-helper/blob/main/EXAMPLES.md) for runnable recipes with expected output.
+
+## How selection works
+
+Selection weighs three factors, each made explicit in the `report` output so the
+recommendation is reproducible and can be argued with.
+
+### 1. Memory fit (will it run on the accelerator?)
+
+Available memory comes from the highest-priority probe that succeeds: Apple
+Silicon unified memory (`system_profiler`), NVIDIA VRAM (`nvidia-smi`), AMD VRAM
+(`rocm-smi`), else half of system RAM as a conservative CPU-only estimate.
+
+The usable budget is **not** the whole pool. On Apple Silicon, Metal caps GPU
+allocations at about **66%** of unified memory at or below 36 GB and about
+**75%** above it (`recommendedMaxWorkingSetSize`); past that, work spills to the
+CPU and slows sharply. An extra safety `headroom` (default **0.85**) is applied
+on top, reserving room for the OS, your own application, and KV-cache growth as
+context fills. A catalog entry's `ram_gb` is already a peak-inference estimate
+(weights plus a moderate KV cache; roughly weights ÷ 0.7, since weights are only
+about 70% of runtime memory and can approach 2× at long context). A model fits
+when that `ram_gb` is at most the budget.
+
+### 2. Task fit (is it good at the job?)
+
+A task — even a vague phrase like *"retail descriptions and image-quality
+checks"* — maps to a benchmark axis (`generalist`, `code`, `math`, `ocr`,
+`vision`) and to the model kinds it needs (text ⇒ LLM, anything visual ⇒ VLM).
+Among fitting models, the highest benchmark on that axis wins.
+
+### 3. Throughput (how fast will it generate?)
+
+Token generation is **memory-bandwidth bound**: each token reads the active
+model from memory once, so the ceiling is `bandwidth ÷ model-size`, derated to
+about 65% for KV-cache reads and overhead. `report` estimates tokens/s per
+candidate from the chip's memory bandwidth, and offers a lighter, faster
+alternative when one is nearly as strong. Bigger is not automatically better: a
+72B model that technically fits may run at a few tokens/s, while an 8–14B model
+leaves headroom and runs several times faster.
+
+When nothing fits, the tool falls back to the smallest model and says so.
+
+**Sources.** Apple Metal working-set cap (Apple developer docs / apple-specs);
+inference-memory breakdown weights + KV (15–20%) + overhead (5–10%) (local-LLM
+sizing guides); bandwidth-bound decode `tok/s ≈ bandwidth ÷ active-bytes × 0.5–0.8`
+(llama.cpp / MLX community benchmarks). The exact ratios live as documented
+constants in `score.py`.
+
+## Model catalog
+
+The bundled seed catalog (`models.yaml`) covers 13 models from the Qwen 3, Qwen 2.5, and Gemma 3 families, from 3B to 72B parameters, across Q4_K_M and Q8_0 quantizations. The catalog tracks on-disk size, estimated peak RAM, and benchmark scores from the Open LLM Leaderboard v2 and the OpenVLM Leaderboard.
+
+`catalog update` (Phase 0b) refreshes the cache from external sources: the Ollama registry API, the HuggingFace Hub API, the Open LLM Leaderboard v2 dataset, the OpenVLM Leaderboard dataset, and the [ApXML LLM directory](https://apxml.com/models?modelType=open_weight) (open-weight models with VRAM/compute needs and coding benchmarks, consulted regularly). The bundled seed is never modified by the refresh.
+
+## Hardware table
+
+`hardware.yaml` lists known GPU and Apple Silicon chip configurations with their usable memory (physical pool minus OS and driver overhead). `hardware update` (Phase 0b) refreshes NVIDIA entries from TechPowerUp.
+
+## Downstream integration
+
+After `best-engine-ai-helper pull` completes, it writes `~/.best-engine-ai-helper/env.sh`:
+
+```sh
+export BEST_LLM_TEXT=qwen3-vl:72b
+export BEST_LLM_VISION=qwen3-vl:72b
+export BEST_LLM_BACKEND=ollama
+export BEST_LLM_BASE_URL=http://localhost:11434
+```
+
+Projects that consume the selected model source this file or read the companion `config.json`.
+
+## License
+
+[BSD-3-Clause](https://github.com/warith-harchaoui/best-engine-ai-helper/blob/main/LICENSE). Copyright 2026 Warith Harchaoui.

best_engine_ai_helper-0.3.0/best_engine_ai_helper/__init__.py

@@ -0,0 +1,82 @@
+"""
+best_engine_ai_helper — pick the best local LLM/VLM for the current hardware.
+
+Public API (importable without invoking the CLI):
+
+  from best_engine_ai_helper.detect import platform_name, chip_vendor, available_memory
+  from best_engine_ai_helper.catalog import load_catalog, estimate_ram
+  from best_engine_ai_helper.hardware import load_hardware, lookup_chip
+  from best_engine_ai_helper.score import select, rank, effective_budget
+  from best_engine_ai_helper import text_model, vision_model  # cheap tag resolvers
+
+The CLI entry point is ``best-engine-ai-helper`` (see cli.py). Importing this
+package does not trigger any CLI parsing or subprocess calls.
+
+Downstream suite packages that just need "which model tag do I use?" should call
+:func:`text_model` / :func:`vision_model` — they resolve an env override, then
+the selection persisted by ``pull``, then a safe default, without ever probing
+hardware, so they are cheap and deterministic (CI-safe).
+
+Author
+------
+Warith Harchaoui <warith.harchaoui@gmail.com>
+"""
+
+from __future__ import annotations
+
+from .catalog import estimate_ram, load_catalog
+
+# Cheap, deterministic model-tag resolution (env -> persisted config -> default);
+# the entry point downstream packages call to answer "which model do I use?".
+from .config import (
+    DEFAULT_TEXT_MODEL,
+    DEFAULT_VISION_MODEL,
+    load_config,
+    resolved_models,
+    text_model,
+    vision_model,
+)
+from .detect import (
+    available_memory,
+    chip_name,
+    chip_vendor,
+    compute_profile,
+    platform_name,
+)
+from .hardware import load_hardware, lookup_chip
+
+# Export the engine-recommendation function under a distinct name so it does
+# not shadow the ``recommend`` submodule on attribute access.
+from .recommend import parse_task, to_markdown, write_report
+from .recommend import recommend as recommend_engines
+from .score import effective_budget, estimated_tokens_per_second, rank, select
+
+__all__ = [
+    "platform_name",
+    "chip_vendor",
+    "chip_name",
+    "available_memory",
+    "compute_profile",
+    "load_catalog",
+    "estimate_ram",
+    "load_hardware",
+    "lookup_chip",
+    "select",
+    "rank",
+    "effective_budget",
+    "estimated_tokens_per_second",
+    "recommend_engines",
+    "parse_task",
+    "to_markdown",
+    "write_report",
+    "text_model",
+    "vision_model",
+    "resolved_models",
+    "load_config",
+    "DEFAULT_TEXT_MODEL",
+    "DEFAULT_VISION_MODEL",
+]
+
+__version__ = "0.3.0"
+__author__ = "Warith Harchaoui"
+__email__ = "warith.harchaoui@gmail.com"

best_engine_ai_helper-0.3.0/best_engine_ai_helper/catalog.py

@@ -0,0 +1,164 @@
+"""
+catalog — load and merge the bundled model catalog with the user's cache.
+
+The catalog lives in two layers:
+
+1. The **bundled seed** (`models.yaml` in the package root). Hand-maintained,
+   always present, never deleted by auto-refresh.
+2. The **user cache** (`~/.best-engine-ai-helper/catalog_cache.yaml`). Written
+   by `catalog update`; entries keyed by `id` overwrite matching seed entries.
+   Absent on first run; load_catalog silently skips it in that case.
+
+Keeping the seed immutable and the cache additive means offline machines always
+have a usable catalog and updates never lose hand-curated data.
+
+Author
+------
+Warith Harchaoui <warith.harchaoui@gmail.com>
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+# Root of the installed package; models.yaml sits next to pyproject.toml
+_PACKAGE_ROOT = Path(__file__).resolve().parent.parent
+
+# Default path for the bundled seed catalog
+_SEED_PATH = _PACKAGE_ROOT / "models.yaml"
+
+# User-writable runtime directory; created on first run
+_USER_DIR = Path.home() / ".best-engine-ai-helper"
+_CACHE_PATH = _USER_DIR / "catalog_cache.yaml"
+
+# Quant-specific overhead factors for estimating peak inference RAM.
+# Values are empirically derived: KV cache at 4K context adds ~10-20%
+# beyond on-disk size depending on quantization precision.
+_QUANT_OVERHEAD: dict[str, float] = {
+    "Q4_K_M": 1.12,
+    "Q8_0": 1.10,
+    "FP16": 1.05,
+    "Q2_K": 1.20,
+}
+_DEFAULT_OVERHEAD = 1.15  # fallback for unknown quant identifiers
+
+
+def estimate_ram(disk_gb: float, quant: str) -> float:
+    """
+    Estimate peak inference RAM from on-disk model size.
+
+    The estimate covers the model weights plus KV cache at the default context
+    length (4K tokens). For models with very large context windows (256K+),
+    actual RAM may exceed this estimate significantly; treat it as a lower bound.
+
+    Parameters
+    ----------
+    disk_gb : float
+        On-disk footprint of the model in GB.
+    quant : str
+        Quantization identifier, e.g. 'Q4_K_M', 'Q8_0', 'FP16', 'Q2_K'.
+
+    Returns
+    -------
+    float
+        Estimated peak RAM in GB.
+
+    Examples
+    --------
+    >>> estimate_ram(6.1, 'Q4_K_M')
+    6.832
+    >>> estimate_ram(10.0, 'FP16')
+    10.5
+    """
+    overhead = _QUANT_OVERHEAD.get(quant, _DEFAULT_OVERHEAD)
+    return round(disk_gb * overhead, 3)
+
+
+def _load_yaml_file(path: Path) -> list[dict[str, Any]]:
+    """
+    Load a YAML file and return its contents as a list of dicts.
+
+    Returns an empty list on FileNotFoundError so callers can treat the
+    absence of the cache file as a no-op rather than an error.
+
+    Parameters
+    ----------
+    path : Path
+        Absolute path to the YAML file.
+
+    Returns
+    -------
+    list[dict[str, Any]]
+        Parsed entries, or [] if the file is absent or empty.
+    """
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return []
+    # yaml.safe_load returns None for empty files
+    if raw is None:
+        return []
+    return list(raw)
+
+
+def load_catalog(catalog_path: Path | None = None) -> list[dict[str, Any]]:
+    """
+    Load the bundled seed catalog merged with the user's local cache.
+
+    Cache entries whose `id` matches a seed entry overwrite the seed entry.
+    New cache entries (no matching seed id) are appended. The seed is never
+    modified on disk.
+
+    Parameters
+    ----------
+    catalog_path : Path or None
+        Path to the seed `models.yaml`. Defaults to the bundled file next to
+        `pyproject.toml`. Pass an explicit path in tests to use a fixture.
+
+    Returns
+    -------
+    list[dict[str, Any]]
+        Merged model entries. Each entry is guaranteed to have at minimum:
+        ``id``, ``kind``, ``ram_gb``, ``benchmarks``.
+
+    Raises
+    ------
+    FileNotFoundError
+        If ``catalog_path`` is given explicitly and does not exist.
+
+    Examples
+    --------
+    >>> entries = load_catalog()
+    >>> len(entries) > 0
+    True
+    >>> all('id' in e for e in entries)
+    True
+    """
+    seed_path = catalog_path if catalog_path is not None else _SEED_PATH
+
+    # Start with the bundled seed; this must exist
+    seed = _load_yaml_file(seed_path)
+    if not seed and catalog_path is not None:
+        raise FileNotFoundError(f"Catalog not found: {seed_path}")
+
+    # Build a lookup by id so cache entries can overwrite in O(1)
+    merged: dict[str, dict[str, Any]] = {e["id"]: e for e in seed}
+
+    # Overlay user cache entries; absent cache is silently ignored
+    for entry in _load_yaml_file(_CACHE_PATH):
+        merged[entry["id"]] = entry
+
+    # Preserve seed ordering; append cache-only entries at the end
+    result: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for e in seed:
+        result.append(merged[e["id"]])
+        seen.add(e["id"])
+    for eid, entry in merged.items():
+        if eid not in seen:
+            result.append(entry)
+
+    return result