Metadata-Version: 2.4
Name: llm-model-alias
Version: 0.1.0
Summary: Standalone model alias resolver
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: huggingface_hub>=1.4.1
Requires-Dist: requests>=2.32.5
Provides-Extra: dev
Requires-Dist: pytest>=9.0.1; extra == "dev"
Dynamic: license-file

# 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:

```bash
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:

```json
{
  "mappings": []
}
```

Path precedence:

1. `data_file` constructor parameter
1. `MODEL_ALIAS_JSON_FILE` environment variable
1. 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
1. `MODEL_ALIAS_OLLAMA_URL` environment variable
1. `http://localhost:11434`

## Usage

```python
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`.
