Metadata-Version: 2.5
Name: modelchoice
Version: 0.1.0
Summary: Provider-neutral model discovery and picker metadata
Project-URL: Homepage, https://github.com/lumpenspace/modelchoice
Project-URL: Issues, https://github.com/lumpenspace/modelchoice/issues
Author: lumpenspace
License-Expression: MIT
License-File: LICENSE
Keywords: catalog,huggingface,llm,models,openrouter
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# modelchoice

`modelchoice` is a small, UI-independent Python library for discovering model
providers and producing stable picker rows. It is shared by Fash, Clash, and
other local AI clients without importing any of their application code.

```python
from modelchoice import HuggingFaceSource, ModelCatalog

catalog = ModelCatalog()
quick_rows = catalog.quick_options()       # no subprocesses or network calls
all_local_rows = catalog.initial_options() # includes installed CLI listings
router_rows = catalog.search_openrouter("coder")

hub = ModelCatalog([HuggingFaceSource()])
hub_rows = hub.search_huggingface("qwen coder")
```

Every source implements the `ModelSource` protocol and returns immutable
`ModelOption` and `ProviderMetadata` values. Built-in sources cover Claude
Code, Codex, Agy, Cursor, OpenRouter, OpenAI-compatible APIs, local servers,
and Hugging Face Hub discovery.

Credential metadata contains environment-variable **names only**. API keys,
tokens, and other credential values are never stored in catalog rows or cache
files. Applications remain responsible for passing credentials directly to
their selected runtime backend.
