AI providers

Formspring talks to LLM providers for AI Insights, content moderation, and any future AI-powered form features. The default text provider is OpenRouter (config/ai.php 'default' => 'openrouter') because it ships a free Gemma 4 tier that lets us validate AI features with zero spend before committing to a paid model. Anthropic is the recommended production upgrade. config/ai.php is wired for 15 providers - only configure the ones actually in use.

This is a server-wide integration. AI features are gated by the use-ai plan flag (per-team).

Supported providers (in config/ai.php)

* * *

Quickstart: OpenRouter (the default)

OpenRouter brokers requests to many underlying models behind one API. It works out of the box because config/ai.php ships with OPENROUTER_TEXT_MODEL defaulting to google/gemma-4-31b-it:free, a free tier that's enough to validate the AI Insights flow end-to-end.

Step 1 - Get an OpenRouter API key

1. Go to https://openrouter.ai/keys.
2. Create Key → name it Formspring.
3. Copy the key - starts with sk-or-v1-....

Step 2 - Configure Formspring

OPENROUTER_API_KEY=sk-or-v1-...
# Optional override; defaults to google/gemma-4-31b-it:free if unset.
OPENROUTER_TEXT_MODEL=google/gemma-4-31b-it:free

Restart the app. config/ai.php reads these.

Step 3 - Verify

Trigger an AI Insights run on a form with a few submissions and confirm the analysis returns text. Errors here mean the key is wrong, the model name was changed to something not on the account's tier, or the free quota for the day is exhausted.

* * *

Production upgrade: Anthropic (Claude)

When you're ready for higher-quality output (cleaner summaries, better moderation judgment), point default at Anthropic. Most teams running AI Insights on real form traffic move here within the first week.

Step 1 - Get an Anthropic API key

1. Go to https://console.anthropic.com/.
2. API Keys → Create Key.
3. Name: Formspring.
4. Workspace: the workspace whose credit pool you want this to consume.
5. Copy the key - starts with sk-ant-....

Step 2 - Configure Formspring

ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-sonnet-4-6     # or claude-opus-4-7 for top quality

Then either flip the default in config/ai.php ('default' => 'anthropic') or pass provider: 'anthropic' to individual calls. Restart the app.

* * *

Adding OpenAI (for audio / transcription / embeddings)

OpenAI is the default for audio, transcription, and embeddings (config/ai.php lines 18-20). Set it up if you use any of those features.

OPENAI_API_KEY=sk-proj-...
OPENAI_ORG_ID=org-...                # optional
OPENAI_MODEL=gpt-4o-mini              # or gpt-4o for higher quality

Get the key at https://platform.openai.com/api-keys → + Create new secret key.

* * *

Adding Google Gemini (for image generation)

GEMINI_API_KEY=AI...
GEMINI_MODEL=gemini-2.5-flash

Get the key at https://aistudio.google.com/app/apikey.

* * *

Adding Ollama (locally hosted)

For runs that should not leave the local network:

OLLAMA_URL=http://ollama:11434
OLLAMA_MODEL=llama3.2:8b

Trade-offs: lower quality than Anthropic/OpenAI on most tasks; full data sovereignty; latency depends on the host hardware.

* * *

Where the credential lives

• Server: .env → config/ai.php per-provider blocks.
• Usage: app/Ai/Brain.php (core), app/Support/AiInsightsData.php, app/Http/Controllers/AiInsightsController.php.
• Plan gate: Gate::define('use-ai', ...) in app/Providers/AppServiceProvider.php.

* * *

Cost & quota considerations

• Most providers price per 1M tokens (input + output, separately).
• OpenRouter's google/gemma-4-31b-it:free is $0 at the time of writing - read the model card before relying on it for production. Free tiers can be retired.
• On Anthropic Sonnet 4.6, AI Insights for a typical form (50–500 submissions) costs <$0.01 per analysis.
• Set spending caps at the provider:
  • OpenRouter: openrouter.ai/settings/credits → spending limits.
  • Anthropic: console.anthropic.com → Plans & Billing → spending limits.
  • OpenAI: platform.openai.com → Settings → Billing → Usage limits.
• Watch your platform's ai_features plan flag - only teams on plans with that feature can trigger AI calls.

* * *

Security

• Treat all API keys as critical secrets. A leaked key can drain credits + leak prompt content.
• Rotate at the provider's API keys page. Anthropic and OpenRouter keys are immediate-revocable; OpenAI gives you a 5-minute grace.
• PII considerations: form submissions can contain PII. Confirm the provider's data-use policy:
  • OpenRouter: passes prompts through to the underlying model provider; data policy depends on which model you route to. Check the model card on openrouter.ai.
  • Anthropic: doesn't train on API content (default).
  • OpenAI: doesn't train on API content since 2023; check current ToS.
  • Gemini: free tier may use prompts for training; paid tier doesn't.
  • Ollama: zero data leaves your infra.

For high-PII forms, prefer Anthropic API direct or a locally-hosted Ollama - not OpenRouter, since the routed-to-provider's policy applies.

* * *

Multi-provider failover

config/ai.php supports a fallback chain - if the default provider 5xxs, it can route to a backup (e.g. OpenRouter → Anthropic → Mistral). Out of scope for this doc.

* * *

Troubleshooting

* * *

Provider docs

• Anthropic: https://docs.anthropic.com/
• OpenAI: https://platform.openai.com/docs
• Google Gemini: https://ai.google.dev/
• Mistral: https://docs.mistral.ai/