tracia 0.2.0 → 0.2.3

package/dist/index.d.mts

@@ -1,5 +1,7 @@
 interface TraciaOptions {
     apiKey: string;
+    /** Called when background trace creation fails */
+    onTraceError?: (error: Error, traceId: string) => void;
 }
 interface RunVariables {
     [key: string]: string;
@@ -33,7 +35,16 @@ declare enum TraciaErrorCode {
     INVALID_REQUEST = "INVALID_REQUEST",
     NETWORK_ERROR = "NETWORK_ERROR",
     TIMEOUT = "TIMEOUT",
-    UNKNOWN = "UNKNOWN"
+    ABORTED = "ABORTED",
+    UNKNOWN = "UNKNOWN",
+    MISSING_PROVIDER_SDK = "MISSING_PROVIDER_SDK",
+    MISSING_PROVIDER_API_KEY = "MISSING_PROVIDER_API_KEY",
+    UNSUPPORTED_MODEL = "UNSUPPORTED_MODEL"
+}
+declare enum LLMProvider {
+    OPENAI = "openai",
+    ANTHROPIC = "anthropic",
+    GOOGLE = "google"
 }
 interface ApiSuccessResponse {
     text: string;
@@ -43,7 +54,7 @@ interface ApiSuccessResponse {
     usage: TokenUsage;
     cost: number;
 }
-type MessageRole = 'system' | 'user' | 'assistant';
+type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
 interface PromptMessage {
     id: string;
     role: MessageRole;
@@ -151,6 +162,344 @@ interface EvaluateResult {
     note: string | null;
     createdAt: string;
 }
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: ToolParameters;
+}
+interface ToolParameters {
+    type: 'object';
+    properties: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+interface JsonSchemaProperty {
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+    description?: string;
+    enum?: (string | number)[];
+    items?: JsonSchemaProperty;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+/**
+ * Tool call returned in results - user-friendly format.
+ */
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+type ToolChoice = 'auto' | 'none' | 'required' | {
+    tool: string;
+};
+type FinishReason = 'stop' | 'tool_calls' | 'max_tokens';
+/**
+ * Text content part for messages.
+ */
+interface TextPart {
+    type: 'text';
+    text: string;
+}
+/**
+ * Tool call part in assistant messages.
+ */
+interface ToolCallPart {
+    type: 'tool_call';
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+type ContentPart = TextPart | ToolCallPart;
+/**
+ * Message format for LLM conversations.
+ *
+ * @example System message
+ * ```typescript
+ * { role: 'system', content: 'You are a helpful assistant.' }
+ * ```
+ *
+ * @example User message
+ * ```typescript
+ * { role: 'user', content: 'What is the weather?' }
+ * ```
+ *
+ * @example Assistant message with tool calls
+ * ```typescript
+ * {
+ *   role: 'assistant',
+ *   content: [
+ *     { type: 'text', text: 'Let me check the weather.' },
+ *     { type: 'tool_call', id: 'call_123', name: 'get_weather', arguments: { location: 'Paris' } }
+ *   ]
+ * }
+ * ```
+ *
+ * @example Tool result message (simple format)
+ * ```typescript
+ * { role: 'tool', toolCallId: 'call_123', toolName: 'get_weather', content: '{"temp": 22, "unit": "celsius"}' }
+ * ```
+ */
+interface LocalPromptMessage {
+    role: MessageRole;
+    content: string | ContentPart[];
+    /** Required when role is 'tool' - the ID of the tool call this is responding to */
+    toolCallId?: string;
+    /** Required when role is 'tool' - the name of the tool that was called */
+    toolName?: string;
+}
+interface RunLocalInput {
+    messages: LocalPromptMessage[];
+    model: string;
+    /** Enable streaming. When true, returns LocalStream. When false/undefined, returns Promise<RunLocalResult>. */
+    stream?: boolean;
+    /** Explicitly specify the provider. Use for new/custom models not in the built-in list. */
+    provider?: LLMProvider;
+    temperature?: number;
+    maxOutputTokens?: number;
+    topP?: number;
+    stopSequences?: string[];
+    /** Timeout in milliseconds for the LLM call */
+    timeoutMs?: number;
+    /** Provider-specific options passed directly to the SDK */
+    customOptions?: Record<string, unknown>;
+    variables?: Record<string, string>;
+    providerApiKey?: string;
+    tags?: string[];
+    userId?: string;
+    sessionId?: string;
+    sendTrace?: boolean;
+    /** Custom trace ID. Must match format: tr_ + 16 hex characters */
+    traceId?: 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;
+}
+interface RunLocalResult {
+    text: string;
+    traceId: string;
+    latencyMs: number;
+    usage: TokenUsage;
+    cost: number | null;
+    provider: LLMProvider;
+    model: string;
+    /** Tool calls made by the model, empty array if none */
+    toolCalls: ToolCall[];
+    /** Reason the model stopped generating */
+    finishReason: FinishReason;
+    /** Full assistant message for round-tripping in multi-turn conversations */
+    message: LocalPromptMessage;
+}
+interface CreateTracePayload {
+    traceId: string;
+    model: string;
+    provider: LLMProvider;
+    input: {
+        messages: LocalPromptMessage[];
+    };
+    variables: Record<string, string> | null;
+    output: string | null;
+    status: TraceStatus;
+    error: string | null;
+    latencyMs: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    tags?: string[];
+    userId?: string;
+    sessionId?: string;
+    temperature?: number;
+    maxOutputTokens?: number;
+    topP?: number;
+    tools?: ToolDefinition[];
+    toolCalls?: ToolCall[];
+}
+interface CreateTraceResult {
+    traceId: string;
+    cost: number | null;
+}
+/**
+ * Final result returned after a stream completes.
+ * Includes all fields from RunLocalResult plus abort status.
+ */
+interface StreamResult extends RunLocalResult {
+    /** Whether the stream was aborted before completion */
+    aborted: boolean;
+}
+/**
+ * A streaming response from runLocal({ stream: true }).
+ *
+ * @example
+ * ```typescript
+ * const stream = tracia.runLocal({
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'Write a haiku' }],
+ *   stream: true,
+ * })
+ *
+ * // traceId is available immediately
+ * console.log('Trace:', stream.traceId)
+ *
+ * // Iterate over text chunks as they arrive
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk)
+ * }
+ *
+ * // Get final result with usage stats after iteration completes
+ * const result = await stream.result
+ * console.log(result.usage)
+ * ```
+ *
+ * @remarks
+ * - You must iterate over the stream for the result promise to resolve
+ * - Calling abort() will stop the stream and resolve result with aborted: true
+ * - The stream can only be iterated once
+ */
+interface LocalStream {
+    /** Trace ID for this request, available immediately */
+    readonly traceId: string;
+    /** Async iterator yielding text chunks */
+    [Symbol.asyncIterator](): AsyncIterator<string>;
+    /**
+     * Promise that resolves to the final result after stream completes.
+     * Only resolves after the stream has been fully iterated or aborted.
+     */
+    readonly result: Promise<StreamResult>;
+    /** Abort the stream. The result promise will resolve with aborted: true */
+    abort(): void;
+}
+/**
+ * Input item for the Responses API.
+ * Can be a message (developer/user) or a function call output.
+ */
+type ResponsesInputItem = {
+    role: 'developer' | 'user';
+    content: string;
+} | {
+    type: 'function_call_output';
+    call_id: string;
+    output: string;
+} | ResponsesOutputItem;
+/**
+ * Output item from a Responses API call.
+ * These can be added back to input for multi-turn conversations.
+ */
+interface ResponsesOutputItem {
+    type: 'message' | 'function_call' | 'reasoning';
+    [key: string]: unknown;
+}
+/**
+ * Event yielded during Responses API streaming.
+ */
+type ResponsesEvent = {
+    type: 'text_delta';
+    data: string;
+} | {
+    type: 'text';
+    data: string;
+} | {
+    type: 'reasoning';
+    content: string;
+} | {
+    type: 'tool_call';
+    id: string;
+    callId: string;
+    name: string;
+    arguments: Record<string, unknown>;
+} | {
+    type: 'done';
+    usage: TokenUsage;
+};
+/**
+ * Input options for runResponses().
+ */
+interface RunResponsesInput {
+    /** Model to use (e.g., 'gpt-4o', 'o1', 'o3-mini') */
+    model: string;
+    /** Input items for the conversation */
+    input: ResponsesInputItem[];
+    /** Enable streaming. When true, returns ResponsesStream. When false/undefined, returns Promise<RunResponsesResult>. */
+    stream?: boolean;
+    /** Tool definitions for function calling */
+    tools?: ToolDefinition[];
+    /** Maximum output tokens */
+    maxOutputTokens?: number;
+    /** Provider API key override */
+    providerApiKey?: string;
+    /** AbortSignal to cancel the request (only used when stream: true) */
+    signal?: AbortSignal;
+    /** Timeout in milliseconds */
+    timeoutMs?: number;
+    /** Whether to send trace to Tracia (default: true) */
+    sendTrace?: boolean;
+    /** Custom trace ID */
+    traceId?: string;
+    /** Tags for the trace */
+    tags?: string[];
+    /** User ID for the trace */
+    userId?: string;
+    /** Session ID for the trace */
+    sessionId?: string;
+}
+/**
+ * Final result from a Responses API call.
+ */
+interface RunResponsesResult {
+    /** Final text output */
+    text: string;
+    /** Trace ID for this request */
+    traceId: string;
+    /** Latency in milliseconds */
+    latencyMs: number;
+    /** Token usage */
+    usage: TokenUsage;
+    /** Output items that can be added back to input for multi-turn */
+    outputItems: ResponsesOutputItem[];
+    /** Tool calls made by the model */
+    toolCalls: Array<{
+        id: string;
+        callId: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }>;
+    /** Whether the stream was aborted */
+    aborted: boolean;
+}
+/**
+ * A streaming response from runResponses({ stream: true }).
+ *
+ * @example
+ * ```typescript
+ * const stream = tracia.runResponses({
+ *   model: 'o3-mini',
+ *   input: [
+ *     { role: 'developer', content: 'You are a helpful assistant.' },
+ *     { role: 'user', content: 'What is 2+2?' },
+ *   ],
+ *   stream: true,
+ * })
+ *
+ * for await (const event of stream) {
+ *   if (event.type === 'text_delta') process.stdout.write(event.data)
+ *   if (event.type === 'reasoning') console.log('Thinking:', event.content)
+ *   if (event.type === 'tool_call') console.log('Tool:', event.name)
+ * }
+ *
+ * const result = await stream.result
+ * console.log('Output items:', result.outputItems)
+ * ```
+ */
+interface ResponsesStream {
+    /** Trace ID for this request, available immediately */
+    readonly traceId: string;
+    /** Async iterator yielding events */
+    [Symbol.asyncIterator](): AsyncIterator<ResponsesEvent>;
+    /** Promise that resolves to the final result after stream completes */
+    readonly result: Promise<RunResponsesResult>;
+    /** Abort the stream */
+    abort(): void;
+}
 
 interface HttpClientOptions {
     apiKey: string;
@@ -178,9 +527,15 @@ 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 {
     private readonly client;
+    private pendingTraces;
     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>;
@@ -198,9 +553,108 @@ declare const Eval: {
 };
 declare class Tracia {
     private readonly client;
+    private readonly pendingTraces;
+    private readonly onTraceError?;
     readonly prompts: Prompts;
     readonly traces: Traces;
     constructor(options: TraciaOptions);
+    /**
+     * Execute an LLM call locally using the Vercel AI SDK.
+     *
+     * @example Non-streaming (default)
+     * ```typescript
+     * const result = await tracia.runLocal({
+     *   model: 'gpt-4o',
+     *   messages: [{ role: 'user', content: 'Hello' }],
+     * })
+     * console.log(result.text)
+     * ```
+     *
+     * @example Streaming
+     * ```typescript
+     * const stream = tracia.runLocal({
+     *   model: 'gpt-4o',
+     *   messages: [{ role: 'user', content: 'Write a poem' }],
+     *   stream: true,
+     * })
+     *
+     * for await (const chunk of stream) {
+     *   process.stdout.write(chunk)
+     * }
+     *
+     * const result = await stream.result
+     * console.log('Tokens used:', result.usage.totalTokens)
+     * ```
+     */
+    runLocal(input: RunLocalInput & {
+        stream: true;
+    }): LocalStream;
+    runLocal(input: RunLocalInput & {
+        stream?: false;
+    }): Promise<RunLocalResult>;
+    private runLocalNonStreaming;
+    private runLocalStreaming;
+    /**
+     * Execute an LLM call using OpenAI's Responses API.
+     *
+     * The Responses API is OpenAI-specific and supports:
+     * - Reasoning models (o1, o3-mini) with reasoning summaries
+     * - Multi-turn conversations with output items
+     * - Different input format (developer/user roles, function_call_output)
+     *
+     * @example Non-streaming (default)
+     * ```typescript
+     * const result = await tracia.runResponses({
+     *   model: 'o3-mini',
+     *   input: [
+     *     { role: 'developer', content: 'You are helpful.' },
+     *     { role: 'user', content: 'What is 2+2?' },
+     *   ],
+     * })
+     * console.log(result.text)
+     * ```
+     *
+     * @example Streaming
+     * ```typescript
+     * const stream = tracia.runResponses({
+     *   model: 'o3-mini',
+     *   input: [
+     *     { role: 'developer', content: 'You are helpful.' },
+     *     { role: 'user', content: 'What is 2+2?' },
+     *   ],
+     *   stream: true,
+     * })
+     *
+     * for await (const event of stream) {
+     *   if (event.type === 'text_delta') process.stdout.write(event.data)
+     *   if (event.type === 'reasoning') console.log('Reasoning:', event.content)
+     *   if (event.type === 'tool_call') console.log('Tool:', event.name, event.arguments)
+     * }
+     *
+     * const result = await stream.result
+     * console.log('Output items:', result.outputItems)
+     * ```
+     */
+    runResponses(input: RunResponsesInput & {
+        stream: true;
+    }): ResponsesStream;
+    runResponses(input: RunResponsesInput & {
+        stream?: false;
+    }): Promise<RunResponsesResult>;
+    private runResponsesNonStreaming;
+    private runResponsesStreaming;
+    private validateResponsesInput;
+    private createResponsesStream;
+    private createLocalStream;
+    private combineAbortSignals;
+    flush(): Promise<void>;
+    private validateRunLocalInput;
+    private scheduleTraceCreation;
+    private createTraceWithRetry;
+    private delay;
+    private interpolateMessages;
+    private buildAssistantMessage;
+    private getProviderApiKey;
 }
 
-export { type CreatePromptOptions, Eval, type EvaluateOptions, type EvaluateResult, type ListTracesOptions, type ListTracesResult, type MessageRole, type Prompt, type PromptListItem, type PromptMessage, type RunOptions, type RunResult, type RunVariables, type TokenUsage, type Trace, type TraceListItem, type TraceStatus, Tracia, TraciaError, TraciaErrorCode, type TraciaOptions, type UpdatePromptOptions };
+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 };