Research CommonsResearch Commons
llm-rotate/Quickstart

Quickstart

Configure llm-rotate and make your first resilient LLM call in under a minute.

This walks through the fastest path to a working call: set your keys as environment variables, call configure() once, then use the lm singleton anywhere in your app.

1. Set your API keys

llm-rotate never stores secrets. Keys are referenced by URI (env://VAR) and resolved at call time, so export them into the environment:

export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."

2. Configure once

Call configure() before the first use of lm. It takes a registry of keys and the subset you want active.

app/bootstrap.py
from llm_rotate import configure
 
configure(
    registry={
        "keys": [
            {
                "key_id": "openai-1",
                "provider": "openai",
                "secret_ref": "env://OPENAI_API_KEY",
                "models": ["gpt-4o-mini"],
            },
            {
                "key_id": "gemini-1",
                "provider": "google_ai_studio",
                "secret_ref": "env://GOOGLE_API_KEY",
                "models": ["gemini-2.0-flash"],
            },
        ]
    },
    use_keys=["openai-1", "gemini-1"],
)
Configure exactly once

Using lm before configure() raises ConfigurationError. Calling configure() twice also raises — initialise it at process startup. For tests, llm_rotate.reset_singleton() clears the state.

3. Make a call

The lm singleton mirrors the LMRotate API. Provider is inferred from the model name, so you usually don't pass it.

from llm_rotate import lm
 
response = await lm.chat(
    "gpt-4o-mini",
    [{"role": "user", "content": "Write a haiku about rotating keys."}],
)
 
print(response.content)
print(response.provider, response.key_id, response.latency_ms)

chat() returns a ChatResponse with the text plus metadata about which provider and key actually served the request.

4. (Optional) prefer a direct instance

If you'd rather avoid the module-level singleton — for example in a library or a test — build an LMRotate instance directly:

from llm_rotate import LMRotate, configure_from_dict
 
config = configure_from_dict(
    registry={"keys": [...]},
    use_keys=["openai-1"],
)
rot = LMRotate(config)
 
response = await rot.chat("gpt-4o-mini", [{"role": "user", "content": "Hi"}])
await rot.close()

Next steps