Alias-first LLM routing with lockfiles
llmring decouples code from model IDs. Instead of hardcoding “gpt-4o”, you use aliases like “fast” or “smart” that resolve through a lockfile—like package managers pin dependencies.
Project resources
- Main site: https://llmring.ai - Documentation and guides
- Registry: https://llmring.github.io/registry/ - Live model capabilities and pricing
- Source: https://github.com/juanre/llmring - Python package
Core architecture
The system has three independent layers:
- Lockfile (
llmring.lock) - Local alias bindings, version-controlled with your code - Registry - Public model database, versioned per provider, human-curated daily
- Receipts - Cryptographic audit trail (optional, requires server)
Your Code → Alias ("fast") → Lockfile → Registry validation → Provider
↓ ↓ ↓
Task identity Git-tracked Versioned truth
Why aliases matter
Models change. Prices change. New models appear. When you hardcode “gpt-4o-mini” everywhere, updates require code changes. With aliases, you change the lockfile:
# llmring.lock - your configuration
[aliases.default]
fast = "openai:gpt-4o-mini" # $0.15/1M input
smart = "anthropic:claude-3-5-sonnet-latest" # Better at reasoning
[aliases.prod]
fast = "openai:gpt-4o" # Faster in production
Your code stays clean:
# Code doesn't know or care which model runs
response = await ring.chat_with_alias("fast", messages=[...])
The lockfile pattern
Like package-lock.json or Pipfile.lock, but for LLMs:
- Reproducible: Same aliases resolve to same models
- Versionable: Track configuration changes in git
- Profile-aware: Different models for dev/staging/prod
- Constraint-based: Set cost or context requirements
# Initialize with smart defaults based on your API keys
llmring lock init
# Bind an alias with constraints
llmring bind smart "anthropic:*" --min-context 100000 --max-cost 10.0
# Validate against registry
llmring lock validate
Registry as source of truth
The registry tracks what models actually exist, their prices, and capabilities. It’s versioned per provider so you can detect drift:
- Registry v42 says gpt-4o costs $5/1M
- Registry v43 says gpt-4o costs $2.50/1M
- Your lockfile pinned v42 → you know prices changed
This isn’t true reproducibility (providers control actual behavior), but it enables drift detection.
Installation
uv add llmring
# or
pip install llmring
What makes this different
- Not a proxy - Direct provider connections, no middleman
- Not a framework - Just routing and receipts, compose with anything
- Not vendor lock-in - Works fully offline with just the lockfile
- Not a database - Optional server only stores aliases and receipts
The lockfile is always authoritative. The registry provides truth. Receipts prove what happened.
Version
llmring v0.3.0 - Supersedes llmbridge-py