@revenium/perplexity 1.0.22 → 1.0.25

package/playground/v2/metadata.js

@@ -0,0 +1,76 @@
+import { PerplexityV2Controller } from "@revenium/perplexity";
+
+const metadataV2Example = async () => {
+  console.log("=".repeat(50));
+  console.log(
+    "📊 Perplexity V2 Enhanced Metadata Example (JavaScript - OpenAI Responses API)"
+  );
+  console.log("=".repeat(50));
+
+  try {
+    const controller = new PerplexityV2Controller();
+
+    // Enhanced custom metadata for V2
+    const customMetadata = {
+      traceId: "trace-v2-js-67890",
+      taskType: "advanced-research",
+      subscriberEmail: "researcher@example.com",
+      subscriberId: "user-v2-js-123",
+      organizationId: "org-v2-js-456",
+      agent: "perplexity-v2-js-enhanced",
+      responseQualityScore: 0.95,
+      operationType: "chat-completion",
+    };
+
+    const result = await controller.createChat(
+      [
+        "Provide a comprehensive analysis of the impact of artificial intelligence on modern healthcare systems",
+      ],
+      "sonar-pro",
+      customMetadata
+    );
+
+    console.log("📝 V2 Enhanced Response:");
+    console.log(result.choices[0].message.content);
+
+    console.log("\n📊 V2 Enhanced Usage Statistics:");
+    console.log(`Prompt tokens: ${result.usage.prompt_tokens}`);
+    console.log(`Completion tokens: ${result.usage.completion_tokens}`);
+    console.log(`Total tokens: ${result.usage.total_tokens}`);
+
+    console.log("\n🔧 V2 Enhanced Response Structure:");
+    console.log(`ID: ${result.id}`);
+    console.log(`Object: ${result.object}`);
+    console.log(`Created: ${new Date(result.created * 1000).toISOString()}`);
+    console.log(`Model: ${result.model}`);
+    console.log(`Choice Index: ${result.choices[0].index}`);
+    console.log(`Message Role: ${result.choices[0].message.role}`);
+    console.log(`Finish Reason: ${result.choices[0].finish_reason}`);
+
+    console.log("\n🏷️ V2 Enhanced Metadata:");
+    console.log(`Transaction ID: ${result.metadata.transactionId}`);
+    console.log(`Processing Time: ${result.metadata.processingTime}ms`);
+    console.log(`Version: ${result.metadata.version}`);
+
+    console.log("\n📋 Custom Metadata Sent:");
+    console.log(`Trace ID: ${customMetadata.traceId}`);
+    console.log(`Task Type: ${customMetadata.taskType}`);
+    console.log(`Subscriber: ${customMetadata.subscriberEmail}`);
+    console.log(`Organization: ${customMetadata.organizationId}`);
+    console.log(`Agent: ${customMetadata.agent}`);
+    console.log(`Quality Score: ${customMetadata.responseQualityScore}`);
+    console.log(`Operation Type: ${customMetadata.operationType}`);
+
+    // V2 Enhanced Analytics
+    console.log("\n📈 V2 Enhanced Analytics:");
+    const performance = controller.getModelPerformance("sonar-pro");
+    console.log(`Context Window: ${performance.contextWindow} tokens`);
+    console.log(`Online Capabilities: ${performance.online}`);
+    console.log(`Estimated Latency: ${performance.estimatedLatency}`);
+    console.log(`Cost Tier: ${performance.costTier}`);
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+};
+
+metadataV2Example();

package/playground/v2/streaming.js

@@ -0,0 +1,67 @@
+import { PerplexityV2Controller } from "@revenium/perplexity";
+
+const streamingV2Example = async () => {
+  console.log("=".repeat(50));
+  console.log(
+    "🌊 Perplexity V2 Streaming Example (JavaScript - Enhanced Response Format)"
+  );
+  console.log("=".repeat(50));
+
+  try {
+    const controller = new PerplexityV2Controller();
+
+    // Streaming chat completion with V2 enhanced response
+    const result = await controller.createStreaming(
+      [
+        "Write a detailed explanation of how machine learning algorithms work, including examples.",
+      ],
+      "sonar-pro"
+    );
+
+    console.log("📝 V2 Streaming Response:");
+    console.log("-".repeat(30));
+
+    let fullResponse = "";
+    let chunkCount = 0;
+    let lastUsage = null;
+
+    for await (const chunk of result.stream) {
+      chunkCount++;
+      const content = chunk.choices?.[0]?.delta?.content || "";
+
+      if (content) {
+        process.stdout.write(content);
+        fullResponse += content;
+      }
+
+      // Capture usage data from the last chunk
+      if (chunk.usage) {
+        lastUsage = chunk.usage;
+      }
+    }
+
+    console.log("\n" + "-".repeat(30));
+    console.log(`\n📊 V2 Enhanced Streaming Stats:`);
+    console.log(`Total chunks received: ${chunkCount}`);
+    console.log(`Response length: ${fullResponse.length} characters`);
+
+    if (lastUsage) {
+      console.log(`Prompt tokens: ${lastUsage.prompt_tokens}`);
+      console.log(`Completion tokens: ${lastUsage.completion_tokens}`);
+      console.log(`Total tokens: ${lastUsage.total_tokens}`);
+    }
+
+    console.log(`\n🔧 V2 Metadata:`);
+    console.log(`Stream ID: ${result.id}`);
+    console.log(`Object: ${result.object}`);
+    console.log(`Transaction ID: ${result.metadata.transactionId}`);
+    console.log(
+      `Start Time: ${new Date(result.metadata.startTime).toISOString()}`
+    );
+    console.log(`Version: ${result.metadata.version}`);
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+};
+
+streamingV2Example();

package/src/index.ts

@@ -1,4 +1,17 @@
 import { config } from "dotenv";
 config();
 
-export * from "./middleware";
+// V1 Controllers (compatible with current API)
+export * from "./v1/perplexityV1.controller";
+
+// V2 Controllers (enhanced response format following OpenAI Responses API)
+export * from "./v2/perplexityV2.controller";
+
+// Interfaces
+export * from "./interfaces/perplexityResponse";
+export * from "./interfaces/perplexityStreaming";
+export * from "./interfaces/usageMetadata";
+export * from "./interfaces/chatCompletionRequest";
+
+// Constants
+export * from "./utils/constants/perplexityModels";

package/src/interfaces/chatCompletionRequest.ts

@@ -1,9 +1,14 @@
-import { ChatCompletionMessageParam } from "openai/resources/index";
 import { IUsageMetadata } from "./usageMetadata";
 
+// Flexible message interface for Perplexity
+export interface IPerplexityMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
 export interface IChatCompletionRequest {
   model?: string;
-  messages: ChatCompletionMessageParam[];
+  messages: IPerplexityMessage[];
   stream?: boolean;
   usageMetadata?: IUsageMetadata;
   [key: string]: any;

package/src/interfaces/meteringResponse.ts

@@ -25,4 +25,5 @@ export interface IMeteringResponse {
   completionStartTime: string;
   timeToFirstToken: number;
   middleware_source: string;
+  traceId?: string;
 }

package/src/interfaces/perplexityResponse.ts

@@ -0,0 +1,63 @@
+import { IUsageMetadata } from "./usageMetadata";
+
+// Perplexity Chat Response Interface (V1 - Compatible with current middleware)
+export interface IPerplexityResponseChat {
+  responses: IPerplexityResponseMessage[];
+  usageMetadata: IUsageMetadata;
+  modelVersion: string;
+  transactionId: string;
+}
+
+export interface IPerplexityResponseMessage {
+  text: string;
+  role: "assistant" | "user" | "system";
+  finishReason?: string;
+}
+
+// Raw OpenAI-compatible response from Perplexity API
+export interface IPerplexityRawResponse {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    message: {
+      role: string;
+      content: string;
+    };
+    finish_reason: string;
+  }>;
+  usage: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}
+
+// V2 Enhanced Response Structure (Following OpenAI Responses API)
+export interface IPerplexityV2Response {
+  id: string;
+  object: "chat.completion";
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    message: {
+      role: string;
+      content: string;
+    };
+    finish_reason: string;
+  }>;
+  usage: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+  // Enhanced metadata for V2
+  metadata: {
+    transactionId: string;
+    processingTime: number;
+    version: "v2";
+  };
+}

package/src/interfaces/perplexityStreaming.ts

@@ -0,0 +1,56 @@
+import { IUsageMetadata } from "./usageMetadata";
+
+// Perplexity Streaming Response Interface (V1 - Compatible with current middleware)
+export interface IPerplexityStreamingResponse {
+  stream: AsyncIterable<IPerplexityStreamChunk>;
+  usageMetadata: IUsageMetadata;
+  modelVersion: string;
+  transactionId: string;
+}
+
+export interface IPerplexityStreamChunk {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    delta: {
+      role?: string;
+      content?: string;
+    };
+    finish_reason?: string;
+  }>;
+}
+
+// V2 Enhanced Streaming Response (Following OpenAI Responses API)
+export interface IPerplexityV2StreamingResponse {
+  id: string;
+  object: "chat.completion.chunk";
+  stream: AsyncIterable<IPerplexityV2StreamChunk>;
+  metadata: {
+    transactionId: string;
+    startTime: number;
+    version: "v2";
+  };
+}
+
+export interface IPerplexityV2StreamChunk {
+  id: string;
+  object: "chat.completion.chunk";
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    delta: {
+      role?: string;
+      content?: string;
+    };
+    finish_reason?: string;
+  }>;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}

package/src/models/Metering.ts

@@ -9,7 +9,7 @@ import {
   REVENIUM_METERING_BASE_URL,
 } from "../utils";
 import { calculateDurationMs } from "../utils/calculateDurationMs";
-import { formatTimestamp } from "../utils/formatTimeStamp";
+import { formatTimestamp } from "../utils/formatTimestamp";
 import { generateTransactionId } from "../utils/generateTransactionId";
 import { logger } from "./Logger";
 
@@ -31,7 +31,7 @@ export class Metering {
       stopReason: usageMetadata?.stopReason ?? metering.stopReason,
       costType: COST_TYPE,
       isStreamed,
-      taskType: COST_TYPE,
+      taskType: usageMetadata?.taskType ?? COST_TYPE,
       agent: usageMetadata?.agent ?? agent,
       operationType:
         usageMetadata?.operationType ?? metering.operationType.toString(),
@@ -83,6 +83,7 @@ export class Metering {
         formatTimestamp(metering.endTime),
       timeToFirstToken: usageMetadata?.timeToFirstToken ?? 0,
       middleware_source: MIDDLEWARE_SOURCE,
+      traceId: usageMetadata?.traceId,
     };
   }
 
@@ -90,6 +91,12 @@ export class Metering {
     metering: IMeteringResponse
   ): Promise<void> => {
     try {
+      // Log the metering data being sent for debugging
+      logger.info(
+        "Sending metering data to Revenium:",
+        JSON.stringify(metering, null, 2)
+      );
+
       const response = await fetch(`${this.endpoint}/v2/ai/completions`, {
         method: "POST",
         headers: {

package/src/utils/constants/perplexityModels.ts

@@ -0,0 +1,71 @@
+// Perplexity AI Models (based on current models in utils)
+export const PERPLEXITY_MODELS = {
+  // Sonar Models (Chat Completions with online search)
+  SONAR_SMALL: "sonar-small",
+  SONAR_MEDIUM: "sonar-medium",
+  SONAR_PRO: "sonar-pro",
+
+  // Legacy Models (for V1 compatibility)
+  LLAMA_3_1_SONAR_SMALL: "llama-3.1-sonar-small-128k-online",
+  LLAMA_3_1_SONAR_LARGE: "llama-3.1-sonar-large-128k-online",
+  LLAMA_3_1_SONAR_HUGE: "llama-3.1-sonar-huge-128k-online",
+
+  // Chat Models (without online search)
+  LLAMA_3_1_8B: "llama-3.1-8b-instruct",
+  LLAMA_3_1_70B: "llama-3.1-70b-instruct",
+  LLAMA_3_1_405B: "llama-3.1-405b-instruct",
+} as const;
+
+export type PerplexityModel =
+  (typeof PERPLEXITY_MODELS)[keyof typeof PERPLEXITY_MODELS];
+
+// Default models for different operations
+export const DEFAULT_CHAT_MODEL = PERPLEXITY_MODELS.SONAR_PRO;
+
+// Model capabilities
+export const MODEL_CAPABILITIES: Record<
+  string,
+  {
+    chat: boolean;
+    streaming: boolean;
+    online: boolean;
+    contextWindow: number;
+  }
+> = {
+  [PERPLEXITY_MODELS.SONAR_SMALL]: {
+    chat: true,
+    streaming: true,
+    online: true,
+    contextWindow: 127072,
+  },
+  [PERPLEXITY_MODELS.SONAR_MEDIUM]: {
+    chat: true,
+    streaming: true,
+    online: true,
+    contextWindow: 127072,
+  },
+  [PERPLEXITY_MODELS.SONAR_PRO]: {
+    chat: true,
+    streaming: true,
+    online: true,
+    contextWindow: 127072,
+  },
+  [PERPLEXITY_MODELS.LLAMA_3_1_8B]: {
+    chat: true,
+    streaming: true,
+    online: false,
+    contextWindow: 131072,
+  },
+  [PERPLEXITY_MODELS.LLAMA_3_1_70B]: {
+    chat: true,
+    streaming: true,
+    online: false,
+    contextWindow: 131072,
+  },
+  [PERPLEXITY_MODELS.LLAMA_3_1_405B]: {
+    chat: true,
+    streaming: true,
+    online: false,
+    contextWindow: 131072,
+  },
+} as const;

package/src/v1/perplexityV1.controller.ts

@@ -0,0 +1,164 @@
+import { logger } from "../models/Logger";
+import { IUsageMetadata } from "../interfaces/usageMetadata";
+import {
+  IChatCompletionRequest,
+  IPerplexityMessage,
+} from "../interfaces/chatCompletionRequest";
+import { IPerplexityResponseChat } from "../interfaces/perplexityResponse";
+import { IPerplexityStreamingResponse } from "../interfaces/perplexityStreaming";
+import {
+  DEFAULT_CHAT_MODEL,
+  PERPLEXITY_MODELS,
+  MODEL_CAPABILITIES,
+} from "../utils/constants/perplexityModels";
+import { PerplexityV1Service } from "./perplexityV1.service";
+import { models } from "../utils";
+
+export class PerplexityV1Controller {
+  private service: PerplexityV1Service;
+
+  constructor() {
+    this.service = new PerplexityV1Service();
+    logger.info("Perplexity V1 Controller initialized");
+  }
+
+  /**
+   * Create a chat completion using Perplexity V1 API (Compatible with current middleware)
+   * @param messages Array of message strings or OpenAI message objects
+   * @param model Optional model name (defaults to sonar-pro)
+   * @param customMetadata Optional custom metadata for tracking
+   * @returns Promise<IPerplexityResponseChat>
+   */
+  async createChat(
+    messages: string[] | Array<{ role: string; content: string }>,
+    model: string = DEFAULT_CHAT_MODEL,
+    customMetadata?: IUsageMetadata
+  ): Promise<IPerplexityResponseChat> {
+    try {
+      // Normalize messages to OpenAI format
+      const normalizedMessages = this.normalizeMessages(messages);
+
+      // Validate model
+      this.validateModel(model);
+
+      // Create chat completion request
+      const request: IChatCompletionRequest = {
+        messages: normalizedMessages,
+        usageMetadata: customMetadata,
+      };
+
+      logger.info(
+        `Creating Perplexity V1 chat completion with model: ${model}`
+      );
+
+      return await this.service.createChatCompletion(request, model);
+    } catch (error) {
+      logger.error("Error in Perplexity V1 createChat:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Create a streaming chat completion using Perplexity V1 API (Compatible with current middleware)
+   * @param messages Array of message strings or OpenAI message objects
+   * @param model Optional model name (defaults to sonar-pro)
+   * @param customMetadata Optional custom metadata for tracking
+   * @returns Promise<IPerplexityStreamingResponse>
+   */
+  async createStreaming(
+    messages: string[] | Array<{ role: string; content: string }>,
+    model: string = DEFAULT_CHAT_MODEL,
+    customMetadata?: IUsageMetadata
+  ): Promise<IPerplexityStreamingResponse> {
+    try {
+      // Normalize messages to OpenAI format
+      const normalizedMessages = this.normalizeMessages(messages);
+
+      // Validate model
+      this.validateModel(model);
+
+      // Create streaming request
+      const request: IChatCompletionRequest = {
+        messages: normalizedMessages,
+        usageMetadata: customMetadata,
+      };
+
+      logger.info(
+        `Creating Perplexity V1 streaming completion with model: ${model}`
+      );
+
+      return await this.service.createStreamingCompletion(request, model);
+    } catch (error) {
+      logger.error("Error in Perplexity V1 createStreaming:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get available models for Perplexity V1
+   * @returns Array of available model names
+   */
+  getAvailableModels(): string[] {
+    return models; // Use the existing models from utils
+  }
+
+  /**
+   * Check if a model supports a specific capability
+   * @param model Model name
+   * @param capability Capability to check (chat, streaming, online)
+   * @returns boolean
+   */
+  supportsCapability(
+    model: string,
+    capability: "chat" | "streaming" | "online"
+  ): boolean {
+    return MODEL_CAPABILITIES[model]?.[capability] || false;
+  }
+
+  /**
+   * Get model information including capabilities and context window
+   * @param model Model name
+   * @returns Model information object
+   */
+  getModelInfo(model: string) {
+    const capabilities = MODEL_CAPABILITIES[model];
+    if (!capabilities) {
+      throw new Error(`Model "${model}" is not supported`);
+    }
+
+    return {
+      model,
+      capabilities: {
+        chat: capabilities.chat,
+        streaming: capabilities.streaming,
+        online: capabilities.online,
+      },
+      contextWindow: capabilities.contextWindow,
+      version: "v1",
+    };
+  }
+
+  private normalizeMessages(
+    messages: string[] | Array<{ role: string; content: string }>
+  ): IPerplexityMessage[] {
+    if (Array.isArray(messages) && typeof messages[0] === "string") {
+      // Convert string array to message objects
+      return (messages as string[]).map((content, index) => ({
+        role: index === 0 ? "user" : "assistant",
+        content,
+      })) as IPerplexityMessage[];
+    }
+
+    return messages as IPerplexityMessage[];
+  }
+
+  private validateModel(model: string): void {
+    if (!models.includes(model)) {
+      throw new Error(
+        `Model "${model}" is not supported. Available models: ${models.join(
+          ", "
+        )}`
+      );
+    }
+  }
+}