Configuring AI model providers for BoardPulse AI

BoardPulse AI supports three model provider modes: cloud for OpenAI-compatible APIs, local for Ollama running on your own hardware, and mock for deterministic test responses that require no API key. You can set a default provider in .env and override it per request — a useful pattern when you want most queries to use a cheaper local model but need cloud quality for specific tasks.

Provider modes at a glance

Mode	Requires	Best for
`mock`	Nothing	Local development, CI, schema validation
`cloud`	OpenAI API key (or compatible)	Production, highest accuracy
`local`	Ollama running and reachable	Air-gapped deployments, cost control

How routing works

The ModelRouter resolves the backend for each request using this priority order:

Explicit request override — if the request includes preferred_provider: "cloud", "local", or "mock", that takes precedence (subject to the provider being configured and available).
hybrid shortcut — requests with preferred_provider: "hybrid" try Ollama first, then fall back to cloud if Ollama is not enabled.
DEFAULT_MODEL_PROVIDER — if no per-request override is set and the default is not mock, the default is used.
Auto-detect — if DEFAULT_MODEL_PROVIDER=mock and no override is given, the router checks whether Ollama is enabled or an OpenAI key is present and uses whichever is available.
Mock fallback — if nothing is configured, responses fall back to mock automatically.

A preferred_provider of "local" only resolves to Ollama if OLLAMA_ENABLED=true. A preferred_provider of "cloud" only resolves to cloud if OPENAI_API_KEY is set. Otherwise the router falls through to the next option.

Configuration by provider

Mock
Cloud (OpenAI-compatible)
Local (Ollama)

Mock mode returns deterministic, pre-built SQL responses without calling any AI model. It is the default out of the box and requires no credentials.

DEFAULT_MODEL_PROVIDER=mock

Mock responses always generate a SELECT * FROM <first_approved_table> LIMIT 10 query. Use mock mode to:

Verify your database connection and table allowlist are working
Run integration tests in CI without API costs
Explore the BoardPulse AI interface before choosing a real provider

Start every new deployment in mock mode. Once you’ve confirmed that queries return data from your source database, switch to cloud or local.

Cloud mode sends requests to any OpenAI-compatible API. By default this is OpenAI’s API, but you can point OPENAI_BASE_URL at any compatible endpoint — Azure OpenAI, Groq, Mistral, a local LiteLLM proxy, or others.

DEFAULT_MODEL_PROVIDER=cloud
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4.1-mini
OPENAI_BASE_URL=https://api.openai.com/v1

OPENAI_API_KEY

string

required

Your API key for the OpenAI-compatible provider.

OPENAI_MODEL

string

default:"gpt-4.1-mini"

Model name to use. Must be a model available on the endpoint specified by OPENAI_BASE_URL.

OPENAI_BASE_URL

string

default:"https://api.openai.com/v1"

Base URL of the OpenAI-compatible API. Change this to use a different provider.

Example: using a different OpenAI-compatible provider

DEFAULT_MODEL_PROVIDER=cloud
OPENAI_API_KEY=your-provider-key
OPENAI_MODEL=mixtral-8x7b-32768
OPENAI_BASE_URL=https://api.groq.com/openai/v1

Any provider that implements the OpenAI chat completions API (/v1/chat/completions) works with BoardPulse AI. You are not limited to OpenAI.

Local mode sends requests to an Ollama instance running on your own infrastructure. No data leaves your network.

DEFAULT_MODEL_PROVIDER=local
OLLAMA_ENABLED=true
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_MODEL=qwen3:8b

OLLAMA_ENABLED

boolean

default:"false"

Must be true to enable the local provider. If false, requests that specify preferred_provider: "local" will fall through to the next available provider.

OLLAMA_BASE_URL

string

default:"http://ollama:11434"

URL of your Ollama server. Inside Docker Compose, use the service name ollama. For an external Ollama instance, use its hostname or IP address.

OLLAMA_MODEL

string

default:"qwen3:8b"

Ollama model tag to use. The model must already be pulled on the Ollama server before BoardPulse AI starts.

Before starting the stack, pull the model on your Ollama server:

ollama pull qwen3:8b

Example: external Ollama server

DEFAULT_MODEL_PROVIDER=local
OLLAMA_ENABLED=true
OLLAMA_BASE_URL=http://192.168.1.50:11434
OLLAMA_MODEL=qwen3:8b

qwen3:8b is the recommended default for SQL generation tasks. Larger models generally produce more accurate SQL but require more VRAM and respond more slowly.

Switching providers at runtime

You can override the provider on a per-request basis using the preferred_provider field in the API request body. This lets you run most queries through a fast local model and escalate specific queries to cloud when needed — without changing .env or restarting the stack.

{
  "message": "What were total sales by region last quarter?",
  "preferred_provider": "cloud"
}

Valid values for preferred_provider: "mock", "cloud", "local", "hybrid".

Get Started

Configuration

Core Features

Deployment

Configuring AI model providers for BoardPulse AI

Provider modes at a glance

How routing works

Configuration by provider

Switching providers at runtime

Build docs developers (and LLMs) love

Get Started

Configuration

Core Features

Deployment

Documentation Index

​Provider modes at a glance

​How routing works

​Configuration by provider

​Switching providers at runtime

Build docs developers (and LLMs) love

Provider modes at a glance

How routing works

Configuration by provider

Switching providers at runtime