@lelemondev/sdk 0.9.3 → 0.9.5

package/dist/index.d.mts

@@ -1,264 +1,40 @@
-/**
- * Core types for Lelemon SDK
- */
-interface ServiceConfig {
-    /** Service name (e.g., "my-ai-chatbot") */
-    name?: string;
-    /** Service version (e.g., "1.2.3") */
-    version?: string;
-    /** Deployment environment (e.g., "production", "staging", "development") */
-    environment?: string;
-}
-interface LelemonConfig {
-    /** API key (or set LELEMON_API_KEY env var) */
-    apiKey?: string;
-    /** API endpoint (default: https://lelemon.dev) */
-    endpoint?: string;
-    /** Enable debug logging */
-    debug?: boolean;
-    /** Disable tracing */
-    disabled?: boolean;
-    /** Batch size before flush (default: 10) */
-    batchSize?: number;
-    /** Auto-flush interval in ms (default: 1000) */
-    flushIntervalMs?: number;
-    /** Request timeout in ms (default: 10000) */
-    requestTimeoutMs?: number;
-    /** Service metadata for telemetry */
-    service?: ServiceConfig;
-}
-interface SDKTelemetry {
-    /** SDK name */
-    'telemetry.sdk.name': string;
-    /** SDK version */
-    'telemetry.sdk.version': string;
-    /** SDK language */
-    'telemetry.sdk.language': string;
-    /** Runtime name (nodejs, deno, bun, browser) */
-    'process.runtime.name'?: string;
-    /** Runtime version */
-    'process.runtime.version'?: string;
-    /** OS type (linux, darwin, windows) */
-    'os.type'?: string;
-    /** Service name */
-    'service.name'?: string;
-    /** Service version */
-    'service.version'?: string;
-    /** Deployment environment */
-    'deployment.environment'?: string;
-}
-type ProviderName = 'openai' | 'anthropic' | 'gemini' | 'bedrock' | 'openrouter' | 'agent' | 'unknown';
-interface ObserveOptions {
-    /** Session ID to group related calls */
-    sessionId?: string;
-    /** User ID for the end user */
-    userId?: string;
-    /** Custom metadata added to all traces */
-    metadata?: Record<string, unknown>;
-    /** Tags for filtering */
-    tags?: string[];
-}
-type SpanType = 'llm' | 'agent' | 'tool' | 'retrieval' | 'embedding' | 'guardrail' | 'rerank' | 'custom';
-interface CaptureSpanOptions {
-    /** Span type */
-    type: SpanType;
-    /** Span name (tool name, retrieval source, custom name) */
-    name: string;
-    /** Input data */
-    input: unknown;
-    /** Output data */
-    output: unknown;
-    /** Duration in milliseconds */
-    durationMs: number;
-    /** Status */
-    status?: 'success' | 'error';
-    /** Error message if status is 'error' */
-    errorMessage?: string;
-    /** Tool call ID (for linking tool results) */
-    toolCallId?: string;
-    /** Custom metadata */
-    metadata?: Record<string, unknown>;
-}
+import { O as ObserveOptions } from './capture-ChybLulj.mjs';
+export { C as CaptureSpanOptions, L as LelemonConfig, P as ProviderName, b as SDKTelemetry, S as ServiceConfig, h as SpanOptions, d as SpanType, T as TraceContext, e as TraceOptions, c as captureSpan, f as flush, g as getTraceContext, i as init, a as isEnabled, s as span, t as trace } from './capture-ChybLulj.mjs';
 
 /**
- * Global Configuration
+ * Observe Function
  *
- * Manages SDK configuration and transport instance.
+ * Main entry point for wrapping LLM clients with automatic tracing.
  */
 
 /**
- * Initialize the SDK
- * Call once at app startup
- */
-declare function init(config?: LelemonConfig): void;
-/**
- * Check if SDK is enabled
- */
-declare function isEnabled(): boolean;
-/**
- * Flush all pending traces
- */
-declare function flush(): Promise<void>;
-
-/**
- * Trace Context Module
+ * Wrap an LLM client with automatic tracing
  *
- * Provides AsyncLocalStorage-based context for grouping spans under a parent trace.
- * Supports hierarchical tracing where:
- * - trace() creates a root "agent" span
- * - LLM calls become children of the root
- * - Tool calls become children of the LLM that triggered them (via toolCallId linking)
+ * @param client - OpenAI, Anthropic, or Bedrock client instance
+ * @param options - Optional context (sessionId, userId, etc.)
+ * @returns The wrapped client with the same type
  *
  * @example
- * ```typescript
- * import { trace, span } from '@lelemondev/sdk';
- *
- * await trace({ name: 'sales-agent', input: userMessage }, async () => {
- *   const response = await client.send(new ConverseCommand({...}));
- *   // Tools automatically linked to their parent LLM via toolCallId
- *   return response;
- * });
- * ```
- */
-interface TraceContext {
-    /** Unique trace ID (shared by all spans in this trace) */
-    traceId: string;
-    /** Root span ID (the agent/workflow span) */
-    rootSpanId: string;
-    /** Current span ID (for nesting - LLM calls become children of this) */
-    currentSpanId: string;
-    /** Parent span ID (for nested trace() calls) */
-    parentSpanId?: string;
-    /** Trace name */
-    name: string;
-    /** Start time in ms */
-    startTime: number;
-    /** Input data */
-    input?: unknown;
-    /** Trace metadata */
-    metadata?: Record<string, unknown>;
-    /** Trace tags */
-    tags?: string[];
-    /** Map of toolCallId → llmSpanId for linking tool spans to their parent LLM */
-    pendingToolCalls: Map<string, string>;
-}
-interface TraceOptions {
-    /** Name for the trace (e.g., 'sales-agent', 'rag-query') */
-    name: string;
-    /** Input data for the trace */
-    input?: unknown;
-    /** Custom metadata */
-    metadata?: Record<string, unknown>;
-    /** Tags for filtering */
-    tags?: string[];
-}
-interface SpanOptions {
-    /** Span type */
-    type: 'retrieval' | 'embedding' | 'tool' | 'guardrail' | 'rerank' | 'custom';
-    /** Span name (e.g., 'pinecone-search', 'cohere-rerank') */
-    name: string;
-    /** Input data */
-    input?: unknown;
-    /** Output data */
-    output?: unknown;
-    /** Duration in milliseconds (optional, will be set automatically if not provided) */
-    durationMs?: number;
-    /** Status */
-    status?: 'success' | 'error';
-    /** Error message if status is 'error' */
-    errorMessage?: string;
-    /** Tool call ID (links this tool span to the LLM that requested it) */
-    toolCallId?: string;
-    /** Custom metadata */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Get the current trace context, if any
- */
-declare function getTraceContext(): TraceContext | undefined;
-/**
- * Execute a function within a trace context.
- * Creates a root "agent" span that contains all LLM calls and tool executions.
- * The result of the function becomes the output of the root span.
+ * import { observe } from '@lelemondev/sdk';
+ * import OpenAI from 'openai';
  *
- * @example Simple usage (just name)
- * ```typescript
- * await trace('sales-agent', async () => {
- *   await client.send(new ConverseCommand({...}));
- *   return finalResponse;
- * });
- * ```
+ * const openai = observe(new OpenAI());
  *
- * @example With options
- * ```typescript
- * await trace({ name: 'rag-query', input: question, tags: ['production'] }, async () => {
- *   const docs = await search(question);
- *   span({ type: 'retrieval', name: 'pinecone', output: { count: docs.length } });
- *   return client.send(new ConverseCommand({...}));
- * });
- * ```
+ * // All calls are now automatically traced
+ * const response = await openai.chat.completions.create({...});
  */
-declare function trace<T>(nameOrOptions: string | TraceOptions, fn: () => Promise<T>): Promise<T>;
+declare function observe<T>(client: T, options?: ObserveOptions): T;
 /**
- * Manually capture a span for non-LLM operations (retrieval, embedding, tool, etc.)
- * Must be called within a trace() block.
- *
- * @example Tool with toolCallId (links to parent LLM)
- * ```typescript
- * span({
- *   type: 'tool',
- *   name: 'query_database',
- *   toolCallId: 'tooluse_abc123',  // Links to LLM that requested this
- *   input: { sql: 'SELECT ...' },
- *   output: { rows: [...] },
- *   durationMs: 15,
- * });
- * ```
- *
- * @example Retrieval without toolCallId
- * ```typescript
- * span({
- *   type: 'retrieval',
- *   name: 'pinecone-search',
- *   input: { topK: 5 },
- *   output: { count: 10 },
- *   durationMs: 50,
- * });
- * ```
- */
-declare function span(options: SpanOptions): void;
-
-/**
- * Capture Module
- *
- * Handles trace capture and batching.
- * Called by providers to record LLM calls.
- */
-
-/**
- * Manually capture a span (tool call, retrieval, custom)
- * Use this when auto-detection doesn't cover your use case
+ * Create a scoped observe function with preset context
  *
  * @example
- * // Capture a tool call
- * captureSpan({
- *   type: 'tool',
- *   name: 'get_weather',
- *   input: { location: 'San Francisco' },
- *   output: { temperature: 72, conditions: 'sunny' },
- *   durationMs: 150,
+ * const observeWithSession = createObserve({
+ *   sessionId: 'session-123',
+ *   userId: 'user-456',
  * });
  *
- * @example
- * // Capture a retrieval/RAG operation
- * captureSpan({
- *   type: 'retrieval',
- *   name: 'vector_search',
- *   input: { query: 'user question', k: 5 },
- *   output: { documents: [...] },
- *   durationMs: 50,
- * });
+ * const openai = observeWithSession(new OpenAI());
  */
-declare function captureSpan(options: CaptureSpanOptions): void;
+declare function createObserve(defaultOptions: ObserveOptions): <T>(client: T, options?: ObserveOptions) => T;
 
-export { type CaptureSpanOptions, type LelemonConfig, type ObserveOptions, type ProviderName, type SDKTelemetry, type ServiceConfig, type SpanOptions, type SpanType, type TraceContext, type TraceOptions, captureSpan, flush, getTraceContext, init, isEnabled, span, trace };
+export { ObserveOptions, createObserve, observe };

package/dist/index.d.ts

@@ -1,264 +1,40 @@
-/**
- * Core types for Lelemon SDK
- */
-interface ServiceConfig {
-    /** Service name (e.g., "my-ai-chatbot") */
-    name?: string;
-    /** Service version (e.g., "1.2.3") */
-    version?: string;
-    /** Deployment environment (e.g., "production", "staging", "development") */
-    environment?: string;
-}
-interface LelemonConfig {
-    /** API key (or set LELEMON_API_KEY env var) */
-    apiKey?: string;
-    /** API endpoint (default: https://lelemon.dev) */
-    endpoint?: string;
-    /** Enable debug logging */
-    debug?: boolean;
-    /** Disable tracing */
-    disabled?: boolean;
-    /** Batch size before flush (default: 10) */
-    batchSize?: number;
-    /** Auto-flush interval in ms (default: 1000) */
-    flushIntervalMs?: number;
-    /** Request timeout in ms (default: 10000) */
-    requestTimeoutMs?: number;
-    /** Service metadata for telemetry */
-    service?: ServiceConfig;
-}
-interface SDKTelemetry {
-    /** SDK name */
-    'telemetry.sdk.name': string;
-    /** SDK version */
-    'telemetry.sdk.version': string;
-    /** SDK language */
-    'telemetry.sdk.language': string;
-    /** Runtime name (nodejs, deno, bun, browser) */
-    'process.runtime.name'?: string;
-    /** Runtime version */
-    'process.runtime.version'?: string;
-    /** OS type (linux, darwin, windows) */
-    'os.type'?: string;
-    /** Service name */
-    'service.name'?: string;
-    /** Service version */
-    'service.version'?: string;
-    /** Deployment environment */
-    'deployment.environment'?: string;
-}
-type ProviderName = 'openai' | 'anthropic' | 'gemini' | 'bedrock' | 'openrouter' | 'agent' | 'unknown';
-interface ObserveOptions {
-    /** Session ID to group related calls */
-    sessionId?: string;
-    /** User ID for the end user */
-    userId?: string;
-    /** Custom metadata added to all traces */
-    metadata?: Record<string, unknown>;
-    /** Tags for filtering */
-    tags?: string[];
-}
-type SpanType = 'llm' | 'agent' | 'tool' | 'retrieval' | 'embedding' | 'guardrail' | 'rerank' | 'custom';
-interface CaptureSpanOptions {
-    /** Span type */
-    type: SpanType;
-    /** Span name (tool name, retrieval source, custom name) */
-    name: string;
-    /** Input data */
-    input: unknown;
-    /** Output data */
-    output: unknown;
-    /** Duration in milliseconds */
-    durationMs: number;
-    /** Status */
-    status?: 'success' | 'error';
-    /** Error message if status is 'error' */
-    errorMessage?: string;
-    /** Tool call ID (for linking tool results) */
-    toolCallId?: string;
-    /** Custom metadata */
-    metadata?: Record<string, unknown>;
-}
+import { O as ObserveOptions } from './capture-ChybLulj.js';
+export { C as CaptureSpanOptions, L as LelemonConfig, P as ProviderName, b as SDKTelemetry, S as ServiceConfig, h as SpanOptions, d as SpanType, T as TraceContext, e as TraceOptions, c as captureSpan, f as flush, g as getTraceContext, i as init, a as isEnabled, s as span, t as trace } from './capture-ChybLulj.js';
 
 /**
- * Global Configuration
+ * Observe Function
  *
- * Manages SDK configuration and transport instance.
+ * Main entry point for wrapping LLM clients with automatic tracing.
  */
 
 /**
- * Initialize the SDK
- * Call once at app startup
- */
-declare function init(config?: LelemonConfig): void;
-/**
- * Check if SDK is enabled
- */
-declare function isEnabled(): boolean;
-/**
- * Flush all pending traces
- */
-declare function flush(): Promise<void>;
-
-/**
- * Trace Context Module
+ * Wrap an LLM client with automatic tracing
  *
- * Provides AsyncLocalStorage-based context for grouping spans under a parent trace.
- * Supports hierarchical tracing where:
- * - trace() creates a root "agent" span
- * - LLM calls become children of the root
- * - Tool calls become children of the LLM that triggered them (via toolCallId linking)
+ * @param client - OpenAI, Anthropic, or Bedrock client instance
+ * @param options - Optional context (sessionId, userId, etc.)
+ * @returns The wrapped client with the same type
  *
  * @example
- * ```typescript
- * import { trace, span } from '@lelemondev/sdk';
- *
- * await trace({ name: 'sales-agent', input: userMessage }, async () => {
- *   const response = await client.send(new ConverseCommand({...}));
- *   // Tools automatically linked to their parent LLM via toolCallId
- *   return response;
- * });
- * ```
- */
-interface TraceContext {
-    /** Unique trace ID (shared by all spans in this trace) */
-    traceId: string;
-    /** Root span ID (the agent/workflow span) */
-    rootSpanId: string;
-    /** Current span ID (for nesting - LLM calls become children of this) */
-    currentSpanId: string;
-    /** Parent span ID (for nested trace() calls) */
-    parentSpanId?: string;
-    /** Trace name */
-    name: string;
-    /** Start time in ms */
-    startTime: number;
-    /** Input data */
-    input?: unknown;
-    /** Trace metadata */
-    metadata?: Record<string, unknown>;
-    /** Trace tags */
-    tags?: string[];
-    /** Map of toolCallId → llmSpanId for linking tool spans to their parent LLM */
-    pendingToolCalls: Map<string, string>;
-}
-interface TraceOptions {
-    /** Name for the trace (e.g., 'sales-agent', 'rag-query') */
-    name: string;
-    /** Input data for the trace */
-    input?: unknown;
-    /** Custom metadata */
-    metadata?: Record<string, unknown>;
-    /** Tags for filtering */
-    tags?: string[];
-}
-interface SpanOptions {
-    /** Span type */
-    type: 'retrieval' | 'embedding' | 'tool' | 'guardrail' | 'rerank' | 'custom';
-    /** Span name (e.g., 'pinecone-search', 'cohere-rerank') */
-    name: string;
-    /** Input data */
-    input?: unknown;
-    /** Output data */
-    output?: unknown;
-    /** Duration in milliseconds (optional, will be set automatically if not provided) */
-    durationMs?: number;
-    /** Status */
-    status?: 'success' | 'error';
-    /** Error message if status is 'error' */
-    errorMessage?: string;
-    /** Tool call ID (links this tool span to the LLM that requested it) */
-    toolCallId?: string;
-    /** Custom metadata */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Get the current trace context, if any
- */
-declare function getTraceContext(): TraceContext | undefined;
-/**
- * Execute a function within a trace context.
- * Creates a root "agent" span that contains all LLM calls and tool executions.
- * The result of the function becomes the output of the root span.
+ * import { observe } from '@lelemondev/sdk';
+ * import OpenAI from 'openai';
  *
- * @example Simple usage (just name)
- * ```typescript
- * await trace('sales-agent', async () => {
- *   await client.send(new ConverseCommand({...}));
- *   return finalResponse;
- * });
- * ```
+ * const openai = observe(new OpenAI());
  *
- * @example With options
- * ```typescript
- * await trace({ name: 'rag-query', input: question, tags: ['production'] }, async () => {
- *   const docs = await search(question);
- *   span({ type: 'retrieval', name: 'pinecone', output: { count: docs.length } });
- *   return client.send(new ConverseCommand({...}));
- * });
- * ```
+ * // All calls are now automatically traced
+ * const response = await openai.chat.completions.create({...});
  */
-declare function trace<T>(nameOrOptions: string | TraceOptions, fn: () => Promise<T>): Promise<T>;
+declare function observe<T>(client: T, options?: ObserveOptions): T;
 /**
- * Manually capture a span for non-LLM operations (retrieval, embedding, tool, etc.)
- * Must be called within a trace() block.
- *
- * @example Tool with toolCallId (links to parent LLM)
- * ```typescript
- * span({
- *   type: 'tool',
- *   name: 'query_database',
- *   toolCallId: 'tooluse_abc123',  // Links to LLM that requested this
- *   input: { sql: 'SELECT ...' },
- *   output: { rows: [...] },
- *   durationMs: 15,
- * });
- * ```
- *
- * @example Retrieval without toolCallId
- * ```typescript
- * span({
- *   type: 'retrieval',
- *   name: 'pinecone-search',
- *   input: { topK: 5 },
- *   output: { count: 10 },
- *   durationMs: 50,
- * });
- * ```
- */
-declare function span(options: SpanOptions): void;
-
-/**
- * Capture Module
- *
- * Handles trace capture and batching.
- * Called by providers to record LLM calls.
- */
-
-/**
- * Manually capture a span (tool call, retrieval, custom)
- * Use this when auto-detection doesn't cover your use case
+ * Create a scoped observe function with preset context
  *
  * @example
- * // Capture a tool call
- * captureSpan({
- *   type: 'tool',
- *   name: 'get_weather',
- *   input: { location: 'San Francisco' },
- *   output: { temperature: 72, conditions: 'sunny' },
- *   durationMs: 150,
+ * const observeWithSession = createObserve({
+ *   sessionId: 'session-123',
+ *   userId: 'user-456',
  * });
  *
- * @example
- * // Capture a retrieval/RAG operation
- * captureSpan({
- *   type: 'retrieval',
- *   name: 'vector_search',
- *   input: { query: 'user question', k: 5 },
- *   output: { documents: [...] },
- *   durationMs: 50,
- * });
+ * const openai = observeWithSession(new OpenAI());
  */
-declare function captureSpan(options: CaptureSpanOptions): void;
+declare function createObserve(defaultOptions: ObserveOptions): <T>(client: T, options?: ObserveOptions) => T;
 
-export { type CaptureSpanOptions, type LelemonConfig, type ObserveOptions, type ProviderName, type SDKTelemetry, type ServiceConfig, type SpanOptions, type SpanType, type TraceContext, type TraceOptions, captureSpan, flush, getTraceContext, init, isEnabled, span, trace };
+export { ObserveOptions, createObserve, observe };