---
title: "AI Providers & LLM Gateway Management"
description: "Documentation for AI Providers"
---

## Table of Contents
1. [Overview & Architecture](#1-overview--architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Layout](#4-visual-interface--layout)
5. [Field Reference & Parameter Specification](#5-field-reference--parameter-specification)
6. [Supported Provider Ecosystem & Dynamic Capabilities](#6-supported-provider-ecosystem--dynamic-capabilities)
7. [Enterprise Security & Credential Isolation](#7-enterprise-security--credential-isolation)
8. [Verification & Diagnostics](#8-verification--diagnostics)
9. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
10. [Glossary](#10-glossary)

---

## 1. Overview & Architecture

In **Ring2All SBC**, the **AI Providers** module serves as the centralized artificial intelligence gateway, managing outbound API connections and authentication credentials across external commercial cloud providers and on-premises local model runners. It provides the foundation for the SBC's cognitive capabilities—including real-time Model Context Protocol (MCP) diagnostics, SIP packet flow interpretation, automated perimeter threat scoring, and voice synthesis.

```
       ┌────────────────────────────────────────────────────────────┐
       │             RING2ALL SBC AI PROVIDER GATEWAY               │
       │           (Stored in sbc_admin.ai_providers)               │
       └─────────────────────────────┬──────────────────────────────┘
                                     │
           ┌─────────────────────────┼─────────────────────────┐
           ▼                         ▼                         ▼
   ┌────────────────┐       ┌────────────────┐       ┌────────────────┐
   │ COMMERCIAL LLM │       │ VOICE AI & TTS │       │ ON-PREM LOCAL  │
   ├────────────────┤       ├────────────────┤       ├────────────────┤
   │ • OpenAI       │       │ • ElevenLabs   │       │ • Ollama       │
   │ • Anthropic    │       │ • Azure Speech │       │ • LM Studio    │
   │ • Google Cloud │       │ • Custom TTS   │       │ • vLLM Server  │
   └────────────────┘       └────────────────┘       └────────────────┘
           │                         │                         │
           └─────────────────────────┼─────────────────────────┘
                                     ▼
           ┌──────────────────────────────────────────────────┐
           │      RING2ALL SBC AI CONSUMPTION SUBSYSTEMS      │
           ├─────────────────────────┬────────────────────────┤
           │  SBC NOC Copilot (MCP)  │  AI Perimeter Threat   │
           │  SIP Trace Diagnostics  │  Real-Time Voice IVR   │
           └─────────────────────────┴────────────────────────┘
```

The gateway manages secure credential storage, endpoint routing, and dynamic capability discovery (`chat`, `embeddings`, `tts`, `stt`), exposing normalized execution interfaces to downstream SBC services.

---

## 2. Business & Operational Significance

* **Vendor Independence & Redundancy**: Avoids vendor lock-in by supporting multiple upstream providers. Administrators can route high-reasoning tasks to Anthropic Claude or OpenAI while delegating bulk telemetry analysis to low-cost or on-premise models.
* **Sovereign Telecommunications Compliance**: For defense, healthcare, and enterprise environments with strict data sovereignty mandates, the gateway natively connects to private, air-gapped on-premise LLMs (Ollama/vLLM), ensuring zero customer call telemetry leaves the local perimeter.
* **Unified Credential Governance**: Consolidates API keys, organization IDs, and rate-limit quotas into a single audited interface rather than scattering tokens across disparate microservices.
* **Automated Connectivity Validation**: Built-in `Test Connection` verification performs real-time challenge handshakes against provider endpoints prior to committing changes, preventing operational disruptions caused by invalid keys or network firewalls.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Administrative Permissions | Operational Responsibilities |
| :--- | :--- | :--- |
| **AI Systems Administrator** | Full Read & Write | Registers upstream providers, provisions API keys, configures base URLs, and manages quota boundaries. |
| **Telecom Security Officer** | Read & Audit | Audits credential usage, enforces privacy routing policies, and mandates on-premise LLM routing for sensitive domains. |
| **NOC Support Engineer** | Read-Only | Performs live connection health checks and monitors provider uptime indicators. |
| **AI Model Gateway Copilot** | Programmatic Discovery & Health Audits | Discovers available intelligence engines, verifies endpoint reachability, and inspects supported modalities (chat, embeddings, TTS) via MCP. |

---

## 4. Visual Interface & Layout

### AI Providers Inventory Table
The main repository interface provides a clear overview of all configured AI integration endpoints:

![AI Providers List View](/screenshots/sbc/admin/ai-providers/ai-providers-list.png)

* **Name & Provider**: Displays the friendly provider label along with the underlying provider type (`anthropic`, `openai`, `elevenlabs`, `ollama`).
* **API Key Type**: Indicates whether standard API keys or specialized enterprise bearer tokens are utilized.
* **Status Badge**: Real-time status indicator (`Active` / `Disabled`).
* **Actions**: Edit configuration, clone provider definition, or delete.

### Provider Configuration Form
The registration dialog configures upstream API credentials and endpoints:

![AI Provider Configuration Form](/screenshots/sbc/admin/ai-providers/ai-providers-form.png)

* Includes inline `Test Connection` utility to validate authorization headers against provider endpoints before saving.

---

## 5. Field Reference & Parameter Specification

| Field Name | Type | Constraints | Description |
| :--- | :---: | :--- | :--- |
| **Name** | `string` | 3–100 characters | Descriptive display name for the provider integration (e.g., `Anthropic Claude`). |
| **Provider** | `select` | Valid provider enum | Target AI engine: `openai`, `anthropic`, `google`, `azure`, `elevenlabs`, `ollama`, `lmstudio`, `local`, `custom`. |
| **Organization** | `string` | Optional string | Enterprise organization identifier required by providers like OpenAI to scope billing and projects. |
| **Base URL** | `string` | Valid URL format | Custom API root endpoint (mandatory for Ollama, LM Studio, or private Azure OpenAI deployments). |
| **API Key** | `password` | Min 1 character | Secret API authorization token. Displayed as masked characters in the UI; never exposed in plain text. |
| **Enabled** | `boolean` | `true` / `false` | Administrative toggle activating or deactivating provider availability across all SBC services. |
| **Capabilities** | `jsonb` | Auto/JSON structure | Dynamic capabilities negotiated with the provider (e.g., `{"chat": true, "embeddings": true, "tts": false}`). |

---

## 6. Supported Provider Ecosystem & Dynamic Capabilities

| Provider | Engine Type | Supported Capabilities | Typical Use Case in Ring2All SBC |
| :--- | :---: | :---: | :--- |
| **OpenAI** | Commercial Cloud | `chat`, `embeddings`, `tts` | General NOC Copilot assistance, SIP ladder diagram summaries, and function calling. |
| **Anthropic** | Commercial Cloud | `chat` | Complex heuristic reasoning for perimeter threat intelligence and multi-stage fraud analysis. |
| **ElevenLabs** | Voice AI Cloud | `tts` | Ultra-low latency, human-like voice prompt generation and real-time IVR speech synthesis. |
| **Ollama / Local** | On-Premises | `chat`, `embeddings` | Sovereign, air-gapped packet analysis, local CDR classification, and zero-data-leakage compliance. |
| **Google Gemini** | Commercial Cloud | `chat`, `embeddings` | Multi-modal log processing and high-context telecom troubleshooting. |

---

## 7. Enterprise Security & Credential Isolation

* **Cryptographic Storage & Masking**: API keys are securely hashed or encrypted at rest in `sbc_admin.ai_providers`. The administrative frontend presents masked fields (`••••••••••••`), preventing shoulder-surfing and DOM token inspection.
* **Strict Tenant Scoping**: In multi-tenant environments, AI provider records are bounded by `tenant_id`, ensuring enterprise accounts cannot view or consume carrier-level AI tokens.
* **Egress Firewall Rules**: On-premise deployments can restrict outbound AI traffic strictly to specific provider IP ranges, blocking unauthorized model endpoints.

---

## 8. Verification & Diagnostics

Administrators can evaluate provider connectivity, test API handshakes, and query active capabilities from the command line:

```bash
# 1. Query active AI providers from PostgreSQL
sudo -u postgres psql -d sbc_admin -c "SELECT id, name, provider, status FROM ai_providers WHERE status = true;"

# 2. Test local Ollama endpoint connectivity from the host
curl -s http://127.0.0.1:11434/api/tags | jq .

# 3. Test external OpenAI API key validity
curl -s -o /dev/null -w "%{http_code}\n" https://api.openai.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key-here"

# 4. Verify AI provider resolution within SBC API logs
journalctl -u softswitch-sbc-api -n 50 --no-pager | grep -i "ai_provider"
```

---

## 9. Model Context Protocol (MCP) AI Integration

The **AI Providers** module is accessible via the Ring2All SBC Model Context Protocol (MCP) server, enabling supervisory AI agents and NOC assistants to audit configured intelligence backends, discover available capabilities, and verify endpoint statuses without exposing raw authentication keys.

### 9.1 MCP Tool Summary

| Tool Name | Action | Risk Level | Purpose |
| :--- | :--- | :--- | :--- |
| `list_sbc_ai_providers` | Read | `read` | List all configured AI model providers with status, endpoint URLs, and capability profiles. |
| `get_sbc_ai_provider` | Read | `read` | Retrieve full configuration details for a specific AI provider ID with masked API secrets. |

### 9.2 Tool Schemas & Input Parameters

#### Schema: `list_sbc_ai_providers`
```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

#### Schema: `get_sbc_ai_provider`
```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Unique integer ID of the AI provider"
    }
  },
  "required": ["id"],
  "additionalProperties": false
}
```

### 9.3 Sample Tool Execution Payloads

#### Example 1: Listing All Configured Providers
**Request Payload:**
```json
{
  "tool": "list_sbc_ai_providers",
  "parameters": {}
}
```

**Response Payload:**
```json
{
  "success": true,
  "data": {
    "total": 3,
    "providers": [
      {
        "id": 1,
        "uuid": "7a3e1b4c-9f82-41a2-89cd-123456789abc",
        "name": "OpenAI Production",
        "provider": "openai",
        "baseUrl": "https://api.openai.com/v1",
        "organization": "org-ring2all-enterprise",
        "apiKeyConfigured": true,
        "capabilities": {
          "chat": true,
          "embeddings": true,
          "tts": true
        },
        "status": true,
        "createdAt": "2026-06-15T10:00:00Z"
      },
      {
        "id": 2,
        "uuid": "8b4f2c5d-0a93-52b3-90de-234567890bcd",
        "name": "Anthropic Reasoning Engine",
        "provider": "anthropic",
        "baseUrl": "https://api.anthropic.com/v1",
        "organization": null,
        "apiKeyConfigured": true,
        "capabilities": {
          "chat": true,
          "embeddings": false,
          "tts": false
        },
        "status": true,
        "createdAt": "2026-07-20T14:30:00Z"
      },
      {
        "id": 3,
        "uuid": "9c5a3d6e-1ba4-63c4-01ef-345678901cde",
        "name": "Local Sovereign Ollama",
        "provider": "ollama",
        "baseUrl": "http://127.0.0.1:11434",
        "organization": null,
        "apiKeyConfigured": false,
        "capabilities": {
          "chat": true,
          "embeddings": true,
          "tts": false
        },
        "status": true,
        "createdAt": "2026-08-01T09:15:00Z"
      }
    ]
  }
}
```

#### Example 2: Inspecting Specific AI Provider Details
**Request Payload:**
```json
{
  "tool": "get_sbc_ai_provider",
  "parameters": {
    "id": 1
  }
}
```

**Response Payload:**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "uuid": "7a3e1b4c-9f82-41a2-89cd-123456789abc",
    "name": "OpenAI Production",
    "provider": "openai",
    "baseUrl": "https://api.openai.com/v1",
    "organization": "org-ring2all-enterprise",
    "apiKeyType": "standard",
    "apiKeyConfigured": true,
    "capabilities": {
      "chat": true,
      "embeddings": true,
      "tts": true
    },
    "status": true,
    "createdAt": "2026-06-15T10:00:00Z",
    "updatedAt": "2026-08-10T12:00:00Z"
  }
}
```

### 9.4 Bilingual Natural Language Copilot Prompts

#### English Prompts
* *"List all configured AI providers and check which ones support chat completions."*
  → Agent invokes `list_sbc_ai_providers()`.
* *"Inspect AI provider ID 3 to verify the local Ollama base URL and operational status."*
  → Agent invokes `get_sbc_ai_provider({"id": 3})`.

#### Spanish Prompts (Español)
* *"Lista todos los proveedores de IA configurados y verifica cuáles soportan completado de chat."*
  → Agente invoca `list_sbc_ai_providers()`.
* *"Inspecciona el proveedor de IA con ID 3 para verificar la URL base de Ollama local y su estado."*
  → Agente invoca `get_sbc_ai_provider({"id": 3})`.

### 9.5 Enterprise Security & Execution Safeguards

1. **Cryptographic Key Masking**: Raw API tokens (`sk-proj-...`, `ant-api-...`) are never exposed via MCP responses. The API returns `apiKeyConfigured: true` without disclosing cleartext tokens.
2. **Read-Only Inspection Safeguard**: All provider discovery tools are restricted to `read` actions to ensure autonomous agents cannot tamper with production billing accounts or redirect AI base URLs.
3. **Audit Trail Compliance**: Invocations of AI provider inspection tools are recorded in system audit logs with requesting user context.

---

## 10. Glossary

* **LLM**: Large Language Model; an advanced deep-learning model capable of processing, understanding, and generating natural language.
* **MCP**: Model Context Protocol; an open architectural protocol that enables AI models to safely execute administrative tools and query database state.
* **On-Premises AI**: Hosting and running open-source models (e.g., Llama 3, Mistral) locally on dedicated hardware without third-party internet dependencies.
* **TTS / STT**: Text-to-Speech (speech synthesis) and Speech-to-Text (automated speech recognition).