feat: add openrouter provider (#107)

* Add openrouter configs in default models
* Improve metadata and logging for better debugging
* Add openrouter in react playground example
* Fix fallback logic - retry a provider only when it is configured properly i.e. has api key if auth mandatory
* Update docs and readme

Author: gitcommitshow

README.md

@@ -15,7 +15,7 @@ Check out [examples](./examples/), ready to ship.
 
 ### Key Features
 
-- **Unified API**: One `.chat()` works seamlessly across OpenAI, Anthropic, Google, Ollama, and custom providers
+- **Unified API**: One `.chat()` works seamlessly across OpenAI, Anthropic, Google, OpenRouter, Ollama, and custom providers
 - **Built-in Resilience**: Automatic retries, exponential backoff, and circuit breakers handle failures gracefully
 - **Token Bucket Algorithm**: Automatically enforces provider rate limits intelligently
 - **Automatic Token Counting**: Accurate token estimation for every request, no manual calculation needed
@@ -33,7 +33,7 @@ npm i resilient-llm
 import { ResilientLLM } from 'resilient-llm';
 
 const llm = new ResilientLLM({
-  aiService: 'openai', // or 'anthropic', 'google', 'ollama'
+  aiService: 'openai', // or 'anthropic', 'google', 'openrouter', 'ollama'
   model: 'gpt-5-nano',
   maxTokens: 2048,
   temperature: 0.7,
@@ -151,7 +151,7 @@ For all supported shapes (including plain schema objects) and parsing/validation
 
 ## Supported LLM Providers
 
-ResilientLLM comes with built-in support for all text chat completiion models provided by **OpenAI**, **Anthropic**, **Google/Gemini**, **Ollama** API, etc.
+ResilientLLM comes with built-in support for all text chat completion models provided by **OpenAI**, **Anthropic**, **Google/Gemini**, **OpenRouter**, and **Ollama** APIs.
 
 **Adding custom providers:** You can add support for other LLM providers (e.g., Together AI, Groq, self-hosted vLLM, or any OpenAI/Anthropic-compatible API) using `ProviderRegistry.configure()`. See the [Custom Provider Guide](./docs/custom-providers.md) for detailed instructions and examples.
 
@@ -164,11 +164,41 @@ The simplest way is using environment variables:
 export OPENAI_API_KEY=sk-your-key-here
 export ANTHROPIC_API_KEY=sk-ant-your-key-here
 export GOOGLE_API_KEY=your-key-here
+export OPENROUTER_API_KEY=your-key-here
 export OLLAMA_API_KEY=your-key-here
 ```
 
 For more ways to configure API key, see the [API Key Configuration guide](./docs/reference.md#api-key-configuration) in the reference documentation.
 
+## Free LLM API Setup
+
+You can try ResilientLLM without paid provider keys using [OpenRouter](https://openrouter.ai/) free models. OpenRouter routes requests to free models (with rate limits); no credit card is required to sign up.
+
+1. Sign up at [openrouter.ai](https://openrouter.ai/) (email or GitHub).
+2. Open **Keys** in the dashboard ([openrouter.ai/keys](https://openrouter.ai/keys)).
+3. Click **Create Key**, give it a name, and copy the key (starts with `sk-or-`).
+
+You can then use `openrouter/free` model which randomly selects a free model.
+
+
+```javascript
+import { ResilientLLM } from 'resilient-llm';
+
+const llm = new ResilientLLM({
+  aiService: 'openrouter',
+  model: 'openrouter/free',
+  apiKey: 'sk-or-***'
+});
+
+const { content } = await llm.chat([
+  { role: 'user', content: 'What is the capital of France?' }
+]);
+
+console.log(content);
+```
+
+The output might be extremely poor with `openrouter/free` model. If so, try a specific [free model from this list](https://openrouter.ai/models?max_price=0&output_modalities=text) or use a one of the [popular paid models](https://openrouter.ai/models?output_modalities=text&order=most-popular).
+
 ## Examples and Playground
 
 Complete working projects using Resilient LLM as core library to call LLM APIs with resilience.

docs/custom-providers.md

@@ -8,6 +8,7 @@ ResilientLLM uses a `ProviderRegistry` to manage LLM providers. By default, it i
 - OpenAI
 - Anthropic (Claude)
 - Google (Gemini)
+- OpenRouter
 - Ollama
 
 You can extend this by adding your own providers, such as:
@@ -16,6 +17,19 @@ You can extend this by adding your own providers, such as:
 - Custom API endpoints
 - Other LLM providers with compatible interfaces
 
+### Using built-in OpenRouter
+
+OpenRouter is supported as a built-in provider through `aiService: 'openrouter'`:
+
+```javascript
+import { ResilientLLM } from 'resilient-llm';
+
+const llm = new ResilientLLM({
+  aiService: 'openrouter',
+  model: 'openrouter/free' // or any OpenRouter model ID (provider/model e.g. openai/gpt-5-nano)
+});
+```
+
 ## Quick Start
 
 The simplest way to add a custom provider is using `ProviderRegistry.configure()`:

docs/reference.md

@@ -18,7 +18,7 @@ Complete technical reference for the ResilientLLM library API.
 
 ## ResilientLLM
 
-A unified interface for interacting with multiple LLM providers (OpenAI, Anthropic, Google/Gemini, Ollama) with built-in resilience features including rate limiting, retries, circuit breakers, and error handling.
+A unified interface for interacting with multiple LLM providers (OpenAI, Anthropic, Google/Gemini, OpenRouter, Ollama) with built-in resilience features including rate limiting, retries, circuit breakers, and error handling.
 
 ### ResilientLLM Constructor
 
@@ -39,7 +39,7 @@ new ResilientLLM(options?: ResilientLLMOptions)
 
 | Property | Type | Required | Default | Description |
 |----------|------|----------|---------|-------------|
-| `aiService` | `string` | No | `process.env.PREFERRED_AI_SERVICE` or `"anthropic"` | AI service provider: `"openai"`, `"anthropic"`, `"google"`, or `"ollama"` |
+| `aiService` | `string` | No | `process.env.PREFERRED_AI_SERVICE` or `"anthropic"` | AI service provider: `"openai"`, `"anthropic"`, `"google"`, `"openrouter"`, or `"ollama"` |
 | `model` | `string` | No | `process.env.PREFERRED_AI_MODEL` or `"claude-3-5-sonnet-20240620"` | Model identifier for the selected AI service |
 | `temperature` | `number` | No | `process.env.AI_TEMPERATURE` or `0` | Temperature parameter (0-2) controlling randomness in responses |
 | `maxTokens` | `number` | No | `process.env.MAX_TOKENS` or `2048` | Maximum number of tokens in the response |
@@ -304,9 +304,21 @@ parseError(statusCode: number | null, error: Error, operationMetadata?: Operatio
 | `error` | `Error` | Yes | Underlying error |
 | `operationMetadata` | `OperationMetadata \| null` | No | Merged onto the thrown error’s `metadata` |
 
-**Returns:** `never` — always throws **`ResilientLLMError`**.
+**Status Code Mappings:**
 
-If `error` is already a **`ResilientLLMError`**, it is rethrown (metadata may be merged). Otherwise **`statusCode`** selects a **`PROVIDER_*`** code (e.g. `401` → `PROVIDER_UNAUTHORIZED`); `null` or unknown statuses map to **`PROVIDER_ERROR`**. See [`lib/ResilientLLMError.ts`](../lib/ResilientLLMError.ts) for the full `ResilientLLMErrorCode` union.
+| Status Code | Error Message |
+|------------|---------------|
+| `400` | "Bad request" |
+| `401` | "Invalid API Key" |
+| `403` | "You are not authorized to access this resource" |
+| `404` | "Not found" |
+| `429` | "Rate limit exceeded" |
+| `500` | "Internal server error" |
+| `503` | "Service unavailable" |
+| `529` | "API temporarily overloaded" |
+| Other | "Unknown error" |
+
+**Note:** This method is called internally by the `chat()` method when errors occur. You typically don't need to call it directly.
 
 ---
 
@@ -784,6 +796,7 @@ Set at least one API key for your chosen service:
 | `OPENAI_API_KEY` | OpenAI | Yes (if using OpenAI) |
 | `ANTHROPIC_API_KEY` | Anthropic | Yes (if using Anthropic) |
 | `GOOGLE_API_KEY` or `GOOGLE_GENERATIVE_AI` or `GEMINI_API_KEY` | Google | Yes (if using Google) |
+| `OPENROUTER_API_KEY` | OpenRouter | Yes (if using OpenRouter) |
 | `OLLAMA_API_KEY` | Ollama | No (optional) |
 
 **Note:** For custom providers, use the environment variable names specified in `ProviderRegistry.configure()` via `envVarNames`.
@@ -800,6 +813,8 @@ Set at least one API key for your chosen service:
 | `MAX_INPUT_TOKENS` | `100000` | Default max input tokens |
 | `AI_TOP_P` | `0.95` | Default top-p value |
 | `OLLAMA_API_URL` | `"http://localhost:11434/api/generate"` | Ollama API URL |
+| `OPENROUTER_HTTP_REFERER` | `undefined` | Optional attribution header (`HTTP-Referer`) for OpenRouter |
+| `OPENROUTER_APP_TITLE` | `undefined` | Optional attribution header (`X-Title`) for OpenRouter |
 | `STORE_AI_API_CALLS` | `undefined` | Set to `"true"` to store API calls (OpenAI) |
 
 ---
@@ -998,6 +1013,14 @@ See [Custom Provider Guide](./custom-providers.md) for details on configuring pr
 - Uses standard `Authorization: Bearer <token>` header
 - Can store API calls if `STORE_AI_API_CALLS=true`
 
+### OpenRouter
+
+- Uses OpenAI-compatible endpoint `https://openrouter.ai/api/v1/chat/completions`
+- Uses `Authorization: Bearer <token>` header
+- Works with provider-prefixed model IDs (for example `openai/gpt-5-nano` or `openai/o1`)
+- Choosing `openrouter/free` model will select a free model, but the quality might degrade severly
+- Optional attribution headers can be set via `OPENROUTER_HTTP_REFERER` and `OPENROUTER_APP_TITLE`
+
 ### Google
 
 - Uses OpenAI-compatible endpoint

examples/playground-react/client/utils/providerUtils.js

@@ -15,6 +15,7 @@ export const PROVIDER_DISPLAY_NAMES = {
     openai: 'OpenAI',
     anthropic: 'Anthropic',
     google: 'Google',
+    openrouter: 'OpenRouter',
     ollama: 'Ollama',
     local: 'Local / Other' // Special case for UI
 };
@@ -36,7 +37,7 @@ export function getProviderDisplayName(providerId) {
  * @returns {string[]} Array of provider IDs
  */
 export function getProviderIds() {
-    return ['openai', 'anthropic', 'google', 'ollama'];
+    return ['openai', 'anthropic', 'google', 'openrouter', 'ollama'];
 }
 
 /**

lib/ProviderRegistry.ts

@@ -66,7 +66,7 @@ export interface ConfigureInput {
 /**
  * Unified model schema (normalized across providers).
  * @property id - Model identifier (e.g. 'gpt-4o', 'claude-3-5-sonnet-20241022')
- * @property provider - Provider name ('openai', 'anthropic', 'google', 'ollama')
+ * @property provider - Provider name ('openai', 'anthropic', 'google', 'openrouter', 'ollama')
  * @property name - Display name (if available from API)
  * @property contextWindow - Maximum tokens limit (if available from API, e.g. Gemini)
  * @property raw - Full raw API response for this model
@@ -91,7 +91,7 @@ class ProviderRegistry {
     /** Runtime API keys (stored separately from config to avoid serialization). Map<providerName, apiKey> */
     static #apiKeys = new Map<string, string>();
 
-    /** Default provider configurations (openai, anthropic, google, ollama). */
+    /** Default provider configurations (openai, anthropic, google, openrouter, ollama). */
     static DEFAULT_PROVIDERS: Record<string, ProviderConfig> = {
         openai: {
             name: 'openai',
@@ -201,6 +201,41 @@ class ProviderRegistry {
             },
             active: true
         },
+        openrouter: {
+            name: 'openrouter',
+            displayName: 'OpenRouter',
+            chatApiUrl: 'https://openrouter.ai/api/v1/chat/completions',
+            modelsApiUrl: 'https://openrouter.ai/api/v1/models',
+            docsUrl: 'https://openrouter.ai/docs/api/api-reference/chat/send-chat-completion-request',
+            envVarNames: ['OPENROUTER_API_KEY'],
+            defaultModel: 'openrouter/free',
+            apiVersion: null,
+            iconUrl: null,
+            customHeaders: {
+                ...(process.env.OPENROUTER_HTTP_REFERER ? { 'HTTP-Referer': process.env.OPENROUTER_HTTP_REFERER } : {}),
+                ...(process.env.OPENROUTER_APP_TITLE ? { 'X-Title': process.env.OPENROUTER_APP_TITLE } : {})
+            },
+            authConfig: {
+                type: 'header',
+                headerName: 'Authorization',
+                headerFormat: 'Bearer {key}'
+            },
+            parseConfig: {
+                modelsPath: 'data',
+                idField: 'id',
+                nameField: 'id',
+                displayNameField: 'name',
+                contextWindowField: 'context_length',
+                idPrefix: null
+            },
+            chatConfig: {
+                messageFormat: 'openai',
+                responseParsePath: 'choices[0].message.content',
+                toolSchemaType: 'openai',
+                structuredOutputRequestField: 'response_format',
+            },
+            active: true
+        },
         ollama: {
             name: 'ollama',
             displayName: 'Ollama',