Models, keys and limits
Choosing a model
Section titled “Choosing a model”Every bubble has its own model. It starts on the default model you set on the Models page, and you can change it in the bubble’s inspector: provider, model, key and reply format. Favourite models and per-role defaults for a project live on the Models page too.
OpenRouter and NVIDIA accept any model name you type, so a model that is not in the list yet can still be used.
For adding keys and where they are stored, see Add a provider key.
A pool is an ordered list of up to eight models (and up to eight keys) that a bubble uses as one. When the model in use is rate-limited, down, or keeps sending answers it cannot read, the pool moves on to the next entry.
- Batch (the default), cycle and proportional decide how entries are picked.
- A failed entry rests for ten minutes before it is tried again.
- A pass waits at most eight minutes in total for a free entry, and tells you when it has been waiting.
On free tiers, pools help most. Put two or three free models in one pool, and a bubble keeps working when one of them is out of requests.
Rate limits
Section titled “Rate limits”Perfica tracks requests per minute and per day for each model and key, and spaces calls so a bubble does not trip the provider’s limit.
It works out each limit in this order:
- what you typed on the Limits page,
- what the provider’s rate-limit refusals have taught it,
- the published limits it ships with (for example, OpenRouter’s free models at 20 a minute and 50 a day, and Google’s free tier).
Local models (Ollama, LM Studio) have no limit.
When a limit is reached
Section titled “When a limit is reached”- A refusal that says how long to wait makes the loop pause, then resume on its own after that wait.
- When a day’s allowance is spent, a single-model bubble stops and waits for you to press Play. A pool skips that entry instead.
- None of this spends the loop’s error caps.
When a provider is down
Section titled “When a provider is down”Dropped connections and server errors are retried three times, a few seconds apart. If the provider is still down, the loop pauses on the same bubble and waits for Play.
The Usage tab shows tokens and cost per run, from the provider’s own token counts. A model the price list does not cover shows as not priced, never as $0. Local Ollama models count as free.
Images
Section titled “Images”A bubble can be shown images: pasted into a Manager message or a task card, or read from the project. If its model cannot see, the loopspace’s vision model describes the image instead. Set it on the Models page under Helper models. Without one, a blind model stops with a notice rather than guessing what the picture shows.