unified-ai-router 3.3.14 → 3.4.0

package/.env.example

@@ -1,10 +1,8 @@
-OPENAI_API_KEY=API_KEY
 GEMINI_API_KEY=API_KEY
 OPENROUTER_API_KEY=API_KEY
 ZAI_API_KEY=API_KEY
 GROK_API_KEY=API_KEY
 QROQ_API_KEY=API_KEY
-VERCEL_AI_GATEWAY_API_KEY=API_KEY
 COHERE_API_KEY=API_KEY
 CEREBRAS_API_KEY=API_KEY
 LLM7_API_KEY=API_KEY

package/docs/configuration.md

@@ -45,10 +45,22 @@ Each provider object supports (at minimum) these fields:
   name: "openai",               // simple identifier for logs/debug
   apiKey: process.env.OPENAI_API_KEY,
   model: "gpt-4",               // model id to request from this provider
-  apiUrl: "https://api.openai.com/v1", // base URL for provider-compatible OpenAI endpoints
+  apiUrl: "https://api.openai.com/v1", // base URL for provider-compatible OpenAI endpoints,
 }
 ```
 
+### Circuit Breaker Configuration
+
+The router includes built-in circuit breaker protection for each provider using the "opossum" library. This provides fault tolerance by automatically stopping requests to a provider that's experiencing issues and preventing cascading failures.
+
+Default circuit breaker options:
+
+* **timeout**: 300000ms (5 minutes) - time before action is considered failed
+* **errorThresholdPercentage**: 50% - percentage of failures before opening the circuit
+* **resetTimeout**: 9000000ms (15 minutes) - time to wait before trying the provider again  
+
+You can override these options per provider by passing `circuitOptions`.
+
 ### Important notes
 
 * `apiKey` should reference the environment variable (use `process.env.X`). If the env var is missing the router will skip that provider and log a warning.

package/docs/index.md

@@ -16,6 +16,8 @@ hero:
 features:
   - title: Multi-provider fallback
     details: If one provider fails, requests automatically fall back to the next available provider.
+  - title: Circuit breaker protection
+    details: Built-in fault tolerance with automatic circuit breaking for each provider to prevent cascading failures.
   - title: OpenAI-compatible API
     details: Run a drop-in replacement for the OpenAI chat completion endpoints (streaming & non-streaming).
   - title: Tool calling & streaming

package/main.js

@@ -4,11 +4,63 @@ const pretty = require( "pino-pretty" );
 const pinoStream = pretty({ colorize: true, ignore: "pid,hostname" });
 const logger = pino({ base: false }, pinoStream );
 
+const CircuitBreaker = require( "opossum" ); // <-- added
+
 class AIRouter
 {
 	constructor ( providers )
 	{
 		this.providers = providers;
+
+		const defaultCircuitOptions = {
+			timeout: 300000, // time in ms before action considered failed
+			errorThresholdPercentage: 50, // % of failures before opening the circuit
+			resetTimeout: 9000000, // time in ms to wait before trying again
+		};
+
+		for ( const provider of this.providers )
+		{
+			// allow provider to override circuit options
+			const circuitOptions = Object.assign({}, defaultCircuitOptions, provider.circuitOptions || {});
+
+			// action receives an object: { params, withResponse }
+			const action = async ({ params, withResponse }) =>
+			{
+				const client = this.createClient( provider );
+
+				// If caller requested .withResponse() use it
+				if ( withResponse )
+				{
+					// return whatever .withResponse() returns (assumed promise resolving to { data, response })
+					return client.chat.completions.create( params ).withResponse();
+				}
+
+				// Normal create (may return Promise resolving to response OR an async iterable for streaming)
+				return client.chat.completions.create( params );
+			};
+
+			const breaker = new CircuitBreaker( action, circuitOptions );
+
+			// simple logging for breaker transitions
+			breaker.on( "open", ( ) =>
+			{
+				return logger.warn( `Circuit open for provider: ${provider.name}` )
+			});
+			breaker.on( "halfOpen", () => { return logger.info( `Circuit half-open for provider: ${provider.name}` ) });
+			breaker.on( "close", () => { return logger.info( `Circuit closed for provider: ${provider.name}` ) });
+			breaker.on( "fallback", () => { return logger.warn( `Fallback triggered for provider: ${provider.name}` ) });
+			breaker.on( "failure", ( err ) =>
+			{
+				logger.error({ provider: provider.name, event: "failure", error: err.message }, "Breaker failure event" );
+			 });
+			// optional fallback: we throw so the router will continue to next provider
+			breaker.fallback( ( err ) =>
+			{
+				throw new Error( `Circuit open for ${provider.name}` );
+			});
+
+			provider.breaker = breaker;
+		}
 	}
 
 	createClient ( provider )
@@ -33,8 +85,6 @@ class AIRouter
 			try
 			{
 				logger.info( `Attempting with provider: ${provider.name}` );
-				const client = this.createClient( provider );
-
 				const params = {
 					messages,
 					...tools && tools.length > 0 ? { tools } : {},
@@ -42,10 +92,11 @@ class AIRouter
 					...restOptions,
 					model: provider.model
 				};
-
+				const result = await provider.breaker.fire({ params, withResponse: false });
+				logger.info( `Successful with provider: ${provider.name}` );
 				if ( isStreaming )
 				{
-					const responseStream = await client.chat.completions.create( params );
+					const responseStream = result;
 					return ( async function* ()
 					{
 						for await ( const chunk of responseStream )
@@ -78,7 +129,7 @@ class AIRouter
 				}
 				else
 				{
-					const response = await client.chat.completions.create( params );
+					const response = result;
 					const content = response.choices[0]?.message?.content;
 					const reasoning = response.choices[0]?.message?.reasoning;
 					const tool_calls = response.choices[0]?.message?.tool_calls
@@ -104,7 +155,7 @@ class AIRouter
 				// Continue to next provider
 			}
 		}
-		throw new Error( `All providers failed. Last error: ${lastError.message}` );
+		throw new Error( `All providers failed. Last error: ${lastError?.message || "unknown"}` );
 	}
 
 	async chatCompletionWithResponse ( messages, options = {})
@@ -120,7 +171,6 @@ class AIRouter
 			try
 			{
 				logger.info( `Attempting with provider: ${provider.name}` );
-				const client = this.createClient( provider );
 
 				const params = {
 					messages,
@@ -130,7 +180,8 @@ class AIRouter
 					model: provider.model
 				};
 
-				const { data, response: rawResponse } = await client.chat.completions.create( params ).withResponse();
+				const { data, response: rawResponse } = await provider.breaker.fire({ params, withResponse: true });
+				logger.info( `Successful with provider: ${provider.name}` );
 				return { data, response: rawResponse }
 			}
 			catch ( error )
@@ -140,7 +191,7 @@ class AIRouter
 				// Continue to next provider
 			}
 		}
-		throw new Error( `All providers failed. Last error: ${lastError.message}` );
+		throw new Error( `All providers failed. Last error: ${lastError?.message || "unknown"}` );
 	}
 
 	async getModels ()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unified-ai-router",
-  "version": "3.3.14",
+  "version": "3.4.0",
   "description": "A unified interface for multiple LLM providers with automatic fallback. This project includes an OpenAI-compatible server and a deployable Telegram bot with a Mini App interface. It supports major providers like OpenAI, Google, Grok, and more, ensuring reliability and flexibility for your AI applications.",
   "license": "ISC",
   "author": "mlibre",
@@ -46,6 +46,7 @@
     "eslint": "^9.33.0",
     "express": "^5.1.0",
     "openai": "^6.1.0",
+    "opossum": "^9.0.0",
     "pino": "^9.9.0",
     "pino-pretty": "^13.1.1"
   },

package/provider.js

@@ -6,22 +6,22 @@ module.exports = [
 		apiUrl: "https://generativelanguage.googleapis.com/v1beta/openai/",
 	},
 	{
-		name: "gemini_3",
-		apiKey: process.env.GEMINI_API_KEY_3,
+		name: "gemini_2",
+		apiKey: process.env.GEMINI_API_KEY_2,
 		model: "gemini-2.5-pro",
 		apiUrl: "https://generativelanguage.googleapis.com/v1beta/openai/",
 	},
 	{
-		name: "gemini_2",
-		apiKey: process.env.GEMINI_API_KEY_2,
+		name: "gemini_3",
+		apiKey: process.env.GEMINI_API_KEY_3,
 		model: "gemini-2.5-pro",
 		apiUrl: "https://generativelanguage.googleapis.com/v1beta/openai/",
 	},
 	{
-		name: "vercel",
-		apiKey: process.env.VERCEL_AI_GATEWAY_API_KEY,
-		model: "openai/gpt-oss-120b",
-		apiUrl: "https://ai-gateway.vercel.sh/v1",
+		name: "cerebras",
+		apiKey: process.env.CEREBRAS_API_KEY,
+		model: "gpt-oss-120b",
+		apiUrl: "https://api.cerebras.ai/v1",
 	},
 	{
 		name: "cerebras_2",
@@ -30,22 +30,22 @@ module.exports = [
 		apiUrl: "https://api.cerebras.ai/v1",
 	},
 	{
-		name: "cerebras",
-		apiKey: process.env.CEREBRAS_API_KEY,
-		model: "gpt-oss-120b",
-		apiUrl: "https://api.cerebras.ai/v1",
+		name: "openrouter",
+		apiKey: process.env.OPENROUTER_API_KEY,
+		model: "qwen/qwen3-coder:free",
+		apiUrl: "https://openrouter.ai/api/v1",
 	},
 	{
-		name: "openrouter_2",
-		apiKey: process.env.OPENROUTER_API_KEY_2,
+		name: "openrouter",
+		apiKey: process.env.OPENROUTER_API_KEY,
 		model: "z-ai/glm-4.5-air:free",
 		apiUrl: "https://openrouter.ai/api/v1",
 	},
 	{
-		name: "qroq",
-		apiKey: process.env.QROQ_API_KEY,
-		model: "openai/gpt-oss-120b",
-		apiUrl: "https://api.groq.com/openai/v1",
+		name: "openrouter_2",
+		apiKey: process.env.OPENROUTER_API_KEY_2,
+		model: "z-ai/glm-4.5-air:free",
+		apiUrl: "https://openrouter.ai/api/v1",
 	},
 	{
 		name: "openrouter_2",
@@ -53,12 +53,24 @@ module.exports = [
 		model: "qwen/qwen3-coder:free",
 		apiUrl: "https://openrouter.ai/api/v1",
 	},
+	{
+		name: "openrouter_3",
+		apiKey: process.env.OPENROUTER_API_KEY_3,
+		model: "qwen/qwen3-coder:free",
+		apiUrl: "https://openrouter.ai/api/v1",
+	},
 	{
 		name: "openrouter_3",
 		apiKey: process.env.OPENROUTER_API_KEY_3,
 		model: "z-ai/glm-4.5-air:free",
 		apiUrl: "https://openrouter.ai/api/v1",
 	},
+	{
+		name: "qroq",
+		apiKey: process.env.QROQ_API_KEY,
+		model: "openai/gpt-oss-120b",
+		apiUrl: "https://api.groq.com/openai/v1",
+	},
 	{
 		name: "gemini_1",
 		apiKey: process.env.GEMINI_API_KEY,

package/readme.md

@@ -22,6 +22,7 @@ It supports all the OpenAI-compatible servers, including major providers like Op
 
 - **Multi-Provider Support**: Works with OpenAI, Google, Grok, OpenRouter, Z.ai, Qroq, Cohere, Cerebras, LLM7 and etc
 - **Automatic Fallback**: If one provider fails for **any reason**, automatically tries the next
+- **Circuit Breaker**: Built-in fault tolerance with automatic circuit breaking for each provider to prevent cascading failures
 - **OpenAI-Compatible Server**: Drop-in replacement for the OpenAI API, enabling easy integration with existing tools and clients
 - **Simple API**: Easy-to-use interface for all supported providers
 - **Streaming and Non-Streaming Support**: Handles both streaming and non-streaming responses