swarmauri_llm_openrouter

Use OpenRouter's unified APIs through Swarmauri's native LLM, tool-LLM, vision-language, and image-generation contracts.

Features

• Text, reasoning, structured-output, streaming, and batch workflows.
• Client-side Swarmauri toolkit execution through OpenRouter tool calling.
• URL and base64 image inputs without flattening multimodal messages.
• Dedicated image generation with binary results.
• Provider ordering, fallback, parameter, data-collection, and ZDR controls.
• Explicit live model discovery without constructor-time network requests.
• Composition with swarmauri_provider_openrouter for provider configuration.
• Persistent, injectable Swarmauri HTTP execution with conservative retries.

Installation

Install with uv:

uv add swarmauri_llm_openrouter

Install with pip:

pip install swarmauri_llm_openrouter

Usage

Chat

from swarmauri_llm_openrouter import OpenRouterModel
from swarmauri_standard.conversations.Conversation import Conversation
from swarmauri_standard.messages.HumanMessage import HumanMessage

conversation = Conversation()
conversation.add_message(HumanMessage(content="Explain provider routing."))
model = OpenRouterModel(
    api_key="...",
    name="openai/gpt-4o-mini",
    allowed_models=["openai/gpt-4o-mini"],
    app_name="My Swarmauri application",
)
model.predict(conversation, temperature=0.2)
print(conversation.get_last().content)

Pass an OpenRouterProvider as provider, an IHttpClient as http_client, or an IHttpRetryPolicy as retry_policy to replace the defaults. Upstream routing preferences use the separate routing argument.

Vision

from swarmauri_llm_openrouter import OpenRouterVLM

vlm = OpenRouterVLM(
    api_key="...",
    name="openai/gpt-4o-mini",
    allowed_models=["openai/**"],
)
# Add a HumanMessage whose content contains text and image_url items, then:
vlm.predict_vision(conversation)

Image generation

from swarmauri_llm_openrouter import OpenRouterImgGenModel

image_model = OpenRouterImgGenModel(
    api_key="...",
    name="openai/gpt-image-1",
    allowed_models=["openai/gpt-image-1"],
)
image_bytes = image_model.generate_image(
    "A geometric tiger rendered as stained glass",
    size="1024x1024",
    output_format="png",
)

Model discovery

from swarmauri_llm_openrouter import OpenRouterModel
from swarmauri_provider_openrouter import OpenRouterProvider

provider = OpenRouterProvider(api_key="...")
discovery = OpenRouterModel(
    provider=provider,
    allowed_models=["*"],
)
discovery.refresh_catalog()
available_models = discovery.catalog.list_model_ids(
    output_modalities="text"
)
model = OpenRouterModel(
    provider=provider,
    name="openai/gpt-4o-mini",
    allowed_models=available_models,
)

allowed_models is an inherited policy, not a provider catalog. An empty list denies every model, exact IDs allow only those models, provider patterns such as ["anthropic/**"] allow matching namespaces, and ["*"] explicitly permits all names. Model availability changes independently of package releases, so use the OpenRouter catalog when a concrete policy should mirror currently available models.

Project links

• Swarmauri SDK
• OpenRouter documentation
• Contributing guide