Catalog

Federated model discovery across HuggingFace, Ollama Hub, and Modelscope. These routes power the Catalog page in the Web UI (see 12 — Model catalog) and answer the operator question "what could I pull?" — orthogonal to the "which adapters do I have" view served by /admin/adapters.

The router lives at packages/catalog/federation/admin_routes.py.

Endpoints

Method	Path	Auth	Summary
GET	/admin/catalog/search	Bearer	Workspace-scoped model search across federated sources.
GET	/admin/catalog/models/{model_id}	Bearer	Resolve a single canonical model id.
GET	/admin/catalog/models/{model_id}/revisions	Bearer	List revisions of a model the source knows about.

GET /admin/catalog/search

Query params (all optional):

Param	Type	Notes
query	string	Free-text search.
family	string	Filter by family (llama, qwen, mistral, …).
modality	enum	One of ModelModality values (text, vision, …).
formats	enum[]	One or more ModelFormatKind values (repeat the param).
requires_tool_calling	bool	Default false.
max_params_billions	float	Upper bound on model size.
min_params_billions	float	Lower bound on model size.
limit	int	1..500, default 50.

Filter assembly is centralised in CatalogFilter (packages/catalog/federation/types.py).

Response shape:

{
  "data": [
    {
      "id": "qwen/Qwen2.5-7B-Instruct",
      "family": "qwen",
      "display_name": "Qwen2.5 7B Instruct",
      "params_billions": 7.0,
      "license": "apache-2.0",
      "modality": "text",
      "context_length": 32768,
      "tool_calling": true,
      "tags": ["instruct"],
      "downloads_30d": 12345,
      "sources": ["huggingface"],
      "metadata_confidence": "high",
      "formats": [
        {
          "kind": "safetensors",
          "quantization": null,
          "source_uri": "https://huggingface.co/qwen/Qwen2.5-7B-Instruct",
          "size_gb": 14.5,
          "min_vram_gb": 16.0
        }
      ]
    }
  ],
  "count": 1
}

curl -H "Authorization: Bearer $BIGWAVE_ADMIN_TOKEN" \
  "http://localhost:8000/admin/catalog/search?family=qwen&min_params_billions=3&limit=10"

GET /admin/catalog/models/{model_id}

Resolve a single model id. model_id accepts a path containing slashes (qwen/Qwen2.5-7B-Instruct). Returns the same item shape as search.data[*], or 404 when not found.

GET /admin/catalog/models/{model_id}/revisions

Enumerate revisions the upstream source knows about.

{
  "data": [
    {
      "revision": "main",
      "timestamp": "2024-08-01T00:00:00Z",
      "formats": [
        { "kind": "safetensors", "quantization": null, "source_uri": "…" }
      ]
    }
  ]
}

Operator notes

• No catalog wired. When app.state.model_catalog is missing every route returns 503 with "Model catalog is not configured on this deployment.". The in-tree default federates HuggingFace + Ollama Hub when huggingface_hub and the relevant tokens are available; otherwise the catalog falls back to a no-op.
• Upstream errors.

  Status	Meaning
  429	Source rate-limited us — see CatalogRateLimitedError.
  504	Source request timed out — see CatalogTimeoutError.
  503	Catalog misconfigured (missing API key, etc.).

• Workspace scoping. Catalog content is not workspace-scoped (a Qwen exists for every tenant), but each request is still authenticated and scoped to the calling workspace so audit telemetry attributes correctly.
• Source mix. See the Catalog page concept for the precedence rules when the same model id appears in multiple sources.