llm-provider-adapter

llm-provider-adapter is a small, synchronous Python library for calling LLM chat providers through one stable request, response, retry, error, and telemetry contract.

Version 0.1 supports OpenAI, Claude, DeepSeek, OpenRouter, and LiteLLM. It does not provide an Agent framework, persistence, secret storage, async calls, streaming, multimodal content, or automatic cross-provider fallback.

Install

Python 3.11 or newer is required. Install only the provider SDK you need:

pip install "llm-provider-adapter[openai]>=0.1.0,<0.2.0"
pip install "llm-provider-adapter[claude]>=0.1.0,<0.2.0"
pip install "llm-provider-adapter[deepseek]>=0.1.0,<0.2.0"
pip install "llm-provider-adapter[openrouter]>=0.1.0,<0.2.0"
pip install "llm-provider-adapter[litellm]>=0.1.0,<0.2.0"

Use [all] only when an application must expose every adapter. The core distribution imports without any provider SDK.

Minimal chat

Credentials, model IDs, and endpoints are always explicit. The library never reads environment variables or persists secrets.

from llm_provider_adapter import ChatRequest
from llm_provider_adapter.providers import OpenAIProvider

provider = OpenAIProvider(api_key="...")
response = provider.chat(
    ChatRequest(
        model="gpt-5-mini",
        messages=[{"role": "user", "content": "Return one short greeting."}],
        timeout_seconds=30,
    )
)
print(response.content)

No real request is made when using the fake example:

python examples/fake_chat.py

Tool calling

Tools use the OpenAI function-tool shape at the public boundary. Provider adapters translate it when required and normalize returned calls into ToolCall(id, name, arguments).

request = ChatRequest(
    model="gpt-5-mini",
    messages=[{"role": "user", "content": "Weather in Shanghai?"}],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "weather",
                "description": "Read weather for a city.",
                "parameters": {
                    "type": "object",
                    "properties": {"city": {"type": "string"}},
                    "required": ["city"],
                },
            },
        }
    ],
    tool_choice="auto",
)

Unsupported capabilities fail before the SDK request when possible. Parameters are never silently discarded to make a request succeed.

Errors, retries, and timeout

• RetryPolicy owns one bounded retry loop; SDK/LiteLLM retries are disabled.
• Authentication, invalid request, capability, and context-limit failures do not retry.
• Any recognized timeout, including an SDK-default timeout when the request omits timeout_seconds, is never automatically replayed because the upstream may already have accepted or billed the request.
• The library never changes provider automatically.
• Public errors and retry records omit raw SDK exception text, payloads, headers, credentials, and response bodies.

Catch LLMProviderError for normalized provider failures and MissingProviderExtraError when the selected optional SDK is absent.

Telemetry

Pass an object implementing TelemetryObserver.on_event(event) to a provider. Request, response, retry, and error events include provider/model identifiers, counts, status classifications, request IDs, and normalized usage only. They do not include messages, tool arguments, headers, raw payloads, arbitrary request metadata, or raw exception text. Observer failures never change the chat call.

Documentation

• Provider support
• Configuration
• Security
• Compatibility
• Migration from Taskweavn
• Release process

Development

uv sync --all-extras --all-groups
uv run ruff check .
uv run mypy src tests
uv run pytest -q
uv build
uv run twine check dist/*

The project is licensed under the MIT License.