best_engine_ai_helper.hardware module

hardware — load and query the bundled chip lookup table.

The hardware database records the usable memory for each known GPU or Apple Silicon chip. ‘Usable’ means the pool available to Ollama after the OS, display driver, and kernel pages have reserved their share. The 80% safety headroom in score.py applies on top of this value.

Like the model catalog, the hardware table has two layers:

  1. The bundled seed (hardware.yaml in the package root).

  2. The user cache (~/.best-engine-ai-helper/hardware_cache.yaml), written by hardware update. Cache entries overwrite seed entries on the same (chip, memory_gb) pair.

Author

Warith Harchaoui <warith.harchaoui@deraison.ai>

best_engine_ai_helper.hardware.detect_local_entry(fetched_at=None)[source]

Build a hardware entry for the machine this runs on, from live detection.

There is no public specs API for the full GPU/Apple-Silicon universe, so a refresh records ground truth for the current machine instead: the detected chip, its memory pool, and the Ollama-usable share after the OS reservation. Repeated runs upsert the same row (keyed on chip + memory tier), keeping the table correct for whatever hardware the user actually has.

Parameters:

fetched_at (str or None) – Refresh timestamp for the entry; defaults to today (UTC).

Returns:

A hardware entry, or None when no usable memory figure could be detected (nothing worth writing).

Return type:

dict[str, Any] or None

best_engine_ai_helper.hardware.load_hardware(hardware_path=None)[source]

Load the bundled hardware chip table merged with the user’s local cache.

Cache entries whose (chip, memory_gb) pair matches a seed entry overwrite it. New entries are appended. The seed file is never modified.

Parameters:

hardware_path (Path or None) – Path to the seed hardware.yaml. Defaults to the bundled file. Pass an explicit path in tests to use a fixture.

Returns:

Merged hardware entries. Each entry has at minimum: chip, vendor, memory_gb, ollama_usable_gb.

Return type:

list[dict[str, Any]]

Examples

>>> entries = load_hardware()
>>> len(entries) > 0
True
>>> all('chip' in e for e in entries)
True
best_engine_ai_helper.hardware.lookup_chip(chip_name, hardware)[source]

Find a hardware entry by a case-insensitive substring match on the chip name.

When multiple entries share the same chip name (for example, an Apple M2 Max at 32 GB and at 96 GB), this returns the first match in the list order. The caller should supply the most specific chip string available to avoid ambiguity.

Parameters:

  • chip_name (str) – Chip name or substring to search for, e.g. 'Apple M2 Max'.

  • hardware (list[dict[str, Any]]) – Hardware entries as returned by load_hardware().

Returns:

The first matching entry, or None if no entry contains chip_name as a case-insensitive substring.

Return type:

dict[str, Any] or None

Examples

>>> hw = load_hardware()
>>> entry = lookup_chip('Apple M2 Max', hw)
>>> entry is not None
True
>>> entry['vendor']
'apple'
best_engine_ai_helper.hardware.write_cache(entries, cache_path=None)[source]

Merge entries into the hardware cache by (chip, memory_gb) and write it.

Existing cache rows are preserved; an incoming row on the same chip and memory tier overwrites it, so a refresh is idempotent. The bundled seed is untouched.

Parameters:

  • entries (list[dict[str, Any]]) – Hardware entries to add or update, e.g. from detect_local_entry().

  • cache_path (Path or None) – Destination cache file. Defaults to CACHE_PATH; override in tests.

Returns:

The path written.

Return type:

Path