best_engine_ai_helper.sources.ollama_library module

ollama_library — widen the catalog with tags Ollama can actually pull.

The bundled seed holds twenty models, hand-maintained and fully scored. The ApXML adapter can add hundreds more, but it keys them by the paper’s slug (qwen36-35b-a3b), which is a HuggingFace repo name and not something ollama pull resolves — so those entries are vLLM-only and the Ollama-servable pool stays at twenty. That is the real reason this catalog is small, and it is not a scoring problem.

This source closes that gap. ollama.com/library publishes the official library: family name, capabilities, and the parameter sizes each family ships. A family plus a size is a pull tag — qwen3 plus 8b is qwen3:8b, exactly the spelling the seed already uses — so every entry produced here passes catalog.servable() and can be served today.

What it deliberately does not do

It invents no benchmark scores. Ollama’s library page carries descriptions and sizes, not leaderboard results, so every entry lands with null benchmarks and therefore ranks below any scored model. That is the honest outcome and the same contract the ApXML adapter already follows: an entry with no provenance is worth less than no entry, so widening must not be bought by making scores up.

The practical effect is that this widens reach — the set of models the tool knows how to size and pull — without touching ranking, until a scored source fills the benchmarks in.

One request

The index alone carries everything needed, because it lists each family’s sizes inline. Walking the 256 per-family tag pages would be 256 requests for a slightly more precise disk figure, which is not a trade worth making in a command someone runs interactively.

Author

Warith Harchaoui <warithmetics@deraison.ai>

best_engine_ai_helper.sources.ollama_library.LIBRARY_URL = 'https://ollama.com/library'

The official library index. No API is published, so this reads the page.

best_engine_ai_helper.sources.ollama_library.REFRESH_QUANT = 'Q4_K_M'

Quantisation label recorded on entries from this source, matching what ollama pull <family>:<size> actually fetches for the default tag.

best_engine_ai_helper.sources.ollama_library.fetch_library(session=None, timeout=30.0, limit=None)[source]

Fetch and parse the official Ollama library index.

Parameters:

  • session (requests.Session or None) – Optional shared session.

  • timeout (float) – Request timeout in seconds. Always bounded: a hung index read would stall a command someone is sitting in front of.

  • limit (int or None) – Keep at most this many families, in the page’s own ordering (most popular first), so a partial refresh takes the models people use.

Returns:

As parse_library().

Return type:

list of dict

Examples

>>> families = fetch_library(limit=5)
>>> families[0]["name"]
'llama3.1'
best_engine_ai_helper.sources.ollama_library.fetch_pullable_models(session=None, timeout=30.0, limit=None)[source]

Every size of every family in the library, as concrete pull tags.

Parameters:

  • session (requests.Session or None) – Optional shared session.

  • timeout (float) – Request timeout in seconds.

  • limit (int or None) – Maximum number of families to expand, not tags: a family yields several tags, and cutting mid-family would hide sizes of a model the caller was told about.

Returns:

Specs, one per pull tag.

Return type:

list of dict

best_engine_ai_helper.sources.ollama_library.parse_library(html)[source]

Extract one record per model family from the library index page.

Parameters:

html (str) – The fetched page.

Returns:

[{"name", "capabilities", "sizes", "description"}] in page order, which is the site’s own popularity ordering.

Return type:

list of dict

best_engine_ai_helper.sources.ollama_library.to_specs(families)[source]

Expand families into one spec per concrete pull tag.

A family on its own is not pullable at a chosen size, and the catalog is keyed by what you would actually run. qwen3 with sizes 8b and 14b therefore becomes qwen3:8b and qwen3:14b.

A family listing no sizes is skipped rather than emitted as a bare name. The bare name usually does resolve, to whichever size the publisher made default, but the catalog’s whole job is sizing a model against this machine’s memory — and an entry whose size is unknown cannot be sized.

Parameters:

families (list of dict) – As returned by parse_library().

Returns:

Specs ready for catalog.normalize_ollama_spec().

Return type:

list of dict