teckel-ai 0.3.6 → 0.7.1

package/dist/index.d.mts

@@ -1,214 +1,141 @@
+import { T as TeckelConfig, a as TraceData, F as FeedbackData } from './types-c7iVpo4d.mjs';
+export { B as BatchConfig, D as Document, g as FeedbackResult, e as FeedbackType, S as SpanData, d as SpanStatus, c as SpanType, b as TokenUsage, f as TraceResult } from './types-c7iVpo4d.mjs';
 import { z } from 'zod';
 
 /**
- * Type definitions for teckel-ai SDK v0.3.6
- * Simple, clean types matching existing database schema
- */
-/**
- * SDK Configuration
- */
-interface TeckelConfig {
-    apiKey: string;
-    endpoint?: string;
-    debug?: boolean;
-    timeoutMs?: number;
-}
-/**
- * Conversation options
- * sessionRef IS the conversation identifier
+ * TeckelTracer - Fire-and-forget trace collection for AI applications
  *
- * Naming convention:
- * - *Ref = Client-provided identifier (TEXT)
- * - *Id = Server-generated internal ID (UUID)
- */
-interface ConversationOptions {
-    sessionRef?: string;
-    userRef?: string;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Document structure for RAG systems
- * Matches existing documents + chunk_events schema
- */
-interface Document {
-    documentRef: string;
-    documentName: string;
-    documentText: string;
-    documentLastUpdated?: string;
-    sourceUri?: string;
-    sourceType?: string;
-    similarity?: number;
-    rank?: number;
-    ownerEmail?: string;
-    documentType?: string;
-}
-/**
- * Token usage tracking
- */
-interface TokenUsage {
-    prompt: number;
-    completion: number;
-    total: number;
-}
-/**
- * Trace data for a single query-response interaction
- * Matches existing traces table schema
- */
-interface TraceData {
-    query: string;
-    response: string;
-    model?: string;
-    responseTimeMs?: number;
-    documents?: Document[];
-    tokens?: TokenUsage;
-    metadata?: Record<string, unknown>;
-    traceRef?: string;
-    userRef?: string;
-}
-/**
- * Feedback types
- */
-type FeedbackType = 'thumbs_up' | 'thumbs_down' | 'flag' | 'rating';
-/**
- * User feedback signal
- */
-interface FeedbackData {
-    type: FeedbackType;
-    value?: string;
-    comment?: string;
-    traceRef?: string;
-}
-/**
- * Result returned when a trace is created
- */
-interface TraceResult {
-    traceRef: string;
-    turnNumber: number;
-}
-
-/**
- * Conversation class for teckel-ai SDK v0.3.6
- * Manages a single conversation with fire-and-forget semantics
+ * v0.6.0: Added batch ingestion for high-throughput scenarios (100x improvement)
  */
 
-/** Internal type - sessionRef is guaranteed by TeckelTracer.start() */
-interface ResolvedConversationOptions extends ConversationOptions {
-    sessionRef: string;
-}
-declare class Conversation {
+declare class TeckelTracer {
     private readonly apiKey;
     private readonly endpoint;
-    private readonly sessionRef;
-    private readonly userRef?;
-    private readonly metadata?;
-    private readonly startedAt;
     private readonly debug;
     private readonly timeoutMs;
-    private turnCount;
-    private startPromise;
+    private readonly batchConfig;
     private sendQueue;
-    constructor(apiKey: string, endpoint: string, options: ResolvedConversationOptions, debug?: boolean, extras?: {
-        timeoutMs: number;
-    });
+    private batchBuffer;
+    private batchByteCount;
+    private batchFlushTimer;
+    private isDestroyed;
+    constructor(config: TeckelConfig);
+    /**
+     * Record a trace. Fire-and-forget - call flush() in serverless before termination.
+     *
+     * With batching enabled (default), traces are buffered and sent in batches
+     * for dramatically improved throughput (100x for high-volume scenarios).
+     *
+     * Token auto-aggregation: If you provide `spans` but not `tokens`, the tracer
+     * automatically aggregates token counts from all spans. OTel spans contain
+     * per-span token usage (promptTokens, completionTokens) which are summed to
+     * produce the trace-level totals. You can also provide your own `tokens` object
+     * to override this behavior.
+     *
+     * Cost calculation: If you provide `costUsd`, we use your value directly.
+     * Otherwise, cost is automatically calculated server-side from token counts.
+     * Per-span `costUsd` is also supported for detailed breakdown.
+     */
+    trace(data: TraceData): void;
     /**
-     * Record a trace (single query-response interaction)
-     * Fire-and-forget by default - never blocks
-     * For serverless, call flush() before function termination
+     * Submit feedback for a trace or session.
+     * Feedback is always sent immediately (not batched).
      */
-    trace(data: TraceData): TraceResult | void;
+    feedback(data: FeedbackData): void;
     /**
-     * Add user feedback signal
-     * Never throws - gracefully handles errors
+     * Wait for queued requests to complete. Essential for serverless environments.
+     * This will flush any pending batch and wait for all requests to complete.
      */
-    feedback(data: FeedbackData): Promise<void>;
+    flush(timeoutMs?: number): Promise<void>;
     /**
-     * End the conversation
-     * Flushes all pending traces before sending end signal
-     * Never throws - gracefully handles errors
+     * Cleanup tracer resources. Call when done with the tracer.
+     * This flushes pending traces and stops the auto-flush timer.
      */
-    end(): Promise<void>;
+    destroy(): Promise<void>;
     /**
-     * Read-only properties
+     * Get current batch buffer size (for testing/debugging)
      */
-    get id(): string;
-    get turns(): number;
-    get started(): Date;
+    get pendingTraceCount(): number;
+    /**
+     * Start the auto-flush timer
+     */
+    private startFlushTimer;
+    /**
+     * Stop the auto-flush timer
+     */
+    private stopFlushTimer;
+    /**
+     * Flush the current batch buffer
+     */
+    private flushBatch;
+    /**
+     * Send a batch of traces
+     */
+    private sendBatch;
+    private send;
     private fetchWithRetry;
-    private _startConversation;
-    private _sendTrace;
-    private _sendFeedback;
-    private _endConversation;
-    private enqueueSend;
+    private enqueue;
     /**
-     * Flush queued sends with a bounded timeout.
-     * Returns when the queue is empty or the timeout elapses (whichever comes first).
+     * Log validation errors with actionable hints for common issues.
+     * Optionally reports to platform for internal debugging.
      */
-    flush(timeoutMs?: number): Promise<void>;
-}
-
-/**
- * TeckelTracer - Main SDK class for teckel-ai v0.3.6
- * Simple, lightweight SDK for AI conversation tracking
- */
-
-declare class TeckelTracer {
-    private readonly apiKey;
-    private readonly endpoint;
-    private readonly debug;
-    private readonly timeoutMs;
-    constructor(config: TeckelConfig);
+    private logValidationError;
     /**
-     * Start a new conversation
-     * sessionRef IS the public conversation identifier
-     * If not provided, auto-generates one as 'auto:{8-char-uuid}'
+     * Provide actionable hints for common validation errors.
      */
-    start(options?: ConversationOptions): Conversation;
+    private getValidationHint;
+    /**
+     * Report dropped traces to platform for internal debugging.
+     * Fire-and-forget - never blocks or throws.
+     */
+    private reportDropped;
+    private logHttpError;
 }
 
 /**
- * Zod validation schemas for teckel-ai SDK v0.3.6
+ * Zod validation schemas for teckel-ai SDK
  */
 
-/**
- * Document schema
- */
+/** Payload size limits */
+declare const TRACE_SIZE_LIMITS: {
+    readonly METADATA_MAX_BYTES: 10000;
+    readonly TRACE_MAX_BYTES: 3000000;
+    readonly MAX_DOCUMENTS: 15;
+};
 declare const DocumentSchema: z.ZodObject<{
-    documentRef: z.ZodString;
-    documentName: z.ZodString;
-    documentText: z.ZodString;
-    documentLastUpdated: z.ZodOptional<z.ZodString>;
-    sourceUri: z.ZodOptional<z.ZodString>;
-    sourceType: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    name: z.ZodString;
+    text: z.ZodString;
+    lastUpdated: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    fileFormat: z.ZodOptional<z.ZodString>;
     similarity: z.ZodOptional<z.ZodNumber>;
     rank: z.ZodOptional<z.ZodNumber>;
     ownerEmail: z.ZodOptional<z.ZodString>;
-    documentType: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    documentRef: string;
-    documentName: string;
-    documentText: string;
-    documentLastUpdated?: string | undefined;
-    sourceUri?: string | undefined;
-    sourceType?: string | undefined;
+    id: string;
+    name: string;
+    text: string;
+    lastUpdated?: string | undefined;
+    url?: string | undefined;
+    source?: string | undefined;
+    fileFormat?: string | undefined;
     similarity?: number | undefined;
     rank?: number | undefined;
     ownerEmail?: string | undefined;
-    documentType?: string | undefined;
 }, {
-    documentRef: string;
-    documentName: string;
-    documentText: string;
-    documentLastUpdated?: string | undefined;
-    sourceUri?: string | undefined;
-    sourceType?: string | undefined;
+    id: string;
+    name: string;
+    text: string;
+    lastUpdated?: string | undefined;
+    url?: string | undefined;
+    source?: string | undefined;
+    fileFormat?: string | undefined;
     similarity?: number | undefined;
     rank?: number | undefined;
     ownerEmail?: string | undefined;
-    documentType?: string | undefined;
 }>;
-/**
- * Token usage schema
- */
 declare const TokenUsageSchema: z.ZodObject<{
     prompt: z.ZodNumber;
     completion: z.ZodNumber;
@@ -222,168 +149,561 @@ declare const TokenUsageSchema: z.ZodObject<{
     completion: number;
     total: number;
 }>;
-/**
- * Trace data schema
- */
-declare const TraceDataSchema: z.ZodObject<{
+/** Span size limits */
+declare const SPAN_SIZE_LIMITS: {
+    readonly MAX_SPANS: 100;
+    readonly JSONB_MAX_BYTES: 512000;
+};
+/** Span type enum - 6 meaningful operation types */
+declare const SpanTypeSchema: z.ZodEnum<["llm_call", "tool_call", "retrieval", "agent", "guardrail", "custom"]>;
+/** Span status enum */
+declare const SpanStatusSchema: z.ZodEnum<["running", "completed", "error"]>;
+/** Schema for span data */
+declare const SpanDataSchema: z.ZodEffects<z.ZodObject<{
+    spanId: z.ZodOptional<z.ZodString>;
+    parentSpanId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    name: z.ZodString;
+    type: z.ZodDefault<z.ZodEnum<["llm_call", "tool_call", "retrieval", "agent", "guardrail", "custom"]>>;
+    startedAt: z.ZodString;
+    endedAt: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodDefault<z.ZodEnum<["running", "completed", "error"]>>;
+    statusMessage: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    toolName: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    toolArguments: z.ZodEffects<z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, Record<string, unknown> | null | undefined, Record<string, unknown> | null | undefined>;
+    toolResult: z.ZodEffects<z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, Record<string, unknown> | null | undefined, Record<string, unknown> | null | undefined>;
+    model: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    promptTokens: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    completionTokens: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    costUsd: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    input: z.ZodEffects<z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, Record<string, unknown> | null | undefined, Record<string, unknown> | null | undefined>;
+    output: z.ZodEffects<z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, Record<string, unknown> | null | undefined, Record<string, unknown> | null | undefined>;
+    metadata: z.ZodEffects<z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, Record<string, unknown> | null | undefined, Record<string, unknown> | null | undefined>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "llm_call" | "tool_call" | "retrieval" | "agent" | "guardrail" | "custom";
+    status: "running" | "completed" | "error";
+    startedAt: string;
+    spanId?: string | undefined;
+    parentSpanId?: string | null | undefined;
+    endedAt?: string | null | undefined;
+    durationMs?: number | undefined;
+    statusMessage?: string | null | undefined;
+    toolName?: string | null | undefined;
+    toolArguments?: Record<string, unknown> | null | undefined;
+    toolResult?: Record<string, unknown> | null | undefined;
+    model?: string | null | undefined;
+    promptTokens?: number | null | undefined;
+    completionTokens?: number | null | undefined;
+    costUsd?: number | null | undefined;
+    input?: Record<string, unknown> | null | undefined;
+    output?: Record<string, unknown> | null | undefined;
+    metadata?: Record<string, unknown> | null | undefined;
+}, {
+    name: string;
+    startedAt: string;
+    type?: "llm_call" | "tool_call" | "retrieval" | "agent" | "guardrail" | "custom" | undefined;
+    status?: "running" | "completed" | "error" | undefined;
+    spanId?: string | undefined;
+    parentSpanId?: string | null | undefined;
+    endedAt?: string | null | undefined;
+    durationMs?: number | undefined;
+    statusMessage?: string | null | undefined;
+    toolName?: string | null | undefined;
+    toolArguments?: Record<string, unknown> | null | undefined;
+    toolResult?: Record<string, unknown> | null | undefined;
+    model?: string | null | undefined;
+    promptTokens?: number | null | undefined;
+    completionTokens?: number | null | undefined;
+    costUsd?: number | null | undefined;
+    input?: Record<string, unknown> | null | undefined;
+    output?: Record<string, unknown> | null | undefined;
+    metadata?: Record<string, unknown> | null | undefined;
+}>, {
+    name: string;
+    type: "llm_call" | "tool_call" | "retrieval" | "agent" | "guardrail" | "custom";
+    status: "running" | "completed" | "error";
+    startedAt: string;
+    spanId?: string | undefined;
+    parentSpanId?: string | null | undefined;
+    endedAt?: string | null | undefined;
+    durationMs?: number | undefined;
+    statusMessage?: string | null | undefined;
+    toolName?: string | null | undefined;
+    toolArguments?: Record<string, unknown> | null | undefined;
+    toolResult?: Record<string, unknown> | null | undefined;
+    model?: string | null | undefined;
+    promptTokens?: number | null | undefined;
+    completionTokens?: number | null | undefined;
+    costUsd?: number | null | undefined;
+    input?: Record<string, unknown> | null | undefined;
+    output?: Record<string, unknown> | null | undefined;
+    metadata?: Record<string, unknown> | null | undefined;
+}, {
+    name: string;
+    startedAt: string;
+    type?: "llm_call" | "tool_call" | "retrieval" | "agent" | "guardrail" | "custom" | undefined;
+    status?: "running" | "completed" | "error" | undefined;
+    spanId?: string | undefined;
+    parentSpanId?: string | null | undefined;
+    endedAt?: string | null | undefined;
+    durationMs?: number | undefined;
+    statusMessage?: string | null | undefined;
+    toolName?: string | null | undefined;
+    toolArguments?: Record<string, unknown> | null | undefined;
+    toolResult?: Record<string, unknown> | null | undefined;
+    model?: string | null | undefined;
+    promptTokens?: number | null | undefined;
+    completionTokens?: number | null | undefined;
+    costUsd?: number | null | undefined;
+    input?: Record<string, unknown> | null | undefined;
+    output?: Record<string, unknown> | null | undefined;
+    metadata?: Record<string, unknown> | null | undefined;
+}>;
+declare const TraceDataSchema: z.ZodEffects<z.ZodObject<{
     query: z.ZodString;
     response: z.ZodString;
+    agentName: z.ZodNullable<z.ZodOptional<z.ZodString>>;
     model: z.ZodOptional<z.ZodString>;
-    responseTimeMs: z.ZodOptional<z.ZodNumber>;
+    latencyMs: z.ZodOptional<z.ZodNumber>;
+    tokens: z.ZodOptional<z.ZodObject<{
+        prompt: z.ZodNumber;
+        completion: z.ZodNumber;
+        total: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        prompt: number;
+        completion: number;
+        total: number;
+    }, {
+        prompt: number;
+        completion: number;
+        total: number;
+    }>>;
+    costUsd: z.ZodOptional<z.ZodNumber>;
     documents: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        documentRef: z.ZodString;
-        documentName: z.ZodString;
-        documentText: z.ZodString;
-        documentLastUpdated: z.ZodOptional<z.ZodString>;
-        sourceUri: z.ZodOptional<z.ZodString>;
-        sourceType: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        name: z.ZodString;
+        text: z.ZodString;
+        lastUpdated: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodString>;
+        fileFormat: z.ZodOptional<z.ZodString>;
         similarity: z.ZodOptional<z.ZodNumber>;
         rank: z.ZodOptional<z.ZodNumber>;
         ownerEmail: z.ZodOptional<z.ZodString>;
-        documentType: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        documentRef: string;
-        documentName: string;
-        documentText: string;
-        documentLastUpdated?: string | undefined;
-        sourceUri?: string | undefined;
-        sourceType?: string | undefined;
+        id: string;
+        name: string;
+        text: string;
+        lastUpdated?: string | undefined;
+        url?: string | undefined;
+        source?: string | undefined;
+        fileFormat?: string | undefined;
         similarity?: number | undefined;
         rank?: number | undefined;
         ownerEmail?: string | undefined;
-        documentType?: string | undefined;
     }, {
-        documentRef: string;
-        documentName: string;
-        documentText: string;
-        documentLastUpdated?: string | undefined;
-        sourceUri?: string | undefined;
-        sourceType?: string | undefined;
+        id: string;
+        name: string;
+        text: string;
+        lastUpdated?: string | undefined;
+        url?: string | undefined;
+        source?: string | undefined;
+        fileFormat?: string | undefined;
         similarity?: number | undefined;
         rank?: number | undefined;
         ownerEmail?: string | undefined;
-        documentType?: string | undefined;
     }>, "many">>;
-    tokens: z.ZodOptional<z.ZodObject<{
-        prompt: z.ZodNumber;
-        completion: z.ZodNumber;
-        total: z.ZodNumber;
+    spans: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
+        spanId: z.ZodOptional<z.ZodString>;
+        parentSpanId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        name: z.ZodString;
+        type: z.ZodDefault<z.ZodEnum<["llm_call", "tool_call", "retrieval", "agent", "guardrail", "custom"]>>;
+        startedAt: z.ZodString;
+        endedAt: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        status: z.ZodDefault<z.ZodEnum<["running", "completed", "error"]>>;
+        statusMessage: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        toolName: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        toolArguments: z.ZodEffects<z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, Record<string, unknown> | null | undefined, Record<string, unknown> | null | undefined>;
+        toolResult: z.ZodEffects<z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, Record<string, unknown> | null | undefined, Record<string, unknown> | null | undefined>;
+        model: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        promptTokens: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        completionTokens: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        costUsd: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        input: z.ZodEffects<z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, Record<string, unknown> | null | undefined, Record<string, unknown> | null | undefined>;
+        output: z.ZodEffects<z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, Record<string, unknown> | null | undefined, Record<string, unknown> | null | undefined>;
+        metadata: z.ZodEffects<z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, Record<string, unknown> | null | undefined, Record<string, unknown> | null | undefined>;
     }, "strip", z.ZodTypeAny, {
-        prompt: number;
-        completion: number;
-        total: number;
+        name: string;
+        type: "llm_call" | "tool_call" | "retrieval" | "agent" | "guardrail" | "custom";
+        status: "running" | "completed" | "error";
+        startedAt: string;
+        spanId?: string | undefined;
+        parentSpanId?: string | null | undefined;
+        endedAt?: string | null | undefined;
+        durationMs?: number | undefined;
+        statusMessage?: string | null | undefined;
+        toolName?: string | null | undefined;
+        toolArguments?: Record<string, unknown> | null | undefined;
+        toolResult?: Record<string, unknown> | null | undefined;
+        model?: string | null | undefined;
+        promptTokens?: number | null | undefined;
+        completionTokens?: number | null | undefined;
+        costUsd?: number | null | undefined;
+        input?: Record<string, unknown> | null | undefined;
+        output?: Record<string, unknown> | null | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
     }, {
-        prompt: number;
-        completion: number;
-        total: number;
-    }>>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    traceRef: z.ZodOptional<z.ZodString>;
-    userRef: z.ZodOptional<z.ZodString>;
+        name: string;
+        startedAt: string;
+        type?: "llm_call" | "tool_call" | "retrieval" | "agent" | "guardrail" | "custom" | undefined;
+        status?: "running" | "completed" | "error" | undefined;
+        spanId?: string | undefined;
+        parentSpanId?: string | null | undefined;
+        endedAt?: string | null | undefined;
+        durationMs?: number | undefined;
+        statusMessage?: string | null | undefined;
+        toolName?: string | null | undefined;
+        toolArguments?: Record<string, unknown> | null | undefined;
+        toolResult?: Record<string, unknown> | null | undefined;
+        model?: string | null | undefined;
+        promptTokens?: number | null | undefined;
+        completionTokens?: number | null | undefined;
+        costUsd?: number | null | undefined;
+        input?: Record<string, unknown> | null | undefined;
+        output?: Record<string, unknown> | null | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+    }>, {
+        name: string;
+        type: "llm_call" | "tool_call" | "retrieval" | "agent" | "guardrail" | "custom";
+        status: "running" | "completed" | "error";
+        startedAt: string;
+        spanId?: string | undefined;
+        parentSpanId?: string | null | undefined;
+        endedAt?: string | null | undefined;
+        durationMs?: number | undefined;
+        statusMessage?: string | null | undefined;
+        toolName?: string | null | undefined;
+        toolArguments?: Record<string, unknown> | null | undefined;
+        toolResult?: Record<string, unknown> | null | undefined;
+        model?: string | null | undefined;
+        promptTokens?: number | null | undefined;
+        completionTokens?: number | null | undefined;
+        costUsd?: number | null | undefined;
+        input?: Record<string, unknown> | null | undefined;
+        output?: Record<string, unknown> | null | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+    }, {
+        name: string;
+        startedAt: string;
+        type?: "llm_call" | "tool_call" | "retrieval" | "agent" | "guardrail" | "custom" | undefined;
+        status?: "running" | "completed" | "error" | undefined;
+        spanId?: string | undefined;
+        parentSpanId?: string | null | undefined;
+        endedAt?: string | null | undefined;
+        durationMs?: number | undefined;
+        statusMessage?: string | null | undefined;
+        toolName?: string | null | undefined;
+        toolArguments?: Record<string, unknown> | null | undefined;
+        toolResult?: Record<string, unknown> | null | undefined;
+        model?: string | null | undefined;
+        promptTokens?: number | null | undefined;
+        completionTokens?: number | null | undefined;
+        costUsd?: number | null | undefined;
+        input?: Record<string, unknown> | null | undefined;
+        output?: Record<string, unknown> | null | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+    }>, "many">>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+    traceId: z.ZodOptional<z.ZodString>;
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodEffects<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>, Record<string, unknown> | undefined, Record<string, unknown> | undefined>;
 }, "strip", z.ZodTypeAny, {
     query: string;
     response: string;
     model?: string | undefined;
-    responseTimeMs?: number | undefined;
+    costUsd?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    agentName?: string | null | undefined;
+    latencyMs?: number | undefined;
+    tokens?: {
+        prompt: number;
+        completion: number;
+        total: number;
+    } | undefined;
     documents?: {
-        documentRef: string;
-        documentName: string;
-        documentText: string;
-        documentLastUpdated?: string | undefined;
-        sourceUri?: string | undefined;
-        sourceType?: string | undefined;
+        id: string;
+        name: string;
+        text: string;
+        lastUpdated?: string | undefined;
+        url?: string | undefined;
+        source?: string | undefined;
+        fileFormat?: string | undefined;
         similarity?: number | undefined;
         rank?: number | undefined;
         ownerEmail?: string | undefined;
-        documentType?: string | undefined;
     }[] | undefined;
+    spans?: {
+        name: string;
+        type: "llm_call" | "tool_call" | "retrieval" | "agent" | "guardrail" | "custom";
+        status: "running" | "completed" | "error";
+        startedAt: string;
+        spanId?: string | undefined;
+        parentSpanId?: string | null | undefined;
+        endedAt?: string | null | undefined;
+        durationMs?: number | undefined;
+        statusMessage?: string | null | undefined;
+        toolName?: string | null | undefined;
+        toolArguments?: Record<string, unknown> | null | undefined;
+        toolResult?: Record<string, unknown> | null | undefined;
+        model?: string | null | undefined;
+        promptTokens?: number | null | undefined;
+        completionTokens?: number | null | undefined;
+        costUsd?: number | null | undefined;
+        input?: Record<string, unknown> | null | undefined;
+        output?: Record<string, unknown> | null | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+    }[] | undefined;
+    sessionId?: string | undefined;
+    userId?: string | undefined;
+    traceId?: string | undefined;
+    systemPrompt?: string | undefined;
+}, {
+    query: string;
+    response: string;
+    model?: string | undefined;
+    costUsd?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    agentName?: string | null | undefined;
+    latencyMs?: number | undefined;
     tokens?: {
         prompt: number;
         completion: number;
         total: number;
     } | undefined;
-    metadata?: Record<string, unknown> | undefined;
-    traceRef?: string | undefined;
-    userRef?: string | undefined;
-}, {
+    documents?: {
+        id: string;
+        name: string;
+        text: string;
+        lastUpdated?: string | undefined;
+        url?: string | undefined;
+        source?: string | undefined;
+        fileFormat?: string | undefined;
+        similarity?: number | undefined;
+        rank?: number | undefined;
+        ownerEmail?: string | undefined;
+    }[] | undefined;
+    spans?: {
+        name: string;
+        startedAt: string;
+        type?: "llm_call" | "tool_call" | "retrieval" | "agent" | "guardrail" | "custom" | undefined;
+        status?: "running" | "completed" | "error" | undefined;
+        spanId?: string | undefined;
+        parentSpanId?: string | null | undefined;
+        endedAt?: string | null | undefined;
+        durationMs?: number | undefined;
+        statusMessage?: string | null | undefined;
+        toolName?: string | null | undefined;
+        toolArguments?: Record<string, unknown> | null | undefined;
+        toolResult?: Record<string, unknown> | null | undefined;
+        model?: string | null | undefined;
+        promptTokens?: number | null | undefined;
+        completionTokens?: number | null | undefined;
+        costUsd?: number | null | undefined;
+        input?: Record<string, unknown> | null | undefined;
+        output?: Record<string, unknown> | null | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+    }[] | undefined;
+    sessionId?: string | undefined;
+    userId?: string | undefined;
+    traceId?: string | undefined;
+    systemPrompt?: string | undefined;
+}>, {
     query: string;
     response: string;
     model?: string | undefined;
-    responseTimeMs?: number | undefined;
+    costUsd?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    agentName?: string | null | undefined;
+    latencyMs?: number | undefined;
+    tokens?: {
+        prompt: number;
+        completion: number;
+        total: number;
+    } | undefined;
     documents?: {
-        documentRef: string;
-        documentName: string;
-        documentText: string;
-        documentLastUpdated?: string | undefined;
-        sourceUri?: string | undefined;
-        sourceType?: string | undefined;
+        id: string;
+        name: string;
+        text: string;
+        lastUpdated?: string | undefined;
+        url?: string | undefined;
+        source?: string | undefined;
+        fileFormat?: string | undefined;
         similarity?: number | undefined;
         rank?: number | undefined;
         ownerEmail?: string | undefined;
-        documentType?: string | undefined;
     }[] | undefined;
+    spans?: {
+        name: string;
+        type: "llm_call" | "tool_call" | "retrieval" | "agent" | "guardrail" | "custom";
+        status: "running" | "completed" | "error";
+        startedAt: string;
+        spanId?: string | undefined;
+        parentSpanId?: string | null | undefined;
+        endedAt?: string | null | undefined;
+        durationMs?: number | undefined;
+        statusMessage?: string | null | undefined;
+        toolName?: string | null | undefined;
+        toolArguments?: Record<string, unknown> | null | undefined;
+        toolResult?: Record<string, unknown> | null | undefined;
+        model?: string | null | undefined;
+        promptTokens?: number | null | undefined;
+        completionTokens?: number | null | undefined;
+        costUsd?: number | null | undefined;
+        input?: Record<string, unknown> | null | undefined;
+        output?: Record<string, unknown> | null | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+    }[] | undefined;
+    sessionId?: string | undefined;
+    userId?: string | undefined;
+    traceId?: string | undefined;
+    systemPrompt?: string | undefined;
+}, {
+    query: string;
+    response: string;
+    model?: string | undefined;
+    costUsd?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    agentName?: string | null | undefined;
+    latencyMs?: number | undefined;
     tokens?: {
         prompt: number;
         completion: number;
         total: number;
     } | undefined;
-    metadata?: Record<string, unknown> | undefined;
-    traceRef?: string | undefined;
-    userRef?: string | undefined;
-}>;
-/**
- * Conversation options schema
- */
-declare const ConversationOptionsSchema: z.ZodObject<{
-    sessionRef: z.ZodOptional<z.ZodString>;
-    userRef: z.ZodOptional<z.ZodString>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, "strip", z.ZodTypeAny, {
-    metadata?: Record<string, unknown> | undefined;
-    userRef?: string | undefined;
-    sessionRef?: string | undefined;
-}, {
-    metadata?: Record<string, unknown> | undefined;
-    userRef?: string | undefined;
-    sessionRef?: string | undefined;
+    documents?: {
+        id: string;
+        name: string;
+        text: string;
+        lastUpdated?: string | undefined;
+        url?: string | undefined;
+        source?: string | undefined;
+        fileFormat?: string | undefined;
+        similarity?: number | undefined;
+        rank?: number | undefined;
+        ownerEmail?: string | undefined;
+    }[] | undefined;
+    spans?: {
+        name: string;
+        startedAt: string;
+        type?: "llm_call" | "tool_call" | "retrieval" | "agent" | "guardrail" | "custom" | undefined;
+        status?: "running" | "completed" | "error" | undefined;
+        spanId?: string | undefined;
+        parentSpanId?: string | null | undefined;
+        endedAt?: string | null | undefined;
+        durationMs?: number | undefined;
+        statusMessage?: string | null | undefined;
+        toolName?: string | null | undefined;
+        toolArguments?: Record<string, unknown> | null | undefined;
+        toolResult?: Record<string, unknown> | null | undefined;
+        model?: string | null | undefined;
+        promptTokens?: number | null | undefined;
+        completionTokens?: number | null | undefined;
+        costUsd?: number | null | undefined;
+        input?: Record<string, unknown> | null | undefined;
+        output?: Record<string, unknown> | null | undefined;
+        metadata?: Record<string, unknown> | null | undefined;
+    }[] | undefined;
+    sessionId?: string | undefined;
+    userId?: string | undefined;
+    traceId?: string | undefined;
+    systemPrompt?: string | undefined;
 }>;
-/**
- * Feedback data schema
- */
-declare const FeedbackDataSchema: z.ZodObject<{
+declare const FeedbackDataSchema: z.ZodEffects<z.ZodObject<{
+    traceId: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
     type: z.ZodEnum<["thumbs_up", "thumbs_down", "flag", "rating"]>;
     value: z.ZodOptional<z.ZodString>;
     comment: z.ZodOptional<z.ZodString>;
-    traceRef: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "thumbs_up" | "thumbs_down" | "flag" | "rating";
     value?: string | undefined;
-    traceRef?: string | undefined;
+    sessionId?: string | undefined;
+    traceId?: string | undefined;
+    comment?: string | undefined;
+}, {
+    type: "thumbs_up" | "thumbs_down" | "flag" | "rating";
+    value?: string | undefined;
+    sessionId?: string | undefined;
+    traceId?: string | undefined;
+    comment?: string | undefined;
+}>, {
+    type: "thumbs_up" | "thumbs_down" | "flag" | "rating";
+    value?: string | undefined;
+    sessionId?: string | undefined;
+    traceId?: string | undefined;
     comment?: string | undefined;
 }, {
     type: "thumbs_up" | "thumbs_down" | "flag" | "rating";
     value?: string | undefined;
-    traceRef?: string | undefined;
+    sessionId?: string | undefined;
+    traceId?: string | undefined;
     comment?: string | undefined;
 }>;
-/**
- * Config schema
- */
+/** Batch configuration schema for high-throughput ingestion */
+declare const BatchConfigSchema: z.ZodObject<{
+    maxSize: z.ZodOptional<z.ZodNumber>;
+    maxBytes: z.ZodOptional<z.ZodNumber>;
+    flushIntervalMs: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    maxSize?: number | undefined;
+    maxBytes?: number | undefined;
+    flushIntervalMs?: number | undefined;
+}, {
+    maxSize?: number | undefined;
+    maxBytes?: number | undefined;
+    flushIntervalMs?: number | undefined;
+}>;
 declare const TeckelConfigSchema: z.ZodObject<{
     apiKey: z.ZodString;
     endpoint: z.ZodOptional<z.ZodString>;
     debug: z.ZodOptional<z.ZodBoolean>;
     timeoutMs: z.ZodOptional<z.ZodNumber>;
+    batch: z.ZodOptional<z.ZodObject<{
+        maxSize: z.ZodOptional<z.ZodNumber>;
+        maxBytes: z.ZodOptional<z.ZodNumber>;
+        flushIntervalMs: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        maxSize?: number | undefined;
+        maxBytes?: number | undefined;
+        flushIntervalMs?: number | undefined;
+    }, {
+        maxSize?: number | undefined;
+        maxBytes?: number | undefined;
+        flushIntervalMs?: number | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     apiKey: string;
     endpoint?: string | undefined;
     debug?: boolean | undefined;
     timeoutMs?: number | undefined;
+    batch?: {
+        maxSize?: number | undefined;
+        maxBytes?: number | undefined;
+        flushIntervalMs?: number | undefined;
+    } | undefined;
 }, {
     apiKey: string;
     endpoint?: string | undefined;
     debug?: boolean | undefined;
     timeoutMs?: number | undefined;
+    batch?: {
+        maxSize?: number | undefined;
+        maxBytes?: number | undefined;
+        flushIntervalMs?: number | undefined;
+    } | undefined;
 }>;
 
-export { Conversation, type ConversationOptions, ConversationOptionsSchema, type Document, DocumentSchema, type FeedbackData, FeedbackDataSchema, type FeedbackType, type TeckelConfig, TeckelConfigSchema, TeckelTracer, type TokenUsage, TokenUsageSchema, type TraceData, TraceDataSchema, type TraceResult };
+export { BatchConfigSchema, DocumentSchema, FeedbackData, FeedbackDataSchema, SPAN_SIZE_LIMITS, SpanDataSchema, SpanStatusSchema, SpanTypeSchema, TRACE_SIZE_LIMITS, TeckelConfig, TeckelConfigSchema, TeckelTracer, TokenUsageSchema, TraceData, TraceDataSchema };