What you are building

A risk verdict attached to every submitted query, so a reviewer opens their queue and sees a score, a level and an explanation rather than a wall of raw SQL. It does not decide anything on its own — a human still approves — but it turns "read this and judge it" into "check whether I agree".

Do I have to send my queries to a third party?

No. Anthropic and OpenAI are hosted options, but Ollama runs models on your own hardware and the OpenAI-compatible option covers anything speaking that protocol — vLLM, LM Studio, a local text-generation server. What is sent is the SQL, the database type, and optionally schema names; never query results.

You can have more than one. Configurations are not one-per-organization. Create as many as you need — a cheap fast model for one datasource, something stronger for another — and bind each datasource to one of them. Adding a fallback priority turns the set into a pool that fails over when a provider is unavailable.

1. Create the configuration

Admin section → AI configurations → Add AI configuration. The wizard is three steps: Provider, Connection, Test.

Provider	Default model	API key
Anthropic	`claude-sonnet-4-20250514`	Required
OpenAI	`gpt-4o`	Required
Ollama	`llama3.1:70b`	Not used — set the endpoint to your server
Hugging Face	`meta-llama/Llama-3.3-70B-Instruct`	Optional — needed for the hosted router, not for a local server
Custom (OpenAI-compatible)	You supply one	Optional

Picking a tile pre-fills the model and, where relevant, the endpoint. On the Connection step, give the configuration a name you will recognise in a dropdown later, then set the model and the key.

Three limits are required and pre-filled sensibly: Timeout (ms), Max prompt tokens and Max completion tokens. They are two separate token budgets, not one — the prompt budget bounds how much schema context can be sent, the completion budget bounds the answer.

The final step sends a test prompt. Do it: a wrong key or an unreachable endpoint is far easier to diagnose here than as a stream of failed analyses later.

The AI configuration creation wizard showing the connection step with model, endpoint, API key and token limit fields. — The AI configuration wizard — provider, then connection details, then a live test prompt.

ENCRYPTION_KEY has to be set properly. API keys are encrypted with it before storage. It must be a 32-byte value as 64 hex characters, and the application will not start without one — but if you are running the zero-config demo stack, yours is the committed insecure default. Generate a real one before storing a real provider key.

2. Turn it on for a datasource

Analysis is enabled per datasource, not globally. Open the datasource's settings, and on the Configuration tab switch on Enable AI analysis and pick your configuration under AI configuration.

The two go together: switching analysis on without choosing a configuration is rejected with a message telling you exactly that. The same applies to text-to-SQL, which lets people describe a query in plain English and uses the same configuration to draft it.

Submit a query against that datasource and it now passes through Pending AI before reaching a reviewer, arriving with a risk score, a level of Low, Medium, High or Critical, a summary and a list of issues.

Analysis becomes a gate on submission. Once a datasource has AI analysis enabled, the editor requires the submitter to run Analyze before the submit button becomes available. This surprises people the first time — it is the most common reason a submission appears stuck.

3. Know what happens when it fails

An AI outage does not let queries through. When a provider is unreachable, over budget, rate-limited, or returns something unparseable, AccessFlow records the analysis as Critical at the maximum risk score, with the failure reason as the reviewer-facing summary. The query goes to a human with a loud marker on it — it is never quietly approved.

If you configured a fallback pool, the other configurations are tried before it comes to that. Turning analysis off for a datasource is different again: queries simply skip the AI step and proceed to review with no verdict, and no analysis record is written.

Two guardrails are worth setting before you point this at a busy instance. ACCESSFLOW_AI_RATE_LIMIT_REQUESTS_PER_MINUTE defaults to 30, and ACCESSFLOW_AI_RATE_LIMIT_TOKENS_PER_MONTH defaults to unlimited — set the latter if you would rather hit a ceiling you chose than one your provider's billing chooses for you.

4. Adjust the prompt, if you need to

The built-in prompt is a reasonable default. Where your organization has rules the model cannot infer — naming conventions that mark sensitive tables, a compliance regime, a house style for what counts as high risk — the System prompt field takes an override. Use Load / reset to default to start from the built-in one rather than from scratch.

A custom prompt must contain {{sql}}. Without it the query never reaches the model and the save is rejected. Six placeholders are substituted in total — {{sql}}, {{db_type}}, {{schema_context}}, {{rag_context}}, {{cost_estimate}} and {{language}} — and any of them may resolve to a "not available" note, so write a prompt that reads sensibly when they do.

The response has to come back as JSON matching the expected shape. If it does not, AccessFlow treats it as a failed analysis rather than guessing, which is the behaviour described above. Keep that in mind when instructing the model about its output.

5. See what it is doing

AI analyses in the admin section charts risk over time, the issue categories coming up most often, the most active submitters, and token cost and latency per model. It is the page that tells you whether your prompt is working and what the feature is costing you.

Anomalies is a separate, complementary thing: rather than scoring one query, it watches each person's pattern of activity and flags deviations — unusual volumes, access at odd hours. Anomalies are acknowledged or dismissed from that page.

The AI analyses dashboard showing risk score over time, top issue categories, top submitters and token cost per model. — `/admin/ai-analyses` — risk trends, issue categories, and what the analysis is costing per model.

Going further

A knowledge base. Switching on retrieval-augmented generation (RAG) within a configuration lets you add documents — data dictionaries, internal policy — that are retrieved and injected into the analysis, so the model knows things about your schema that the schema itself does not say. Add the documents after saving the configuration.
Tracing. Connecting Langfuse records a trace for every analysis and can serve the prompt itself, so prompt changes become versioned rather than typed into a form.
Acting on the verdict automatically. Once you trust the scores, routing policies can auto-approve low-risk reads or demand extra approvals on anything critical — which is where the AI stops being advisory and starts saving reviewers time.

Every field, the default prompt in full, and the RAG and Langfuse reference: AI.