@lelemondev/sdk 0.1.0

package/README.md

@@ -0,0 +1,151 @@
+# @lelemon/sdk
+
+Low-friction LLM observability. **3 lines of code.**
+
+```typescript
+import { trace } from '@lelemon/sdk';
+
+const t = trace({ input: userMessage });
+try {
+  // ... your agent code ...
+  await t.success(messages);
+} catch (error) {
+  await t.error(error, messages);
+}
+```
+
+## Installation
+
+```bash
+npm install @lelemon/sdk
+# or
+yarn add @lelemon/sdk
+# or
+pnpm add @lelemon/sdk
+```
+
+## Setup
+
+Set your API key:
+
+```bash
+export LELEMON_API_KEY=le_your_api_key
+```
+
+Or configure programmatically:
+
+```typescript
+import { init } from '@lelemon/sdk';
+
+init({ apiKey: 'le_xxx' });
+```
+
+## Quick Start
+
+```typescript
+import { trace } from '@lelemon/sdk';
+
+async function runAgent(userMessage: string) {
+  const t = trace({ input: userMessage });
+
+  try {
+    const messages = [
+      { role: 'system', content: 'You are a helpful assistant.' },
+      { role: 'user', content: userMessage },
+    ];
+
+    const response = await openai.chat.completions.create({
+      model: 'gpt-4',
+      messages,
+    });
+
+    // Optional: log response to capture token usage
+    t.log(response);
+
+    messages.push(response.choices[0].message);
+
+    await t.success(messages);
+    return response.choices[0].message.content;
+  } catch (error) {
+    await t.error(error, messages);
+    throw error;
+  }
+}
+```
+
+## Supported Providers
+
+| Provider | Message Format | Auto-detected |
+|----------|---------------|---------------|
+| **OpenAI** | `role: 'user' \| 'assistant'` | Yes |
+| **Anthropic** | `role: 'user' \| 'assistant'` | Yes |
+| **Gemini** | `role: 'user' \| 'model'` | Yes |
+| **AWS Bedrock** | Anthropic format | Yes |
+
+## API Reference
+
+### `trace(options)`
+
+Start a new trace.
+
+```typescript
+const t = trace({
+  input: userMessage,        // Required
+  name: 'my-agent',          // Optional
+  sessionId: 'session-123',  // Optional
+  userId: 'user-456',        // Optional
+  metadata: { ... },         // Optional
+  tags: ['prod'],            // Optional
+});
+```
+
+### `t.success(messages)`
+
+Complete trace successfully.
+
+```typescript
+await t.success(messages);
+```
+
+### `t.error(error, messages?)`
+
+Complete trace with error.
+
+```typescript
+await t.error(error, messages);
+```
+
+### `t.log(response)`
+
+Log an LLM response to capture tokens (optional).
+
+```typescript
+t.log(response);
+```
+
+### `init(config)`
+
+Initialize SDK globally (optional).
+
+```typescript
+init({
+  apiKey: 'le_xxx',
+  endpoint: 'https://custom.endpoint.com',
+  debug: true,
+  disabled: process.env.NODE_ENV === 'test',
+});
+```
+
+## What Gets Captured
+
+- System prompt
+- User input
+- Tool calls and results
+- Final output
+- Token usage
+- Duration
+- Errors with stack traces
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,248 @@
+/**
+ * Lelemon SDK Types
+ * Minimal, low-friction API for LLM observability
+ */
+interface LelemonConfig {
+    /**
+     * API key for authentication (starts with 'le_')
+     * Can also be set via LELEMON_API_KEY env var
+     */
+    apiKey?: string;
+    /**
+     * API endpoint (default: https://api.lelemon.dev)
+     */
+    endpoint?: string;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+    /**
+     * Disable tracing (useful for testing)
+     */
+    disabled?: boolean;
+}
+interface TraceOptions {
+    /**
+     * Initial input (user message, prompt, etc.)
+     */
+    input: unknown;
+    /**
+     * Session ID to group related traces
+     */
+    sessionId?: string;
+    /**
+     * User ID for the end user
+     */
+    userId?: string;
+    /**
+     * Custom metadata
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * 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 for sending data to Lelemon API
+ */
+
+interface TransportConfig {
+    apiKey: string;
+    endpoint: string;
+    debug: boolean;
+    disabled: boolean;
+}
+declare class Transport {
+    private config;
+    constructor(config: TransportConfig);
+    /**
+     * Check if transport is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Create a new trace
+     */
+    createTrace(data: CreateTraceRequest): Promise<{
+        id: string;
+    }>;
+    /**
+     * Complete a trace (success or error)
+     */
+    completeTrace(traceId: string, data: CompleteTraceRequest): Promise<void>;
+    /**
+     * Make HTTP request to API
+     */
+    private request;
+}
+
+/**
+ * Lelemon Tracer - Simple, low-friction API
+ *
+ * Usage:
+ *   const t = trace({ input: userMessage });
+ *   try {
+ *     // your agent code
+ *     t.success(messages);
+ *   } catch (error) {
+ *     t.error(error, messages);
+ *   }
+ */
+
+/**
+ * Initialize the SDK globally (optional)
+ * If not called, trace() will auto-initialize with env vars
+ */
+declare function init(config?: LelemonConfig): void;
+/**
+ * Active trace handle returned by trace()
+ */
+declare class Trace {
+    private id;
+    private transport;
+    private options;
+    private startTime;
+    private completed;
+    private debug;
+    private disabled;
+    private llmCalls;
+    constructor(options: TraceOptions, transport: Transport, debug: boolean, disabled: boolean);
+    /**
+     * Initialize trace on server (called internally)
+     */
+    init(): Promise<void>;
+    /**
+     * Log an LLM response (optional - for tracking individual calls)
+     * Use this if you want to track tokens per call, not just at the end
+     */
+    log(response: unknown): void;
+    /**
+     * Complete trace successfully
+     * @param messages - The full message history (OpenAI/Anthropic format)
+     */
+    success(messages: unknown): Promise<void>;
+    /**
+     * Complete trace with error
+     * @param error - The error that occurred
+     * @param messages - The message history up to the failure (optional)
+     */
+    error(error: Error | unknown, messages?: unknown): Promise<void>;
+}
+/**
+ * Start a new trace
+ *
+ * @example
+ * const t = trace({ input: userMessage });
+ * try {
+ *   const messages = [...];
+ *   // ... your agent code ...
+ *   await t.success(messages);
+ * } catch (error) {
+ *   await t.error(error, messages);
+ *   throw error;
+ * }
+ */
+declare function trace(options: TraceOptions): Trace;
+
+/**
+ * Message Parser
+ * Auto-detects OpenAI/Anthropic/Gemini message formats and extracts relevant data
+ */
+
+/**
+ * Parse messages array and extract structured data
+ */
+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)
+ */
+declare function parseResponse(response: unknown): Partial<ParsedLLMCall>;
+/**
+ * Parse Bedrock InvokeModel response body
+ * Call this with the parsed JSON body from Bedrock
+ */
+declare function parseBedrockResponse(body: unknown): Partial<ParsedLLMCall>;
+
+export { type AnthropicMessage, type LelemonConfig, type Message, type OpenAIMessage, type ParsedLLMCall, type ParsedToolCall, type ParsedTrace, Trace, type TraceOptions, init, parseBedrockResponse, parseMessages, parseResponse, trace };

package/dist/index.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Lelemon SDK Types
+ * Minimal, low-friction API for LLM observability
+ */
+interface LelemonConfig {
+    /**
+     * API key for authentication (starts with 'le_')
+     * Can also be set via LELEMON_API_KEY env var
+     */
+    apiKey?: string;
+    /**
+     * API endpoint (default: https://api.lelemon.dev)
+     */
+    endpoint?: string;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+    /**
+     * Disable tracing (useful for testing)
+     */
+    disabled?: boolean;
+}
+interface TraceOptions {
+    /**
+     * Initial input (user message, prompt, etc.)
+     */
+    input: unknown;
+    /**
+     * Session ID to group related traces
+     */
+    sessionId?: string;
+    /**
+     * User ID for the end user
+     */
+    userId?: string;
+    /**
+     * Custom metadata
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * 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 for sending data to Lelemon API
+ */
+
+interface TransportConfig {
+    apiKey: string;
+    endpoint: string;
+    debug: boolean;
+    disabled: boolean;
+}
+declare class Transport {
+    private config;
+    constructor(config: TransportConfig);
+    /**
+     * Check if transport is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Create a new trace
+     */
+    createTrace(data: CreateTraceRequest): Promise<{
+        id: string;
+    }>;
+    /**
+     * Complete a trace (success or error)
+     */
+    completeTrace(traceId: string, data: CompleteTraceRequest): Promise<void>;
+    /**
+     * Make HTTP request to API
+     */
+    private request;
+}
+
+/**
+ * Lelemon Tracer - Simple, low-friction API
+ *
+ * Usage:
+ *   const t = trace({ input: userMessage });
+ *   try {
+ *     // your agent code
+ *     t.success(messages);
+ *   } catch (error) {
+ *     t.error(error, messages);
+ *   }
+ */
+
+/**
+ * Initialize the SDK globally (optional)
+ * If not called, trace() will auto-initialize with env vars
+ */
+declare function init(config?: LelemonConfig): void;
+/**
+ * Active trace handle returned by trace()
+ */
+declare class Trace {
+    private id;
+    private transport;
+    private options;
+    private startTime;
+    private completed;
+    private debug;
+    private disabled;
+    private llmCalls;
+    constructor(options: TraceOptions, transport: Transport, debug: boolean, disabled: boolean);
+    /**
+     * Initialize trace on server (called internally)
+     */
+    init(): Promise<void>;
+    /**
+     * Log an LLM response (optional - for tracking individual calls)
+     * Use this if you want to track tokens per call, not just at the end
+     */
+    log(response: unknown): void;
+    /**
+     * Complete trace successfully
+     * @param messages - The full message history (OpenAI/Anthropic format)
+     */
+    success(messages: unknown): Promise<void>;
+    /**
+     * Complete trace with error
+     * @param error - The error that occurred
+     * @param messages - The message history up to the failure (optional)
+     */
+    error(error: Error | unknown, messages?: unknown): Promise<void>;
+}
+/**
+ * Start a new trace
+ *
+ * @example
+ * const t = trace({ input: userMessage });
+ * try {
+ *   const messages = [...];
+ *   // ... your agent code ...
+ *   await t.success(messages);
+ * } catch (error) {
+ *   await t.error(error, messages);
+ *   throw error;
+ * }
+ */
+declare function trace(options: TraceOptions): Trace;
+
+/**
+ * Message Parser
+ * Auto-detects OpenAI/Anthropic/Gemini message formats and extracts relevant data
+ */
+
+/**
+ * Parse messages array and extract structured data
+ */
+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)
+ */
+declare function parseResponse(response: unknown): Partial<ParsedLLMCall>;
+/**
+ * Parse Bedrock InvokeModel response body
+ * Call this with the parsed JSON body from Bedrock
+ */
+declare function parseBedrockResponse(body: unknown): Partial<ParsedLLMCall>;
+
+export { type AnthropicMessage, type LelemonConfig, type Message, type OpenAIMessage, type ParsedLLMCall, type ParsedToolCall, type ParsedTrace, Trace, type TraceOptions, init, parseBedrockResponse, parseMessages, parseResponse, trace };