@lelemondev/sdk 0.6.3 → 0.7.1

package/dist/index.d.mts

@@ -28,6 +28,27 @@ interface ObserveOptions {
     /** Tags for filtering */
     tags?: string[];
 }
+type SpanType = 'llm' | '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>;
+}
 
 /**
  * Global Configuration
@@ -85,4 +106,151 @@ declare function observe<T>(client: T, options?: ObserveOptions): T;
  */
 declare function createObserve(defaultOptions: ObserveOptions): <T>(client: T, options?: ObserveOptions) => T;
 
-export { type LelemonConfig, type ObserveOptions, type ProviderName, createObserve, flush, init, isEnabled, observe };
+/**
+ * Trace Context Module
+ *
+ * Provides AsyncLocalStorage-based context for grouping spans under a parent trace.
+ * This enables hierarchical tracing without modifying the simple observe() API.
+ *
+ * @example
+ * ```typescript
+ * import { trace, span } from '@lelemondev/sdk';
+ *
+ * await trace('sales-agent', async () => {
+ *   await client.send(new ConverseCommand({...})); // Span 1
+ *   await client.send(new ConverseCommand({...})); // Span 2
+ *   span({ type: 'retrieval', name: 'pinecone', output: { count: 5 } });
+ * });
+ * ```
+ */
+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[];
+}
+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;
+    /** 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.
+ * All LLM calls made within this function will be grouped under the same trace.
+ *
+ * @example Simple usage (just name)
+ * ```typescript
+ * await trace('sales-agent', async () => {
+ *   await client.send(new ConverseCommand({...}));
+ *   await client.send(new ConverseCommand({...}));
+ * });
+ * ```
+ *
+ * @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({...}));
+ * });
+ * ```
+ */
+declare function trace<T>(nameOrOptions: string | TraceOptions, fn: () => Promise<T>): Promise<T>;
+/**
+ * Manually capture a span for non-LLM operations (retrieval, embedding, etc.)
+ * Must be called within a trace() block.
+ *
+ * @example
+ * ```typescript
+ * await trace('rag-query', async () => {
+ *   const t0 = Date.now();
+ *   const docs = await pinecone.query({ vector, topK: 5 });
+ *   span({
+ *     type: 'retrieval',
+ *     name: 'pinecone-search',
+ *     input: { topK: 5 },
+ *     output: { count: docs.length },
+ *     durationMs: Date.now() - t0,
+ *   });
+ *
+ *   return client.send(new ConverseCommand({...}));
+ * });
+ * ```
+ */
+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
+ *
+ * @example
+ * // Capture a tool call
+ * captureSpan({
+ *   type: 'tool',
+ *   name: 'get_weather',
+ *   input: { location: 'San Francisco' },
+ *   output: { temperature: 72, conditions: 'sunny' },
+ *   durationMs: 150,
+ * });
+ *
+ * @example
+ * // Capture a retrieval/RAG operation
+ * captureSpan({
+ *   type: 'retrieval',
+ *   name: 'vector_search',
+ *   input: { query: 'user question', k: 5 },
+ *   output: { documents: [...] },
+ *   durationMs: 50,
+ * });
+ */
+declare function captureSpan(options: CaptureSpanOptions): void;
+
+export { type CaptureSpanOptions, type LelemonConfig, type ObserveOptions, type ProviderName, type SpanOptions, type SpanType, type TraceOptions, captureSpan, createObserve, flush, getTraceContext, init, isEnabled, observe, span, trace };

package/dist/index.d.ts

@@ -28,6 +28,27 @@ interface ObserveOptions {
     /** Tags for filtering */
     tags?: string[];
 }
+type SpanType = 'llm' | '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>;
+}
 
 /**
  * Global Configuration
@@ -85,4 +106,151 @@ declare function observe<T>(client: T, options?: ObserveOptions): T;
  */
 declare function createObserve(defaultOptions: ObserveOptions): <T>(client: T, options?: ObserveOptions) => T;
 
-export { type LelemonConfig, type ObserveOptions, type ProviderName, createObserve, flush, init, isEnabled, observe };
+/**
+ * Trace Context Module
+ *
+ * Provides AsyncLocalStorage-based context for grouping spans under a parent trace.
+ * This enables hierarchical tracing without modifying the simple observe() API.
+ *
+ * @example
+ * ```typescript
+ * import { trace, span } from '@lelemondev/sdk';
+ *
+ * await trace('sales-agent', async () => {
+ *   await client.send(new ConverseCommand({...})); // Span 1
+ *   await client.send(new ConverseCommand({...})); // Span 2
+ *   span({ type: 'retrieval', name: 'pinecone', output: { count: 5 } });
+ * });
+ * ```
+ */
+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[];
+}
+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;
+    /** 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.
+ * All LLM calls made within this function will be grouped under the same trace.
+ *
+ * @example Simple usage (just name)
+ * ```typescript
+ * await trace('sales-agent', async () => {
+ *   await client.send(new ConverseCommand({...}));
+ *   await client.send(new ConverseCommand({...}));
+ * });
+ * ```
+ *
+ * @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({...}));
+ * });
+ * ```
+ */
+declare function trace<T>(nameOrOptions: string | TraceOptions, fn: () => Promise<T>): Promise<T>;
+/**
+ * Manually capture a span for non-LLM operations (retrieval, embedding, etc.)
+ * Must be called within a trace() block.
+ *
+ * @example
+ * ```typescript
+ * await trace('rag-query', async () => {
+ *   const t0 = Date.now();
+ *   const docs = await pinecone.query({ vector, topK: 5 });
+ *   span({
+ *     type: 'retrieval',
+ *     name: 'pinecone-search',
+ *     input: { topK: 5 },
+ *     output: { count: docs.length },
+ *     durationMs: Date.now() - t0,
+ *   });
+ *
+ *   return client.send(new ConverseCommand({...}));
+ * });
+ * ```
+ */
+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
+ *
+ * @example
+ * // Capture a tool call
+ * captureSpan({
+ *   type: 'tool',
+ *   name: 'get_weather',
+ *   input: { location: 'San Francisco' },
+ *   output: { temperature: 72, conditions: 'sunny' },
+ *   durationMs: 150,
+ * });
+ *
+ * @example
+ * // Capture a retrieval/RAG operation
+ * captureSpan({
+ *   type: 'retrieval',
+ *   name: 'vector_search',
+ *   input: { query: 'user question', k: 5 },
+ *   output: { documents: [...] },
+ *   durationMs: 50,
+ * });
+ */
+declare function captureSpan(options: CaptureSpanOptions): void;
+
+export { type CaptureSpanOptions, type LelemonConfig, type ObserveOptions, type ProviderName, type SpanOptions, type SpanType, type TraceOptions, captureSpan, createObserve, flush, getTraceContext, init, isEnabled, observe, span, trace };