LLM tiers

TulipFarm talks to language models through a single adapter (the Vercel AI SDK). It ships four provider integrations — Anthropic, OpenAI, Azure Foundry, and any OpenAI-compatible endpoint (which covers gateways like OpenRouter, Together, and Groq through their compatible APIs). You do not wire a model into each agent. Instead you define tiers, and the runtime picks a tier per turn.

Three tiers

Every instance configures three tiers, from cheapest and fastest to most capable:

These are recommended models, not enforced defaults — each tier needs at least one provider and model assigned before agents can run. The tier configuration lives in soul/llm.config.yaml and is edited through Settings → LLM in the web UI. Each tier is an ordered list of providers — and the order is the fallback chain.

Fallback chains

A tier can list more than one provider. The runtime tries the first; if that provider fails, it walks down the list to the next. This is why a tier is an ordered list rather than a single model: you can put a primary provider first and a backup beneath it, and a provider outage degrades to the backup instead of failing the turn.

Automatic tier selection

A turn does not have to name a tier. With model: auto, TulipFarm picks one from context. The starting point is the agent's autonomy:

An agent with no autonomy set starts at standard. Two adjustments then apply on top:

• Tasks flagged as decisions escalate to complex.
• A quick turn is bumped to standard when tools are in scope.

A single request can also override the model for that turn without changing the stored configuration.

Credentials

A provider entry references its API key with an api_key_ref field. Two forms are accepted:

• env://VAR_NAME — reads directly from the environment variable VAR_NAME.
• A bare name like anthropic-api-key — resolved from the secrets store at runtime and cached after first use.

Keys never live in the LLM config file itself. A provider must have its credentials configured in Settings → Secrets before it can be selected in a tier — see Configure LLM providers.