best_engine_ai_helper.usages module

usages — the sev7n usage catalog (“description d’usage”).

A usage profile names a concrete sev7n workload (text2sql, rag-answer, embeddings, …) and states only its needs: task type, whether it needs schema-constrained output, a comfort throughput floor, a memory headroom, an advisory quality bar and context length. A profile never names a model — that would defeat the whole tool. best-engine reads the needs, probes the machine, and chooses the concrete local model, writing that choice into a gitignored, machine-specific engine file (the extension of the env.sh it already emits).

Each profile is, at heart, a named llm.brief.yaml: its brief block holds exactly the fields engine.resolve() already understands, so a profile is resolved by the same four-criteria picker (structured output, memory fit, task fit, throughput) as any hand-written brief. The catalog supplies the criteria; the picker supplies the model.

Profiles are grouped into families (F1 constrained-generation, F2 prose-generation, F3 embeddings) — the usages that can share one model. A caller can resolve a whole family in one shot (one model for the group) or a single profile (specialised) when the hardware allows it.

The bundled catalog is usages.yaml at the package root; a user overlay at ~/.best-engine-ai-helper/usages_cache.yaml overrides profiles by name and families by id.

Author

Warith Harchaoui <warith.harchaoui@deraison.ai>

best_engine_ai_helper.usages.family_brief(family_id)[source]

Return the representative brief for a family (ready for engine.resolve()).

Parameters:

family_id (str) – The family id.

Returns:

The brief block with mode: local.

Return type:

dict[str, Any]

Examples

>>> family_brief("F2")["kind"]
'llm'
best_engine_ai_helper.usages.get_family(family_id)[source]

Return one family by id, with a helpful error when it is unknown.

Parameters:

family_id (str) – The family id ("F1", "F2" or "F3").

Returns:

The family dict.

Return type:

dict[str, Any]

Raises:

KeyError – If no family carries that id.

Examples

>>> get_family("F3")["name"]
'embeddings'
best_engine_ai_helper.usages.get_usage(name)[source]

Return one profile by name, with a helpful error when it is unknown.

Parameters:

name (str) – The profile name (e.g. "text2sql").

Returns:

The profile dict.

Return type:

dict[str, Any]

Raises:

KeyError – If no profile carries that name; the message suggests close matches.

Examples

>>> get_usage("text2sql")["family"]
'F1'
best_engine_ai_helper.usages.list_families()[source]

Enumerate families for discovery: id, name, members, summary.

Returns:

One compact row per family, in catalog order.

Return type:

list[dict[str, Any]]

Examples

>>> [r["id"] for r in list_families()]
['F1', 'F2', 'F3']
best_engine_ai_helper.usages.list_usages()[source]

Enumerate profiles for discovery: name, family, status, summary.

Returns:

One compact row per profile, in catalog order.

Return type:

list[dict[str, Any]]

Examples

>>> rows = list_usages()
>>> {"name", "family", "status", "summary"} <= set(rows[0])
True
best_engine_ai_helper.usages.load_families(usages_path=None)[source]

Load the bundled families merged with the user overlay.

Parameters:

usages_path (Path or None) – Path to the seed usages.yaml. Defaults to the bundled file.

Returns:

Family dicts, each with at least id, brief and members.

Return type:

list[dict[str, Any]]

Examples

>>> [f["id"] for f in load_families()]
['F1', 'F2', 'F3']
best_engine_ai_helper.usages.load_usages(usages_path=None)[source]

Load the bundled usage profiles merged with the user overlay.

Parameters:

usages_path (Path or None) – Path to the seed usages.yaml. Defaults to the bundled file; pass an explicit path in tests.

Returns:

Profile dicts, each with at least name, brief and family.

Return type:

list[dict[str, Any]]

Examples

>>> names = [p["name"] for p in load_usages()]
>>> "text2sql" in names and "embeddings" in names
True
best_engine_ai_helper.usages.resolve_family(family_id, *, backend='auto', endpoint=None, catalog=None, hw=None, compute=None)[source]

Resolve a whole family into one machine-specific engine descriptor.

Resolving a family yields a single model for the group (the shared pick), whereas resolve_usage() yields the possibly-specialised model for one profile. The result is machine-specific — persist it gitignored, never commit.

Parameters:
Returns:

The engine descriptor, annotated with the family’s metadata.

Return type:

dict[str, Any]

Examples

>>> hw = {"unified_gb": 96.0, "vram_gb": None, "ram_gb": 96.0}
>>> cat = [{"id": "emb", "kind": "embed", "ram_gb": 1.2,
...         "benchmarks": {"mteb": 66}}]
>>> eng = resolve_family("F3", catalog=cat, hw=hw,
...                      compute={"chip": "M2", "accelerator": "apple"})
>>> eng["embed"]["model"], eng["family"]
('emb', 'F3')
best_engine_ai_helper.usages.resolve_usage(name, *, backend='auto', endpoint=None, catalog=None, hw=None, compute=None)[source]

Resolve a usage profile into a machine-specific engine descriptor.

This is the “give me the model for profile name” entry point. It reads only the profile’s needs, then lets best-engine choose the concrete model for this machine. The returned descriptor is machine-specific: persist it to a gitignored file (see engine.write_engine()), never commit it.

Parameters:

  • name (str) – The profile name ("text2sql", "rag-answer", …).

  • backend ({'auto', 'ollama', 'vllm'}) – Serving backend; auto picks per engine.default_backend().

  • endpoint (str or None) – Override the server base URL.

  • catalog (optional) – Injectable for tests; default to the live catalog and detected hardware.

  • hw (optional) – Injectable for tests; default to the live catalog and detected hardware.

  • compute (optional) – Injectable for tests; default to the live catalog and detected hardware.

Returns:

The engine descriptor, annotated with the profile’s metadata.

Return type:

dict[str, Any]

Examples

>>> hw = {"unified_gb": 96.0, "vram_gb": None, "ram_gb": 96.0}
>>> compute = {"accelerator": "apple", "chip": "M2", "bandwidth_gbs": None}
>>> cat = [{"id": "coder", "kind": "llm", "size_b": 7, "ram_gb": 5.0,
...         "benchmarks": {"general": 66, "code": 85},
...         "structured_output": True, "vllm_id": "org/Coder"}]
>>> eng = resolve_usage("text2sql", backend="ollama", catalog=cat,
...                     hw=hw, compute=compute)
>>> eng["llm"]["model"], eng["usage"], eng["status"]
('coder', 'text2sql', 'stable')
best_engine_ai_helper.usages.usage_brief(name)[source]

Return the resolvable brief for a profile (ready for engine.resolve()).

Parameters:

name (str) – The profile name.

Returns:

The brief block with mode: local.

Return type:

dict[str, Any]

Examples

>>> usage_brief("classification")["kind"]
'llm'