AI Providers Module Documentation

Module Overview (Technical)
Module Overview (Commercial & Business Value)
🎯 User Roles & Key Capabilities
Visual Interface & Form Structure
Architectural Flow & Security Governance
Common Scenarios & Operational Playbooks
Troubleshooting & Diagnostic Commands
Model Context Protocol (MCP) AI Integration
Glossary

1. Module Overview (Technical)

The AI Providers module (public.ai_providers) establishes and governs external upstream connections to Large Language Model (LLM) and Text-To-Speech (TTS) cloud inference engines for Ring2All Billing. In modern telecom operations, AI agents assist with billing inquiries, automated CDR fraud explanation, conversational IVRs, and natural language customer support.

This module provides a unified abstraction layer connecting to premier AI backends—including OpenAI, Anthropic, DeepSeek, and private OpenAI-compatible inference servers (such as vLLM, Ollama, or LiteLLM gateways)—with credential encryption, capability discovery, base URL overrides, and live connectivity health checks.

Data Model & Architecture Diagram

 ┌────────────────────────────────────────────────────────────────────────┐
 │                   AI Providers (public.ai_providers)                   │
 │  • id: bigint (Primary Key)                                            │
 │  • uuid: UUID (Unique Public Identifier)                               │
 │  • tenant_id: bigint / domain_id: bigint                               │
 │  • provider: 'openai' | 'anthropic' | 'deepseek' | 'custom'            │
 │  • name: text (e.g., 'OpenAI Official Cloud', 'DeepSeek Copilot')      │
 │  • organization: text (Optional Org ID / Tenant Header)                │
 │  • api_key: text (Encrypted Upstream Bearer Token)                     │
 │  • base_url: text (Custom Gateway Endpoint e.g., https://api.openai...)│
 │  • api_key_type: VARCHAR(50) ('standard', 'managed')                   │
 │  • capabilities: jsonb (Supported features: chat, tts, vision, etc.)   │
 │  • status: boolean (Active / Inactive)                                 │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │ Upstream Transport Gateway
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │                     External AI Inference Engines                      │
 │  • OpenAI API (GPT-4o, GPT-4o-mini, Whisper, TTS-1)                    │
 │  • Anthropic API (Claude 3.5 Sonnet, Claude 3.5 Haiku)                 │
 │  • DeepSeek API (DeepSeek-V3, DeepSeek-Reasoner R1)                    │
 │  • Private On-Premise Gateways (vLLM / LiteLLM / Ollama)               │
 └────────────────────────────────────────────────────────────────────────┘

PostgreSQL Schema Architecture

public.ai_providers:
- id: Numeric primary key (bigserial).
- uuid: Immutable UUID utilized in frontend routing and REST APIs.
- provider: Upstream provider protocol driver (openai, anthropic, deepseek, custom).
- name: Descriptive label assigned by the administrator.
- organization: Optional organization ID header passed to providers supporting multi-project billing.
- api_key: API authorization key.
- base_url: Optional custom endpoint URL, allowing rerouting to private proxies or localized regional endpoints.
- capabilities: Dynamic JSONB schema storing discovered model lists, token limits, and TTS voice registries.
- status: Operational toggle enabling or disabling all profiles linked to the provider.

2. Module Overview (Commercial & Business Value)

Multi-Provider Resilience & Zero Vendor Lock-In: Organizations are not tethered to a single AI vendor. If an upstream provider suffers rate limiting or an outage, billing copilots can be switched across providers seamlessly.
Cost Optimization Across Workload Profiles: High-reasoning tasks (such as forensic CDR fraud analysis) can leverage DeepSeek Reasoner or Claude 3.5 Sonnet, while high-volume standard customer notifications leverage cost-efficient models.
Private & On-Premise Compliance: Financial institutions and telecom carriers with strict data residency laws can direct base_url to an internal on-premise vLLM or Ollama cluster, guaranteeing customer billing data never leaves the private perimeter.
Centralized Key Management: API tokens are managed in one secure vault rather than distributed across multiple microservices or client applications.

3. 🎯 User Roles & Key Capabilities

Role	Key Capabilities & Permissions in AI Providers
Platform Administrator	Adds, configures, and tests AI service providers; enters upstream API keys; manages organization tags and custom base URLs.
Security Engineer	Rotates API tokens, reviews outgoing connection security, and ensures private endpoints adhere to TLS encryption standards.
NOC Engineer	Monitors provider connectivity status, executes live test connection probes, and troubleshoots upstream latency or rate limits.
Billing Specialist	Views available providers and supported capabilities when configuring AI Profiles for customer billing support.

4. Visual Interface & Form Structure

The AI Providers module features a clean administrative list view and a dedicated creation/editing surface.

4.1 AI Providers Listing

AI Providers List

The list view displays all configured AI inference providers:

Header Controls:
- Search Input: Filters providers by name or provider type.
- + Add: Navigates to /ai-providers/new to register a new provider.
Data Grid Columns:
- Name: Descriptive name of the integration (e.g., OpenAI Official Cloud, Anthropic Claude Services, DeepSeek Telecom Copilot).
- Provider: Driver engine badge with Bot icon (openai, anthropic, deepseek).
- API Key Type: Credential type badge (STANDARD).
- Enabled: Operational status badge (Active in green).
- Actions: Direct actions to edit settings (Pencil), duplicate configuration (Copy), or delete provider (Trash).

4.2 Create / Edit AI Provider Form

Create AI Provider Form

The Level 2 form provides a structured configuration box with immediate verification capabilities:

Header:
- < List: Returns to the main providers grid.
- Title: Create New or Edit Provider.
Provider Configuration Fields:
- Name *: Human-readable label (e.g., OpenAI Official Cloud).
- Organization: Optional organization ID (e.g., org-xxxxxxxx).
- Provider *: Dropdown selection (OpenAI, Anthropic, DeepSeek, Custom).
- Base URL: Endpoint override (e.g., https://api.openai.com/v1 or custom on-premise proxy).
- API Key *: Secret token provided by the upstream AI vendor.
- Enabled: Switch toggling provider availability.
- Test Connection: Interactive button that initiates an immediate ping to the upstream API to validate credentials before saving.
Sticky Bottom Bar (FixedActionBar):
- Cancel: Discards uncommitted changes.
- Save and close: Validates input and persists configuration.

5. Architectural Flow & Security Governance

 ┌──────────────────────┐
 │  AI Profile Request  │
 │ (Copilot / Assistant)│
 └──────────┬───────────┘
            │
            ▼
 ┌────────────────────────────────────────────────────────┐
 │                 AI Gateway Dispatcher                  │
 │  1. Fetches provider credentials from public.ai_providers│
 │  2. Appends auth headers & optional Org ID             │
 │  3. Routes HTTP/SSE request to configured Base URL     │
 └──────────────────────────┬─────────────────────────────┘
                            │
             ┌──────────────┼──────────────┐
             ▼              ▼              ▼
     [ OpenAI Cloud ] [ Anthropic ] [ DeepSeek / On-Prem ]

Token Protection: API keys are restricted at the database level and never exposed in plain text in browser client applications.
Dynamic Header Injection: The gateway dynamically injects vendor-specific headers (e.g., x-api-key for Anthropic, Authorization: Bearer for OpenAI).
Connection Pre-Flight Checks: The Test Connection button sends a lightweight query (e.g., model listing) to verify authentication without consuming inference credits.

6. Common Scenarios & Operational Playbooks

Playbook A: Registering an Official OpenAI Provider

Navigate to ADMIN > AI Integration > Providers.
Click + Add.
Set Name to OpenAI Official Cloud.
Select Provider as OpenAI.
Enter the API Key beginning with sk-....
Click Test Connection. A green success notification confirms API key validity.
Click Save and close.

Playbook B: Connecting a Private On-Premise vLLM Server

Click + Add.
Set Name to Private Datacenter LLM.
Select Provider as Custom (or OpenAI Compatible).
In Base URL, enter http://10.10.50.20:8000/v1.
Enter the internal cluster token in API Key.
Click Test Connection and verify reachability.
Click Save and close.

7. Troubleshooting & Diagnostic Commands

Querying Configured Providers in SQL

SELECT
    id,
    name,
    provider,
    base_url,
    status,
    created_at
FROM public.ai_providers
ORDER BY id ASC;

Testing Upstream Provider Reachability via Curl

curl -s -X POST https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 5}'

8. Model Context Protocol (MCP) AI Integration

The AI Providers module connects directly to the Ring2All BSS MCP Server, providing administrators and cognitive copilots with programmatic visibility into registered neural model inference backends and operational states.

Available MCP Tools

Tool Name	Access Role	Description & Primary Function	Example Arguments
`list_ai_providers`	`Super Administrator`	Lists upstream Artificial Intelligence (LLM) inference providers with active status and model types.	`{}`

Sample MCP Tool Execution: `list_ai_providers`

Request Payload

{
  "name": "list_ai_providers",
  "arguments": {}
}

Response Payload

[
  {
    "id": 1,
    "name": "OpenAI Production",
    "provider": "openai",
    "status": "active",
    "baseUrl": "https://api.openai.com/v1",
    "modelsCount": 4
  },
  {
    "id": 2,
    "name": "Anthropic Claude Core",
    "provider": "anthropic",
    "status": "active",
    "baseUrl": "https://api.anthropic.com",
    "modelsCount": 3
  }
]

Conversational AI Prompts for Copilot

“List all active AI inference providers and their configured endpoints.”
“Is OpenAI Production currently active and accessible?”
“Show which AI providers are registered for chatbot operations.”

9. Glossary

LLM (Large Language Model): Advanced neural network models capable of understanding, summarizing, and generating natural language and code.
Base URL: The target root URL where REST requests are dispatched, allowing rerouting to local models or enterprise caching proxies.
Provider Protocol: The specific API convention implemented by the vendor (OpenAI REST, Anthropic Messages API, etc.).
Test Connection: An active probe verifying API authentication and network reachability without committing configuration.
Model Context Protocol (MCP): Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.