openrouter_model_filter is a command-line tool designed to fetch, filter, and sort models from the OpenRouter API.

The primary idea behind this tool was to make it easy to identify and use the best currently available free models on OpenRouter. However, its filtering capabilities are flexible and can be adapted for various other criteria and use cases beyond just free models.

pip install openrouter-model-filter

No API keys are required to use this tool as it only fetches publicly available model information.

By default, openrouter_model_filter fetches models, keeps those tagged as :free, removes common base, instruct, or math specific models (which are often less suitable for general chat), sorts them by context length (descending), and returns a newline-separated list of model IDs. This sorting order generally places models with larger context windows, often the most recent or "frontier-like" ones, at the top of the list.

You can customize the behavior using various command-line options:

openrouter_model_filter --help

This tool was initially created to be integrated with Simon Willison's llm tool. The following command demonstrates how to use openrouter_model_filter to select one of the top 5 free models at random and then use it with llm:

llm --model "openrouter/$(openrouter_model_filter --n 5 | shuf | head -n 1)" "Hi, please tell me which model you are and what company made you."

Or like that:

alias freemodel="echo \"openrouter/$(openrouter_model_filter --n 5 | shuf | head -n 1)\""
alias freellm="llm -m $(freemodel)"
freellm "Hi, please tell me which model you are and what company made you."

Note: When using models via OpenRouter, you often need to explicitly agree to their terms, which may include allowing your prompts to be used for training by the model providers. Please check the OpenRouter documentation and model-specific terms.

• --n: Number of models to return (-1 for all).
• --return-format: Output format (dict, json, str). Default is str.
• --keep-regexes: Comma-separated regexes. Models matching ALL regexes are kept. Default is .*:free.
• --remove-regexes: Comma-separated regexes. Models matching ANY regex are removed. Default is .*\bbase\b.*,.*\binstruct\b.*,.*\bmath\b. Pass "" for no removal.
• --sort-key: Key to sort models by (e.g., context_length, name). Default is context_length. Pass "" for no sorting.

For example, to get the top 3 free models sorted by name:

openrouter_model_filter --n 3 --sort-key name

To get all models that are not free, in JSON format, without sorting:

openrouter_model_filter --keep-regexes ".*" --remove-regexes ".*:free" --return-format json --sort-key ""

This project uses click for the CLI and requests for API interaction.

Further development and contributions are welcome!

This project was developed with assistance from aider.chat.