Source: AI_PROVIDER_SYSTEM.md

What this source is

The architectural documentation for SuiteCentral 2.0’s multi-provider AI system. Deeper than 04-technical-proof’s provider table — this source describes the three routing layers, task-aware execution, database-backed configuration, and provider-by-provider capability details.

Key claims (new content beyond 04-technical-proof)

1. 7 total provider types, not 4:
   • 4 “Real” production providers: OpenAI, Anthropic (Claude), OpenRouter, Local AI (LMStudio/Ollama)
   • 2 “Experimental” providers: Google Gemini, xAI Grok
   • 1 “Fallback” provider: Rule-Based Engine (deterministic pattern matching, no external API calls) → production-proof — prior framing was “4 production providers” which is accurate but incomplete. Gemini and Grok are also wired up, just classified as experimental.
2. Per-provider accuracy baselines (NEW specific numbers):

   Provider	Accuracy
   Rule-Based	78%
   OpenAI	92%
   Claude	91%
   OpenRouter	91%
   Gemini	90%
   Grok	89%
   LMStudio	87%
   The 78% rule-based number is interesting — it’s a fallback that still delivers ~78% accuracy for pattern-based mapping, meaning the system degrades gracefully if all AI providers fail.

3. 3 routing layers (NEW architectural detail) — the AI provider system has three distinct routing layers that stack:
   • AIConfigurationService + TaskAwareProviderFactory — uses saved AI Config records per user/task; primary execution path for the AI Configuration dashboard
   • ProviderFactory (Week 9 tier-based routing) — 4 named tiers:
     • premium: Claude → OpenRouter → OpenAI → Gemini → LMStudio
     • default: OpenAI → OpenRouter → Claude → Gemini → LMStudio
     • economy: Gemini → OpenRouter → OpenAI → LMStudio → Claude
     • local: LMStudio → OpenAI → Gemini → OpenRouter → Claude
   • IntelligentProviderRouter — scores providers on capability, cost, latency, availability, privacy, and track record; session budget guard reroutes through local tier fallback when budget exhausted; rerouted responses include reroutedFrom metadata
4. 4 task types (first formal enumeration): field_mapping, quality_assessment, data_validation, transformation_suggestion. A user can configure a different provider per task type via AITaskModelConfig.
5. Database-backed configuration (AIProviderConfig schema):
   • User-scoped with multi-user isolation
   • AES-256 encrypted API keys at rest in PostgreSQL
   • Per-config: endpoint, modelVersion, maxTokens, temperature, isActive, priority
   • Usage tracking via audit logs and cost monitoring
6. Provider-specific model catalogs (NEW):
   • OpenAI: GPT-4, GPT-4 Turbo, GPT-3.5 Turbo (note: 04-technical-proof says GPT-4o is primary — this source may be slightly older and doesn’t include GPT-4o)
   • Claude: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku
   • OpenRouter: 50+ upstream models, free tier at openrouter/free
   • Gemini: Gemini 1.5 Pro, 1.5 Flash, 1.0 Pro
   • Grok: Grok Beta, Grok Vision Beta
   • Local AI: Llama 3.1:8b (default), custom via Ollama
7. Endpoint documentation:
   • OpenAI: https://api.openai.com/v1/chat/completions
   • Anthropic: https://api.anthropic.com/v1/messages
   • OpenRouter: https://openrouter.ai/api/v1
   • Gemini: https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent
   • xAI Grok: https://api.x.ai/v1/chat/completions
   • LMStudio: http://127.0.0.1:1234 (default)
   • Ollama: http://localhost:11434 (default)
8. REST API endpoints for provider configuration management: GET/POST /api/ai-config/providers, POST /api/ai-config/providers/:id/test, DELETE /api/ai-config/providers/:id, GET/POST /api/ai-config/tasks, GET /api/ai-config/models/:providerType, GET /api/ai-config/usage, GET /api/ai-config/health
9. Best-practice configuration defaults (NEW):
   • Temperature: 0.1 (for consistent field mapping — explicitly recommended)
   • Max tokens: 2000 (sufficient for most mapping tasks)
   • Confidence threshold: 0.8 (balance of accuracy vs coverage)
10. Security details:
    • Server-side API keys AES-256 encrypted in the database OR supplied via env vars
    • HTTPS-only API communication
    • Provider isolation
    • Legacy browser flows may still persist AI configuration in localStorage — this is a honest disclosure of a less-secure legacy path that should be treated as “trusted-machine only”
11. “Zero-downtime provider changes via API” — dynamic provider switching without restart
12. Implementation status honesty: the document distinguishes ✅ Fully Implemented, 🔄 Available Features, ⚠️ LLM Integration (“Cloud providers ready for API wiring”) — meaning the configuration and routing infrastructure is complete but the actual API calls to cloud providers may not all be wired up yet in every environment.

Pages updated by this ingest

Updated (2 existing pages):

• production-proof — added the 7-provider total (4 real + 2 experimental + 1 fallback), per-provider accuracy baselines, 3-layer routing architecture
• suitecentral-2-overview — added the 4 task types, session budget guard, reroutedFrom metadata

Notable quotes

“The Integration Hub features a sophisticated AI provider system that supports 4 real AI providers + 2 experimental providers + a rule-based fallback, with database-backed AI configuration, Week 9 tier-based routing, task-aware execution, and cross-component synchronization.” — Opening paragraph

“IntelligentProviderRouter scores configured providers on capability, cost, latency, availability, privacy, and track record” — Routing Layers section

Cross-references / contradictions found

• Model list discrepancy — RESOLVED 2026-04-07 from source code:
  • This source lists OpenAI models as “GPT-4, GPT-4 Turbo, GPT-3.5 Turbo”
  • 04-technical-proof lists “GPT-4o” as primary
  • Canonical source of truth: src/services/ai/ModelCatalogService.ts lines 42-46 defines the OpenAI capability matrix as exactly three models: gpt-4o, gpt-4o-mini, gpt-4.1. No GPT-4, no GPT-4 Turbo, no GPT-3.5 Turbo.
  • Conclusion: this source (AI_PROVIDER_SYSTEM.md) is stale and should be refreshed. The canonical OpenAI model list is gpt-4o / gpt-4o-mini / gpt-4.1 as documented in the code. 04-technical-proof is correct (GPT-4o primary); this source is out of date.
  • Wiki pages citing OpenAI models should use the canonical code-sourced list, NOT the values in this AI_PROVIDER_SYSTEM doc.
• “4 production providers” vs “7 total providers”: not a contradiction. The canonical pitch number is 4 production. The full system supports 7 but 2 are “experimental” and 1 is “fallback.” So “4 production-ready” from 26-canonical-metrics-and-wording is correct and style-guide-compliant.
• Confirms 4 task types that were hinted at in the feature inventory: field_mapping, quality_assessment, data_validation, transformation_suggestion.
• Rule-based 78% accuracy is new context for the “graceful degradation” narrative: if all cloud AI providers fail and the local AI fails, the rule-based engine still delivers 78% field mapping accuracy. That’s the floor of the system’s accuracy curve — not 0%.
• Session budget guard + reroutedFrom metadata: important for the CFO’s cost-control story. A session can be capped on AI budget, and when the budget is hit, the system automatically reroutes to the local tier (LMStudio/rule-based) and marks the response with reroutedFrom. The CFO gets predictable cost per session, and the reviewer sees exactly when the reroute happened.

Notes

• This source is the architectural companion to 04-technical-proof’s AI Provider Configuration table. 04-TP gives the high-level table; this document gives the routing architecture, task-aware execution, database schema, and per-provider API details.
• The three routing layers are worth emphasizing: AIConfigurationService (user-config-driven), ProviderFactory (tier-based), IntelligentProviderRouter (score-based with session budget). They stack — a request can go through all three depending on context.
• Intelligent routing on 6 dimensions (capability, cost, latency, availability, privacy, track record) is a sophisticated scoring function. No other source has described provider routing at this level of architectural specificity.
• The honest “LLM Integration: Cloud providers ready for API wiring” status qualifier is a subtle flag — it means not every provider is wired to actual API calls in every environment. Rule-based is fully functional; cloud providers require API key setup; the configuration infrastructure is all there.
• This document is 11,700 characters — the largest single source-summary so far. Most of the content is code snippets, endpoint URLs, and configuration examples that don’t cleanly fit as atomic claims but are useful reference for a technical deep-dive.