llm_model_alias

A standalone Python package for resolving model aliases across platforms (vllm, vllm-metal, ollama, openai, custom) with JSON-backed mappings.

Features

• Resolve a model alias to a platform-specific model id.
• Store mappings in a JSON file.
• Seed defaults from packaged mappings.
• Pass through openai and custom model names unchanged.
• Local-only is_downloaded checks for Ollama and Hugging Face cache.

Installation

From the llm_model_alias directory:

pip install -e .

Public API

• Class: LLMModelAlias
• Types: ModelPlatform, ModelPlatformMapping, ModelMapping, ResolvedModelMapping
• Constant: MODEL_PLATFORMS

Main methods:

• resolve(model_name, platform) -> str
• get(model_name, platform) -> ResolvedModelMapping
• is_downloaded(model_name, platform) -> bool
• load() -> list[ModelMapping]
• json_path() -> Path
• normalize_model_name(model_name) -> str
• ollama_url() -> str

Configuration

Mapping file location

JSON schema:

{
  "mappings": []
}

Path precedence:

1. data_file constructor parameter
2. MODEL_ALIAS_JSON_FILE environment variable
3. OS default path

If the selected path does not exist and data_file is not explicitly provided, packaged defaults are loaded from src/llm_model_alias/data/default_model_mappings.json.

OS defaults:

• Linux: ${XDG_DATA_HOME:-~/.local/share}/llm_model_alias/model_mappings.json
• macOS: ~/Library/Application Support/llm_model_alias/model_mappings.json

Ollama URL

URL precedence:

1. ollama_url constructor parameter
2. MODEL_ALIAS_OLLAMA_URL environment variable
3. http://localhost:11434

Usage

from pathlib import Path

from llm_model_alias import LLMModelAlias

alias = LLMModelAlias(
  data_file=Path("./model_mappings.json"),
  ollama_url="http://localhost:11434",
)

resolved = alias.resolve("qwen3.5:9b", "vllm")
print(resolved)

mapping = alias.get("qwen3.5:9b", "vllm")
print(mapping)

Notes

• Default mappings live at src/llm_model_alias/data/default_model_mappings.json.