AI Provider

Description

An AI Provider is a named connection to a language-model endpoint: provider type, base URL, model name, API key, timeout and temperature. Objects are managed in the Metadata perspective and stored as JSON under:

metadata/ai-provider/

Use Refresh models to load model ids from the provider (OpenAI-compatible /models, Anthropic and Mistral catalogs, Ollama /api/tags). Hugging Face has no list API; type a router model id. The combo stays editable so you can enter a name that is not in the list.

Use the Test button in the editor to send a short health-check prompt.

The AI Assistant uses these objects as the credential source of truth. Global configuration only stores the enable flag and the default provider name.

Do not paste a live API key into this metadata object. Set ${AI_API_KEY} (or a similar name containing PASSWORD, SECRET or TOKEN) in an environment configuration file, or better a variable resolver expression such as #{vault:secret/data/ai:api-key}. The same pattern applies to every other secret in the project: never hard-code it in pipelines, workflows or metadata. See Secrets and personal information.

The Language model chat transform can optionally select a named AI Provider. Connection fields from the provider overlay the transform’s inline values; empty provider fields keep the inline values. Input/output mapping, mock mode, proxy and retries stay on the transform.

Provider types

Type Default base URL Default model API key

Type	Default base URL	Default model	API key
OpenAI	`https://api.openai.com/v1`	`gpt-4o-mini`	Yes
Grok (xAI)	`https://api.x.ai/v1`	`grok-4`	Yes
Gemini (OpenAI-compatible)	`https://generativelanguage.googleapis.com/v1beta/openai`	`gemini-2.5-flash`	Yes
Custom (OpenAI-compatible)	(you set it)	(you set it)	Usually
Anthropic	(plugin default)	`claude-3-5-sonnet-20241022`	Yes
Ollama	`http://localhost:11434`	`llama3.2`	No
Mistral	`https://api.mistral.ai/v1`	`mistral-small-latest`	Yes
Hugging Face	Dedicated inference endpoint URL, if you use one. Leave empty for the public inference router.	Router model id (for example `meta-llama/Llama-3.3-70B-Instruct`), or a dedicated endpoint URL if Base URL is empty	Yes (token)

OpenAI

https://api.openai.com/v1

gpt-4o-mini

Yes

Grok (xAI)

https://api.x.ai/v1

grok-4

Yes

Gemini (OpenAI-compatible)

https://generativelanguage.googleapis.com/v1beta/openai

gemini-2.5-flash

Yes

Custom (OpenAI-compatible)

(you set it)

Usually

Anthropic

(plugin default)

claude-3-5-sonnet-20241022

Yes

Ollama

http://localhost:11434

llama3.2

Mistral

https://api.mistral.ai/v1

mistral-small-latest

Yes

Hugging Face

Dedicated inference endpoint URL, if you use one. Leave empty for the public inference router.

Router model id (for example meta-llama/Llama-3.3-70B-Instruct), or a dedicated endpoint URL if Base URL is empty

Yes (token)

OpenAI, Grok, Gemini and Custom share the OpenAI Chat Completions API. A GitHub Copilot-style OAuth provider is an extension point; it is not bundled.

Options

Option Description

Option	Description
Provider	Plugin implementation (OpenAI, Grok, …)
Base URL	Override the type’s default endpoint. Variables such as `'${AI_BASE_URL}'` are resolved at send time. For Hugging Face, a URL here is used as the dedicated inference endpoint when Model name is empty.
API key	Secret stored as a Hop password field. Not sent in advisor prompts. Prefer `${AI_API_KEY}` from an environment file or a keystore resolver expression, not a pasted key.
Model name	Model identifier for the chosen provider. Refresh models fills the combo from the live catalog when the provider supports it. For Hugging Face, a model id is sent to the inference router; an `http(s)` URL is called as a dedicated endpoint. If this field is empty, Base URL is used instead.
Models per role	Optional. One model for each role this provider serves, so a single provider can back a chat transform and an embedding transform at the same time. See below.
Timeout (seconds)	HTTP timeout for completions.
Temperature	Sampling temperature, when the provider supports it.

Provider

Plugin implementation (OpenAI, Grok, …)

Base URL

Override the type’s default endpoint. Variables such as '${AI_BASE_URL}' are resolved at send time. For Hugging Face, a URL here is used as the dedicated inference endpoint when Model name is empty.

API key

Secret stored as a Hop password field. Not sent in advisor prompts. Prefer ${AI_API_KEY} from an environment file or a keystore resolver expression, not a pasted key.

Model name

Model identifier for the chosen provider. Refresh models fills the combo from the live catalog when the provider supports it. For Hugging Face, a model id is sent to the inference router; an http(s) URL is called as a dedicated endpoint. If this field is empty, Base URL is used instead.

Models per role

Optional. One model for each role this provider serves, so a single provider can back a chat transform and an embedding transform at the same time. See below.

Timeout (seconds)

HTTP timeout for completions.

Temperature

Sampling temperature, when the provider supports it.

When Language Model Chat points at an AI Provider, extra transform options (proxy, retries, mock, I/O fields) are not taken from the provider.

Models per role

A provider endpoint usually serves more than one kind of model. The same OpenAI key reaches a chat model and an embedding model; the same Ollama server serves both, and a reranker besides. Models per role lets one provider object cover all of them, so the base URL and the API key are configured once.

Each row pairs a role with a model name:

Role Used by

Role	Used by
`CHAT`	Conversation and completion, for example Language Model Chat, the AI Advisor and Structured extract.
`EMBEDDING`	Turning text into a vector, for example Embed text.
`SCORING`	Scoring a passage against a query, used by rerankers.
`IMAGE`	Image generation.
`MODERATION`	Content moderation.

CHAT

Conversation and completion, for example Language Model Chat, the AI Advisor and Structured extract.

EMBEDDING

Turning text into a vector, for example Embed text.

SCORING

Scoring a passage against a query, used by rerankers.

IMAGE

Image generation.

MODERATION

Content moderation.

A transform never asks which role to use: it needs one kind of model and looks up that role. Point a chat transform and an embedding transform at the same provider and each finds its own model.

Use at most one row per role, since that is what makes the lookup unambiguous. A transform that needs a different model than the provider’s default for its role can override it on the transform itself.

Relationship to Model name

Model name above is the chat model, and it stays that way. A provider with no rows in this table behaves exactly as before: CHAT falls back to Model name, and nothing else resolves.

The fallback is deliberately limited to CHAT. Handing a chat model to an embedding endpoint fails inside the provider with a message that is hard to act on, so a provider with no EMBEDDING row reports that plainly instead.