Universal LLM Connector

A Python SDK that provides a unified interface to all major LLM providers. Built on httpx for reliable HTTPS handling - system certificate support, custom base URLs, and async out of the box.

Problem Statement

Python developers face two recurring problems when working with LLM APIs:

1. No unified interface across providers. OpenAI, Anthropic, Google Gemini, Azure, AWS Bedrock, and others all have different request/response formats, auth methods, and endpoint patterns. Switching providers means rewriting integration code.

2. SSL certificate issues in managed environments. Python's HTTP libraries (requests, urllib3, httpx, aiohttp) use certifi - a static bundle of ~130 public CA certificates. If the OS trust store contains additional certificates, Python ignores them. Downloads, API calls through gateways, and pip installs from internal mirrors all fail with SSLError: certificate verify failed.

The existing solution (litellm) is built on requests (synchronous only, same SSL issues) and uses fragile model name decoding.

Solution

universal-llm-connector provides:

1. A unified API for 10 LLM providers (sync + async, streaming, embeddings, tool calling, vision)
2. corporate_fix() - configures Python to use the OS certificate store instead of certifi's static bundle
3. configure_huggingface() - patches huggingface_hub so transformers, diffusers, and accelerate use system certificates

Installation

Works on Windows, macOS, and Linux. Requires Python 3.10+.

pip install universal-llm-connector

With optional extras:

pip install universal-llm-connector[socks]       # SOCKS5 proxy support
pip install universal-llm-connector[bedrock]     # AWS Bedrock (SigV4 signing)
pip install universal-llm-connector[huggingface] # HuggingFace Hub patching
pip install universal-llm-connector[all]         # Everything

From source:

git clone https://github.com/rs2pydev/universal-llm-connector.git
cd universal-llm-connector
pip install -e ".[dev]"

Quick Start

Basic completion

from universal_llm_connector import completion

response = completion(
    model="openai/gpt-4o",
    api_key="sk-...",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
)
print(response.content)

Custom base URL (API gateways, self-hosted endpoints)

response = completion(
    model="openai/gpt-4o",
    base_url="https://your-gateway.example.com/v1",
    api_key="your-token",
    use_system_certs=True,
    messages=[{"role": "user", "content": "Hello!"}],
)

OpenAI Responses API

response = completion(
    model="openai/gpt-4o",
    api="responses",
    api_key="sk-...",
    input="Explain quantum computing in one sentence.",
    instructions="Be concise.",
)

Async

import asyncio
from universal_llm_connector import acompletion

async def main():
    response = await acompletion(
        model="openai/gpt-4o",
        api_key="sk-...",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(response.content)

asyncio.run(main())

Streaming

from universal_llm_connector import completion

for chunk in completion(
    model="openai/gpt-4o",
    api_key="sk-...",
    messages=[{"role": "user", "content": "Write a haiku."}],
    stream=True,
):
    print(chunk.content, end="", flush=True)

Embeddings

from universal_llm_connector import embed

response = embed(
    model="openai/text-embedding-3-small",
    input=["First sentence", "Second sentence"],
    api_key="sk-...",
)
vectors = response.embeddings

Tool calling

from universal_llm_connector import completion
from universal_llm_connector.models.messages import Tool, FunctionDef

weather_tool = Tool(
    function=FunctionDef(
        name="get_weather",
        description="Get weather for a city",
        parameters={
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    )
)

response = completion(
    model="openai/gpt-4o",
    api_key="sk-...",
    messages=[{"role": "user", "content": "Weather in Tokyo?"}],
    tools=[weather_tool],
)

Vision (multimodal)

response = completion(
    model="openai/gpt-4o",
    api_key="sk-...",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this image."},
            {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}},
        ],
    }],
)

Reusable client (connection pooling)

from universal_llm_connector import UniversalClient

with UniversalClient(
    base_url="https://your-gateway.example.com/v1",
    api_key="token",
    use_system_certs=True,
) as client:
    r1 = client.completion(model="openai/gpt-4o", messages=[...])
    r2 = client.completion(model="openai/gpt-4o-mini", messages=[...])
    embedding = client.embed(model="openai/text-embedding-3-small", input="hello")

SSL Certificate Fix

Python's certifi uses a static CA bundle that does not include certificates from the OS trust store. This causes SSL failures in environments where additional CAs are installed at the OS level.

Fix for all Python HTTP libraries

from universal_llm_connector import corporate_fix

corporate_fix()

This exports the OS certificate store to a PEM file and configures requests, urllib3, httpx, aiohttp, pip, and git to use it via environment variables and session patching.

Fix for HuggingFace

from universal_llm_connector import configure_huggingface

configure_huggingface()

from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")

Advanced configuration

corporate_fix(
    ca_bundle="/path/to/custom-ca.pem",
    proxy="http://proxy.example.com:8080",
    hf_endpoint="https://hf.example.com",
    hf_token="hf_xxxxx",
    pip_index_url="https://pypi.example.com/simple",
    verbose=True,
)

Supported Providers

All providers support custom base_url for self-hosted or gateway endpoints.

API Reference

completion() / acompletion()

embed() / aembed()

ChatResponse

EmbedResponse

Error Handling

from universal_llm_connector.exceptions import (
    AuthenticationError,    # 401/403
    RateLimitError,         # 429, includes retry_after
    ModelNotFoundError,     # 404
    ContextLengthError,     # Input too long
    NetworkError,           # Connection/timeout
    SSLCertificateError,    # Cert verification failed
    InvalidRequestError,    # 400
)

Development

git clone https://github.com/rs2pydev/universal-llm-connector.git
cd universal-llm-connector
pip install -e ".[dev]"

pytest                        # 81 unit tests
ruff check src/ tests/        # Lint
mypy src/                     # Type check
python -m build               # Build wheel + sdist

Requirements

• Python 3.10+
• httpx >= 0.27
• pydantic >= 2.0
• tenacity >= 8.0
• truststore >= 0.9
• certifi

License

MIT