@lelemondev/sdk 0.2.1 → 0.3.0

package/README.md

@@ -4,15 +4,16 @@
 [![CI](https://github.com/lelemondev/lelemondev-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/lelemondev/lelemondev-sdk/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Fire-and-forget LLM observability for Node.js. Track your AI agents with 3 lines of code.
+Automatic LLM observability for Node.js. Track your AI agents with zero code changes.
 
 ## Features
 
-- 🔥 **Fire-and-forget** - Never blocks your code
-- 📦 **Auto-batching** - Efficient network usage
-- ⚡ **Zero config** - Works out of the box
-- 🛡️ **Error-safe** - Never crashes your app
-- 🌐 **Serverless-ready** - Built-in flush for Lambda/Vercel
+- **Automatic Tracing** - Wrap your client, everything is traced
+- **Fire-and-forget** - Never blocks your code
+- **Auto-batching** - Efficient network usage
+- **Streaming Support** - Full support for streaming responses
+- **Type-safe** - Preserves your client's TypeScript types
+- **Serverless-ready** - Built-in flush for Lambda/Vercel
 
 ## Installation
 
@@ -23,26 +24,34 @@ npm install @lelemondev/sdk
 ## Quick Start
 
 ```typescript
-import { init, trace, flush } from '@lelemondev/sdk';
+import { init, observe, flush } from '@lelemondev/sdk';
+import OpenAI from 'openai';
 
-// Initialize once at app startup
+// 1. Initialize once at app startup
 init({ apiKey: process.env.LELEMON_API_KEY });
 
-// Trace your agent (fire-and-forget, no awaits needed!)
-const t = trace({ input: userMessage });
+// 2. Wrap your client
+const openai = observe(new OpenAI());
 
-try {
-  const result = await myAgent(userMessage);
-  t.success(result.messages);  // Sync, doesn't block
-} catch (error) {
-  t.error(error);              // Sync, doesn't block
-  throw error;
-}
+// 3. Use normally - all calls are traced automatically
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
 
-// For serverless: flush before response
+// 4. For serverless: flush before response
 await flush();
 ```
 
+That's it! No manual tracing code needed.
+
+## Supported Providers
+
+| Provider | Status | Methods |
+|----------|--------|---------|
+| OpenAI | Supported | `chat.completions.create()`, `completions.create()`, `embeddings.create()` |
+| Anthropic | Supported | `messages.create()`, `messages.stream()` |
+
 ## API Reference
 
 ### `init(config)`
@@ -54,58 +63,88 @@ init({
   apiKey: 'le_xxx',           // Required (or set LELEMON_API_KEY env var)
   endpoint: 'https://...',    // Optional, custom endpoint
   debug: false,               // Optional, enable debug logs
+  disabled: false,            // Optional, disable all tracing
   batchSize: 10,              // Optional, items per batch
   flushIntervalMs: 1000,      // Optional, auto-flush interval
+  requestTimeoutMs: 10000,    // Optional, HTTP request timeout
 });
 ```
 
-### `trace(options)`
+### `observe(client, options?)`
 
-Start a new trace. Returns a `Trace` object.
+Wrap an LLM client with automatic tracing. Returns the same client type.
 
 ```typescript
-const t = trace({
-  input: userMessage,         // Required, the input to your agent
+import Anthropic from '@anthropic-ai/sdk';
+
+const anthropic = observe(new Anthropic(), {
   sessionId: 'session-123',   // Optional, group related traces
   userId: 'user-456',         // Optional, identify the user
-  name: 'chat-agent',         // Optional, name for this trace
-  metadata: { ... },          // Optional, custom metadata
-  tags: ['prod', 'v2'],       // Optional, tags for filtering
+  metadata: { source: 'api' }, // Optional, custom metadata
+  tags: ['production'],       // Optional, tags for filtering
 });
 ```
 
-### `Trace.success(messages)`
+### `createObserve(defaultOptions)`
 
-Complete the trace successfully. Fire-and-forget (no await needed).
+Create a scoped observe function with preset options.
 
 ```typescript
-t.success(result.messages);
+const observeWithSession = createObserve({
+  sessionId: 'session-123',
+  userId: 'user-456',
+});
+
+const openai = observeWithSession(new OpenAI());
+const anthropic = observeWithSession(new Anthropic());
 ```
 
-### `Trace.error(error, messages?)`
+### `flush()`
 
-Complete the trace with an error. Fire-and-forget (no await needed).
+Wait for all pending traces to be sent. Use in serverless environments.
 
 ```typescript
-t.error(error);
-t.error(error, partialMessages);  // Include messages up to failure
+await flush();
 ```
 
-### `Trace.log(response)`
+### `isEnabled()`
 
-Log an LLM response for token tracking (optional).
+Check if tracing is enabled.
 
 ```typescript
-const response = await openai.chat.completions.create(...);
-t.log(response);  // Extracts model, tokens automatically
+if (isEnabled()) {
+  console.log('Tracing is active');
+}
 ```
 
-### `flush()`
+## Streaming Support
 
-Wait for all pending traces to be sent. Use in serverless environments.
+Both OpenAI and Anthropic streaming are fully supported:
 
 ```typescript
-await flush();
+// OpenAI streaming
+const stream = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Hello!' }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content || '');
+}
+// Trace is captured automatically when stream completes
+
+// Anthropic streaming
+const stream = anthropic.messages.stream({
+  model: 'claude-3-opus-20240229',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+
+for await (const event of stream) {
+  // Process events
+}
+// Trace is captured automatically
 ```
 
 ## Serverless Usage
@@ -114,53 +153,65 @@ await flush();
 
 ```typescript
 import { waitUntil } from '@vercel/functions';
-import { trace, flush } from '@lelemondev/sdk';
+import { init, observe, flush } from '@lelemondev/sdk';
+import OpenAI from 'openai';
+
+init({ apiKey: process.env.LELEMON_API_KEY });
+const openai = observe(new OpenAI());
 
 export async function POST(req: Request) {
-  const t = trace({ input: message });
-
-  try {
-    const result = await myAgent(message);
-    t.success(result);
-    return Response.json(result);
-  } catch (error) {
-    t.error(error);
-    throw error;
-  } finally {
-    waitUntil(flush());  // Flush after response
-  }
+  const { message } = await req.json();
+
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: message }],
+  });
+
+  waitUntil(flush());  // Flush after response
+  return Response.json(response.choices[0].message);
 }
 ```
 
 ### AWS Lambda
 
 ```typescript
-import { trace, flush } from '@lelemondev/sdk';
+import { init, observe, flush } from '@lelemondev/sdk';
+import OpenAI from 'openai';
+
+init({ apiKey: process.env.LELEMON_API_KEY });
+const openai = observe(new OpenAI());
 
 export const handler = async (event) => {
-  const t = trace({ input: event.body });
-
-  try {
-    const result = await myAgent(event.body);
-    t.success(result);
-    return { statusCode: 200, body: JSON.stringify(result) };
-  } catch (error) {
-    t.error(error);
-    throw error;
-  } finally {
-    await flush();  // Always flush before Lambda ends
-  }
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: event.body }],
+  });
+
+  await flush();  // Always flush before Lambda ends
+  return { statusCode: 200, body: JSON.stringify(response) };
 };
 ```
 
-## Supported Providers
+## What Gets Traced
+
+Each LLM call automatically captures:
+
+- **Provider** - openai, anthropic
+- **Model** - gpt-4, claude-3-opus, etc.
+- **Input** - Messages/prompt (sanitized)
+- **Output** - Response content
+- **Tokens** - Input and output token counts
+- **Duration** - Request latency in ms
+- **Status** - success or error
+- **Streaming** - Whether streaming was used
+
+## Security
+
+The SDK automatically sanitizes sensitive data:
 
-| Provider | Auto-detected |
-|----------|---------------|
-| OpenAI | ✅ |
-| Anthropic | ✅ |
-| Google Gemini | ✅ |
-| AWS Bedrock | ✅ |
+- API keys and tokens are redacted
+- Large payloads are truncated
+- Errors are captured without stack traces
 
 ## Environment Variables
 
@@ -170,4 +221,4 @@ export const handler = async (event) => {
 
 ## License
 
-MIT © [Lelemon](https://lelemon.dev)
+MIT

package/dist/index.d.mts

@@ -1,316 +1,88 @@
 /**
- * Lelemon SDK Types
- * Minimal, low-friction API for LLM observability
+ * Core types for Lelemon SDK
  */
 interface LelemonConfig {
-    /**
-     * API key for authentication (starts with 'le_')
-     * Can also be set via LELEMON_API_KEY env var
-     */
+    /** API key (or set LELEMON_API_KEY env var) */
     apiKey?: string;
-    /**
-     * API endpoint (default: https://api.lelemon.dev)
-     */
+    /** API endpoint (default: https://api.lelemon.dev) */
     endpoint?: string;
-    /**
-     * Enable debug logging
-     */
+    /** Enable debug logging */
     debug?: boolean;
-    /**
-     * Disable tracing (useful for testing)
-     */
+    /** Disable tracing */
     disabled?: boolean;
-    /**
-     * Number of items to batch before sending (default: 10)
-     */
+    /** Batch size before flush (default: 10) */
     batchSize?: number;
-    /**
-     * Interval in ms to flush pending items (default: 1000)
-     */
+    /** Auto-flush interval in ms (default: 1000) */
     flushIntervalMs?: number;
-    /**
-     * Request timeout in ms (default: 10000)
-     */
+    /** Request timeout in ms (default: 10000) */
     requestTimeoutMs?: number;
 }
-interface TraceOptions {
-    /**
-     * Initial input (user message, prompt, etc.)
-     */
-    input: unknown;
-    /**
-     * Session ID to group related traces
-     */
+type ProviderName = 'openai' | 'anthropic' | 'google' | 'bedrock' | 'unknown';
+interface ObserveOptions {
+    /** Session ID to group related calls */
     sessionId?: string;
-    /**
-     * User ID for the end user
-     */
+    /** User ID for the end user */
     userId?: string;
-    /**
-     * Custom metadata
-     */
+    /** Custom metadata added to all traces */
     metadata?: Record<string, unknown>;
-    /**
-     * Tags for filtering
-     */
+    /** Tags for filtering */
     tags?: string[];
-    /**
-     * Name for this trace (e.g., 'chat-agent', 'summarizer')
-     */
-    name?: string;
-}
-interface OpenAIMessage {
-    role: 'system' | 'user' | 'assistant' | 'tool';
-    content: string | null;
-    tool_calls?: OpenAIToolCall[];
-    tool_call_id?: string;
-}
-interface OpenAIToolCall {
-    id: string;
-    type: 'function';
-    function: {
-        name: string;
-        arguments: string;
-    };
-}
-interface AnthropicMessage {
-    role: 'user' | 'assistant';
-    content: string | AnthropicContent[];
-}
-interface AnthropicContent {
-    type: 'text' | 'tool_use' | 'tool_result';
-    text?: string;
-    id?: string;
-    name?: string;
-    input?: unknown;
-    tool_use_id?: string;
-    content?: string;
-}
-type Message = OpenAIMessage | AnthropicMessage | Record<string, unknown>;
-interface ParsedTrace {
-    systemPrompt?: string;
-    userInput?: string;
-    output?: string;
-    llmCalls: ParsedLLMCall[];
-    toolCalls: ParsedToolCall[];
-    totalInputTokens: number;
-    totalOutputTokens: number;
-    models: string[];
-    provider?: 'openai' | 'anthropic' | 'gemini' | 'bedrock' | 'unknown';
-}
-interface ParsedLLMCall {
-    model?: string;
-    provider?: string;
-    inputTokens?: number;
-    outputTokens?: number;
-    input?: unknown;
-    output?: unknown;
-    toolCalls?: ParsedToolCall[];
-}
-interface ParsedToolCall {
-    name: string;
-    input: unknown;
-    output?: unknown;
-}
-interface CreateTraceRequest {
-    name?: string;
-    sessionId?: string;
-    userId?: string;
-    input?: unknown;
-    metadata?: Record<string, unknown>;
-    tags?: string[];
-}
-interface CompleteTraceRequest {
-    status: 'completed' | 'error';
-    output?: unknown;
-    errorMessage?: string;
-    errorStack?: string;
-    systemPrompt?: string;
-    llmCalls?: ParsedLLMCall[];
-    toolCalls?: ParsedToolCall[];
-    models?: string[];
-    totalInputTokens?: number;
-    totalOutputTokens?: number;
-    totalCostUsd?: number;
-    durationMs?: number;
-    metadata?: Record<string, unknown>;
-}
-
-/**
- * Transport layer with queue-based batching
- *
- * Features:
- * - Fire-and-forget API (sync enqueue)
- * - Automatic batching (by size or interval)
- * - Single flush promise (no duplicate requests)
- * - Graceful error handling (never crashes caller)
- * - Request timeout protection
- */
-
-interface TransportConfig {
-    apiKey: string;
-    endpoint: string;
-    debug: boolean;
-    disabled: boolean;
-    batchSize?: number;
-    flushIntervalMs?: number;
-    requestTimeoutMs?: number;
-}
-declare class Transport {
-    private readonly config;
-    private queue;
-    private flushPromise;
-    private flushTimer;
-    private pendingResolvers;
-    private idCounter;
-    constructor(config: TransportConfig);
-    /**
-     * Check if transport is enabled
-     */
-    isEnabled(): boolean;
-    /**
-     * Enqueue trace creation (returns promise that resolves to trace ID)
-     */
-    enqueueCreate(data: CreateTraceRequest): Promise<string | null>;
-    /**
-     * Enqueue trace completion (fire-and-forget)
-     */
-    enqueueComplete(traceId: string, data: CompleteTraceRequest): void;
-    /**
-     * Flush all pending items
-     * Safe to call multiple times (deduplicates)
-     */
-    flush(): Promise<void>;
-    /**
-     * Get pending item count (for testing/debugging)
-     */
-    getPendingCount(): number;
-    private generateTempId;
-    private enqueue;
-    private scheduleFlush;
-    private cancelScheduledFlush;
-    private sendBatch;
-    private request;
-    private log;
 }
 
 /**
- * Lelemon Tracer - Fire-and-forget LLM observability
- *
- * Usage:
- *   const t = trace({ input: userMessage });
- *   try {
- *     const result = await myAgent(userMessage);
- *     t.success(result.messages);
- *   } catch (error) {
- *     t.error(error);
- *     throw error;
- *   }
+ * Global Configuration
  *
- * For serverless:
- *   await flush(); // Before response
+ * Manages SDK configuration and transport instance.
  */
 
 /**
- * Initialize the SDK (optional, will auto-init with env vars)
- *
- * @example
- * init({ apiKey: 'le_xxx' });
- * init({ apiKey: 'le_xxx', debug: true });
+ * Initialize the SDK
+ * Call once at app startup
  */
 declare function init(config?: LelemonConfig): void;
-/**
- * Start a new trace
- *
- * @example
- * const t = trace({ input: userMessage });
- * try {
- *   const result = await myAgent(userMessage);
- *   t.success(result.messages);
- * } catch (error) {
- *   t.error(error);
- *   throw error;
- * }
- */
-declare function trace(options: TraceOptions): Trace;
-/**
- * Flush all pending traces to the server
- * Call this before process exit in serverless environments
- *
- * @example
- * // In Next.js API route
- * export async function POST(req: Request) {
- *   // ... your code with traces ...
- *   await flush();
- *   return Response.json(result);
- * }
- *
- * // With Vercel waitUntil
- * import { waitUntil } from '@vercel/functions';
- * waitUntil(flush());
- */
-declare function flush(): Promise<void>;
 /**
  * Check if SDK is enabled
  */
 declare function isEnabled(): boolean;
-declare class Trace {
-    private id;
-    private idPromise;
-    private readonly transport;
-    private readonly startTime;
-    private readonly debug;
-    private readonly disabled;
-    private completed;
-    private llmCalls;
-    constructor(options: TraceOptions, transport: Transport, debug: boolean, disabled: boolean);
-    /**
-     * Log an LLM response for token tracking
-     * Optional - use if you want per-call token counts
-     */
-    log(response: unknown): this;
-    /**
-     * Complete trace successfully (fire-and-forget)
-     *
-     * @param messages - Full message history (OpenAI/Anthropic format)
-     */
-    success(messages: unknown): void;
-    /**
-     * Complete trace with error (fire-and-forget)
-     *
-     * @param error - The error that occurred
-     * @param messages - Optional message history up to failure
-     */
-    error(error: Error | unknown, messages?: unknown): void;
-    /**
-     * Get the trace ID (may be null if not yet created or failed)
-     */
-    getId(): string | null;
-    /**
-     * Wait for trace ID to be available
-     */
-    waitForId(): Promise<string | null>;
-    private aggregateCalls;
-}
-
 /**
- * Message Parser
- * Auto-detects OpenAI/Anthropic/Gemini message formats and extracts relevant data
+ * Flush all pending traces
  */
+declare function flush(): Promise<void>;
 
 /**
- * Parse messages array and extract structured data
+ * Observe Function
+ *
+ * Main entry point for wrapping LLM clients with automatic tracing.
  */
-declare function parseMessages(messages: unknown): ParsedTrace;
+
 /**
- * Extract data from an OpenAI/Anthropic/Bedrock response object
- * This handles the raw API response (not the messages array)
+ * Wrap an LLM client with automatic tracing
+ *
+ * @param client - OpenAI or Anthropic client instance
+ * @param options - Optional context (sessionId, userId, etc.)
+ * @returns The wrapped client with the same type
+ *
+ * @example
+ * import { observe } from '@lelemondev/sdk';
+ * import OpenAI from 'openai';
+ *
+ * const openai = observe(new OpenAI());
+ *
+ * // All calls are now automatically traced
+ * const response = await openai.chat.completions.create({...});
  */
-declare function parseResponse(response: unknown): Partial<ParsedLLMCall>;
+declare function observe<T>(client: T, options?: ObserveOptions): T;
 /**
- * Parse Bedrock InvokeModel response body
- * Call this with the parsed JSON body from Bedrock
+ * Create a scoped observe function with preset context
+ *
+ * @example
+ * const observeWithSession = createObserve({
+ *   sessionId: 'session-123',
+ *   userId: 'user-456',
+ * });
+ *
+ * const openai = observeWithSession(new OpenAI());
  */
-declare function parseBedrockResponse(body: unknown): Partial<ParsedLLMCall>;
+declare function createObserve(defaultOptions: ObserveOptions): <T>(client: T, options?: ObserveOptions) => T;
 
-export { type AnthropicMessage, type LelemonConfig, type Message, type OpenAIMessage, type ParsedLLMCall, type ParsedToolCall, type ParsedTrace, Trace, type TraceOptions, flush, init, isEnabled, parseBedrockResponse, parseMessages, parseResponse, trace };
+export { type LelemonConfig, type ObserveOptions, type ProviderName, createObserve, flush, init, isEnabled, observe };