best_engine_ai_helper.catalog module

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

best_engine_ai_helper.catalog.estimate_ram(disk_gb, quant)[source]

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:

Estimated peak RAM in GB.

Return type:

float

Examples

>>> estimate_ram(6.1, 'Q4_K_M')
6.832
>>> estimate_ram(10.0, 'FP16')
10.5
best_engine_ai_helper.catalog.load_catalog(catalog_path=None)[source]

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:

Merged model entries. Each entry is guaranteed to have at minimum: id, kind, ram_gb, benchmarks.

Return type:

list[dict[str, Any]]

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
best_engine_ai_helper.catalog.normalize_apxml_spec(spec, fetched_at)[source]

Map one ApXML spec dict onto a catalog entry.

The ApXML adapter (best_engine_ai_helper.sources.apxml) yields spec and memory-fit metadata but no numeric benchmarks, so the benchmarks block is left null. disk_gb is estimated from the Q4 VRAM figure by dividing out the quant overhead — the inverse of estimate_ram().

Parameters:

  • spec (dict[str, Any]) – A normalized spec as returned by apxml.parse_model_page.

  • fetched_at (str) – ISO 8601 date recorded on the entry as its refresh timestamp.

Returns:

A catalog entry, or None when the spec lacks the slug needed to key it (such an entry could never be merged or pulled).

Return type:

dict[str, Any] or None

best_engine_ai_helper.catalog.normalize_apxml_specs(specs, fetched_at=None)[source]

Normalize a batch of ApXML specs into catalog entries, dropping unusable ones.

Parameters:

  • specs (list[dict[str, Any]]) – Specs as returned by apxml.fetch_open_weight_models.

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

Returns:

Catalog entries, in input order, minus specs with no slug.

Return type:

list[dict[str, Any]]

best_engine_ai_helper.catalog.write_cache(entries, cache_path=None)[source]

Merge entries into the user catalog cache by id and write it to disk.

Existing cache entries are preserved; an incoming entry whose id matches one already cached overwrites it, so a refresh is idempotent and never loses previously cached models. The bundled seed is untouched.

Parameters:

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

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

Returns:

The path written.

Return type:

Path