Guides

Choosing models

Every NPC answers on some Provider and some Model. A Village can mix them freely — Claude for one NPC, a model on your own machine for another — and there are three ways an NPC gets its model, in this order:

Its own Provider and Model, named on the NPC.
A Level — Beginner, Advanced, Expert or Ultra — each of which the Operator maps to a Provider and Model in Settings.
The Village default, for an NPC that names neither.

Providers

A Provider is somewhere models run. Every Village starts with Anthropic and OpenAI, which read their keys from ANTHROPIC_API_KEY and OPENAI_API_KEY in the root .env. The Operator can add any OpenAI-compatible server in Settings → Providers: a model on this machine (Ollama, LM Studio), one on the LAN or a GPU box (vLLM), or a hosted gateway (OpenRouter, Groq, Together). See Using local models.

A key pasted in Settings is encrypted at rest and never shown again. On the two built-in Providers it replaces the .env key; Use .env key goes back to it.

Set the Village default

Open Settings. The first card is Default model. Pick a Provider, type or pick a Model, and save.

Only the Operator can save this. Every Player can see it, because an NPC form has to show what "inherit" currently resolves to; a Player who is not the Operator sees the controls disabled and no save button. The route behind the card is GET /api/settings to read and PATCH /api/settings to write, and a write from anyone but the Operator is refused with NOT_OPERATOR.

Changing the default takes effect on the next Message. You do not edit any NPC.

Levels

Model Levels, the second card, has four slots: Beginner, Advanced, Expert and Ultra, cheapest and least capable first. The Operator maps each one to a Provider and Model — a small local model at Beginner and a frontier model at Ultra is the usual shape — and an NPC says which Levels it works at.

One Level: the NPC always answers on that Level's model.
Several Levels: each Player message is routed. One short call to the Beginner model rates how hard the message is, and the NPC answers on the smallest of its Levels that is at least that hard. Easy questions cost what the cheap model costs; hard ones get the capable model.
No Levels: the NPC uses the Village default.

A Level the Operator left unmapped falls back to the next mapped Level below it, then to the Village default. Routing never blocks a reply: if the rating call fails, or its answer is not a Level, the NPC answers at its lowest Level.

The Player can override the router for one message: an NPC with more than one Level shows a Level select next to Send, set to Auto by default. Every reply produced at a Level carries a badge naming it, and the badge survives a reload (message.level).

In a Party the message is rated once and every speaker is clamped to its own Levels, so a rating costs one call per Player message, not one per NPC.

Provider and Model move together

The pair is stored as npc.provider and npc.model, and AgentsVille treats it as one value. Either both are set or both are null — a Model id only means something to the Provider that issued it, so a half-set pair is refused with "Choose a provider and a model together, or inherit both". The same rule applies to the Village default: defaultProvider and defaultModel are saved together or cleared together.

Give one NPC its own model

Open an NPC's edit form. The Provider select offers Levels or the Village default, which shows the default model it currently resolves to, and then every Provider the Village has.

Leave it on the first option and both columns stay null; the Levels chips below choose which Levels the NPC works at. Pick a Provider instead and the Levels disappear: an NPC with its own model always uses it.

The Model box is free text with suggestions. For Anthropic and OpenAI they come from AgentsVille's catalogue (GET /api/models); for any other Provider, from that Provider's own /models endpoint (GET /api/providers/:id/models), so an Ollama suggests exactly the models it has pulled.

Use a Model AgentsVille has not heard of

Nothing validates what you type against a list, on the NPC form, on a Level or on the Village default. A Provider that ships a new model this morning is usable this morning:

If you type an id the Provider does not recognise, the refusal comes from the Provider when the NPC next answers, not from AgentsVille.

What happens when a model is unavailable

An NPC whose Provider has no key — or, for an OpenAI-compatible Provider, no address — is refused before the reply stream opens, with a 400 and the code PROVIDER_NOT_CONFIGURED, and the message names the Provider. You get a plain failure rather than an error buried inside a half-written reply.

An NPC that has no model of its own, no mapped Level and no Village default to fall back on is refused the same way, with NO_MODEL_CONFIGURED. In a Party, a later speaker with no usable model ends the exchange with a line saying it cannot answer, instead of breaking the stream.

Thinking level

The same form carries a Thinking select, stored as npc.thinking:

Off — the default
Brief, Moderate, Thorough

Thinking is per NPC, not per Village, and it is off by default because it costs tokens on every Message and not every model supports it. Each level maps to the Provider's own reasoning control, so the meaning of "Thorough" depends on which Provider the NPC runs on. OpenAI-compatible servers have no common switch for it, so the setting has no effect there; a model that reasons by default still shows its reasoning.

What you get for it is described in Reading thinking and tool calls.