airouter-sdk 0.2.6

Official Python SDK for airouter.io - Automatically route requests to the best Large Language Model (LLM).

🪄 AI Router: Automatically get the best LLM for any request.

Documentation | Pricing | FAQ

Installation

Basic Installation

Install the package using pip:

pip install "airouter_sdk"

Privacy Features

To enable privacy mode for local embedding generation:

pip install "airouter_sdk[privacy]"

Development Setup

For SDK development, use Poetry:

poetry install --no-root

Usage

Basic Usage

Initialize the AiRouter class with your API key:

from airouter.router import AiRouter

# Initialize with API key
airouter = AiRouter(api_key="your_api_key_here")  # Note: Use AIROUTER_API_KEY env var instead in production

# Create a chat completion
response = airouter.chat.completions.create(
    messages=[
        {"role": "user", "content": "Hello, world!"}
    ]
)
print(response)

Environment Variables

For security best practices, set your API key as an environment variable:

export AIROUTER_API_KEY="your_api_key_here"

Model Selection

You can very easily retrieve the best model:

# Get the best model for your use case
model_name = airouter.get_best_model(
    messages=[
        {"role": "user", "content": "Hello, world!"}
    ]
)
print(model_name)  # Returns the recommended model identifier

This is particularly useful when working with private models or when you need to handle the model calling logic yourself.

You can also limit the models, for example to create a simple switch between gpt-4o-mini and gpt-4o:

model_name = airouter.get_best_model(
    messages=[
        {"role": "user", "content": "Hello, world!"}
    ],
    models=[Model.GPT_4O_MINI, Model.GPT_4O]
)
if model_name == Model.GPT_4O_MINI:
    # call your private gpt-4o-mini endpoint
else:
    # call your private gpt-4o endpoint

Privacy Features

For enhanced privacy, use the full_privacy mode to avoid sending message content:

# Use privacy mode for sensitive content
model_name = airouter.get_best_model(
    messages=[
        {"role": "user", "content": "Hello, world!"}
    ],
    full_privacy=True
)
print(model_name)

This mode:

• Generates embeddings locally
• Only sends embeddings to AI Router
• Protects sensitive message content
• Requires the privacy dependencies: pip install "airouter_sdk[privacy]"

If you want to use existing text-embedding-3-small embeddings, you can do so by handing in these embeddings and setting the embedding type:

# generate openai embeddings
messages = [
    {"role": "user", "content": "Hello, world!"}
]
input = " ".join(message['content'] for message in messages)
input = messages_query.replace("\n", " ")
embedding = openai_client.embeddings.create(
    model="text-embedding-3-small",
    input=input,
    dimensions=1536
)

# Use privacy mode for sensitive content with existing openai embeddings
model_name = airouter.get_best_model(
    full_privacy=True,
    embedding=embedding,
    embedding_type=EmbeddingType.TEXT_EMBEDDING_3_SMALL,
)
print(model_name)

Testing

Running Tests

Run the test suite using Poetry:

poetry run pytest

Integration Tests

For running integration tests (marked with @pytest.mark.integration):

poetry run pytest --run-integration

License

This project is licensed under the MIT License - see the LICENSE file for details.