10.05 Configuring AI Providers

Requires: AI Extra

Provider configuration, API key storage, and per-provider call dispatch all live in the AI Extra at simplerisk/extras/artificial_intelligence/. See The AI Extra Overview for what the Extra does before reading this article.

Why this matters

Provider choice affects cost, performance, privacy, and quality. Anthropic's Claude tends to do well on substantive analysis; OpenAI's GPT-4o is fast and broadly capable; local Ollama keeps everything in your environment but with quality trade-offs. Once configured, the choice is mostly invisible to operators (the AI just produces output), but the procurement and privacy implications are real upfront.

This article walks through the configuration end-to-end: from "Extra activated" to "AI calls succeeding."

Before you start

Have these in hand:

Admin access to the Settings Hub (Settings cog, top-right of any page) → Extras chip → Artificial Intelligence Extra tile (or to the standalone Artificial Intelligence tile under the Customization chip when the Extra isn't installed — see step 4) for the configuration UI.
The AI Extra activated. See Installing Extras.
A provider chosen. Decision factors:
Privacy: regulated content (PHI, PII, classified) → Ollama or a privacy-tier commercial provider.
Quality: substantive analysis → Claude Sonnet 4, GPT-4o, Gemini 2.0 Pro.
Cost: low-volume / budget-constrained → smaller / cheaper models (gpt-4o-mini, gemini-1.5-flash, claude-haiku tiers).
Latency: interactive workflows → faster models (gpt-4o-mini, gemini-1.5-flash, ollama on capable hardware).
An API key for the chosen provider (or a working Ollama install).
The cron queue worker running — AI calls execute via the worker. Without it, AI jobs queue forever.
A test risk or test document for verification.

Step-by-step

1. Pick the provider

Decide based on the factors above. Common starting points:

Anthropic Claude if you want strong substantive analysis and don't need cheapest-possible cost.
OpenAI GPT-4o if you want broadly capable and easy to integrate.
Google Gemini if you're already in Google Cloud and want consolidated billing.
Ollama if data sovereignty is non-negotiable and you have local infrastructure for inference.
Mistral / Grok for specific use cases or as alternatives to the above.

2. Get an API key (commercial providers)

The procurement varies by provider:

Anthropic: https://console.anthropic.com/settings/keys. Create an account; provision an API key.
OpenAI: https://platform.openai.com/api-keys. Create an account; provision an API key.
Google Gemini: https://aistudio.google.com/app/apikey or via Google Cloud Console for production use.
Mistral: https://console.mistral.ai/. Account; API key.
xAI Grok: https://x.ai/api. Account; API key.

For commercial providers, also configure billing and any spending alerts at the provider's console — runaway integrations can produce surprise bills.

3. Set up Ollama (local provider)

For local-inference deployment:

Install Ollama on a server with appropriate resources (https://ollama.com/download). For substantive AI tasks, a GPU is highly recommended.
Pull the model(s) you'll use: ollama pull llama3.2, ollama pull mistral, etc.
Run Ollama in serve mode: ollama serve. By default, listens on http://localhost:11434.
If SimpleRisk runs on a different server, configure Ollama to listen on a network-accessible interface and ensure the network path is open.

4. Configure the provider in SimpleRisk

Settings cog → Settings Hub → Extras chip → Artificial Intelligence Extra tile (or, for installs without the Extra, the standalone Artificial Intelligence tile under the Customization chip at /admin/artificial_intelligence_core.php, which exposes the same Provider Configuration and Context Questions tabs). The settings page exposes:

Provider (ai_provider) — pick from the dropdown: Anthropic, OpenAI, Google Gemini, Mistral, Grok, Ollama, Custom.
API Key (ai_api_key) — paste the API key. Stored encrypted.
Model (ai_model) — pick the specific model. Defaults vary per provider:
Anthropic default: claude-sonnet-4-20250514.
OpenAI default: gpt-4o.
Gemini default: gemini-2.0-flash.
Ollama: whatever model you've pulled (e.g., llama3.2).
Endpoint URL (for Custom or Ollama): the full URL of the provider's API or your local Ollama instance (e.g., http://localhost:11434/v1).

Save.

5. Configure the capabilities catalog

Open the Capabilities tab (same tile as Provider Configuration and Context Questions). This is a searchable catalog, one card per AI capability, with a search box and filter chips for Domain (Recommendations, Risk, Documents, Controls, Assistant), Tier (Free, AI Extra), and State (Enabled, Disabled, Locked).

GRC Framework Recommendations ships with Core and is on by default. It's what powers the framework recommendations and executive summary on the Artificial Intelligence page. Everything else in the catalog belongs to the AI Extra: Risk Recommendations, FAIR Quantitative Analysis, Document Customization, Document ↔ Control Matching, Document Template Library, Control Reference Enhancement, and Chat Assistant. Until the Extra is activated, those cards render locked with an "Included in the AI Extra" label; activate the Extra and each one becomes a live toggle. That locking is deliberate — the catalog doubles as a menu of everything AI can do in SimpleRisk, purchased or not.

Each toggle writes its own ai_cap_{id} setting (for example ai_cap_fair_analysis). Turning a capability off does more than stop the AI call — it hides the capability's entry points. Disable GRC Framework Recommendations and the Recommendations page disappears along with its sidebar submenu; disable every AI submenu item and the whole "AI" sidebar menu goes with it.

Enable only the capabilities you'll use. Disabled capabilities don't make AI calls; you save on cost and reduce surface area. If you're upgrading from an older SimpleRisk version, don't worry about losing your existing configuration — the upgrade seeds each ai_cap_* toggle from whatever the old settings had you running, so nothing silently turns off.

6. Capture the AI context (for FAIR analysis)

If you've enabled the FAIR Quantitative Analysis capability, the AI's FAIR estimates are much better when grounded in your program's context. The Extra exposes a one-time questionnaire:

Settings cog → Settings Hub → Artificial Intelligence Extra tile (or the Core Artificial Intelligence tile) → Context Questions tab.
Walk through the questionnaire: typical loss magnitudes for your organization, threat assumptions, vulnerability levels, etc.
Save.

The context is stored in the extra_ai_context_* settings; subsequent FAIR analyses use it.

Update the context when the organization's risk profile materially changes (mergers, business model shifts, regulatory changes).

7. Verify with a test call

Verify the configuration end-to-end:

Open a test risk in SimpleRisk.
Click the AI assistance trigger (the icon or button added by the Extra; varies by version).
The job queues; the UI shows "processing."
Wait for the cron worker to pick up the job (typically seconds to a minute).
The AI's output appears for operator review.

Verify:

The AI returned a sensible response. If the response is empty or nonsensical, check the model selection (a too-small model may struggle with substantive prompts) and the prompt configuration.
The response was attributed to the right provider. The audit log should record the provider that handled the call.
No error in the cron worker logs. Failed AI calls produce errors; check the SimpleRisk debug log.

If the test fails:

401 / authentication error: API key is wrong or expired. Regenerate at the provider; update SimpleRisk.
402 / payment required: provider billing is unfunded. Check provider console.
429 / rate limit: hitting provider rate limits. Slow down or upgrade your provider tier.
Connection timeout: SimpleRisk can't reach the provider (firewall, network).

8. Set provider-side spending alerts (commercial)

For commercial providers, configure alerts:

Anthropic: monthly spend alerts in the console.
OpenAI: usage limits and email alerts.
Google Cloud: billing alerts on the Gemini-using project.

Alert thresholds you can defend operationally to your finance team. Catching a 10× budget spike early matters more than the exact threshold value.

9. Plan for provider changes

The AI provider landscape evolves rapidly. Programs that picked Provider X two years ago may find Provider Y is now better fit (cost, quality, privacy). Plan for occasional provider switches:

Configuration is per-install, so switching is straightforward (change the provider, key, and model; verify).
Existing AI-generated content is unaffected — the data is just records in SimpleRisk; the provider that generated them isn't recorded permanently.
Coordinate the switch with operations: the AI behavior may change subtly with different models; warn operators that AI suggestions may differ in shape.

10. Document the configuration

Capture in your operations runbook:

Which provider you're using.
Which model.
Where the API key is stored.
Who manages the provider account (for billing, key rotation).
Where the FAIR context document lives.
How to disable AI features in case of a provider outage.

Common pitfalls

A handful of patterns recur with AI provider configuration.

Configuring without testing. "It saved, so it must work" — until the first AI call fails 12 hours later. Test immediately after configuration.
Using a model that doesn't fit the task. A small/cheap model may handle short summarization fine but produce poor FAIR analyses. Match model capability to use case.
Picking commercial providers for regulated content without checking privacy posture. PHI to OpenAI without a BAA is a HIPAA violation. Verify the provider's data-handling commitments before configuring.
Hardcoding the API key in source. Use the Extra's encrypted setting; don't paste into config files or environment variables that bleed into logs.
Forgetting to fund the provider account. API calls fail with 402 once the trial credit runs out. Set up billing.
Not setting spending alerts. A misbehaving integration that calls AI in a tight loop produces a surprise bill. Alerts catch it.
Switching providers mid-program without warning operators. AI output changes; operators see different shapes; trust drops. Communicate the change.
Trying to use Ollama with a model too small for the task. A 3B-parameter model can't do substantive FAIR analysis well. Either scale up the model and the hardware or use a commercial provider.
Configuring Ollama at a network address SimpleRisk can't reach. Firewall rules or non-routable addresses cause connection failures. Verify network path.
Letting the AI Extra's API key expire silently. Keys can be revoked or expire; AI calls suddenly fail. Track key lifecycles.
Activating the Extra and its capabilities without considering the user-facing surface. Operators see new AI buttons in the UI; they need to know what they do. Train before activating.
Treating AI output as canonical without operator review. The Extra's design assumes review. Don't bypass it.