---
type: source-summary
title: 'Source: AI_PROVIDER_SYSTEM.md'
modified: 2026-04-07
tags:
  - ai-provider-system
  - architecture
  - routing
  - source
  - preston-test
---

# Source: AI_PROVIDER_SYSTEM.md

## What this source is

The **architectural documentation for SuiteCentral 2.0's multi-provider AI system**. Deeper than [[sources/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 [[sources/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)
   → [[pages/concepts/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: [[sources/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):
- [[pages/concepts/production-proof]] — added the 7-provider total (4 real + 2 experimental + 1 fallback), per-provider accuracy baselines, 3-layer routing architecture
- [[pages/concepts/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"
  - [[sources/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. [[sources/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 [[sources/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 [[sources/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.