🕵️ Dropout AI Runtime (@dropout-ai/runtime)

Universal AI Behavior Analysis & Capture for Node.js

Dropout is a lightweight, "install-and-forget" runtime that automatically captures AI interactions (prompts & responses) from your application without requiring code changes to your API calls. It acts as a passive observer, patching the network layer to ensure you never miss a conversation.

• 🔌 Universal: Works with OpenAI, Anthropic, Genkit, LangChain, Axios, and fetch.
• 🛡️ Safe: Designed for production with silent failure modes and browser guards.
• ⚡ Zero-Latency: Uses fire-and-forget logging to ensure your app stays fast.
• 🔋 Robust: Explicit initialization ensures you always know when it's running.

🚀 Quick Start (Wizard)

The easiest way to get started is to run our installer. It will install the package and give you the exact code snippet to copy.

npx @dropout-ai/wizard@latest

🛠️ Manual Installation & Usage

If you prefer to install manually, follow these two steps.

1. Install the Package

npm install @dropout-ai/runtime
# or
pnpm add @dropout-ai/runtime

2. Initialize (The "Universal" Method)

To start capturing, you must explicitly initialize Dropout. Place this code snippet as early as possible in your application lifecycle (before you make any AI calls).

It is safe to call init() multiple times; it will only run once.

➤ For Next.js (App Router)

File: src/instrumentation.ts (or instrumentation.ts in root)

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { default: Dropout } = await import('@dropout-ai/runtime');

    Dropout.init({
      apiKey: process.env.DROPOUT_API_KEY,
      projectId: process.env.DROPOUT_PROJECT_ID,
      debug: true // Set to false in production
    });
  }
}

➤ For Node.js / Express / Fastify

File: index.js or server.js (Top of file)

require('dotenv').config(); // Ensure env vars are loaded first
const Dropout = require('@dropout-ai/runtime');

Dropout.init({
  apiKey: process.env.DROPOUT_API_KEY,
  projectId: process.env.DROPOUT_PROJECT_ID,
  debug: process.env.NODE_ENV !== 'production'
});

const express = require('express');
const app = express();
// ...

➤ For NestJS

File: src/main.ts

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import Dropout from '@dropout-ai/runtime';

async function bootstrap() {
  // ✅ Initialize before the app starts
  Dropout.init({
    apiKey: process.env.DROPOUT_API_KEY,
    projectId: process.env.DROPOUT_PROJECT_ID,
    debug: true
  });

  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

⚙️ Configuration

| Option | Type | Description | Required | | --- | --- | --- | --- | | projectId | string | Your Project ID from the dashboard. | ✅ | | apiKey | string | Your Secret Key (dp_live_...). | ✅ | | debug | boolean | Set true to see "🟢 Online" logs and errors in console. | No | | privacy | string | full (capture text) or mask (metadata only). Default: full. | No | | sessionId | string | Optional initial session ID. If not provided, one is generated. | No | | captureEndpoint | string | Custom capture endpoint (for testing). Default: production URL. | No |

🔑 Session Management

Important: A session represents a single conversation thread. By default, Dropout generates one session ID when initialized and uses it for all interactions. For proper analytics, you should call startNewSession() whenever the user starts a new conversation.

When to Call startNewSession()

Call this method when:

• User clicks "New Chat" button
• User switches to a different conversation thread
• User switches AI models (if you want to treat that as a new conversation)
• Page refreshes and you want to start a fresh session

Example Usage

const Dropout = require('@dropout-ai/runtime');

// Initialize once at app startup
const dropout = Dropout.init({
  apiKey: process.env.DROPOUT_API_KEY,
  projectId: process.env.DROPOUT_PROJECT_ID
});

// Later, when user clicks "New Chat":
app.post('/api/new-chat', (req, res) => {
  const newSessionId = dropout.startNewSession();
  console.log(`Started new session: ${newSessionId}`);
  res.json({ sessionId: newSessionId });
});

// Or with a custom session ID:
dropout.startNewSession('user_123_chat_456');

TypeScript Example

import Dropout from '@dropout-ai/runtime';

const dropout = Dropout.init({
  apiKey: process.env.DROPOUT_API_KEY!,
  projectId: process.env.DROPOUT_PROJECT_ID!
});

// Access current session
console.log(dropout.currentSessionId);

// Start new session
const newSessionId = dropout.startNewSession();

❓ Troubleshooting

Q: How do I know if it's working? Set debug: true in your config. When your app starts, you should see this message immediately:

[Dropout] 🟢 Online | Project: <Your-Project-ID>

Q: I don't see any logs.

1. Check that you called Dropout.init().
2. Ensure your apiKey and projectId are not undefined (log them to check).
3. If using Next.js, ensure instrumentation.ts is in the correct folder (src/ if you use it).

Q: Does this work with Edge Functions? No. This runtime relies on Node.js core modules (http, https). It does not support Vercel Edge Runtime or Cloudflare Workers.

Non-Node.js Usage (REST API)

If you are using Python, Go, or other languages, you can manually send interaction logs to our ingestion endpoint.

Endpoint: POST https://hipughmjlwmwjxzyxfzs.supabase.co/functions/v1/capture-sealed Headers: x-dropout-key: <YOUR_API_KEY>

json { "project_id": "your_project_id", "turn_role": "assistant", "content": "AI response text...", "model": "gpt-4", "provider": "openai" }

License

MIT