---
title: "AI Providers Module Documentation"
description: "Documentation for AI Providers"
---

## Table of Contents
1. [Module Overview (Technical)](#1-module-overview-technical)
2. [Module Overview (Commercial & Business Value)](#2-module-overview-commercial--business-value)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Form Structure](#4-visual-interface--form-structure)
5. [Architectural Flow & Security Governance](#5-architectural-flow--security-governance)
6. [Common Scenarios & Operational Playbooks](#6-common-scenarios--operational-playbooks)
7. [Troubleshooting & Diagnostic Commands](#7-troubleshooting--diagnostic-commands)
8. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration)
9. [Glossary](#9-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](/screenshots/billing/admin/ai-integration/ai-providers/ai-providers-list.png)

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](/screenshots/billing/admin/ai-integration/ai-providers/ai-providers-form.png)

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 ]
```

1. **Token Protection:** API keys are restricted at the database level and never exposed in plain text in browser client applications.
2. **Dynamic Header Injection:** The gateway dynamically injects vendor-specific headers (e.g., `x-api-key` for Anthropic, `Authorization: Bearer` for OpenAI).
3. **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
1. Navigate to **ADMIN > AI Integration > Providers**.
2. Click **+ Add**.
3. Set **Name** to `OpenAI Official Cloud`.
4. Select **Provider** as `OpenAI`.
5. Enter the API Key beginning with `sk-...`.
6. Click **Test Connection**. A green success notification confirms API key validity.
7. Click **Save and close**.

### Playbook B: Connecting a Private On-Premise vLLM Server
1. Click **+ Add**.
2. Set **Name** to `Private Datacenter LLM`.
3. Select **Provider** as `Custom` (or `OpenAI Compatible`).
4. In **Base URL**, enter `http://10.10.50.20:8000/v1`.
5. Enter the internal cluster token in **API Key**.
6. Click **Test Connection** and verify reachability.
7. Click **Save and close**.

---

## 7. Troubleshooting & Diagnostic Commands

### Querying Configured Providers in SQL
```sql
SELECT 
    id,
    name,
    provider,
    base_url,
    status,
    created_at
FROM public.ai_providers
ORDER BY id ASC;
```

### Testing Upstream Provider Reachability via Curl
```bash
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
```json
{
  "name": "list_ai_providers",
  "arguments": {}
}
```

#### Response Payload
```json
[
  {
    "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.