@revenium/litellm 0.0.1

package/examples/README.md

@@ -0,0 +1,321 @@
+# Revenium LiteLLM Middleware Examples
+
+Clear, focused examples that demonstrate seamless HTTP interception with LiteLLM Proxy for all providers.
+
+## Quick Start
+
+1. **Set up environment variables** (create `.env` in project root):
+
+```bash
+# Required for all examples
+REVENIUM_METERING_API_KEY=hak_your_api_key
+REVENIUM_METERING_BASE_URL=https://api.revenium.ai
+LITELLM_PROXY_URL=https://your-litellm-proxy.com
+LITELLM_API_KEY=your_litellm_api_key
+
+# Optional: Enable debug logging
+REVENIUM_DEBUG=true
+```
+
+2. **Install the package**:
+
+```bash
+npm install @revenium/litellm dotenv
+npm install --save-dev typescript tsx @types/node
+```
+
+3. **Run any example**:
+
+```bash
+REVENIUM_DEBUG=true npx tsx examples/litellm-basic.ts        # Basic LiteLLM proxy usage with metadata
+REVENIUM_DEBUG=true npx tsx examples/litellm-streaming.ts    # Streaming, multi-provider, and advanced features
+```
+
+## Getting Started - Step by Step
+
+This guide walks you through creating a complete project from scratch. For GitHub users who cloned this repository, you can run the included examples directly. For npm users, copy these examples from `node_modules/@revenium/litellm/examples/` to your project directory.
+
+### Step 1: Create Your First Test
+
+#### TypeScript Test
+
+Create `test-litellm.ts`:
+
+```typescript
+// test-litellm.ts
+import "dotenv/config";
+import "@revenium/litellm";
+
+async function testLiteLLM() {
+  const proxyUrl = process.env.LITELLM_PROXY_URL;
+  const apiKey = process.env.LITELLM_API_KEY;
+
+  try {
+    const response = await fetch(`${proxyUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+        // Optional: Add metadata for tracking
+        "x-revenium-subscriber-id": "test-user",
+        "x-revenium-subscriber-email": "test@example.com",
+        "x-revenium-organization-id": "test-org",
+      },
+      body: JSON.stringify({
+        model: "gpt-4o-mini",
+        messages: [{ role: "user", content: "Hello!" }],
+      }),
+    });
+
+    const data = await response.json();
+    console.log("Response:", data.choices[0].message.content);
+    console.log("Usage tracked automatically by Revenium middleware!");
+  } catch (error) {
+    console.error("Error:", error);
+  }
+}
+
+testLiteLLM();
+```
+
+#### JavaScript Test
+
+Create `test-litellm.js`:
+
+```javascript
+// test-litellm.js
+require("dotenv/config");
+require("@revenium/litellm");
+
+async function testLiteLLM() {
+  const proxyUrl = process.env.LITELLM_PROXY_URL;
+  const apiKey = process.env.LITELLM_API_KEY;
+
+  try {
+    const response = await fetch(`${proxyUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+        "x-revenium-subscriber-id": "test-user",
+        "x-revenium-subscriber-email": "test@example.com",
+      },
+      body: JSON.stringify({
+        model: "gpt-4o-mini",
+        messages: [{ role: "user", content: "Hello!" }],
+      }),
+    });
+
+    const data = await response.json();
+    console.log("Response:", data.choices[0].message.content);
+  } catch (error) {
+    console.error("Error:", error);
+  }
+}
+
+testLiteLLM();
+```
+
+### Step 2: Update package.json
+
+Add test scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "test:litellm": "tsx test-litellm.ts",
+    "test:litellm:js": "node test-litellm.js"
+  }
+}
+```
+
+### Step 3: Run Your Tests
+
+```bash
+# TypeScript version
+npm run test:litellm
+
+# JavaScript version
+npm run test:litellm:js
+
+# Or run directly
+npx tsx test-litellm.ts
+node test-litellm.js
+```
+
+### Step 4: Explore Advanced Examples
+
+Once your basic test works, explore the included examples (GitHub users can run directly, npm users should copy from `node_modules/@revenium/litellm/examples/`):
+
+```bash
+# Basic usage with metadata
+npx tsx examples/litellm-basic.ts
+
+# Streaming and multi-provider
+npx tsx examples/litellm-streaming.ts
+```
+
+### Step 5: Project Structure
+
+A typical project structure:
+
+```
+your-project/
+├── .env                    # API keys (never commit!)
+├── .gitignore             # Protect your .env file
+├── package.json
+├── test-litellm.ts        # Your first test
+└── src/
+    └── index.ts          # Your application code
+```
+
+## Examples
+
+### litellm-basic.ts
+
+**Basic LiteLLM Proxy usage** with seamless metadata:
+
+- Chat completions with and without metadata
+- Embeddings with metadata tracking
+- Shows metadata usage patterns
+- Multiple examples in one file
+
+```typescript
+// Chat with metadata - no complex setup needed!
+const response = await fetch(`${proxyUrl}/chat/completions`, {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${apiKey}`,
+    // Subscriber metadata for enhanced tracking:
+    "x-revenium-subscriber-id": "user-123",
+    "x-revenium-subscriber-email": "user@my-company.com",
+    "x-revenium-subscriber-credential-name": "api-key",
+    "x-revenium-subscriber-credential": "credential-value",
+    "x-revenium-organization-id": "my-company",
+  },
+  body: JSON.stringify({
+    model: "openai/gpt-4o-mini",
+    messages: [{ role: "user", content: "Hello!" }],
+  }),
+});
+```
+
+### litellm-streaming.ts
+
+**Streaming responses and multi-provider support** with seamless metadata:
+
+- Streaming chat completions with metadata
+- Multi-provider examples (OpenAI, Anthropic, etc.)
+- Advanced embeddings with comprehensive metadata
+- Usage tracked automatically when streams complete
+- Real-time responses + comprehensive analytics
+
+### Key Features Demonstrated
+
+**Seamless HTTP Interception**: Automatic tracking of all LiteLLM Proxy requests
+**Flexible Metadata**: Add metadata headers as needed for enhanced tracking
+**Multi-Provider Support**: Works with OpenAI, Anthropic, Google, Azure, and more
+**Chat & Embeddings**: Full support for both operation types
+**Streaming Support**: Real-time tracking when streams complete **LiteLLM Proxy Integration**: Purpose-built for LiteLLM's proxy architecture
+
+## Running Examples
+
+All examples require:
+
+- Node.js 18+
+- Valid Revenium API key
+- Running LiteLLM Proxy server
+
+**Individual examples:**
+
+```bash
+REVENIUM_DEBUG=true npx tsx examples/litellm-basic.ts        # Basic chat completions and embeddings
+REVENIUM_DEBUG=true npx tsx examples/litellm-streaming.ts    # Streaming and multi-provider features
+```
+
+## LiteLLM Proxy Setup
+
+For local testing, you can run LiteLLM Proxy locally:
+
+### Option 1: Simple OpenAI Setup
+
+```bash
+# Install LiteLLM
+pip install litellm
+
+# Start with OpenAI (replace with your API key)
+export OPENAI_API_KEY=sk_your_openai_key
+litellm --model gpt-3.5-turbo --port 4000
+
+# Update your .env for local testing
+LITELLM_PROXY_URL=http://localhost:4000
+LITELLM_API_KEY=sk-1234
+```
+
+### Option 2: Multi-Provider Setup
+
+```bash
+# Create a config file for multiple providers
+cat > litellm_config.yaml << EOF
+model_list:
+  - model_name: gpt-4o-mini
+    litellm_params:
+      model: openai/gpt-4o-mini
+      api_key: \${OPENAI_API_KEY}
+  - model_name: claude-3-haiku
+    litellm_params:
+      model: anthropic/claude-3-haiku-20240307
+      api_key: \${ANTHROPIC_API_KEY}
+EOF
+
+# Start with config
+litellm --config litellm_config.yaml --port 4000
+```
+
+## Understanding the Magic
+
+The middleware works by:
+
+1. **Import**: Import the middleware before making fetch requests
+2. **HTTP Interception**: Middleware patches global `fetch` function
+3. **Request Detection**: Identifies LiteLLM Proxy requests by URL pattern
+4. **Seamless Integration**: Use fetch normally with metadata headers as needed
+5. **Data Extraction**: Captures tokens, timing, model info, and metadata
+6. **Background Tracking**: Sends data to Revenium without blocking your app
+7. **Transparent Response**: Returns original LiteLLM response unchanged
+
+**The result**: Your existing LiteLLM Proxy code works exactly the same, but now you get automatic usage tracking and rich analytics!
+
+## Troubleshooting
+
+**Environment variable errors:**
+
+- Ensure `.env` file is in project root
+- Check variable names match exactly (note: `REVENIUM_METERING_API_KEY`)
+- Verify API keys are valid
+
+**LiteLLM Proxy setup issues:**
+
+- Ensure LiteLLM Proxy is running and accessible
+- Check that LITELLM_PROXY_URL points to the correct server
+- Verify your LiteLLM Proxy has the required provider API keys
+
+**Middleware not working:**
+
+- Ensure middleware is imported before making fetch requests
+- Verify the package is properly installed with `npm install @revenium/litellm`
+- Check that TypeScript compilation is successful if using TypeScript
+
+**Debug mode:**
+
+```bash
+export REVENIUM_DEBUG=true
+npx ts-node examples/litellm-basic.ts
+```
+
+Look for log messages like:
+
+- `[Revenium] LiteLLM request intercepted`
+- `[Revenium] Usage metadata extracted`
+- `[Revenium] Revenium tracking successful`

package/examples/litellm-basic.ts

@@ -0,0 +1,240 @@
+/**
+ * LiteLLM Basic Example
+ *
+ * This example demonstrates basic LiteLLM Proxy usage with optional metadata tracking.
+ * Shows both chat completions and embeddings with and without metadata.
+ */
+
+// Load environment variables from .env file
+import "dotenv/config";
+
+// Step 1: Import the middleware (this enables automatic tracking)
+import "@revenium/litellm";
+
+async function basicExample() {
+  console.log("Starting basic Revenium LiteLLM middleware example...\n");
+
+  // Check environment variables
+  const requiredVars = ["REVENIUM_METERING_API_KEY", "LITELLM_PROXY_URL"];
+  const missing = requiredVars.filter((key) => !process.env[key]);
+
+  if (missing.length > 0) {
+    console.error("❌ Missing required environment variables:");
+    missing.forEach((key) => console.error(`   ${key}`));
+    console.error("\nPlease set them in a .env file in the project root:");
+    console.error("   REVENIUM_METERING_API_KEY=hak_your_api_key");
+    console.error("   REVENIUM_METERING_BASE_URL=https://api.revenium.ai");
+    console.error("   LITELLM_PROXY_URL=https://your-proxy.com");
+    console.error("   LITELLM_API_KEY=your_litellm_key  # Optional");
+    process.exit(1);
+  }
+
+  const proxyUrl = process.env.LITELLM_PROXY_URL!;
+  const apiKey = process.env.LITELLM_API_KEY || "sk-1234";
+
+  // Handle proxy URL - remove endpoint if already included
+  const baseProxyUrl = proxyUrl.replace(
+    /\/(chat\/completions|embeddings)$/,
+    ""
+  );
+
+  // Debug: Show loaded configuration (partially obfuscated)
+  console.log("Configuration loaded:");
+  console.log(
+    `   Revenium API Key: ${process.env.REVENIUM_METERING_API_KEY?.substring(
+      0,
+      8
+    )}...${process.env.REVENIUM_METERING_API_KEY?.slice(-4)}`
+  );
+  console.log(
+    `   Revenium Base URL: ${process.env.REVENIUM_METERING_BASE_URL}`
+  );
+  console.log(`   LiteLLM Proxy URL: ${proxyUrl}`);
+  console.log(`   Base Proxy URL: ${baseProxyUrl}`);
+  console.log(
+    `   LiteLLM API Key: ${apiKey.substring(0, 8)}...${apiKey.slice(-4)}\n`
+  );
+
+  let successCount = 0;
+  let totalRequests = 3;
+
+  try {
+    // Example 1: Basic chat completion without metadata
+    console.log("Example 1: Basic chat completion without metadata...");
+    const chatUrl = `${baseProxyUrl}/chat/completions`;
+    console.log(`   Calling: ${chatUrl}`);
+
+    const basicResponse = await fetch(chatUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+        // No metadata - still tracked automatically!
+      },
+      body: JSON.stringify({
+        model: "openai/gpt-4o-mini",
+        max_tokens: 50,
+        messages: [
+          {
+            role: "user",
+            content: "What is the capital of France? Please be concise.",
+          },
+        ],
+      }),
+    });
+
+    if (basicResponse.ok) {
+      const basicData = await basicResponse.json();
+      console.log(
+        "Basic response:",
+        basicData.choices[0]?.message?.content || "No response"
+      );
+      console.log(
+        `   Tokens: ${basicData.usage?.prompt_tokens} input + ${basicData.usage?.completion_tokens} output\n`
+      );
+      successCount++;
+    } else {
+      console.log(
+        "❌ Basic request failed:",
+        basicResponse.status,
+        basicResponse.statusText
+      );
+      const errorText = await basicResponse.text();
+      console.log("   Error details:", errorText.substring(0, 200));
+    }
+
+    // Example 2: Chat completion with custom metadata
+    console.log("Example 2: Chat completion with custom metadata...");
+
+    const metadataResponse = await fetch(`${baseProxyUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+        // Add custom metadata for enhanced tracking and analytics
+        "x-revenium-subscriber-id": "demo-user-123",
+        "x-revenium-subscriber-email": "demo-user@acme.com",
+        "x-revenium-subscriber-credential-name": "api-key",
+        "x-revenium-subscriber-credential": "demo-credential-value",
+        "x-revenium-organization-id": "my-customer-name",
+        "x-revenium-task-type": "litellm-node-basic",
+        "x-revenium-product-id": "litellm-middleware-demo",
+        "x-revenium-agent": "littellm-node-basic",
+      },
+      body: JSON.stringify({
+        model: "openai/gpt-4o-mini",
+        max_tokens: 100,
+        messages: [
+          {
+            role: "user",
+            content: "Explain quantum computing in one sentence.",
+          },
+        ],
+      }),
+    });
+
+    if (metadataResponse.ok) {
+      const metadataData = await metadataResponse.json();
+      console.log(
+        "Metadata response:",
+        metadataData.choices[0]?.message?.content || "No response"
+      );
+      console.log(
+        `   Tokens: ${metadataData.usage?.prompt_tokens} input + ${metadataData.usage?.completion_tokens} output\n`
+      );
+      successCount++;
+    } else {
+      console.log(
+        "❌ Metadata request failed:",
+        metadataResponse.status,
+        metadataResponse.statusText
+      );
+      const errorText = await metadataResponse.text();
+      console.log("   Error details:", errorText.substring(0, 200));
+    }
+
+    // Example 3: Embeddings with metadata
+    console.log("Example 3: Embeddings with metadata...");
+
+    const embeddingResponse = await fetch(`${baseProxyUrl}/embeddings`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+        // Metadata works with embeddings too!
+        "x-revenium-subscriber-id": "demo-user-123",
+        "x-revenium-subscriber-email": "demo-user@acme.com",
+        "x-revenium-subscriber-credential-name": "embedding-key",
+        "x-revenium-subscriber-credential": "demo-embedding-credential",
+        "x-revenium-organization-id": "my-customer-name",
+        "x-revenium-task-type": "text-embedding",
+        "x-revenium-product-id": "semantic-search-demo",
+      },
+      body: JSON.stringify({
+        model: "text-embedding-ada-002",
+        input: "This is a sample text for embedding generation.",
+      }),
+    });
+
+    if (embeddingResponse.ok) {
+      const embeddingData = await embeddingResponse.json();
+      console.log("Embedding response: Vector generated successfully");
+      console.log(
+        `   Dimensions: ${
+          embeddingData.data[0]?.embedding?.length || "Unknown"
+        }`
+      );
+      console.log(`   Tokens: ${embeddingData.usage?.prompt_tokens} input\n`);
+      successCount++;
+    } else {
+      console.log(
+        "❌ Embedding request failed:",
+        embeddingResponse.status,
+        embeddingResponse.statusText
+      );
+      const errorText = await embeddingResponse.text();
+      console.log("   Error details:", errorText.substring(0, 200));
+    }
+
+    // Report results
+    console.log(
+      `\nResults: ${successCount}/${totalRequests} requests successful`
+    );
+
+    if (successCount === totalRequests) {
+      console.log(
+        "✅ All requests successful and automatically tracked to Revenium!"
+      );
+      console.log("Check your Revenium dashboard to see the tracked usage.");
+    } else if (successCount > 0) {
+      console.log("⚠️  Some requests successful and tracked to Revenium.");
+      console.log("Check your Revenium dashboard to see the tracked usage.");
+    } else {
+      console.log(
+        "❌ No requests were successful. Check your LiteLLM Proxy configuration."
+      );
+      console.log(
+        "Ensure your LiteLLM Proxy is running and accessible at:",
+        baseProxyUrl
+      );
+    }
+  } catch (error) {
+    console.error("❌ Error:", error);
+    throw error;
+  }
+}
+
+// Run the example
+if (require.main === module) {
+  basicExample()
+    .then(() => {
+      console.log("\nBasic example completed!");
+      console.log(
+        "Enable REVENIUM_DEBUG=true to see detailed request tracking logs"
+      );
+    })
+    .catch((error) => {
+      console.error("\nExample failed:", error);
+      process.exit(1);
+    });
+}