ai-requests-adapter 2.2.0 → 3.0.0

package/README.md

@@ -1,6 +1,44 @@
-# AI Requests Adapter
+# ai-requests-adapter (v3.0)
 
-A unified chat-style transformer SDK for handling AI API requests across multiple providers. This SDK provides a single input format (Chat Completions-style) and transforms it into vendor-specific API payloads, making it easy to work with different AI services through a consistent interface.
+A **provider/API transformer** that takes **one unified input shape** (OpenAI **Chat Completions–style** request) and **adapts** it into the **vendor + API-specific request payload** you actually send (OpenAI Responses vs Chat Completions, Anthropic Messages, Gemini generateContent, Groq OpenAI-compat, xAI OpenAI-compat, Moonshot Kimi OpenAI-compat, etc.).
+
+This package is designed to remove "model config broke again" problems by driving behavior from a **capabilities JSON registry**.
+
+---
+
+## Why v3.0
+
+**v3.0** makes one thing explicit:
+
+- Your **unified input is chat-completions style** (what you already have).
+- The library is an **adapter/transformer** (not a normalizer).
+- Provider/model behavior is defined in **metadata JSON**, not scattered conditionals.
+
+---
+
+## Unified Input Form (what you pass in)
+
+The unified input is intentionally **OpenAI Chat Completions–like**:
+
+```ts
+type UnifiedChatCompletionsLikeRequest = {
+  model: string;
+  messages: Array<{ role: "system"|"user"|"assistant"|"tool"; content: string }>;
+
+  max_tokens?: number;
+  temperature?: number;
+  top_p?: number;
+  frequency_penalty?: number;
+  presence_penalty?: number;
+  stop?: string[] | string;
+
+  // optional reasoning knob (used when target supports it)
+  reasoning_effort?: "none"|"minimal"|"low"|"medium"|"high";
+
+  // vendor-specific passthrough namespace
+  extra?: Record<string, any>;
+};
+```
 
 ## Installation
 
@@ -13,114 +51,100 @@ npm install ai-requests-adapter
 ```typescript
 import { transformToVendorRequest } from 'ai-requests-adapter';
 
-// Transform a unified chat-style request to vendor-specific API payload
-const result = transformToVendorRequest({
+// Your unified request (chat-completions style)
+const request = {
   provider: 'openai',
   model: 'gpt-5.2',
   messages: [
     { role: 'system', content: 'You are helpful.' },
-    { role: 'user', content: 'Hello, how are you?' }
+    { role: 'user', content: 'Hello!' }
   ],
   max_tokens: 200,
-  reasoning: { effort: 'medium' },
-  temperature: 0.2
-});
-
-console.log(result.api);        // "responses"
-console.log(result.payload);    // Ready-to-send OpenAI Responses API payload
-console.log(result.warnings);   // Any transformation warnings
-```
-
-## Core Concept
-
-**One unified input format** → **Transformer** → **Vendor + API specific payload**
+  reasoning_effort: 'medium'
+};
 
-Your gateway always receives Chat Completions-style requests:
+// Transform to vendor-specific payload
+const { provider, apiVariant, request: vendorRequest, warnings } = transformToVendorRequest(
+  request,
+  { provider: 'openai' } // target override if needed
+);
 
-```typescript
-{
-  provider: 'openai' | 'anthropic' | 'google' | 'xai',
-  model: string,
-  messages: [{ role: 'system'|'developer'|'user'|'assistant', content: string }, ...],
-  temperature?, top_p?, max_tokens?, frequency_penalty?, presence_penalty?, stop?, tools?, reasoning?
-}
+console.log(apiVariant);    // "responses"
+console.log(vendorRequest); // Ready-to-send OpenAI Responses API payload
+console.log(warnings);      // Any parameter filtering warnings
 ```
 
-The transformer outputs the exact payload needed for each vendor's API.
-
 ## API Reference
 
 ### Main Function
 
-#### `transformToVendorRequest(request, registry?)`
+#### `transformToVendorRequest(unifiedRequest, target, registry?)`
 
-Transforms a unified chat-style request into a vendor-specific API payload.
+The core transformer function.
 
 ```typescript
 import { transformToVendorRequest } from 'ai-requests-adapter';
 
-const result = transformToVendorRequest(unifiedRequest, customRegistry?);
+const { provider, apiVariant, request, warnings } = transformToVendorRequest(
+  unifiedRequest,  // UnifiedChatCompletionsLikeRequest
+  target,          // Target (provider + optional apiVariant)
+  registry?        // Optional custom registry
+);
 ```
 
 **Parameters:**
-- `request: UnifiedChatRequest` - The unified chat-style request
-- `registry?: CapabilitiesRegistry` - Optional custom capabilities registry
-
-**Returns:** `BuiltVendorRequest`
-- `provider: string` - The provider (e.g., 'openai')
-- `api: string` - The API endpoint (e.g., 'responses', 'chat_completions')
-- `payload: Record<string, any>` - Ready-to-send API payload
-- `warnings: string[]` - Any transformation warnings
-
-### Types
-
-#### `UnifiedChatRequest`
-
-The single input format your gateway accepts:
+- `unifiedRequest: UnifiedChatCompletionsLikeRequest` - Your chat-completions-style request
+- `target: Target` - Which provider/API to target
+- `registry?: Registry` - Custom capabilities registry (uses built-in by default)
 
+**Returns:**
 ```typescript
-type UnifiedChatRequest = {
-  provider: 'openai' | 'anthropic' | 'google' | 'xai';
-  model: string;
-  messages: Array<{
-    role: 'system' | 'developer' | 'user' | 'assistant';
-    content: string;
-  }>;
-
-  // Chat-style config (snake_case primary, camelCase accepted):
-  temperature?: number;
-  top_p?: number;
-  max_tokens?: number;
-  frequency_penalty?: number;
-  presence_penalty?: number;
-  stop?: string[] | string;
-  tools?: unknown[];
+{
+  provider: ProviderKey;     // 'openai' | 'anthropic' | etc.
+  apiVariant: string;        // 'responses' | 'chat_completions' | 'messages' | etc.
+  request: Record<string, any>; // Ready-to-send vendor API payload
+  warnings?: string[];       // Parameter filtering warnings
+}
+```
 
-  reasoning?: { effort?: 'none'|'minimal'|'low'|'medium'|'high' };
-  reasoning_effort?: 'none'|'minimal'|'low'|'medium'|'high';
-  reasoningEffort?: 'none'|'minimal'|'low'|'medium'|'high';
+### Target Specification
 
-  // Future keys allowed
-  [k: string]: unknown;
+```typescript
+type Target = {
+  provider: ProviderKey;
+  apiVariant?: string; // If omitted, uses model default from registry
 };
+
+type ProviderKey = 'openai' | 'anthropic' | 'google' | 'groq' | 'xai' | 'moonshot_kimi';
 ```
 
-### OpenAI Examples
+## Provider Examples
 
-#### GPT-5.2 with Responses API
+### OpenAI (Responses API)
 
 ```typescript
-const result = transformToVendorRequest({
-  provider: 'openai',
-  model: 'gpt-5.2',
-  messages: [
-    { role: 'system', content: 'You are helpful.' },
-    { role: 'developer', content: 'Return JSON only.' },
-    { role: 'user', content: 'Hello' }
-  ],
-  max_tokens: 200,
-  reasoning: { effort: 'medium' },
-  temperature: 0.2  // Will be omitted (conditional on reasoning_effort='none')
+const { request } = transformToVendorRequest(
+  {
+    model: 'gpt-5.2',
+    messages: [
+      { role: 'system', content: 'You are helpful.' },
+      { role: 'user', content: 'Hello' }
+    ],
+    max_tokens: 200,
+    reasoning_effort: 'medium',
+    temperature: 0.2  // Omitted: conditional on reasoning_effort='none'
+  },
+  { provider: 'openai' }
+);
+
+// Result: apiVariant = "responses"
+// request = {
+//   model: 'gpt-5.2',
+//   instructions: 'You are helpful.',
+//   input: [{ role: 'user', content: 'Hello' }],
+//   max_output_tokens: 200,
+//   reasoning: { effort: 'medium' }
+// }
 });
 
 console.log(result.api); // "responses"
@@ -168,16 +192,94 @@ console.log(result.payload);
 */
 ```
 
+### Anthropic (Messages API)
+
+```typescript
+const { request } = transformToVendorRequest(
+  {
+    model: 'claude-sonnet-4-5-20250929',
+    messages: [
+      { role: 'system', content: 'You are helpful.' },
+      { role: 'user', content: 'Hello' }
+    ],
+    max_tokens: 200,
+    temperature: 0.7
+  },
+  { provider: 'anthropic' }
+);
+
+// Result: apiVariant = "messages"
+// request = {
+//   system: 'You are helpful.',
+//   messages: [{ role: 'user', content: 'Hello' }],
+//   max_tokens: 200,
+//   temperature: 0.7
+// }
+```
+
+### Google Gemini (Native API)
+
+```typescript
+const { request } = transformToVendorRequest(
+  {
+    model: 'gemini-2.0-flash',
+    messages: [
+      { role: 'system', content: 'You are helpful.' },
+      { role: 'user', content: 'Hello' }
+    ],
+    max_tokens: 200,
+    temperature: 0.7
+  },
+  { provider: 'google' }
+);
+
+// Result: apiVariant = "gemini_generateContent"
+// request = {
+//   systemInstruction: { role: 'system', parts: [{ text: 'You are helpful.' }] },
+//   contents: [{ role: 'user', parts: [{ text: 'Hello' }] }],
+//   generationConfig: { maxOutputTokens: 200, temperature: 0.7 }
+// }
+```
+
+### Groq (OpenAI Compatible)
+
+```typescript
+const { request } = transformToVendorRequest(
+  {
+    model: 'llama-3.3-70b-versatile',
+    messages: [
+      { role: 'user', content: 'Hello' }
+    ],
+    max_tokens: 200,
+    temperature: 0.7
+  },
+  { provider: 'groq' }
+);
+
+// Result: apiVariant = "openai_chat_completions"
+// request = {
+//   model: 'llama-3.3-70b-versatile',
+//   messages: [{ role: 'user', content: 'Hello' }],
+//   max_tokens: 200,
+//   temperature: 0.7
+// }
+```
+
 ## Capabilities Registry
 
-The SDK uses a capabilities registry to determine how to transform requests based on provider and model capabilities.
+Provider/model behavior is defined in JSON, not code. The registry handles:
+
+- **API variant selection** (Responses vs Chat Completions, etc.)
+- **Parameter mapping** (`max_tokens` → `max_output_tokens`)
+- **Capability filtering** (unsupported params are dropped)
+- **Conditional rules** (temperature only when reasoning_effort='none')
+- **Fallback resolution** (exact → pattern → provider defaults)
 
 ### Built-in Registry
 
 ```typescript
 import { capabilities } from 'ai-requests-adapter';
 
-// Access the default registry
 console.log(capabilities.providers.openai.models['gpt-5.2']);
 ```
 
@@ -185,70 +287,42 @@ console.log(capabilities.providers.openai.models['gpt-5.2']);
 
 ```typescript
 import { transformToVendorRequest } from 'ai-requests-adapter';
+import { loadRegistry } from 'ai-requests-adapter';
 
-const customCapabilities = {
-  providers: {
-    openai: {
-      schemaVersion: '2025-12-24',
-      defaults: {
-        tokenParamByApi: {
-          responses: 'max_output_tokens',
-          chat_completions: 'max_tokens'
-        }
-      },
-      models: {
-        'my-custom-model': {
-          api: 'responses',
-          reasoningEffort: { supported: true },
-          sampling: { temperature: { supported: true }, top_p: { supported: true } },
-          penalties: { frequency: false, presence: false },
-          stop: { supported: true }
-        }
-      }
-    }
-  }
-};
-
-const result = transformToVendorRequest(request, customCapabilities);
+const customRegistry = loadRegistry(); // Or build your own
+const result = transformToVendorRequest(unifiedRequest, target, customRegistry);
 ```
 
-## Legacy API (Deprecated)
+## Gateway Integration
 
-The old adapter pattern is still available but deprecated. Use the transformer API instead.
-
-```typescript
-import { AIRequestsAdapter, createAIAdapter } from 'ai-requests-adapter';
-
-// Legacy usage (deprecated)
-const adapter = createAIAdapter();
-adapter.registerProvider('openai', openAIProvider);
-const response = await adapter.sendRequest(request);
-```
-
-## Integration Example
-
-Here's how to integrate with your gateway:
+Your gateway accepts the unified format and routes to vendor APIs:
 
 ```typescript
 import { transformToVendorRequest } from 'ai-requests-adapter';
 
-// Your gateway endpoint
 app.post('/api/chat', async (req, res) => {
   try {
-    // req.body is already in UnifiedChatRequest format
-    const { provider, api, payload, warnings } = transformToVendorRequest(req.body);
+    // req.body is UnifiedChatCompletionsLikeRequest
+    const { provider, apiVariant, request, warnings } = transformToVendorRequest(
+      req.body,
+      { provider: req.body.provider || 'openai' }
+    );
 
-    // Route to appropriate vendor SDK
+    // Route to vendor SDK
     let response;
     switch (provider) {
       case 'openai':
-        if (api === 'responses') {
-          response = await openai.responses.create(payload);
-        } else {
-          response = await openai.chat.completions.create(payload);
-        }
+        response = apiVariant === 'responses'
+          ? await openai.responses.create(request)
+          : await openai.chat.completions.create(request);
+        break;
+      case 'anthropic':
+        response = await anthropic.messages.create(request);
+        break;
+      case 'google':
+        response = await google.generativeAI.generateContent(request);
         break;
-      // Handle other providers...
+      // ... other providers
     }
 
     res.json({ response, warnings });
@@ -258,13 +332,24 @@ app.post('/api/chat', async (req, res) => {
 });
 ```
 
+## Provider Support Matrix
+
+| Provider | API Variants | Message Format | Token Param | Notes |
+|----------|-------------|----------------|-------------|--------|
+| **OpenAI** | `responses`, `chat_completions` | Standard + developer role merging | `max_output_tokens`, `max_tokens` | Reasoning effort, conditional sampling |
+| **Anthropic** | `messages` | System as top-level field | `max_tokens` | Mutual exclusion rules (Claude 4.5) |
+| **Google** | `gemini_generateContent`, `gemini_openai_compat` | Native contents format | `generationConfig.maxOutputTokens` | System as systemInstruction |
+| **Groq** | `openai_chat_completions` | Standard | `max_tokens` | OpenAI-compatible |
+| **xAI** | `openai_chat_completions` | Standard | `max_tokens` | OpenAI-compatible |
+| **Moonshot** | `openai_chat_completions` | Standard | `max_tokens` | OpenAI-compatible |
+
 ## Contributing
 
-Contributions are welcome! The transformer system is designed to be extensible:
+Add new providers by:
 
-- Add new providers to the capabilities registry
-- Implement vendor-specific payload builders
-- Extend the reasoning effort and sampling rules
+1. **Create provider config JSON** in the registry
+2. **Add message transformation logic** in `transformUnifiedRequest()`
+3. **Update API variants** with token/stop param mappings
 
 ## License
 

package/dist/capabilities.d.ts

@@ -1,3 +1,4 @@
-import type { CapabilitiesRegistry } from './chat-style-transformer';
-export declare const capabilities: CapabilitiesRegistry;
+import type { Registry } from './chat-style-transformer';
+export declare const capabilities: Registry;
+export declare function loadRegistry(): Registry;
 //# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAErE,eAAO,MAAM,YAAY,EAAE,oBAwD1B,CAAC"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAMzD,eAAO,MAAM,YAAY,EAAE,QAoP1B,CAAC;AAKF,wBAAgB,YAAY,IAAI,QAAQ,CAEvC"}