@revenium/perplexity 1.0.22 → 1.0.25

package/README.md

@@ -5,17 +5,24 @@
 [![Documentation](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://docs.revenium.io)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Automatically track and meter your Perplexity AI API usage with Revenium. This middleware provides seamless integration with Perplexity AI SDK, requiring minimal code changes.
+Automatically track and meter your Perplexity AI API usage with Revenium. This package provides seamless integration with Perplexity AI API using modern Controller architecture, supporting both V1 (compatible) and V2 (enhanced) response formats.
+
+## 🎯 **New Architecture: V1 & V2 Controllers**
+
+- **V1 Controller**: Maintains compatibility with existing middleware logic
+- **V2 Controller**: Enhanced response format following [OpenAI Responses API](https://platform.openai.com/docs/guides/migrate-to-responses) guidelines
+- **Service Layer**: Handles API calls, metering, and data transformation
+- **Rich Examples**: TypeScript examples and JavaScript playground files
 
 ## 🚀 Getting Started
 
-You have 3 options to start using Revenium middleware for Perplexity AI:
+You have 3 options to start using Revenium Controllers for Perplexity AI:
 
-| Option                                    | Description                                                                         | Best For                                                             |
-| ----------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| **Option 1: Create Project from Scratch** | Perfect for new projects. We'll guide you step-by-step from mkdir to running tests. | 👉 [Go to Step-by-Step Guide](#option-1-create-project-from-scratch) |
-| **Option 2: Clone Our Repository**        | Quick testing with pre-built examples and playground scripts.                       | 👉 [Go to Clone Guide](#option-2-clone-repository)                   |
-| **Option 3: Add to Existing Project**     | Already have a project? Just install and replace imports.                           | 👉 [Go to Quick Integration](#option-3-existing-project-integration) |
+| Option                                    | Description                                                                        | Best For                                                             |
+| ----------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| **Option 1: Create Project from Scratch** | Perfect for new projects. We'll guide you step-by-step using V1 or V2 Controllers. | 👉 [Go to Step-by-Step Guide](#option-1-create-project-from-scratch) |
+| **Option 2: Clone Our Repository**        | Quick testing with pre-built V1/V2 examples and playground scripts.                | 👉 [Go to Clone Guide](#option-2-clone-repository)                   |
+| **Option 3: Add to Existing Project**     | Already have a project? Just install and use Controllers.                          | 👉 [Go to Quick Integration](#option-3-existing-project-integration) |
 
 ---
 
@@ -65,36 +72,67 @@ REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"
 
 ### Step 4: Create Your First Test
 
-Create `test-perplexity.js`:
+Choose between V1 (compatible) or V2 (enhanced) Controller:
+
+#### Option A: V1 Controller (Compatible)
+
+Create `test-perplexity-v1.js`:
+
+```javascript
+// test-perplexity-v1.js
+import { PerplexityV1Controller } from "@revenium/perplexity";
+
+const basicV1Example = async () => {
+  try {
+    const controller = new PerplexityV1Controller();
+
+    const result = await controller.createChat(
+      ["What is the universe?"],
+      "sonar-pro"
+    );
+
+    console.log("*** V1 RESPONSE ***");
+    console.log(result.responses[0].text);
+    console.log(`📊 Tokens: ${result.usageMetadata.totalTokenCount}`);
+    console.log("✅ V1 Controller example successful!");
+  } catch (error) {
+    console.error("❌ V1 Controller example failed:", error);
+    process.exit(1);
+  }
+};
+
+basicV1Example();
+```
+
+#### Option B: V2 Controller (Enhanced)
+
+Create `test-perplexity-v2.js`:
 
 ```javascript
-// test-perplexity.js
-import { PerplexityReveniumMiddleware } from "@revenium/perplexity";
+// test-perplexity-v2.js
+import { PerplexityV2Controller } from "@revenium/perplexity";
 
-const basicExample = async () => {
+const basicV2Example = async () => {
   try {
-    const middleware = new PerplexityReveniumMiddleware();
-    const model = middleware.getGenerativeModel("sonar-pro");
-    const result = await model.createChatCompletion({
-      messages: [
-        {
-          role: "user",
-          content: "What is the universe?",
-        },
-      ],
-    });
-
-    const text = result.choices[0]?.message?.content;
-    console.log("*** RESPONSE ***");
-    console.log(text);
-    console.log("✅ Basic Perplexity AI example successful!");
+    const controller = new PerplexityV2Controller();
+
+    const result = await controller.createChat(
+      ["What is the universe?"],
+      "sonar-pro"
+    );
+
+    console.log("*** V2 ENHANCED RESPONSE ***");
+    console.log(result.choices[0].message.content);
+    console.log(`📊 Usage: ${result.usage.total_tokens} tokens`);
+    console.log(`⚡ Processing: ${result.metadata.processingTime}ms`);
+    console.log("✅ V2 Enhanced Controller example successful!");
   } catch (error) {
-    console.error("❌ Perplexity basic example failed:", error);
+    console.error("❌ V2 Controller example failed:", error);
     process.exit(1);
   }
 };
 
-basicExample();
+basicV2Example();
 ```
 
 ### Step 5: Update package.json
@@ -107,7 +145,8 @@ Add test scripts and module type to your `package.json`:
   "version": "1.0.0",
   "type": "module",
   "scripts": {
-    "test-perplexity": "node test-perplexity.js"
+    "test-v1": "node test-perplexity-v1.js",
+    "test-v2": "node test-perplexity-v2.js"
   },
   "dependencies": {
     "@revenium/perplexity": "^1.0.0"
@@ -132,8 +171,11 @@ Make sure your `package.json` includes `"type": "module"` as shown below.
 ### Step 6: Run Your Tests
 
 ```bash
-# Test Perplexity AI SDK
-npm run test-perplexity
+# Test V1 Controller (Compatible)
+npm run test-v1
+
+# Test V2 Controller (Enhanced)
+npm run test-v2
 ```
 
 ### Step 7: Create Advanced Examples
@@ -144,99 +186,164 @@ Create an examples directory and add these files:
 mkdir examples
 ```
 
-#### Streaming Example
+#### V1 Streaming Example
 
-Create `examples/streaming-perplexity.js`:
+Create `examples/streaming-v1.js`:
 
 ```javascript
-// examples/streaming-perplexity.js
-import { PerplexityReveniumMiddleware } from "@revenium/perplexity";
+// examples/streaming-v1.js
+import { PerplexityV1Controller } from "@revenium/perplexity";
 
-const streamingExample = async () => {
+const streamingV1Example = async () => {
   try {
-    const middleware = new PerplexityReveniumMiddleware();
-    const model = middleware.getGenerativeModel("sonar-pro");
-    const stream = await model.createChatCompletionStream({
-      messages: [
-        {
-          role: "user",
-          content: "What is artificial intelligence?",
-        },
-      ],
-    });
-
-    console.log("*** STREAMING RESPONSE ***");
+    const controller = new PerplexityV1Controller();
+
+    const stream = await controller.createStreaming(
+      ["What is artificial intelligence?"],
+      "sonar-pro"
+    );
+
+    console.log("*** V1 STREAMING RESPONSE ***");
     let fullText = "";
 
     for await (const chunk of stream) {
-      const content = chunk.choices[0]?.delta?.content;
+      if (chunk.text) {
+        process.stdout.write(chunk.text);
+        fullText += chunk.text;
+      }
+    }
+
+    console.log("\n✅ V1 Streaming with metering successful!");
+    console.log(`📊 Total response length: ${fullText.length} characters`);
+  } catch (error) {
+    console.error("❌ V1 streaming example failed:", error);
+    process.exit(1);
+  }
+};
+
+streamingV1Example();
+```
+
+#### V2 Streaming Example
+
+Create `examples/streaming-v2.js`:
+
+```javascript
+// examples/streaming-v2.js
+import { PerplexityV2Controller } from "@revenium/perplexity";
+
+const streamingV2Example = async () => {
+  try {
+    const controller = new PerplexityV2Controller();
+
+    const stream = await controller.createStreaming(
+      ["What is artificial intelligence?"],
+      "sonar-pro"
+    );
+
+    console.log("*** V2 ENHANCED STREAMING RESPONSE ***");
+    let fullText = "";
+
+    for await (const chunk of stream) {
+      const content = chunk.choices?.[0]?.delta?.content;
       if (content) {
         process.stdout.write(content);
         fullText += content;
       }
     }
 
-    console.log("\n✅ Streaming with metering successful!");
+    console.log("\n✅ V2 Enhanced Streaming successful!");
     console.log(`📊 Total response length: ${fullText.length} characters`);
   } catch (error) {
-    console.error("❌ Perplexity streaming example failed:", error);
+    console.error("❌ V2 streaming example failed:", error);
     process.exit(1);
   }
 };
 
-streamingExample();
+streamingV2Example();
 ```
 
-#### METADATA Example
+#### Metadata Example
 
-Create `examples/metadata-perplexity.js`:
+Create `examples/metadata-v1.js`:
 
 ```javascript
-// examples/metadata-perplexity.js
-import { PerplexityReveniumMiddleware } from "@revenium/perplexity";
+// examples/metadata-v1.js
+import { PerplexityV1Controller } from "@revenium/perplexity";
 
-const metadataExample = async () => {
+const metadataV1Example = async () => {
   try {
-    const middleware = new PerplexityReveniumMiddleware();
-    const model = middleware.getGenerativeModel("sonar-pro");
-    const result = await model.createChatCompletion({
-      model: "sonar-pro",
-      messages: [{ role: "user", content: "What is the capital of France?" }],
-      usageMetadata: {
-        taskType: "test",
-        subscriberEmail: "test@revenium.ai",
-        subscriberId: "123456",
-        subscriberCredentialName: "apiKey",
-        subscriberCredential: "keyValue",
-        organizationId: "123456",
-        subscriptionId: "123456",
-        productId: "free-trial",
-        agent: "perplexity",
-        responseQualityScore: 100,
-        transactionId: "123456",
-        timeToFirstToken: 1000,
-        requestTime: new Date(),
-        completionStartTime: new Date(),
-        operationType: "CHAT",
-        inputTokenCount: 10,
-        outputTokenCount: 10,
-        reasoningTokenCount: 20,
-        cacheCreationTokenCount: 0,
-        cacheReadTokenCount: 0,
-        totalTokenCount: 40,
-        responseTime: new Date(),
-        requestDuration: 1000,
-        stopReason: "END",
-      },
-    });
-    console.log("[BASIC REQUEST]", result.choices[0].message);
+    const controller = new PerplexityV1Controller();
+
+    // Custom metadata for tracking
+    const customMetadata = {
+      traceId: "trace-12345",
+      taskType: "research-query",
+      subscriberEmail: "user@example.com",
+      subscriberId: "user-456",
+      organizationId: "org-789",
+      agent: "perplexity-v1-demo",
+    };
+
+    const result = await controller.createChat(
+      ["What is the capital of France?"],
+      "sonar-pro",
+      customMetadata
+    );
+
+    console.log("*** V1 RESPONSE WITH METADATA ***");
+    console.log(result.responses[0].text);
+    console.log(`📊 Tokens: ${result.usageMetadata.totalTokenCount}`);
+    console.log(`🏷️ Trace ID: ${customMetadata.traceId}`);
+    console.log("✅ V1 Metadata example successful!");
   } catch (error) {
-    console.error("❌ Perplexity streaming example failed:", error);
+    console.error("❌ V1 metadata example failed:", error);
     process.exit(1);
   }
 };
 
-metadataExample();
+metadataV1Example();
+```
+
+Create `examples/metadata-v2.js`:
+
+```javascript
+// examples/metadata-v2.js
+import { PerplexityV2Controller } from "@revenium/perplexity";
+
+const metadataV2Example = async () => {
+  try {
+    const controller = new PerplexityV2Controller();
+
+    // Enhanced metadata for V2
+    const customMetadata = {
+      traceId: "trace-v2-67890",
+      taskType: "enhanced-research",
+      subscriberEmail: "user@example.com",
+      subscriberId: "user-456",
+      organizationId: "org-789",
+      agent: "perplexity-v2-demo",
+    };
+
+    const result = await controller.createChat(
+      ["What is the capital of France?"],
+      "sonar-pro",
+      customMetadata
+    );
+
+    console.log("*** V2 ENHANCED RESPONSE WITH METADATA ***");
+    console.log(result.choices[0].message.content);
+    console.log(`📊 Usage: ${result.usage.total_tokens} tokens`);
+    console.log(`⚡ Processing: ${result.metadata.processingTime}ms`);
+    console.log(`🏷️ Trace ID: ${customMetadata.traceId}`);
+    console.log("✅ V2 Enhanced Metadata example successful!");
+  } catch (error) {
+    console.error("❌ V2 metadata example failed:", error);
+    process.exit(1);
+  }
+};
+
+metadataV2Example();
 ```
 
 ### Step 8: Update package.json
@@ -247,9 +354,12 @@ metadataExample();
   "version": "1.0.0",
   "type": "module",
   "scripts": {
-    "test-perplexity": "node test-perplexity.js",
-    "test-perplexity-stream": "node examples/streaming-perplexity.js",
-    "test-perplexity-metadata": "node examples/metadata-perplexity.js"
+    "test-v1": "node test-perplexity-v1.js",
+    "test-v2": "node test-perplexity-v2.js",
+    "test-v1-stream": "node examples/streaming-v1.js",
+    "test-v2-stream": "node examples/streaming-v2.js",
+    "test-v1-metadata": "node examples/metadata-v1.js",
+    "test-v2-metadata": "node examples/metadata-v2.js"
   },
   "dependencies": {
     "@revenium/perplexity": "^1.0.0"
@@ -260,12 +370,13 @@ metadataExample();
 ### Step 9: Test Advanced Examples
 
 ```bash
-# Test streaming
-npm run test-perplexity-stream
-
-# Test metadata
-npm run test-perplexity-metadata
+# Test V1 examples
+npm run test-v1-stream
+npm run test-v1-metadata
 
+# Test V2 examples
+npm run test-v2-stream
+npm run test-v2-metadata
 ```
 
 ---
@@ -299,27 +410,46 @@ REVENIUM_METERING_API_KEY="your_revenium_api_key_here"
 REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"
 ```
 
-### Run Perplexity AI Examples
+### Run V1 & V2 Examples
 
 ```bash
-# Perplexity AI examples
-
-npm run e-basic        # Basic chat completion
-npm run e-streaming    # Streaming response
-npm run e-enhanced     # Enhanced request
-npm run e-chat-completions     # Chat completions
-npm run e-metadata     # Metadata request
-
-# Playground examples
-# Required build first
+# Build the project first
 npm run build
-## Change type to module in package.json
-"type": "module",
-# Then run any of the following
-npm run p-basic
-npm run p-streaming
-npm run p-enhanced
-npm run p-metadata
+
+# V1 Controller Examples (TypeScript)
+npm run e-v1-basic        # V1 Basic chat completion
+npm run e-v1-streaming    # V1 Streaming response
+npm run e-v1-chat         # V1 Multi-turn chat
+npm run e-v1-metadata     # V1 Metadata tracking
+
+# V2 Controller Examples (TypeScript)
+npm run e-v2-basic        # V2 Enhanced chat completion
+npm run e-v2-streaming    # V2 Enhanced streaming
+npm run e-v2-chat         # V2 Enhanced multi-turn chat
+npm run e-v2-metadata     # V2 Enhanced metadata
+
+# V1 Playground Examples (JavaScript)
+npm run p-v1-basic        # V1 Basic (JavaScript)
+npm run p-v1-streaming    # V1 Streaming (JavaScript)
+npm run p-v1-chat         # V1 Chat (JavaScript)
+npm run p-v1-metadata     # V1 Metadata (JavaScript)
+
+# V2 Playground Examples (JavaScript)
+npm run p-v2-basic        # V2 Enhanced (JavaScript)
+npm run p-v2-streaming    # V2 Enhanced Streaming (JavaScript)
+npm run p-v2-chat         # V2 Enhanced Chat (JavaScript)
+npm run p-v2-metadata     # V2 Enhanced Metadata (JavaScript)
+
+# Convenience Scripts
+npm run examples:v1       # Run V1 basic example
+npm run examples:v2       # Run V2 basic example
+npm run examples:all      # Run both V1 and V2 examples
+npm run playground:v1     # Run V1 playground basic
+npm run playground:v2     # Run V2 playground basic
+npm run playground:all    # Run both V1 and V2 playground
+npm run test:v1           # Test all V1 examples
+npm run test:v2           # Test all V2 examples
+npm run test:all          # Test all V1 and V2 examples
 ```
 
 ---
@@ -352,31 +482,45 @@ REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"
 import { OpenAI } from "openai";
 ```
 
-**After:**
+**After (V1 Controller):**
 
 ```javascript
-import { PerplexityReveniumMiddleware } from "@revenium/perplexity";
+import { PerplexityV1Controller } from "@revenium/perplexity";
+```
+
+**After (V2 Controller):**
+
+```javascript
+import { PerplexityV2Controller } from "@revenium/perplexity";
 ```
 
 ### Step 4. Update Your Code
 
-#### Revenium Client Example
+#### V1 Controller Example (Compatible)
+
+```javascript
+import { PerplexityV1Controller } from "@revenium/perplexity";
+
+// Initialize V1 Controller
+const controller = new PerplexityV1Controller();
+const result = await controller.createChat(["Hello world"], "sonar-pro");
+
+console.log("[V1 EXAMPLE]", result.responses[0].text);
+console.log(`Tokens: ${result.usageMetadata.totalTokenCount}`);
+```
+
+#### V2 Controller Example (Enhanced)
 
 ```javascript
-import { PerplexityReveniumMiddleware } from "@revenium/perplexity";
-
-// Initialize (API key from environment variable)
-const middleware = new PerplexityReveniumMiddleware();
-const model = middleware.getGenerativeModel("sonar-pro");
-const result = await model.createChatCompletion({
-  messages: [
-    {
-      role: "user",
-      content: "Hello world",
-    },
-  ],
-});
-console.log("[BASIC EXAMPLE]", result.choices[0].message.content);
+import { PerplexityV2Controller } from "@revenium/perplexity";
+
+// Initialize V2 Controller
+const controller = new PerplexityV2Controller();
+const result = await controller.createChat(["Hello world"], "sonar-pro");
+
+console.log("[V2 ENHANCED EXAMPLE]", result.choices[0].message.content);
+console.log(`Usage: ${result.usage.total_tokens} tokens`);
+console.log(`Processing: ${result.metadata.processingTime}ms`);
 ```
 
 ---
@@ -385,31 +529,98 @@ console.log("[BASIC EXAMPLE]", result.choices[0].message.content);
 
 ### Streaming Responses
 
-#### Revenium Client Streaming
+#### V1 Controller Streaming
 
 ```javascript
-const stream = await model.createChatCompletionStream({
-  messages: [
-    {
-      role: "user",
-      content: "Hello world",
-    },
-  ],
-});
+import { PerplexityV1Controller } from "@revenium/perplexity";
+
+const controller = new PerplexityV1Controller();
+const stream = await controller.createStreaming(["Hello world"], "sonar-pro");
+
 for await (const chunk of stream) {
-  process.stdout.write(chunk.choices[0]?.delta?.content || "");
+  if (chunk.text) {
+    process.stdout.write(chunk.text);
+  }
 }
 ```
 
+#### V2 Controller Streaming (Enhanced)
+
+```javascript
+import { PerplexityV2Controller } from "@revenium/perplexity";
+
+const controller = new PerplexityV2Controller();
+const stream = await controller.createStreaming(["Hello world"], "sonar-pro");
+
+for await (const chunk of stream) {
+  const content = chunk.choices?.[0]?.delta?.content;
+  if (content) {
+    process.stdout.write(content);
+  }
+}
+```
+
+### Custom Metadata Tracking
+
+#### V1 Metadata Example
+
+```javascript
+const customMetadata = {
+  traceId: "trace-12345",
+  taskType: "research-query",
+  subscriberEmail: "user@example.com",
+  organizationId: "org-789",
+  agent: "perplexity-v1-demo",
+};
+
+const result = await controller.createChat(
+  ["What is AI?"],
+  "sonar-pro",
+  customMetadata
+);
+```
+
+#### V2 Enhanced Metadata Example
+
+```javascript
+const customMetadata = {
+  traceId: "trace-v2-67890",
+  taskType: "enhanced-research",
+  subscriberEmail: "user@example.com",
+  organizationId: "org-789",
+  agent: "perplexity-v2-demo",
+};
+
+const result = await controller.createChat(
+  ["What is AI?"],
+  "sonar-pro",
+  customMetadata
+);
+
+// V2 provides additional metadata
+console.log(`Processing time: ${result.metadata.processingTime}ms`);
+console.log(`Transaction ID: ${result.metadata.transactionId}`);
+```
+
 ## 📊 What Gets Tracked
 
+### V1 Controller Tracking
+
 - **Token Usage**: Input and output tokens for accurate billing
 - **Request Duration**: Total time for each API call
 - **Model Information**: Which model was used
 - **Operation Type**: Chat completion, streaming
 - **Error Tracking**: Failed requests and error details
-- **Streaming Metrics**: Time to first token for streaming responses
 - **Custom Metadata**: Rich business context and user tracking
+- **Transaction ID**: Unique identifier for each request
+
+### V2 Enhanced Tracking (Additional)
+
+- **Processing Time**: Enhanced timing metrics
+- **Enhanced Metadata**: Additional context following OpenAI Responses API
+- **Response Format**: OpenAI-compatible response structure
+- **Model Performance**: Enhanced model capability tracking
+- **Streaming Metrics**: Time to first token for streaming responses
 
 ---
 
@@ -420,6 +631,18 @@ for await (const chunk of stream) {
 - **sonar-pro** (Latest and most capable)
 - **sonar-small** (Fast and efficient)
 - **sonar-medium** (Balanced performance)
+- **llama-3.1-sonar-small-128k-online** (Llama-based with online search)
+- **llama-3.1-sonar-large-128k-online** (Large Llama model with online search)
+- **llama-3.1-sonar-huge-128k-online** (Huge Llama model with online search)
+
+### Model Capabilities
+
+Both V1 and V2 Controllers support:
+
+- **Chat Completions**: All models support chat completions
+- **Streaming**: Real-time response streaming
+- **Online Search**: Models with "online" in the name support web search
+- **Large Context**: 128k context window for Llama models
 
 _Note: Model availability depends on your Perplexity AI account and API access level._
 
@@ -474,16 +697,30 @@ This will show:
 
 ## 📚 Examples Repository
 
-Check out our comprehensive examples:
+Check out our comprehensive examples organized by version:
 
-- **Basic Usage**: Simple chat completions
-- **Streaming**: Real-time response streaming
-- **Metadata**: Rich tracking examples
-- **Error Handling**: Robust error management
-- **Advanced Patterns**: Complex use cases
-- **Configuration**: Different setup options
+### V1 Controller Examples (Compatible)
+
+- **Basic Usage**: Simple chat completions with V1 response format
+- **Streaming**: Real-time response streaming with V1 format
+- **Multi-turn Chat**: Conversation handling with V1 controllers
+- **Metadata**: Rich tracking examples with V1 metadata
+- **Model Capabilities**: Check model features and capabilities
+
+### V2 Controller Examples (Enhanced)
+
+- **Enhanced Basic**: Chat completions with OpenAI-compatible responses
+- **Enhanced Streaming**: Streaming with enhanced metadata and timing
+- **Enhanced Chat**: Multi-turn conversations with V2 enhancements
+- **Enhanced Metadata**: Advanced tracking with processing time metrics
+- **Model Performance**: Enhanced model capability and performance tracking
+
+### File Organization
 
-All examples are in the `/examples` and `/playground` directories.
+- **`/examples/v1/`**: TypeScript examples using V1 Controllers (development)
+- **`/examples/v2/`**: TypeScript examples using V2 Controllers (development)
+- **`/playground/v1/`**: JavaScript examples using V1 Controllers (production)
+- **`/playground/v2/`**: JavaScript examples using V2 Controllers (production)
 
 ---