InteropRouter

Seamlessly call major LLMs and image generation models through a unified interface.

InteropRouter is designed to seamlessly interoperate between the most common AI providers at a high level of quality. It uses the OpenAI Responses API types as a common denominator for inputs and outputs, allowing you to switch between providers with minimal code changes. See examples/ for detailed notebooks covering interoperability, function calling, image generation, and more.

Getting Started

Installation

# With uv.
uv add interop-router

# With pip.
pip install interop-router

Usage

from anthropic import AsyncAnthropic
from google import genai
from openai import AsyncOpenAI
from openai.types.responses import EasyInputMessageParam

from interop_router.router import Router
from interop_router.types import ChatMessage

router = Router()
router.register("openai", AsyncOpenAI())
router.register("gemini", genai.Client())
router.register("anthropic", AsyncAnthropic())
router.register("chat_completions", AsyncOpenAI(base_url="http://localhost:8000/v1"))  # Can point to local models, OpenAI, OpenRouter, etc.

# See https://platform.openai.com/docs/guides/migrate-to-responses and the library source for more details on typing.
messages = [ChatMessage(message=EasyInputMessageParam(role="user", content="Hello!"))]

# OpenAI, Azure OpenAI, Gemini, and Anthropic are supported
response = await router.create(input=messages, model="gpt-5.6-terra")
response = await router.create(input=messages, model="gemini-3.6-flash")
response = await router.create(input=messages, model="claude-sonnet-5")
# Explicit provider routing with provider/model.
response = await router.create(input=messages, model="chat_completions/nvidia/Qwen3.6-27B-NVFP4")

Register several clients for the same provider by giving each one a name, then route to it with name/model:

router.register("chat_completions", AsyncOpenAI(base_url="http://localhost:8000/v1"), name="vllm")
router.register("chat_completions", AsyncOpenAI(base_url="https://openrouter.ai/api/v1"), name="openrouter")

response = await router.create(input=messages, model="vllm/nvidia/Qwen3.6-27B-NVFP4")
response = await router.create(input=messages, model="openrouter/moonshotai/kimi-k2")

Count input tokens before making a request using each provider's native token counting endpoint:

token_count = await router.count_tokens(input=messages, model="gpt-5.6-terra")
token_count = await router.count_tokens(input=messages, model="gemini-3.6-flash")
token_count = await router.count_tokens(input=messages, model="claude-sonnet-5")

InteropRouter Design Philosophy

The only goal of InteropRouter is to interoperate between the most common AI providers. To make this goal achievable, we make several trade-offs:

• Focus on OpenAI (Responses API, including Azure OpenAI), Gemini, and Anthropic. Each provider adds a significant amount of possible permutations of features. To maintain high-quality interoperability, we limit the number of first-class providers.
• Also support a chat_completions adapter for OpenAI-compatible Chat Completions endpoints.
• We do not support stateful features where possible. These features are contradictory to the goal of seamless swapping between providers.
• We choose the OpenAI Responses API types as the common denominator for creating pivots between providers. The reason is two-fold: a) The Responses API supports most features b) By picking an existing API, we avoid the need to design and maintain our own schema and Responses API support is gained for "free".
• The supported features will be rigorously tested to ensure seamless swapping between providers within a single conversation.

Development

Prerequisites

• uv
• prek

Setup

Create uv virtual environment and install dependencies:

uv sync --frozen --all-extras --all-groups

Set up git hooks:

prek install

To update dependencies (updates the lock file):

uv sync -U --all-extras --all-groups

Run formatting, linting, type checking, and tests in one command:

uv run ruff format && uv run ruff check --fix && uv run ty check && uv run pytest

Further Information

• docs/DEVELOPMENT.md
• docs/PROVIDER_GUIDE.md

Compatibility and Roadmap

docs/COMPATIBILITY_AND_ROADMAP.md