ZeroLLM is a lightweight, zero-configuration Python library designed to democratize AI access. It automatically discovers, validates, and routes your prompts to 100% free Large Language Models (LLMs) via OpenRouter, handling connection timeouts, cache fallbacks, and model rotation seamlessly.
Stop hardcoding model names. Just send your prompt, and let ZeroLLM handle the routing, caching, and retries under the hood.
- 🕵️ Auto-Discovery: Automatically fetches and filters the list of currently available completely free models (Prompt price = 0 & Completion price = 0).
- 🎲 Smart Rotation: Randomly rotates models to distribute load and maximize request success rates.
- 💾 Hybrid Caching: Remembers the last successful working model in-memory and caches it securely in a local JSON file to accelerate subsequent requests.
- 🛡️ Graceful Fallbacks: If writing to the disk fails (e.g. read-only environments like AWS Lambda), it automatically falls back to in-memory caching without crashing.
- 🔄 Intelligent Retry & Exclusion: If a selected model times out or returns an error, ZeroLLM immediately blacklists it for the active session and retries with a different working model.
- 📝 Flexible Inputs: Send direct text prompts (strings) or structured OpenAI-style lists of messages.
- ⚙️ Developer Friendly: Fallback to
OPENROUTER_API_KEYenvironment variables, custom title settings, and custom console logging.
Clone the repository and install it in editable mode:
git clone https://github.com/H55an/ZeroLLM.git
cd ZeroLLM
pip install -e .Important
Prerequisite: You must first obtain an API key from OpenRouter.ai. Creating an account and getting a key is free and takes less than a minute. Once obtained, you can either pass the key directly to the client or save it as an environment variable named OPENROUTER_API_KEY (highly recommended).
from zerollm import ZeroLLM
# The API key can also be automatically loaded from the OPENROUTER_API_KEY environment variable.
client = ZeroLLM(api_key="your_openrouter_api_key")
# You can pass a string directly!
response = client.chat("What is the speed of light?")
print(response)from zerollm import ZeroLLM
client = ZeroLLM() # Will read from OPENROUTER_API_KEY env variable
messages = [
{"role": "system", "content": "You are a helpful coding assistant."},
{"role": "user", "content": "Explain recursion in Python in one sentence."}
]
response = client.chat(messages, temperature=0.5)
print(response)If you want to see which free model was selected, when caching is triggered, and full retry logs, enable verbose=True:
from zerollm import ZeroLLM
client = ZeroLLM(verbose=True)
response = client.chat("Tell me a developer joke.")Contributions are welcome! If you have suggestions for new features, bug fixes, or enhancements, feel free to open an issue or submit a pull request.
This project is licensed under the MIT License - see the LICENSE file for details.