irouter 0.1.2

Easy access to 100s of LLMs with a few lines of code (using Openrouter).

irouter

irouter ("Intelligence Router") is a Python package with a simple interface to access 100s of LLMs with 2 lines of code.

Installation

1. Install irouter from PyPI:

pip install irouter

2. Create an account on OpenRouter and generate an API key.

3a. (recommended!) Set the OpenRouter API key as an environment variable:

export OPENROUTER_API_KEY=your_api_key

In this way you can use irouter objects like Call and Chat without have to pass an API key.

from irouter import Call
c = Call(model="moonshotai/kimi-k2:free")

3b. Alternatively, pass api_key to irouter objects like Call and Chat.

from irouter import Call
c = Call(model="moonshotai/kimi-k2:free", api_key="your_api_key")

Usage

Call

Call is the simplest interface to call one or more LLMs.

Single LLM

from irouter import Call
c = Call(model="moonshotai/kimi-k2:free")
c("Who are you?")
# "I'm Kimi, your AI friend from Moonshot AI. I'm here to chat, answer your questions, and help you out whenever you need it."

Multiple LLMs

from irouter import Call
c = Call(model=["moonshotai/kimi-k2:free", "google/gemini-2.0-flash-exp:free"])
c("Who are you?")
# {'moonshotai/kimi-k2:free': "I'm Kimi, your AI friend from Moonshot AI. I'm here to chat, answer your questions, and help you out whenever you need it.",
#  'google/gemini-2.0-flash-exp:free': 'I am a large language model, trained by Google.\n'}

Chat

Chat is an easy way to interface with one or more LLMs, while tracking message history and token usage.

Single LLM

from irouter import Chat
c = Chat(model="moonshotai/kimi-k2:free")
c("Who are you?")
print(c.history) # {'moonshotai/kimi-k2:free': [...]}
print(c.usage) # {'moonshotai/kimi-k2:free': {'prompt_tokens': 8, 'completion_tokens': 8, 'total_tokens': 16}}

Multiple LLMs

from irouter import Chat
c = Chat(model=["moonshotai/kimi-k2:free", "google/gemini-2.0-flash-exp:free"])
c("Who are you?")
print(c.history) 
# {'moonshotai/kimi-k2:free': [...], 
# 'google/gemini-2.0-flash-exp:free': [...]}
print(c.usage) 
# {'moonshotai/kimi-k2:free': {'prompt_tokens': 8, 'completion_tokens': 8, 'total_tokens': 16}, 
# 'google/gemini-2.0-flash-exp:free': {'prompt_tokens': 8, 'completion_tokens': 10, 'total_tokens': 18}}

Image

Both Call and Chat support images from image URLs or local images.

Adding images is as simple as providing a list of strings with:

• text and/or
• image URL(s) and/or
• image path(s)

Make sure to select an LLM that supports image input, like gpt-4o-mini.

from irouter import Chat
ic = Chat("gpt-4o-mini")
# Image URL
ic(["https://www.petlandflorida.com/wp-content/uploads/2022/04/shutterstock_1290320698-1-scaled.jpg", 
    "What is in the image?"])
# or local image
# ic(["../assets/puppy.jpg", "What is in the image?"])
# Example output:
# The image shows a cute puppy, ..., The background is blurred, 
# with green hues suggesting an outdoors setting.

# Images are tracked in history
print(ic.history)
# [{'role': 'system', 'content': 'You are a helpful assistant.'}, 
#  {'role': 'user', 'content': [{'type': 'image_url', 'image_url':
#  {'url': '...'}}, {'type': 'text', 'text': 'What is in the image?'}]}, 
#  {'role': 'assistant', 'content': 'The image shows a cute puppy...'}]

For more information on Chat, check out the chat.ipynb notebook in the nbs folder.

PDF Support

Both Call and Chat support PDF processing from URLs or local files.

from irouter import Call
c = Call("moonshotai/kimi-k2:free")
pdf_url = "https://proceedings.neurips.cc/paper_files/paper/2017/file/3f5ee243547dee91fbd053c1c4a845aa-Paper.pdf"
c([pdf_url, "What is the main contribution of this paper?"])
# 'The main contribution of this paper is the introduction of the Transformer architecture...'

Audio Support

Some LLMs have native audio support. Simply pass a local filepath that points to a .mp3 or .wav file with the instruction as a list of strings.

from irouter import Call
c = Call("google/gemini-2.5-flash")
c(["../assets/bottles.mp3", "What do you hear?"])
# 'I hear the sound of a glass bottle being opened and closed...'

Multiple Modalities

Combine text, images, PDFs, and audio in a single request by simply passing a list of strings.

from irouter import Call
c = Call("google/gemini-2.5-flash")
c(["../assets/bottles.mp3", "../assets/puppy.jpg", "What do you hear and see?"])
# 'I hear sounds of glass and see a small, fluffy dog...'

Misc

get_all_models

You can easily get all 300+ models available with irouter using get_all_models.

from irouter.base import get_all_models
get_all_models()
# ['llm_provider1/model1', ... 'llm_providerx/modelx']

history_to_markdown

Convert chat history to markdown for easy display in Jupyter notebooks.

from irouter.base import history_to_markdown
history_to_markdown(c.history, ipython=True)

Credits

This project is built on top of the OpenRouter API infrastructure, which provides access to LLMs through a unified interface.

This project is inspired by Answer.AI's projects like cosette and claudette.

irouter generalizes this idea to support 100s of LLMs, which includes OpenAI and Anthropic models and more, thanks to OpenRouter's infrastructure.