tracia 0.2.7 → 0.3.0

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 interface TraciaOptions {
     apiKey: string;
-    /** Called when background trace creation fails */
-    onTraceError?: (error: Error, traceId: string) => void;
+    /** Called when background span creation fails */
+    onSpanError?: (error: Error, spanId: string) => void;
 }
 interface RunVariables {
     [key: string]: string;
@@ -19,6 +19,9 @@ interface TokenUsage {
 }
 interface RunResult {
     text: string;
+    /** Unique ID for this span (individual LLM call) */
+    spanId: string;
+    /** Trace ID grouping related spans in a session */
     traceId: string;
     promptVersion: number;
     latencyMs: number;
@@ -48,6 +51,7 @@ declare enum LLMProvider {
 }
 interface ApiSuccessResponse {
     text: string;
+    spanId: string;
     traceId: string;
     promptVersion: number;
     latencyMs: number;
@@ -95,13 +99,15 @@ interface UpdatePromptOptions {
     description?: string;
     content?: PromptMessage[];
 }
-type TraceStatus = 'SUCCESS' | 'ERROR';
-interface TraceListItem {
+type SpanStatus = 'SUCCESS' | 'ERROR';
+interface SpanListItem {
     id: string;
+    spanId: string;
     traceId: string;
+    parentSpanId: string | null;
     promptSlug: string;
     model: string;
-    status: TraceStatus;
+    status: SpanStatus;
     latencyMs: number;
     inputTokens: number;
     outputTokens: number;
@@ -109,9 +115,11 @@ interface TraceListItem {
     cost: number | null;
     createdAt: string;
 }
-interface Trace {
+interface Span {
     id: string;
+    spanId: string;
     traceId: string;
+    parentSpanId: string | null;
     promptSlug: string;
     promptVersion: number;
     model: string;
@@ -121,7 +129,7 @@ interface Trace {
     };
     variables: Record<string, string> | null;
     output: string | null;
-    status: TraceStatus;
+    status: SpanStatus;
     error: string | null;
     latencyMs: number;
     inputTokens: number;
@@ -133,9 +141,9 @@ interface Trace {
     sessionId: string | null;
     createdAt: string;
 }
-interface ListTracesOptions {
+interface ListSpansOptions {
     promptSlug?: string;
-    status?: TraceStatus;
+    status?: SpanStatus;
     startDate?: Date;
     endDate?: Date;
     userId?: string;
@@ -144,8 +152,8 @@ interface ListTracesOptions {
     limit?: number;
     cursor?: string;
 }
-interface ListTracesResult {
-    traces: TraceListItem[];
+interface ListSpansResult {
+    spans: SpanListItem[];
     nextCursor?: string;
 }
 interface EvaluateOptions {
@@ -267,17 +275,24 @@ interface RunLocalInput {
     userId?: string;
     sessionId?: string;
     sendTrace?: boolean;
-    /** Custom trace ID. Must match format: tr_ + 16 hex characters */
-    traceId?: string;
+    /** Custom span ID. Must match format: sp_ + 16 hex characters (or legacy tr_ format) */
+    spanId?: string;
     /** Tool definitions for function calling */
     tools?: ToolDefinition[];
     /** Control which tools the model can use */
     toolChoice?: ToolChoice;
     /** AbortSignal to cancel the request (only used when stream: true) */
     signal?: AbortSignal;
+    /** Trace ID to group related spans together (uses first span's ID if not specified in session) */
+    traceId?: string;
+    /** Parent span ID for chaining spans in a sequence */
+    parentSpanId?: string;
 }
 interface RunLocalResult {
     text: string;
+    /** Unique ID for this span (individual LLM call) */
+    spanId: string;
+    /** Trace ID grouping related spans in a session */
     traceId: string;
     latencyMs: number;
     usage: TokenUsage;
@@ -291,8 +306,8 @@ interface RunLocalResult {
     /** Full assistant message for round-tripping in multi-turn conversations */
     message: LocalPromptMessage;
 }
-interface CreateTracePayload {
-    traceId: string;
+interface CreateSpanPayload {
+    spanId: string;
     model: string;
     provider: LLMProvider;
     input: {
@@ -300,7 +315,7 @@ interface CreateTracePayload {
     };
     variables: Record<string, string> | null;
     output: string | null;
-    status: TraceStatus;
+    status: SpanStatus;
     error: string | null;
     latencyMs: number;
     inputTokens: number;
@@ -314,9 +329,13 @@ interface CreateTracePayload {
     topP?: number;
     tools?: ToolDefinition[];
     toolCalls?: ToolCall[];
+    /** Trace ID to group related spans together */
+    traceId?: string;
+    /** Parent span ID for chaining spans in a sequence */
+    parentSpanId?: string;
 }
-interface CreateTraceResult {
-    traceId: string;
+interface CreateSpanResult {
+    spanId: string;
     cost: number | null;
 }
 /**
@@ -338,8 +357,8 @@ interface StreamResult extends RunLocalResult {
  *   stream: true,
  * })
  *
- * // traceId is available immediately
- * console.log('Trace:', stream.traceId)
+ * // spanId is available immediately
+ * console.log('Span:', stream.spanId)
  *
  * // Iterate over text chunks as they arrive
  * for await (const chunk of stream) {
@@ -357,7 +376,9 @@ interface StreamResult extends RunLocalResult {
  * - The stream can only be iterated once
  */
 interface LocalStream {
-    /** Trace ID for this request, available immediately */
+    /** Span ID for this request, available immediately */
+    readonly spanId: string;
+    /** Trace ID grouping related spans, available immediately */
     readonly traceId: string;
     /** Async iterator yielding text chunks */
     [Symbol.asyncIterator](): AsyncIterator<string>;
@@ -431,16 +452,20 @@ interface RunResponsesInput {
     signal?: AbortSignal;
     /** Timeout in milliseconds */
     timeoutMs?: number;
-    /** Whether to send trace to Tracia (default: true) */
+    /** Whether to send span to Tracia (default: true) */
     sendTrace?: boolean;
-    /** Custom trace ID */
-    traceId?: string;
-    /** Tags for the trace */
+    /** Custom span ID */
+    spanId?: string;
+    /** Tags for the span */
     tags?: string[];
-    /** User ID for the trace */
+    /** User ID for the span */
     userId?: string;
-    /** Session ID for the trace */
+    /** Session ID for the span */
     sessionId?: string;
+    /** Trace ID to group related spans together (uses first span's ID if not specified in session) */
+    traceId?: string;
+    /** Parent span ID for chaining spans in a sequence */
+    parentSpanId?: string;
 }
 /**
  * Final result from a Responses API call.
@@ -448,7 +473,9 @@ interface RunResponsesInput {
 interface RunResponsesResult {
     /** Final text output */
     text: string;
-    /** Trace ID for this request */
+    /** Span ID for this request */
+    spanId: string;
+    /** Trace ID grouping related spans in a session */
     traceId: string;
     /** Latency in milliseconds */
     latencyMs: number;
@@ -491,7 +518,9 @@ interface RunResponsesResult {
  * ```
  */
 interface ResponsesStream {
-    /** Trace ID for this request, available immediately */
+    /** Span ID for this request, available immediately */
+    readonly spanId: string;
+    /** Trace ID grouping related spans, available immediately */
     readonly traceId: string;
     /** Async iterator yielding events */
     [Symbol.asyncIterator](): AsyncIterator<ResponsesEvent>;
@@ -500,6 +529,20 @@ interface ResponsesStream {
     /** Abort the stream */
     abort(): void;
 }
+/** @deprecated Use SpanStatus instead */
+type TraceStatus = SpanStatus;
+/** @deprecated Use SpanListItem instead */
+type TraceListItem = SpanListItem;
+/** @deprecated Use Span instead */
+type Trace = Span;
+/** @deprecated Use ListSpansOptions instead */
+type ListTracesOptions = ListSpansOptions;
+/** @deprecated Use ListSpansResult instead */
+type ListTracesResult = ListSpansResult;
+/** @deprecated Use CreateSpanPayload instead */
+type CreateTracePayload = CreateSpanPayload;
+/** @deprecated Use CreateSpanResult instead */
+type CreateTraceResult = CreateSpanResult;
 
 interface HttpClientOptions {
     apiKey: string;
@@ -527,18 +570,105 @@ declare class Prompts {
     run(slug: string, variables?: RunVariables, options?: RunOptions): Promise<RunResult>;
 }
 
-/** @internal Symbol for setting pending traces map - not part of public API */
-declare const INTERNAL_SET_PENDING_TRACES: unique symbol;
-declare class Traces {
+/**
+ * Input for session.runLocal() - same as RunLocalInput but without traceId/parentSpanId
+ * as those are managed by the session.
+ */
+type SessionRunLocalInput = Omit<RunLocalInput, 'traceId' | 'parentSpanId'>;
+/**
+ * Input for session.runResponses() - same as RunResponsesInput but without traceId/parentSpanId
+ * as those are managed by the session.
+ */
+type SessionRunResponsesInput = Omit<RunResponsesInput, 'traceId' | 'parentSpanId'>;
+/**
+ * A session for grouping related spans together under a single trace.
+ *
+ * Sessions automatically chain spans by setting traceId and parentSpanId,
+ * creating a linked sequence of spans that can be viewed together in the Tracia dashboard.
+ *
+ * @example
+ * ```typescript
+ * const session = tracia.createSession()
+ *
+ * // First call - creates the trace group
+ * const result1 = await session.runLocal({
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'What is the weather?' }],
+ * })
+ *
+ * // Second call - automatically linked to the first
+ * const result2 = await session.runLocal({
+ *   model: 'gpt-4o',
+ *   messages: [
+ *     { role: 'user', content: 'What is the weather?' },
+ *     result1.message,
+ *     { role: 'user', content: 'What about tomorrow?' },
+ *   ],
+ * })
+ *
+ * // All spans are grouped under the same trace in the dashboard
+ * ```
+ */
+declare class TraciaSession {
+    private readonly tracia;
+    private traceId;
+    private lastSpanId;
+    /** @internal */
+    constructor(tracia: Tracia);
+    /**
+     * Get the current session's trace ID (the ID that groups all spans together).
+     * Returns null if no spans have been made yet.
+     */
+    getTraceId(): string | null;
+    /**
+     * Get the spanId of the last completed span in the session.
+     * Returns null if no spans have been made yet.
+     */
+    getLastSpanId(): string | null;
+    /**
+     * Reset the session, clearing the trace and parent span IDs.
+     * The next call will start a new trace group.
+     */
+    reset(): void;
+    /**
+     * Execute an LLM call locally, automatically linking it to this session.
+     * See Tracia.runLocal() for full documentation.
+     */
+    runLocal(input: SessionRunLocalInput & {
+        stream: true;
+    }): LocalStream;
+    runLocal(input: SessionRunLocalInput & {
+        stream?: false;
+    }): Promise<RunLocalResult>;
+    private runLocalNonStreaming;
+    private runLocalStreaming;
+    /**
+     * Execute an LLM call using OpenAI's Responses API, automatically linking it to this session.
+     * See Tracia.runResponses() for full documentation.
+     */
+    runResponses(input: SessionRunResponsesInput & {
+        stream: true;
+    }): ResponsesStream;
+    runResponses(input: SessionRunResponsesInput & {
+        stream?: false;
+    }): Promise<RunResponsesResult>;
+    private runResponsesNonStreaming;
+    private runResponsesStreaming;
+    private updateSessionState;
+}
+
+/** @internal Symbol for setting pending spans map - not part of public API */
+declare const INTERNAL_SET_PENDING_SPANS: unique symbol;
+declare class Spans {
     private readonly client;
-    private pendingTraces;
+    private pendingSpans;
     constructor(client: HttpClient);
     /** @internal */
-    [INTERNAL_SET_PENDING_TRACES](map: Map<string, Promise<void>>): void;
-    create(payload: CreateTracePayload): Promise<CreateTraceResult>;
-    get(traceId: string): Promise<Trace>;
-    list(options?: ListTracesOptions): Promise<ListTracesResult>;
-    evaluate(traceId: string, options: EvaluateOptions): Promise<EvaluateResult>;
+    [INTERNAL_SET_PENDING_SPANS](map: Map<string, Promise<void>>): void;
+    create(payload: CreateSpanPayload): Promise<CreateSpanResult>;
+    get(spanId: string): Promise<Span>;
+    list(options?: ListSpansOptions): Promise<ListSpansResult>;
+    evaluate(spanId: string, options: EvaluateOptions): Promise<EvaluateResult>;
 }
 
 declare class TraciaError extends Error {
@@ -553,10 +683,10 @@ declare const Eval: {
 };
 declare class Tracia {
     private readonly client;
-    private readonly pendingTraces;
-    private readonly onTraceError?;
+    private readonly pendingSpans;
+    private readonly onSpanError?;
     readonly prompts: Prompts;
-    readonly traces: Traces;
+    readonly spans: Spans;
     constructor(options: TraciaOptions);
     /**
      * Execute an LLM call locally using the Vercel AI SDK.
@@ -648,13 +778,37 @@ declare class Tracia {
     private createLocalStream;
     private combineAbortSignals;
     flush(): Promise<void>;
+    /**
+     * Create a new session for grouping related spans together under a single trace.
+     *
+     * Sessions automatically chain spans by setting traceId and parentSpanId,
+     * creating a linked sequence of spans that can be viewed together in the Tracia dashboard.
+     *
+     * @example
+     * ```typescript
+     * const session = tracia.createSession()
+     *
+     * // First call - creates the trace group
+     * const result1 = await session.runLocal({
+     *   model: 'gpt-4o',
+     *   messages: [{ role: 'user', content: 'What is the weather?' }],
+     * })
+     *
+     * // Second call - automatically linked to the first
+     * const result2 = await session.runLocal({
+     *   model: 'gpt-4o',
+     *   messages: [...messages, result1.message, { role: 'user', content: 'What about tomorrow?' }],
+     * })
+     * ```
+     */
+    createSession(): TraciaSession;
     private validateRunLocalInput;
-    private scheduleTraceCreation;
-    private createTraceWithRetry;
+    private scheduleSpanCreation;
+    private createSpanWithRetry;
     private delay;
     private interpolateMessages;
     private buildAssistantMessage;
     private getProviderApiKey;
 }
 
-export { type ContentPart, type CreatePromptOptions, type CreateTracePayload, type CreateTraceResult, Eval, type EvaluateOptions, type EvaluateResult, type FinishReason, type JsonSchemaProperty, LLMProvider, type ListTracesOptions, type ListTracesResult, type LocalPromptMessage, type LocalStream, type MessageRole, type Prompt, type PromptListItem, type PromptMessage, type ResponsesEvent, type ResponsesInputItem, type ResponsesOutputItem, type ResponsesStream, type RunLocalInput, type RunLocalResult, type RunOptions, type RunResponsesInput, type RunResponsesResult, type RunResult, type RunVariables, type StreamResult, type TextPart, type TokenUsage, type ToolCall, type ToolCallPart, type ToolChoice, type ToolDefinition, type ToolParameters, type Trace, type TraceListItem, type TraceStatus, Tracia, TraciaError, TraciaErrorCode, type TraciaOptions, type UpdatePromptOptions };
+export { type ContentPart, type CreatePromptOptions, type CreateSpanPayload, type CreateSpanResult, type CreateTracePayload, type CreateTraceResult, Eval, type EvaluateOptions, type EvaluateResult, type FinishReason, type JsonSchemaProperty, LLMProvider, type ListSpansOptions, type ListSpansResult, type ListTracesOptions, type ListTracesResult, type LocalPromptMessage, type LocalStream, type MessageRole, type Prompt, type PromptListItem, type PromptMessage, type ResponsesEvent, type ResponsesInputItem, type ResponsesOutputItem, type ResponsesStream, type RunLocalInput, type RunLocalResult, type RunOptions, type RunResponsesInput, type RunResponsesResult, type RunResult, type RunVariables, type SessionRunLocalInput, type SessionRunResponsesInput, type Span, type SpanListItem, type SpanStatus, type StreamResult, type TextPart, type TokenUsage, type ToolCall, type ToolCallPart, type ToolChoice, type ToolDefinition, type ToolParameters, type Trace, type TraceListItem, type TraceStatus, Tracia, TraciaError, TraciaErrorCode, type TraciaOptions, TraciaSession, type UpdatePromptOptions };