llmshim
One interface, every LLM provider. The proxy server starts automatically — no setup needed.
Install
pip install llmshim
Configure
import llmshim
# Set API keys (writes to ~/.llmshim/config.toml — only needed once)
llmshim.configure(
anthropic="sk-ant-...",
openai="sk-...",
gemini="AIza...",
xai="xai-...",
openrouter="sk-or-...",
)
Or from the CLI: llmshim configure
Self-hosted servers (vLLM / SGLang)
vLLM and SGLang are configured via environment variables (not
config.toml) — the auto-spawned proxy inherits them from your Python
process. Set them before your first call:
import os
os.environ["VLLM_BASE_URL"] = "http://localhost:8000/v1"
os.environ["VLLM_API_KEY"] = "..." # optional
os.environ["SGLANG_BASE_URL"] = "http://localhost:30000/v1"
os.environ["SGLANG_API_KEY"] = "..." # optional
Then address them via the model string — vllm/<served-model> or
sglang/<served-model> (see the model table below).
Chat
import llmshim
resp = llmshim.chat("claude-sonnet-5-5", "What is Rust?")
print(resp["message"]["content"])
With options (all map to the API's provider-agnostic config):
resp = llmshim.chat(
"openai/gpt-6-sol",
"Explain quicksort",
max_tokens=500,
temperature=0.7,
top_p=0.9,
top_k=40,
stop=["\n\n"],
reasoning_effort="high",
)
With message history:
resp = llmshim.chat("claude-sonnet-5-5", [
{"role": "system", "content": "You are a pirate."},
{"role": "user", "content": "Hello!"},
], max_tokens=500)
Streaming
for event in llmshim.stream("claude-sonnet-5-5", "Write a poem"):
if event["type"] == "content":
print(event["text"], end="", flush=True)
elif event["type"] == "reasoning":
pass # thinking tokens
elif event["type"] == "usage":
print(f"\n[↑{event['input_tokens']} ↓{event['output_tokens']}]")
Multi-Model Conversations
Switch models mid-conversation. History carries over.
messages = [{"role": "user", "content": "What is a closure?"}]
r1 = llmshim.chat("claude-sonnet-5-5", messages, max_tokens=500)
print(f"Claude: {r1['message']['content']}")
messages.append({"role": "assistant", "content": r1["message"]["content"]})
messages.append({"role": "user", "content": "Now explain differently."})
r2 = llmshim.chat("gpt-6-sol", messages, max_tokens=500)
print(f"GPT: {r2['message']['content']}")
Reasoning / Thinking
Two provider-agnostic knobs control reasoning; both are clamped to the nearest tier the target model supports:
reasoning_effort—"none","low","medium","high","xhigh", or"max"reasoning_mode—"standard"(default) or"pro"(requests substantially more model work; native on OpenAI gpt-5.6/-pro, emulated as an effort bump elsewhere)
resp = llmshim.chat(
"claude-sonnet-5-5",
"Solve: x^2 - 5x + 6 = 0",
max_tokens=4000,
reasoning_effort="high",
reasoning_mode="pro",
)
print(resp["reasoning"]) # thinking content
print(resp["message"]["content"]) # answer
For full native control, bypass the unified mapping with a namespaced
provider_config (see below), e.g.
provider_config={"x-anthropic": {"thinking": {"type": "adaptive"}, "output_config": {"effort": "high"}}}.
Provider-Specific Controls (provider_config)
provider_config merges into the request root and carries anything the
unified config doesn't cover. Native provider controls MUST be namespaced
per provider (x-anthropic, x-openai, x-gemini, x-openrouter, x-vllm,
x-sglang); it also carries the top-level tools, response_format, and
reasoning_summary keys.
resp = llmshim.chat(
"anthropic/claude-sonnet-5-5",
"Solve this step by step: 17 * 23",
max_tokens=4000,
provider_config={
# native Anthropic adaptive-thinking control
"x-anthropic": {"thinking": {"type": "adaptive"}, "output_config": {"effort": "high"}},
},
)
OpenRouter routing preferences use the x-openrouter namespace:
resp = llmshim.chat(
"openrouter/anthropic/claude-sonnet-5",
"Hello",
max_tokens=200,
provider_config={"x-openrouter": {"provider": {"sort": "throughput"}}},
)
Tool Use / Function Calling
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}]
resp = llmshim.chat("claude-sonnet-5-5", "Weather in Tokyo?", max_tokens=500, tools=tools)
for tc in resp["message"].get("tool_calls", []):
print(f"{tc['function']['name']}({tc['function']['arguments']})")
Tools are accepted in OpenAI Chat Completions format and auto-translated to each provider's native format.
Fallback Chains
resp = llmshim.chat(
"anthropic/claude-sonnet-5-5",
"Hello",
max_tokens=100,
fallback=["openai/gpt-6-sol", "gemini/gemini-3.8-flash"],
)
Error Handling
Non-streaming errors (bad model, unknown provider, provider failures) raise
LlmShimError, which carries the API's structured error fields:
try:
llmshim.chat("unknown/model", "hi")
except llmshim.LlmShimError as e:
print(e.status_code) # 400
print(e.code) # "bad_request"
print(e.message) # human-readable message
Streaming errors that occur mid-stream instead arrive as an error event
(event["type"] == "error"); an HTTP error before the stream starts still
raises LlmShimError.
Types
Spec-faithful TypedDict definitions are available in llmshim.types (and the
common ones are re-exported at the top level) for static type-checking:
from llmshim.types import ChatResponse, StreamEvent, Message, Config
resp: ChatResponse = llmshim.chat("claude-sonnet-5-5", "hi")
Available: ChatRequest, ChatResponse, Config, Message, ToolCall,
Usage, ResponseMessage, ModelEntry, ModelsResponse, HealthResponse,
ErrorResponse, and the StreamEvent union (ContentEvent, ReasoningEvent,
ToolCallEvent, UsageEvent, DoneEvent, ErrorEvent).
Other
llmshim.models() # list available models
llmshim.health() # {"status": "ok", "providers": [...]}
How It Works
On first call, the package:
- Finds the
llmshimbinary (bundled, on PATH, or in repo) - Lets the child bind a random localhost port and reads its private startup record
- Pins the child's one-time TLS certificate, authenticates every request, and keeps a parent-liveness pipe open
- Server stops automatically when Python exits
No Docker, no background services, no manual server management.
Development
The unit tests under tests/ are fully mocked — they run a local HTTP server
returning canned JSON and SSE, so they need no API keys and make no real
provider calls:
pip install httpx pytest
pytest tests/
test_e2e.py is a separate LIVE suite that spawns the real binary and makes
billed provider calls; run it only when you deliberately want to hit real APIs.
Advertised Models
| Provider | Models |
|---|---|
| OpenAI | gpt-6-astra, gpt-6-sol, gpt-6-luna |
| Anthropic | claude-fable-5-1, claude-opus-5-5, claude-sonnet-5-5, claude-haiku-4-5-20251001 |
| Gemini | gemini-3.8-flash, gemini-3.5-flash-lite |
| xAI | grok-4.6 |
Call llmshim.models() for the live list filtered to your configured providers.
OpenRouter & self-hosted (vLLM / SGLang)
These providers are addressed by the model string plus environment variables — any model the upstream serves is reachable, so they aren't in the table above.
| Provider | Address as | Env vars | Native controls |
|---|---|---|---|
| OpenRouter | openrouter/<vendor>/<model> (e.g. openrouter/anthropic/claude-sonnet-5) |
OPENROUTER_API_KEY (or llmshim.configure(openrouter=...)) |
provider_config={"x-openrouter": {...}} (provider, models, transforms) |
| vLLM | vllm/<served-model> |
VLLM_BASE_URL (+ optional VLLM_API_KEY) |
provider_config={"x-vllm": {...}} |
| SGLang | sglang/<served-model> |
SGLANG_BASE_URL (+ optional SGLANG_API_KEY) |
provider_config={"x-sglang": {...}} |
1 maintainer
Metadata
1 maintainer
Release files for llmshim 0.18.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| llmshim-0.18.0.tar.gz | 2.0 MB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| llmshim-0.18.0-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details |
| llmshim-0.18.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | Python 3 | none | Linux glibc 2.17+ x86-64 | Details |
| llmshim-0.18.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details |
| llmshim-0.18.0-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details |
| llmshim-0.18.0-py3-none-macosx_10_12_x86_64.whl | Python 3 | none | macOS 10.12+ x86-64 | Details |
Total release size: 36.3 MB
Release files / llmshim-0.18.0.tar.gz
| Download URL | llmshim-0.18.0.tar.gz |
|---|---|
| Size | 2.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
399b95d7f4a881fb2f9010178ea89d01d2b6935173bf44852d574ccc8f6f1de1
|
|
BLAKE2b-256 checksum How to use checksums |
00199ebb4fd2f1b5db7501784f7e2075ce5c2c725e9f49ac6d67143ed8a6d90a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / llmshim-0.18.0-py3-none-win_amd64.whl
| Download URL | llmshim-0.18.0-py3-none-win_amd64.whl |
|---|---|
| Size | 7.1 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
5a2469863c7364f1594d5d71b87bd4802d185b46b958dfae5df5031122dbcf4c
|
|
BLAKE2b-256 checksum How to use checksums |
04ecb73614ca325423758437681887ac2d5823ee9b85dc0f5557eae58996fd07
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / llmshim-0.18.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | llmshim-0.18.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 7.1 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
06e5aa61dd6d73958b6bf4da74c95567d8451fc981f4ba1d9bae819424e19390
|
|
BLAKE2b-256 checksum How to use checksums |
0796b2b3b417fed0c21f67ac6ea90529b2fd93c0ecf86ec9d6f425f5a5519809
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / llmshim-0.18.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | llmshim-0.18.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 6.7 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
8528f807f96c631d5ae69eeb4bb12682d0c68d285fb4f75ab9ec2feb5f4b6f83
|
|
BLAKE2b-256 checksum How to use checksums |
bf821937818a590a2ad5f2b6532d14c2a426909dca0978cc488e16fbe73e2ff8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / llmshim-0.18.0-py3-none-macosx_11_0_arm64.whl
| Download URL | llmshim-0.18.0-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 6.6 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b36535f5ef6f513a97fb2eb69e20cb7095ac690ede7ddea17ca54e4970787d87
|
|
BLAKE2b-256 checksum How to use checksums |
78d97312988cfe19f6b2a5a8db29f8dcdfaade63a4cce1a9e7e91b0d9707a463
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / llmshim-0.18.0-py3-none-macosx_10_12_x86_64.whl
| Download URL | llmshim-0.18.0-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 6.9 MB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
dc814c015d7aa2e02fd265dd21dba0bb26ce8e5bbace73561cd5b16119e77807
|
|
BLAKE2b-256 checksum How to use checksums |
f2c5594f868aea095098f3a345453fcf10e09c451abdfee3392b45b22d1aa9f5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency log
