@revenium/perplexity 2.0.4 → 2.0.6

package/examples/README.md

@@ -1,322 +1,226 @@
-# Running Examples - Revenium Middleware for Perplexity (Node.js)
-
-This guide shows you how to run the Node.js/TypeScript examples in this repository.
-
-## Prerequisites
-
-- Node.js 20+ installed
-- Perplexity API key
-- Revenium API key
-
-## Setup
-
-### 1. Clone the Repository
-
-```bash
-git clone https://github.com/revenium/revenium-middleware-perplexity-node.git
-cd revenium-middleware-perplexity-node
-```
-
-### 2. Install Dependencies
-
-```bash
-npm install
-```
-
-### 3. Configure Environment Variables
-
-Create a `.env` file in the root directory:
-
-```bash
-# Create .env file
-cp .env.example .env
-```
-
-See [`.env.example`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/.env.example) for the complete list of environment variables and where to get your API keys.
-
-**Replace the placeholder values with your actual keys!**
-
-## Running Examples
-
-### Available Examples
-
-```bash
-npm run example:basic            # Basic chat completion
-npm run example:streaming        # Streaming response
-npm run example:chat             # Multi-turn conversation
-npm run example:metadata         # With custom metadata
-npm run example:advanced         # Advanced features
-npm run example:getting-started  # Quick start example
-npm test                         # Run all examples
-```
-
-## Example Structure
-
-```
-examples/
-├── basic.ts                 # Basic chat completion
-├── streaming.ts             # Streaming response
-├── chat.ts                  # Multi-turn conversation
-├── metadata.ts              # With custom metadata
-├── advanced-features.ts     # Advanced features
-├── getting_started.ts       # Quick start example
-└── README.md                # This file
-```
-
-## Examples Included
-
-### 1. Basic Usage
-
-**Location**: `examples/basic.ts`
-
-**What it demonstrates:**
-
-- Simple chat completion
-- Automatic metering
-- Basic error handling
-
-**Run it:**
-
-```bash
-npm run example:basic
-```
-
-**Expected output:**
-
-```
-✓ Chat Completion Successful
-Response: [AI response here]
-Model: sonar-pro
-Tokens Used: 50 (prompt: 10, completion: 40)
-```
-
----
-
-### 2. Streaming
-
-**Location**: `examples/streaming.ts`
-
-**What it demonstrates:**
-
-- Real-time streaming responses
-- Token tracking for streamed content
-- Automatic usage tracking when stream completes
-
-**Run it:**
-
-```bash
-npm run example:streaming
-```
-
-**Expected output:**
-
-```
-Model: sonar-pro
-Streaming response:
-
-[Streaming text appears here in real-time]
-
-✓ Streaming completed
-```
-
----
-
-### 3. Multi-turn Chat
-
-**Location**: `examples/chat.ts`
-
-**What it demonstrates:**
-
-- Conversation history management
-- Context-aware responses
-- Multi-message interactions
-
-**Run it:**
-
-```bash
-npm run example:chat
-```
-
-**Expected output:**
-
-```
---- Turn 1 ---
-User: What is the capital of France?
-Assistant: [Response]
-
---- Turn 2 ---
-User: What is its population?
-Assistant: [Response]
-
-✓ Chat completed - Total tokens used: 120
-```
-
----
-
-### 4. Custom Metadata
-
-**Location**: `examples/metadata.ts`
-
-**What it demonstrates:**
-
-- Custom metadata tracking
-- Business context in metering
-- Subscriber and organization tracking
-
-**Run it:**
-
-```bash
-npm run example:metadata
-```
-
-**Expected output:**
-
-```
-✓ Chat Completion Successful
-Response: [AI response]
-Model: sonar-pro
-Tokens Used: 50 (prompt: 10, completion: 40)
-Metadata tracked: subscriber, organization, product, agent, trace
-```
-
-**Note:** Custom metadata (subscriber, organizationId, productId, agent, traceId) is automatically sent to Revenium in the background.
-
----
-
-// Manual configuration
-initializeRevenium({
-meteringApiKey: process.env.REVENIUM_METERING_API_KEY!,
-meteringBaseUrl:
-process.env.REVENIUM_METERING_BASE_URL || "https://api.revenium.ai",
-});
-
-**Location**: `examples/advanced-features.ts`
-
-**What it demonstrates:**
-
-- Streaming with metadata
-- Multiple model comparisons
-- Advanced configuration
-
-**Run it:**
-
-```bash
-npm run example:advanced
-```
-
-**Expected output:**
-
-```
-=== Advanced Features Example ===
-
---- Streaming Responses ---
-Model: sonar-pro
-Response:
-[Streaming text appears here in real-time]
-✓ Streaming completed
-
---- Comprehensive Metadata Tracking ---
-Response: [First 100 characters]...
-✓ Metadata tracked successfully
-
---- Multiple Model Types ---
-Using sonar (lightweight search)...
-Response: [First 80 characters]...
-
-Using sonar-reasoning (real-time reasoning)...
-Response: [First 80 characters]...
-
-✓ Multiple models demonstrated
-
-=== All Advanced Features Demonstrated ===
-```
-
----
-
-### 6. Getting Started
-
-**Location**: `examples/getting_started.ts`
-
-**What it demonstrates:**
-
-- Quick start example
-- Minimal configuration
-- Basic usage pattern
-
-**Run it:**
-
-```bash
-npm run example:getting-started
-```
-
----
-
-## Troubleshooting
-
-### "Missing API Key" Error
-
-Make sure you've created a `.env` file with your API keys:
-
-```bash
-# Check if .env exists
-ls .env
-
-# Verify it has the required keys
-cat .env
-```
-
-### "Module not found" Error
-
-Install dependencies first:
-
-```bash
-npm install
-```
-
-### "Requests not being tracked"
-
-1. Check your `.env` file has correct values:
-
-   - `PERPLEXITY_API_KEY` is set
-   - `REVENIUM_METERING_API_KEY` is set
-   - `REVENIUM_METERING_BASE_URL` is set to `https://api.revenium.ai`
-
-2. Enable debug logging:
-
-```bash
-DEBUG=true npm run example:basic
-```
-
-### TypeScript Errors
-
-Ensure you have TypeScript and tsx installed:
-
-```bash
-npm install -D typescript tsx @types/node
-```
-
----
-
-## Getting Your API Keys
-
-### Perplexity API Key
-
-1. Go to [Perplexity AI Settings](https://www.perplexity.ai/settings/api)
-2. Create a new API key
-3. Add to `.env` as `PERPLEXITY_API_KEY`
-
-### Revenium API Key
-
-1. Sign up at [Revenium](https://ai.revenium.io)
-2. Create a new API key in your dashboard
-3. Add to `.env` as `REVENIUM_METERING_API_KEY`
-
----
-
-## Support
-
-For issues or questions:
-
-- [GitHub Issues](https://github.com/revenium/revenium-middleware-perplexity-node/issues)
-- [Documentation](https://docs.revenium.io)
-- Contact: Reach out to the Revenium team for additional support
+# Revenium Perplexity Middleware - Examples
+
+This directory contains examples demonstrating how to use the Revenium Perplexity middleware.
+
+## Prerequisites
+
+Before running the examples, make sure you have:
+
+1. **Node.js 16 or later** installed
+2. **Revenium API Key** - Get one from [Revenium Dashboard](https://app.revenium.io)
+3. **Perplexity API Key** - Get one from [Perplexity Platform](https://www.perplexity.ai)
+
+## Setup
+
+1. **Clone the repository** (if you haven't already):
+
+   ```bash
+   git clone https://github.com/revenium/revenium-middleware-perplexity-node.git
+   cd revenium-middleware-perplexity-node
+   ```
+
+2. **Install dependencies**:
+
+   ```bash
+   npm install
+   ```
+
+3. **Configure environment variables**:
+
+   Copy the `.env.example` file to `.env` and edit it with your API keys:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+   See [.env.example](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/.env.example) for all available configuration options.
+
+## Examples
+
+### 1. Getting Started
+
+**File:** `getting_started.ts`
+
+The simplest example to get you started with Revenium tracking:
+
+- Initialize the middleware
+- Create a basic chat completion
+- Display response and usage metrics
+
+**Run:**
+
+```bash
+npm run example:getting-started
+# or
+npx tsx examples/getting_started.ts
+```
+
+**What it does:**
+
+- Loads configuration from environment variables
+- Creates a simple chat completion request
+- Automatically sends metering data to Revenium API
+- Displays the response
+
+---
+
+### 2. Basic Usage
+
+**File:** `basic.ts`
+
+Demonstrates standard Perplexity API usage:
+
+- Chat completions with metadata
+- Simple metadata tracking
+
+**Run:**
+
+```bash
+npm run example:basic
+# or
+npx tsx examples/basic.ts
+```
+
+**What it does:**
+
+- Creates chat completions with metadata tracking
+- Demonstrates basic metadata usage
+
+---
+
+### 3. Metadata
+
+**File:** `metadata.ts`
+
+Demonstrates all available metadata fields:
+
+- Complete metadata structure
+- All optional fields documented
+- Subscriber information
+
+**Run:**
+
+```bash
+npm run example:metadata
+# or
+npx tsx examples/metadata.ts
+```
+
+**What it does:**
+
+- Shows all available metadata fields
+- Demonstrates subscriber tracking
+- Includes organization and product tracking
+
+**Metadata fields supported:**
+
+- `traceId` - Session or conversation tracking identifier
+- `taskType` - Type of AI task being performed
+- `agent` - AI agent or bot identifier
+- `organizationId` - Organization identifier
+- `productId` - Product or service identifier
+- `subscriptionId` - Subscription tier identifier
+- `responseQualityScore` - Quality rating (0.0-1.0)
+- `subscriber` - Nested subscriber object with `id`, `email`, `credential` (with `name` and `value`)
+
+---
+
+### 4. Streaming
+
+**File:** `stream.ts`
+
+Demonstrates streaming responses:
+
+- Real-time token streaming
+- Accumulating responses
+- Streaming metrics
+
+**Run:**
+
+```bash
+npm run example:stream
+# or
+npx tsx examples/stream.ts
+```
+
+**What it does:**
+
+- Creates a streaming chat completion
+- Displays tokens as they arrive in real-time
+- Tracks streaming metrics
+- Sends metering data after stream completes
+
+---
+
+### 5. Advanced Features
+
+**File:** `advanced.ts`
+
+Demonstrates advanced Perplexity features:
+
+- Multi-turn conversations
+- Different temperature settings
+- Multiple Perplexity models
+
+**Run:**
+
+```bash
+npm run example:advanced
+# or
+npx tsx examples/advanced.ts
+```
+
+**What it does:**
+
+- Demonstrates multi-turn conversation with system prompt
+- Shows creative responses with higher temperature
+- Uses sonar-reasoning model for complex reasoning tasks
+
+---
+
+## Common Issues
+
+### "Client not initialized" error
+
+**Solution:** Make sure to call `Initialize()` before using `GetClient()`.
+
+### "REVENIUM_METERING_API_KEY is required" error
+
+**Solution:** Set the `REVENIUM_METERING_API_KEY` environment variable in your `.env` file.
+
+### "invalid Revenium API key format" error
+
+**Solution:** Revenium API keys should start with `hak_`. Check your API key format.
+
+### Environment variables not loading
+
+**Solution:** Make sure your `.env` file is in the project root directory and contains the required variables.
+
+### Perplexity API errors
+
+**Solution:** Make sure you have set `PERPLEXITY_API_KEY` in your `.env` file and that it starts with `pplx-`.
+
+### Debug Mode
+
+Enable detailed logging to troubleshoot issues:
+
+```bash
+# In .env file
+REVENIUM_DEBUG=true
+
+# Then run examples
+npm run example:getting-started
+```
+
+## Next Steps
+
+- Check the [main README](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/README.md) for detailed documentation
+- Visit the [Revenium Dashboard](https://app.revenium.io) to view your metering data
+- See [.env.example](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/.env.example) for all configuration options
+
+## Support
+
+For issues or questions:
+
+- Documentation: https://docs.revenium.io
+- Email: support@revenium.io

package/examples/advanced.ts

@@ -0,0 +1,123 @@
+/**
+ * Advanced Example
+ * Demonstrates advanced features like system prompts, conversation history,
+ * and different model parameters with Revenium Perplexity middleware.
+ */
+
+import { Initialize, GetClient, UsageMetadata } from "@revenium/perplexity";
+
+async function main() {
+  // Initialize middleware
+  Initialize();
+
+  // Get client
+  const client = GetClient();
+
+  // Metadata for tracking
+  const metadata: UsageMetadata = {
+    organizationId: "org-advanced-demo",
+    productId: "prod-perplexity-advanced",
+    taskType: "multi-turn-conversation",
+    subscriber: {
+      id: "user-advanced-001",
+      email: "advanced@example.com",
+    },
+  };
+
+  console.log("=== Advanced Perplexity Example ===\n");
+
+  // Example 1: Using system prompt and conversation history
+  console.log("1. Multi-turn conversation with system prompt:\n");
+
+  const response1 = await client
+    .chat()
+    .completions()
+    .create(
+      {
+        model: "sonar-pro",
+        messages: [
+          {
+            role: "system",
+            content:
+              "You are a helpful AI assistant that provides concise, accurate answers.",
+          },
+          {
+            role: "user",
+            content: "What is the capital of France?",
+          },
+          {
+            role: "assistant",
+            content: "The capital of France is Paris.",
+          },
+          {
+            role: "user",
+            content: "What is its population?",
+          },
+        ],
+        max_tokens: 500,
+        temperature: 0.7,
+      },
+      metadata
+    );
+
+  console.log(`Assistant: ${response1.choices[0].message.content}\n`);
+  console.log(`Tokens used: ${response1.usage?.total_tokens}\n`);
+
+  // Example 2: Using different temperature for creative responses
+  console.log("2. Creative response with higher temperature:\n");
+
+  const response2 = await client
+    .chat()
+    .completions()
+    .create(
+      {
+        model: "sonar-pro",
+        messages: [
+          {
+            role: "user",
+            content:
+              "Write a creative tagline for an AI company in 10 words or less.",
+          },
+        ],
+        max_tokens: 100,
+        temperature: 1.0, // Higher temperature for more creativity
+      },
+      {
+        ...metadata,
+        taskType: "creative-generation",
+      }
+    );
+
+  console.log(`Assistant: ${response2.choices[0].message.content}\n`);
+
+  // Example 3: Using sonar-reasoning for complex reasoning tasks
+  console.log("3. Complex reasoning with sonar-reasoning model:\n");
+
+  const response3 = await client
+    .chat()
+    .completions()
+    .create(
+      {
+        model: "sonar-reasoning",
+        messages: [
+          {
+            role: "user",
+            content:
+              "If a train travels 120 km in 2 hours, and then 180 km in 3 hours, what is its average speed for the entire journey?",
+          },
+        ],
+        max_tokens: 500,
+      },
+      {
+        ...metadata,
+        taskType: "reasoning",
+      }
+    );
+
+  console.log(`Assistant: ${response3.choices[0].message.content}\n`);
+  console.log(`Tokens used: ${response3.usage?.total_tokens}\n`);
+
+  console.log("\nAll usage data sent to Revenium! Check your dashboard");
+}
+
+main().catch(console.error);