aigie-sdk 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,2268 @@
+import { ZodType, ZodRawShape, ZodObject, z } from 'zod';
+
+/**
+ * Agent framework type definitions for the Aigie SDK.
+ *
+ * These types define the core abstractions for the agent system including
+ * messages, tools, guardrails, signals, evaluation, drift detection,
+ * loop detection, remediation, and streaming.
+ *
+ * @packageDocumentation
+ */
+
+interface Message {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCallId?: string;
+    toolCalls?: ToolCall[];
+    timestamp?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+interface ToolCallResult {
+    toolCallId: string;
+    name: string;
+    result: unknown;
+    error?: string;
+    durationMs?: number;
+}
+interface ModelSettings {
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    stopSequences?: string[];
+    seed?: number;
+    responseFormat?: 'text' | 'json';
+}
+interface RunContext<T = unknown> {
+    deps: T;
+    model: string;
+    messages: Message[];
+    traceId: string;
+    spanId: string;
+    retryCount: number;
+    maxRetries: number;
+    isLastAttempt: boolean;
+    addMessage(msg: Message): void;
+    addUserMessage(content: string): void;
+    addAssistantMessage(content: string): void;
+    getMessagesForApi(): ApiMessage[];
+    withRetry(): RunContext<T>;
+}
+interface ApiMessage {
+    role: string;
+    content: string;
+    tool_call_id?: string;
+    tool_calls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+}
+interface ToolDefinition<TParams = any, TContext = any> {
+    name: string;
+    description: string;
+    parameters: ZodType<TParams>;
+    execute: (params: TParams, ctx: RunContext<TContext>) => unknown | Promise<unknown>;
+    requiresContext: boolean;
+    isAsync: boolean;
+    schema: Record<string, unknown>;
+    toOpenAITool(): OpenAIToolSchema;
+    toAnthropicTool(): AnthropicToolSchema;
+}
+interface ToolConfig<TParams extends ZodRawShape, TContext = unknown> {
+    name: string;
+    description: string;
+    parameters: ZodObject<TParams>;
+    execute: (params: z.infer<ZodObject<TParams>>, ctx: RunContext<TContext>) => unknown | Promise<unknown>;
+}
+interface OpenAIToolSchema {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+interface AnthropicToolSchema {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+interface AgentConfig<TContext = unknown, TOutput = string> {
+    name: string;
+    model: string;
+    systemPrompt?: string | ((ctx: RunContext<TContext>) => string | Promise<string>);
+    tools?: ToolDefinition[];
+    outputType?: ZodType<TOutput>;
+    modelSettings?: ModelSettings;
+    handoffs?: Array<{
+        name: string;
+        agent: any;
+    }>;
+    inputGuardrails?: InputGuardrail[];
+    outputGuardrails?: OutputGuardrail[];
+    maxRetries?: number;
+    maxTurns?: number;
+}
+interface RunOptions<TContext = unknown> {
+    deps?: TContext;
+    messageHistory?: Message[];
+    sessionId?: string;
+    userId?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface AgentResult<T = string> {
+    data: T;
+    usage: UsageInfo;
+    messages: Message[];
+    traceId: string;
+    durationMs: number;
+    toolCalls: number;
+    retries: number;
+    allMessages(): Message[];
+    withToolReturnContent(): Message[];
+}
+interface UsageInfo {
+    requestTokens: number;
+    responseTokens: number;
+    totalTokens: number;
+    costUsd: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    model: string;
+}
+declare enum GuardrailAction {
+    PASS = "pass",
+    WARN = "warn",
+    RETRY = "retry",
+    REDIRECT = "redirect",
+    ADJUST = "adjust",
+    ESCALATE = "escalate"
+}
+interface GuardrailResult {
+    action: GuardrailAction;
+    message?: string;
+    metadata?: Record<string, unknown>;
+}
+interface GuardrailContext {
+    traceId: string;
+    spanId: string;
+    durationMs: number;
+    model: string;
+    metadata: Record<string, unknown>;
+}
+interface InputGuardrail {
+    name: string;
+    execute: (input: string, context: GuardrailContext) => Promise<GuardrailResult>;
+}
+interface OutputGuardrail {
+    name: string;
+    execute: (output: unknown, context: GuardrailContext) => Promise<GuardrailResult>;
+}
+declare enum SignalType {
+    ERROR_CLUSTER = "error_cluster",
+    CONTEXT_DRIFT = "context_drift",
+    TOOL_LOOP = "tool_loop",
+    GOAL_DEVIATION = "goal_deviation",
+    HALLUCINATION = "hallucination",
+    QUALITY_DROP = "quality_drop",
+    LATENCY_SPIKE = "latency_spike",
+    TOKEN_OVERFLOW = "token_overflow",
+    SAFETY_VIOLATION = "safety_violation"
+}
+declare enum SignalSeverity {
+    LOW = "low",
+    MEDIUM = "medium",
+    HIGH = "high",
+    CRITICAL = "critical"
+}
+interface Signal {
+    id: string;
+    type: SignalType;
+    severity: SignalSeverity;
+    message: string;
+    traceId?: string;
+    spanId?: string;
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+}
+interface EmitSignalRequest {
+    type: SignalType;
+    severity: SignalSeverity;
+    message: string;
+    traceId?: string;
+    spanId?: string;
+    metadata?: Record<string, unknown>;
+}
+type ScoreType = 'accuracy' | 'relevance' | 'coherence' | 'fluency' | 'groundedness' | 'hallucination' | 'toxicity' | 'helpfulness' | 'custom';
+interface EvaluationScore {
+    traceId: string;
+    spanId?: string;
+    name: ScoreType | string;
+    value: number;
+    dataType?: 'NUMERIC' | 'CATEGORICAL' | 'BOOLEAN';
+    comment?: string;
+    metadata?: Record<string, unknown>;
+}
+interface JudgeConfig {
+    model: string;
+    criteria: ScoreType[];
+    systemPrompt?: string;
+}
+interface JudgeResult {
+    scores: Record<string, number>;
+    reasoning: string;
+    overallScore: number;
+}
+type DriftType = 'topic' | 'behavior' | 'quality' | 'coherence';
+interface DriftDetectorConfig {
+    detectors: DriftType[];
+    thresholds?: Partial<Record<DriftType, number>>;
+}
+interface DriftResult {
+    hasDrift: boolean;
+    type?: DriftType;
+    score: number;
+    details: string;
+}
+interface PhaseContext {
+    name: string;
+    startTime: number;
+    setOutput(output: unknown): void;
+    setMetadata(metadata: Record<string, unknown>): void;
+}
+interface CycleMetrics {
+    thinkDurationMs: number;
+    actDurationMs: number;
+    observeDurationMs: number;
+    totalDurationMs: number;
+    cycleCount: number;
+}
+interface PlanMetrics {
+    completionRate: number;
+    deviations: Deviation[];
+    unexpectedSteps: number;
+    wrongOrderSteps: number;
+    totalDurationMs: number;
+}
+interface Deviation {
+    type: 'unexpected_step' | 'wrong_order' | 'missing_step' | 'repeated_step';
+    stepName: string;
+    message: string;
+    timestamp: string;
+}
+interface LoopDetectorConfig {
+    similarityThreshold?: number;
+    maxConsecutiveRepeats?: number;
+    action?: 'warn' | 'break' | 'auto_fix';
+}
+interface LoopDetectionResult {
+    isLoop: boolean;
+    similarity: number;
+    repeatCount: number;
+    action?: 'warn' | 'break' | 'auto_fix';
+}
+interface RemediationAction {
+    action: 'retry' | 'fallback' | 'reset' | 'redirect' | 'escalate';
+    newSystemPrompt?: string;
+    newModel?: string;
+    metadata?: Record<string, unknown>;
+}
+type RemediationHandler = (signal: Signal) => Promise<RemediationAction>;
+interface UsageDetails {
+    input: number;
+    output: number;
+    cacheReadInputTokens?: number;
+    total?: number;
+    [key: string]: number | undefined;
+}
+interface CostDetails {
+    input: number;
+    output: number;
+    cacheReadInputTokens?: number;
+    total?: number;
+    [key: string]: number | undefined;
+}
+interface IntegrationInfo {
+    name: string;
+    displayName: string;
+    packageName: string;
+    patchFunction: string;
+    handlerClass?: string;
+    isPatched?: boolean;
+}
+interface StreamChunk {
+    type: 'text' | 'tool_call' | 'tool_result' | 'error' | 'done';
+    content?: string;
+    toolCall?: ToolCall;
+    toolResult?: ToolCallResult;
+    error?: string;
+}
+
+/**
+ * Kyte SDK Type Definitions
+ */
+interface AigieConfig {
+    /** Kyte API endpoint URL */
+    apiUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Project name for grouping traces */
+    projectName?: string;
+    /** Default tags to add to all traces */
+    defaultTags?: string[];
+    /** Default metadata to add to all traces */
+    defaultMetadata?: Record<string, any>;
+    /** Enable/disable tracing */
+    enabled?: boolean;
+    /** Batch traces before sending */
+    batchEnabled?: boolean;
+    /** Batch size (number of traces to batch) */
+    batchSize?: number;
+    /** Batch timeout in milliseconds */
+    batchTimeout?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Default user ID */
+    defaultUserId?: string;
+    /** Default session ID */
+    defaultSessionId?: string;
+    /** Environment (e.g., 'production', 'staging') */
+    environment?: string;
+    /** Release version */
+    release?: string;
+    /** Sampling rate (0-1) */
+    samplingRate?: number;
+    /** Enable compression */
+    compressionEnabled?: boolean;
+    /** Max retries for API calls */
+    maxRetries?: number;
+    /** Retry delay in milliseconds */
+    retryDelay?: number;
+    /** Callback for ingestion errors */
+    onError?: (error: Error) => void;
+    /** Maximum event queue size (default 1000) */
+    maxQueueSize?: number;
+}
+interface TraceOptions {
+    /** Trace name */
+    name?: string;
+    /** Trace type (chain, llm, tool, etc.) */
+    type?: SpanType;
+    /** Input data */
+    input?: Record<string, any>;
+    /** Tags for this trace */
+    tags?: string[];
+    /** Metadata for this trace */
+    metadata?: Record<string, any>;
+    /** User ID for this trace */
+    userId?: string;
+    /** Session ID for grouping multi-turn conversations */
+    sessionId?: string;
+}
+interface SpanOptions extends TraceOptions {
+    /** Parent span ID */
+    parentSpanId?: string;
+    /** Model name (for LLM spans) */
+    modelName?: string;
+}
+interface Trace {
+    /** Unique trace ID */
+    id: string;
+    /** Trace name */
+    name: string;
+    /** Trace type */
+    type: string;
+    /** Input data */
+    input: Record<string, any>;
+    /** Output data */
+    output?: Record<string, any>;
+    /** Status (success, failed, pending) */
+    status: TraceStatus;
+    /** Error message if failed */
+    errorMessage?: string;
+    /** Tags */
+    tags: string[];
+    /** Metadata */
+    metadata: Record<string, any>;
+    /** Project name */
+    projectName?: string;
+    /** User ID */
+    userId?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Start timestamp */
+    startTime: string;
+    /** End timestamp */
+    endTime?: string;
+    /** Duration in nanoseconds */
+    durationNs?: number;
+    /** Created timestamp */
+    createdAt: string;
+}
+interface Span {
+    /** Unique span ID */
+    id: string;
+    /** Parent trace ID */
+    traceId: string;
+    /** Parent span ID */
+    parentSpanId?: string;
+    /** Span name */
+    name: string;
+    /** Span type */
+    type: string;
+    /** Input data */
+    input: Record<string, any>;
+    /** Output data */
+    output?: Record<string, any>;
+    /** Status */
+    status: TraceStatus;
+    /** Error message if failed */
+    errorMessage?: string;
+    /** Tags */
+    tags: string[];
+    /** Metadata */
+    metadata: Record<string, any>;
+    /** Model name (for LLM spans) */
+    modelName?: string;
+    /** Token counts */
+    tokens?: TokenUsage;
+    /** Cost in USD */
+    cost?: number;
+    /** Start timestamp */
+    startTime: string;
+    /** End timestamp */
+    endTime?: string;
+    /** Duration in nanoseconds */
+    durationNs?: number;
+    /** Created timestamp */
+    createdAt: string;
+}
+interface TokenUsage {
+    prompt?: number;
+    completion?: number;
+    total?: number;
+    cached?: number;
+}
+interface Score {
+    /** Score name */
+    name: string;
+    /** Numeric value (0-1 or custom range) */
+    value?: number;
+    /** String value for categorical scores */
+    stringValue?: string;
+    /** Comment/explanation */
+    comment?: string;
+    /** Data type */
+    dataType?: 'numeric' | 'boolean' | 'categorical';
+}
+type SpanType = 'llm' | 'chain' | 'tool' | 'retriever' | 'embedding' | 'prompt' | 'agent' | 'guardrail' | 'evaluation' | 'remediation' | 'custom';
+type TraceStatus = 'success' | 'failed' | 'pending';
+interface TraceContext {
+    /** Current trace ID */
+    traceId: string;
+    /** Current span ID */
+    spanId?: string;
+    /** Add a child span */
+    addSpan: (name: string, options?: SpanOptions) => Promise<SpanContext>;
+    /** End the current trace */
+    end: (output?: Record<string, any>, error?: Error) => Promise<void>;
+    /** Add a score to the trace */
+    addScore: (score: Score) => Promise<void>;
+}
+interface SpanContext {
+    /** Current span ID */
+    spanId: string;
+    /** Parent trace ID */
+    traceId: string;
+    /** End the span */
+    end: (output?: Record<string, any>, error?: Error) => Promise<void>;
+    /** Add a score to the span */
+    addScore: (score: Score) => Promise<void>;
+}
+interface TraceableConfig {
+    /** Name override for the trace/span */
+    name?: string;
+    /** Type override */
+    type?: SpanType;
+    /** Tags to add */
+    tags?: string[];
+    /** Metadata to add */
+    metadata?: Record<string, any>;
+    /** Capture function arguments as input */
+    captureInput?: boolean;
+    /** Capture function output */
+    captureOutput?: boolean;
+    /** Capture errors */
+    captureErrors?: boolean;
+}
+interface AutoInstrumentConfig {
+    /** Auto-instrument OpenAI SDK */
+    openai?: boolean;
+    /** Auto-instrument Anthropic SDK */
+    anthropic?: boolean;
+    /** Auto-instrument LangChain */
+    langchain?: boolean;
+    /** Auto-instrument Vercel AI SDK */
+    vercelAI?: boolean;
+    /** Auto-instrument HTTP/fetch */
+    http?: boolean;
+    /** Auto-instrument LangGraph */
+    langgraph?: boolean;
+    /** Auto-instrument CrewAI */
+    crewai?: boolean;
+    /** Auto-instrument AutoGen */
+    autogen?: boolean;
+    /** Auto-instrument OpenAI Agents SDK */
+    openaiAgents?: boolean;
+    /** Auto-instrument Claude Agent SDK */
+    claudeAgentSdk?: boolean;
+    /** Auto-instrument Browser-Use */
+    browserUse?: boolean;
+    /** Auto-instrument LlamaIndex */
+    llamaindex?: boolean;
+    /** Auto-instrument DSPy */
+    dspy?: boolean;
+    /** Auto-instrument Pipecat */
+    pipecat?: boolean;
+    /** Auto-instrument Instructor */
+    instructor?: boolean;
+    /** Auto-instrument Semantic Kernel */
+    semanticKernel?: boolean;
+    /** Auto-instrument Strands Agents */
+    strands?: boolean;
+    /** Auto-instrument Google ADK */
+    googleAdk?: boolean;
+    /** Patch all registered integrations via IntegrationRegistry */
+    patchAll?: boolean;
+    /** Custom instrumentations */
+    custom?: CustomInstrumentation[];
+}
+interface CustomInstrumentation {
+    /** Name of the instrumentation */
+    name: string;
+    /** Module to instrument */
+    module: string;
+    /** Methods to wrap */
+    methods: string[];
+    /** Wrapper function */
+    wrapper: (original: Function, methodName: string) => Function;
+}
+interface SpanBuilder {
+    /** Set span name */
+    setName(name: string): SpanBuilder;
+    /** Set span type */
+    setType(type: SpanType): SpanBuilder;
+    /** Set input data */
+    setInput(input: Record<string, any>): SpanBuilder;
+    /** Set metadata */
+    setMetadata(metadata: Record<string, any>): SpanBuilder;
+    /** Add metadata (merge) */
+    addMetadata(key: string, value: any): SpanBuilder;
+    /** Set tags */
+    setTags(tags: string[]): SpanBuilder;
+    /** Add tag */
+    addTag(tag: string): SpanBuilder;
+    /** Set user ID */
+    setUserId(userId: string): SpanBuilder;
+    /** Set session ID */
+    setSessionId(sessionId: string): SpanBuilder;
+    /** Set model name */
+    setModelName(modelName: string): SpanBuilder;
+    /** Start the span */
+    start(): ActiveSpan;
+}
+interface ActiveSpan {
+    /** Span ID */
+    readonly id: string;
+    /** Trace ID */
+    readonly traceId: string;
+    /** Update span data */
+    update(data: Partial<SpanUpdateData>): ActiveSpan;
+    /** Set output */
+    setOutput(output: Record<string, any>): ActiveSpan;
+    /** Set tokens */
+    setTokens(tokens: TokenUsage): ActiveSpan;
+    /** Set cost */
+    setCost(cost: number): ActiveSpan;
+    /** Add score */
+    addScore(score: Score): ActiveSpan;
+    /** Set error */
+    setError(error: Error | string): ActiveSpan;
+    /** End the span */
+    end(): Promise<void>;
+}
+interface SpanUpdateData {
+    output?: Record<string, any>;
+    tokens?: TokenUsage;
+    cost?: number;
+    metadata?: Record<string, any>;
+    tags?: string[];
+    modelName?: string;
+}
+interface SmartCacheConfig<T> {
+    /** Time-to-live in milliseconds */
+    ttl: number;
+    /** Serve stale data while refreshing */
+    staleWhileRevalidate?: boolean;
+    /** Refresh in background when expired */
+    backgroundRefresh?: boolean;
+    /** Maximum cache size */
+    maxSize?: number;
+    /** Function to fetch fresh data */
+    onRefresh?: (key: string) => Promise<T>;
+    /** Called when cache entry expires */
+    onExpire?: (key: string, value: T) => void;
+}
+interface CacheEntry<T> {
+    value: T;
+    expiresAt: number;
+    createdAt: number;
+    lastAccessed: number;
+}
+type AnnotationType = 'correction' | 'approval' | 'rejection' | 'comment' | 'label' | 'score' | 'thumbs';
+interface Annotation {
+    /** Unique annotation ID */
+    id: string;
+    /** Trace ID */
+    traceId: string;
+    /** Span ID (optional) */
+    spanId?: string;
+    /** Annotation type */
+    type: AnnotationType;
+    /** Annotation value */
+    value: string | number | boolean;
+    /** Comment/explanation */
+    comment?: string;
+    /** Annotator user ID */
+    annotatorId?: string;
+    /** Metadata */
+    metadata?: Record<string, any>;
+    /** Created timestamp */
+    createdAt: string;
+    /** Updated timestamp */
+    updatedAt?: string;
+}
+interface CreateAnnotationRequest {
+    traceId: string;
+    spanId?: string;
+    type: AnnotationType;
+    value: string | number | boolean;
+    comment?: string;
+    annotatorId?: string;
+    metadata?: Record<string, any>;
+}
+type FeedbackType = 'thumbs' | 'rating' | 'categorical' | 'text';
+interface Feedback {
+    /** Unique feedback ID */
+    id: string;
+    /** Trace ID */
+    traceId: string;
+    /** Span ID (optional) */
+    spanId?: string;
+    /** Feedback type */
+    type: FeedbackType;
+    /** Feedback value */
+    value: 'up' | 'down' | number | string;
+    /** Rating scale (for rating type) */
+    scale?: [number, number];
+    /** Categories (for categorical type) */
+    categories?: string[];
+    /** Comment */
+    comment?: string;
+    /** User ID who provided feedback */
+    userId?: string;
+    /** Metadata */
+    metadata?: Record<string, any>;
+    /** Created timestamp */
+    createdAt: string;
+}
+interface CreateFeedbackRequest {
+    traceId: string;
+    spanId?: string;
+    type: FeedbackType;
+    value: 'up' | 'down' | number | string;
+    scale?: [number, number];
+    categories?: string[];
+    comment?: string;
+    userId?: string;
+    metadata?: Record<string, any>;
+}
+interface FeedbackStats {
+    totalCount: number;
+    thumbsUp: number;
+    thumbsDown: number;
+    averageRating?: number;
+    categoryBreakdown?: Record<string, number>;
+}
+interface MediaReference {
+    /** Unique media ID */
+    id: string;
+    /** SHA256 hash for deduplication */
+    hash: string;
+    /** MIME type */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+    /** URL to access media */
+    url?: string;
+    /** Created timestamp */
+    createdAt: string;
+}
+interface ProcessedMedia {
+    /** Sanitized messages (media replaced with references) */
+    messages: any[];
+    /** Extracted media references */
+    mediaRefs: MediaReference[];
+}
+interface WrapperOptions {
+    /** Custom trace name */
+    traceName?: string;
+    /** User ID */
+    userId?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Tags */
+    tags?: string[];
+    /** Metadata */
+    metadata?: Record<string, any>;
+}
+interface ModelPricing {
+    /** Model name */
+    model: string;
+    /** Provider */
+    provider: 'openai' | 'anthropic' | 'google' | 'cohere' | 'bedrock' | 'other';
+    /** Input price per 1M tokens */
+    inputPricePerMillion: number;
+    /** Output price per 1M tokens */
+    outputPricePerMillion: number;
+    /** Cached input price per 1M tokens (optional) */
+    cachedInputPricePerMillion?: number;
+}
+
+/**
+ * Kyte Client - Core SDK class for tracing and monitoring
+ */
+
+interface TracingContext {
+    traceId: string;
+    spanId?: string;
+    parentSpanId?: string;
+}
+/**
+ * Initialize the Kyte SDK
+ */
+declare function initKyte(config: AigieConfig): AigieClient;
+/**
+ * Alias for initKyte
+ */
+declare const initAigie: typeof initKyte;
+/**
+ * Get the global Kyte client
+ */
+declare function getKyte(): AigieClient;
+/**
+ * Alias for getKyte
+ */
+declare const getAigie: typeof getKyte;
+declare class AigieClient {
+    private config;
+    private eventQueue;
+    private batchTimer;
+    private enabled;
+    constructor(config: AigieConfig);
+    isEnabled(): boolean;
+    disable(): void;
+    enable(): void;
+    getCurrentContext(): TracingContext | undefined;
+    spanBuilder(name: string): SpanBuilder;
+    startSpan(options: SpanOptions): ActiveSpan;
+    trace<T>(name: string, fn: () => T | Promise<T>, options?: TraceOptions): Promise<T>;
+    span<T>(name: string, fn: () => T | Promise<T>, options?: SpanOptions): Promise<T>;
+    addScore(traceId: string, score: Score, spanId?: string): Promise<void>;
+    sendTraceUpdate(trace: Trace): Promise<void>;
+    sendSpanUpdate(span: Span): Promise<void>;
+    private queueEvent;
+    private mapSpanType;
+    private traceToEvent;
+    private buildTokenUsage;
+    private spanToEvent;
+    private traceUpdateEvent;
+    private spanUpdateEvent;
+    private flushBatch;
+    private sendToApi;
+    /**
+     * Force flush all pending spans and signals immediately.
+     * Unlike shutdown(), this does not disable the client afterwards.
+     */
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Decorators
+ *
+ * @traceable decorator and trace wrapper function for automatic tracing.
+ */
+
+/**
+ * @traceable decorator - Auto-trace class methods
+ *
+ * @example
+ * ```typescript
+ * class MyService {
+ *   @traceable({ name: 'processData', type: 'chain' })
+ *   async processData(input: string) {
+ *     return await this.doWork(input);
+ *   }
+ *
+ *   @traceable({ captureInput: true, captureOutput: true })
+ *   async doWork(input: string) {
+ *     return `processed: ${input}`;
+ *   }
+ * }
+ * ```
+ */
+declare function traceable(config?: TraceableConfig): (_target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * trace wrapper function - Wrap any function with tracing
+ *
+ * @example
+ * ```typescript
+ * const tracedFetch = trace(
+ *   async (url: string) => fetch(url),
+ *   { name: 'fetchData', type: 'tool' }
+ * );
+ *
+ * const response = await tracedFetch('https://api.example.com');
+ * ```
+ */
+declare function trace<T extends (...args: any[]) => any>(fn: T, config?: TraceableConfig): T;
+/**
+ * observe decorator - Simpler alternative to @traceable (Laminar-style API)
+ *
+ * @example
+ * ```typescript
+ * class MyAgent {
+ *   @observe()
+ *   async think(input: string) {
+ *     return await this.llm.generate(input);
+ *   }
+ * }
+ * ```
+ */
+declare function observe(config?: {
+    name?: string;
+    type?: SpanType;
+}): (_target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * withTracing - Higher-order function for wrapping functions with tracing
+ *
+ * @example
+ * ```typescript
+ * const myFunction = withTracing(
+ *   async (x: number) => x * 2,
+ *   'doubleValue'
+ * );
+ * ```
+ */
+declare function withTracing<T extends (...args: any[]) => any>(fn: T, name?: string, options?: Omit<TraceableConfig, 'name'>): T;
+
+/**
+ * Error hierarchy for the Aigie SDK agent framework.
+ *
+ * All errors extend AigieError, which ensures correct prototype chains
+ * and sets this.name to the constructor name for proper instanceof checks.
+ */
+declare class AigieError extends Error {
+    constructor(message: string);
+}
+declare class DriftError extends AigieError {
+}
+declare class ContextDriftDetected extends DriftError {
+}
+declare class TopicDriftDetected extends DriftError {
+}
+declare class BehaviorDriftDetected extends DriftError {
+}
+declare class LoopDetectedError extends DriftError {
+}
+declare class RemediationError extends AigieError {
+}
+declare class RemediationFailed extends RemediationError {
+}
+declare class RemediationRejected extends RemediationError {
+}
+declare class RetryExhausted extends RemediationError {
+}
+declare class ModelRetry extends AigieError {
+}
+declare class TracingError extends AigieError {
+}
+declare class InterceptionError extends AigieError {
+}
+declare class GuardrailError extends AigieError {
+}
+declare class AgentExecutionError extends AigieError {
+}
+declare class ConfigurationError extends AigieError {
+}
+declare class TimeoutError extends AigieError {
+}
+declare class ValidationError extends AigieError {
+}
+declare class ToolExecutionError extends AigieError {
+    readonly toolName: string;
+    constructor(message: string, toolName: string);
+}
+declare class ProviderError extends AigieError {
+    readonly provider: string;
+    readonly statusCode?: number | undefined;
+    constructor(message: string, provider: string, statusCode?: number | undefined);
+}
+
+/**
+ * Zod-based tool system for the Aigie SDK agent framework.
+ *
+ * Provides `tool()` and `toolPlain()` functions for defining tools with
+ * Zod schema validation and automatic JSON Schema generation.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Create a tool definition with Zod schema validation.
+ *
+ * The execute function receives both the validated params and a RunContext.
+ *
+ * @example
+ * ```ts
+ * const searchTool = tool({
+ *   name: 'search',
+ *   description: 'Search the database',
+ *   parameters: z.object({
+ *     query: z.string().describe('Search query'),
+ *     limit: z.number().optional().describe('Max results'),
+ *   }),
+ *   execute: async (params, ctx) => {
+ *     return `Results for: ${params.query}`;
+ *   },
+ * });
+ * ```
+ */
+declare function tool<TParams extends ZodRawShape, TContext = unknown>(config: ToolConfig<TParams, TContext>): ToolDefinition<z.infer<ZodObject<TParams>>, TContext>;
+/**
+ * Create a tool definition without RunContext.
+ *
+ * The execute function receives only the validated params.
+ * Sets requiresContext to false.
+ *
+ * @example
+ * ```ts
+ * const uppercaseTool = toolPlain({
+ *   name: 'uppercase',
+ *   description: 'Convert to uppercase',
+ *   parameters: z.object({ input: z.string() }),
+ *   execute: async ({ input }) => input.toUpperCase(),
+ * });
+ * ```
+ */
+declare function toolPlain<TParams extends ZodRawShape>(config: Omit<ToolConfig<TParams, never>, 'execute'> & {
+    execute: (params: z.infer<ZodObject<TParams>>) => unknown | Promise<unknown>;
+}): ToolDefinition<z.infer<ZodObject<TParams>>, never>;
+/**
+ * Handle returned by `startToolCall()` for manual lifecycle tracking (Tier 3).
+ */
+interface ToolCallHandle {
+    /** The span ID for this tool call */
+    readonly spanId: string;
+    /** End the tool call successfully with the given output */
+    end(output: unknown): Promise<void>;
+    /** End the tool call with an error */
+    error(err: Error | string): Promise<void>;
+}
+/**
+ * Tier 2 (Retroactive): Track a tool call after the fact.
+ *
+ * Records a completed tool invocation as a span. Use this when you already
+ * have the input and output and just want to log it retroactively.
+ *
+ * @param name - Tool name
+ * @param input - The input that was passed to the tool
+ * @param output - The output that the tool returned
+ * @param metadata - Optional additional metadata
+ *
+ * @example
+ * ```ts
+ * const result = await myExternalTool(params);
+ * await trackToolCall('myExternalTool', params, result);
+ * ```
+ */
+declare function trackToolCall(name: string, input: unknown, output: unknown, metadata?: Record<string, any>): Promise<void>;
+/**
+ * Tier 3 (Manual Lifecycle): Start a tool call and get a handle to end it later.
+ *
+ * Use this when you need precise control over the tool call timing,
+ * for example when the tool call is long-running or streaming.
+ *
+ * @param name - Tool name
+ * @param input - The input being passed to the tool
+ * @param metadata - Optional additional metadata
+ * @returns A handle with `.end(output)` and `.error(err)` methods
+ *
+ * @example
+ * ```ts
+ * const handle = startToolCall('longRunningTool', { query: 'test' });
+ * try {
+ *   const result = await longRunningTool({ query: 'test' });
+ *   await handle.end(result);
+ * } catch (err) {
+ *   await handle.error(err);
+ * }
+ * ```
+ */
+declare function startToolCall(name: string, input: unknown, metadata?: Record<string, any>): ToolCallHandle;
+
+/**
+ * Wrap an Anthropic client instance for automatic tracing
+ *
+ * @example
+ * ```typescript
+ * import Anthropic from '@anthropic-ai/sdk';
+ * import { wrapAnthropic } from '@kyte/sdk';
+ *
+ * const anthropic = wrapAnthropic(new Anthropic());
+ *
+ * // All calls are now automatically traced
+ * const response = await anthropic.messages.create({
+ *   model: 'claude-3-sonnet-20240229',
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ *   max_tokens: 1024
+ * });
+ * ```
+ */
+declare function wrapAnthropic<T extends object>(client: T, options?: {
+    traceName?: string;
+    userId?: string;
+    sessionId?: string;
+    tags?: string[];
+    metadata?: Record<string, any>;
+}): T;
+
+/**
+ * Wrap a specific fetch call with tracing
+ *
+ * @example
+ * ```typescript
+ * import { tracedFetch } from '@kyte/sdk';
+ *
+ * const response = await tracedFetch('https://api.example.com/data', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ query: 'test' })
+ * }, {
+ *   spanName: 'api.getData',
+ *   tags: ['api'],
+ * });
+ * ```
+ */
+declare function tracedFetch(input: RequestInfo | URL, init?: RequestInit, options?: {
+    spanName?: string;
+    tags?: string[];
+    metadata?: Record<string, any>;
+}): Promise<Response>;
+
+/**
+ * Auto-Instrumentation System
+ *
+ * Zero-code tracing using ES Proxy pattern.
+ * Automatically instruments LLM SDKs without modifying original code.
+ */
+
+/**
+ * Enable auto-instrumentation for specified SDKs
+ *
+ * @example
+ * ```typescript
+ * import { autoInstrument } from '@kyte/sdk';
+ *
+ * autoInstrument({
+ *   openai: true,
+ *   anthropic: true,
+ *   langchain: true
+ * });
+ *
+ * // All subsequent SDK usage is automatically traced
+ * import OpenAI from 'openai';
+ * const openai = new OpenAI();
+ * // Calls are now automatically traced!
+ * ```
+ */
+declare function autoInstrument(config?: AutoInstrumentConfig): Promise<void>;
+/**
+ * Disable all auto-instrumentation and restore original modules
+ */
+declare function disableAutoInstrument(): void;
+/**
+ * Create a proxy wrapper that traces all method calls
+ * This is the core pattern used by Langfuse
+ */
+declare function createTracingProxy<T extends object>(target: T, options?: {
+    name?: string;
+    spanType?: string;
+    captureArgs?: boolean;
+    captureResult?: boolean;
+}): T;
+
+/**
+ * LangChain Callback Handler for automatic tracing
+ *
+ * @example
+ * ```typescript
+ * import { AigieCallbackHandler } from '@kyte/sdk';
+ * import { ChatOpenAI } from '@langchain/openai';
+ *
+ * const handler = new AigieCallbackHandler({
+ *   userId: 'user123',
+ *   sessionId: 'session456'
+ * });
+ *
+ * const model = new ChatOpenAI();
+ * const result = await model.invoke('Hello!', { callbacks: [handler] });
+ * ```
+ */
+declare class AigieCallbackHandler {
+    private userId?;
+    private sessionId?;
+    private tags;
+    private metadata;
+    private spanStack;
+    name: string;
+    constructor(options?: {
+        userId?: string;
+        sessionId?: string;
+        tags?: string[];
+        metadata?: Record<string, any>;
+    });
+    handleLLMStart(llm: {
+        name: string;
+    }, prompts: string[], runId: string, parentRunId?: string, extraParams?: Record<string, any>): Promise<void>;
+    handleLLMEnd(output: any, runId: string): Promise<void>;
+    handleLLMError(error: Error, runId: string): Promise<void>;
+    handleChatModelStart(llm: {
+        name: string;
+    }, messages: any[][], runId: string, parentRunId?: string, extraParams?: Record<string, any>): Promise<void>;
+    handleChainStart(chain: {
+        name: string;
+    }, inputs: Record<string, any>, runId: string, parentRunId?: string): Promise<void>;
+    handleChainEnd(outputs: Record<string, any>, runId: string): Promise<void>;
+    handleChainError(error: Error, runId: string): Promise<void>;
+    handleToolStart(tool: {
+        name: string;
+    }, input: string, runId: string, parentRunId?: string): Promise<void>;
+    handleToolEnd(output: string, runId: string): Promise<void>;
+    handleToolError(error: Error, runId: string): Promise<void>;
+    handleAgentAction(action: any, runId: string): Promise<void>;
+    handleAgentEnd(_action: any, _runId: string): Promise<void>;
+    handleRetrieverStart(retriever: {
+        name: string;
+    }, query: string, runId: string, parentRunId?: string): Promise<void>;
+    handleRetrieverEnd(documents: any[], runId: string): Promise<void>;
+    handleRetrieverError(error: Error, runId: string): Promise<void>;
+}
+/**
+ * Create a new AigieCallbackHandler
+ */
+declare function createAigieHandler(options?: {
+    userId?: string;
+    sessionId?: string;
+    tags?: string[];
+    metadata?: Record<string, any>;
+}): AigieCallbackHandler;
+
+/**
+ * Wrap an OpenAI client instance for automatic tracing
+ *
+ * @example
+ * ```typescript
+ * import OpenAI from 'openai';
+ * import { wrapOpenAI } from '@kyte/sdk';
+ *
+ * const openai = wrapOpenAI(new OpenAI());
+ *
+ * // All calls are now automatically traced
+ * const response = await openai.chat.completions.create({
+ *   model: 'gpt-4',
+ *   messages: [{ role: 'user', content: 'Hello!' }]
+ * });
+ * ```
+ */
+declare function wrapOpenAI<T extends object>(client: T, options?: {
+    traceName?: string;
+    userId?: string;
+    sessionId?: string;
+    tags?: string[];
+    metadata?: Record<string, any>;
+}): T;
+
+/**
+ * Cost Tracking
+ *
+ * Token counting and cost calculation for 50+ LLM models.
+ */
+
+declare const MODEL_PRICING: ModelPricing[];
+/**
+ * Get pricing for a model
+ */
+declare function getModelPricing(model: string, provider?: string): ModelPricing | null;
+/**
+ * Calculate cost for a model call
+ *
+ * @param model - Model name
+ * @param provider - Provider name (openai, anthropic, google, cohere, bedrock)
+ * @param inputTokens - Number of input/prompt tokens
+ * @param outputTokens - Number of output/completion tokens
+ * @param cachedTokens - Number of cached tokens (optional)
+ * @returns Cost in USD or null if pricing not found
+ */
+declare function calculateCost(model: string, provider: string, inputTokens: number, outputTokens: number, cachedTokens?: number): number | null;
+/**
+ * Get all supported models for a provider
+ */
+declare function getModelsForProvider(provider: string): ModelPricing[];
+/**
+ * Get all supported providers
+ */
+declare function getSupportedProviders(): string[];
+/**
+ * Check if a model is supported
+ */
+declare function isModelSupported(model: string, provider?: string): boolean;
+/**
+ * Format cost as currency string
+ */
+declare function formatCost(cost: number, currency?: string): string;
+
+/**
+ * Smart Cache
+ *
+ * Implements stale-while-revalidate pattern with background refresh.
+ * Inspired by Langfuse's sophisticated caching strategy.
+ */
+
+/**
+ * Smart Cache with stale-while-revalidate and background refresh
+ *
+ * @example
+ * ```typescript
+ * const cache = new SmartCache<Prompt>({
+ *   ttl: 60000, // 1 minute
+ *   staleWhileRevalidate: true,
+ *   backgroundRefresh: true,
+ *   onRefresh: async (key) => fetchPromptFromServer(key)
+ * });
+ *
+ * // First call fetches from server
+ * const prompt1 = await cache.get('my-prompt');
+ *
+ * // Subsequent calls return cached value
+ * const prompt2 = await cache.get('my-prompt'); // Instant!
+ *
+ * // After TTL expires, returns stale data while refreshing in background
+ * const prompt3 = await cache.get('my-prompt'); // Returns stale, refreshes async
+ * ```
+ */
+declare class SmartCache<T> {
+    private cache;
+    private refreshing;
+    private config;
+    constructor(config: SmartCacheConfig<T>);
+    /**
+     * Get a value from cache
+     * If expired and staleWhileRevalidate is true, returns stale value while refreshing
+     */
+    get(key: string, fallback?: () => Promise<T>): Promise<T | undefined>;
+    /**
+     * Set a value in cache
+     */
+    set(key: string, value: T, ttl?: number): void;
+    /**
+     * Delete a value from cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear entire cache
+     */
+    clear(): void;
+    /**
+     * Check if key exists and is fresh
+     */
+    has(key: string): boolean;
+    /**
+     * Check if key exists (even if stale)
+     */
+    hasStale(key: string): boolean;
+    /**
+     * Get cache size
+     */
+    get size(): number;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        freshCount: number;
+        staleCount: number;
+        oldestEntry: number | null;
+        newestEntry: number | null;
+    };
+    /**
+     * Manually trigger refresh for a key
+     */
+    refresh(key: string): Promise<T>;
+    /**
+     * Refresh in background (non-blocking)
+     */
+    private refreshInBackground;
+    /**
+     * Evict least recently used entry
+     */
+    private evictLRU;
+    /**
+     * Prune expired entries
+     */
+    prune(): number;
+    /**
+     * Get all keys
+     */
+    keys(): string[];
+    /**
+     * Get all entries (for serialization)
+     */
+    entries(): Array<[string, CacheEntry<T>]>;
+    /**
+     * Restore cache from serialized data
+     */
+    restore(entries: Array<[string, CacheEntry<T>]>): void;
+}
+/**
+ * Create a smart cache with default settings
+ */
+declare function createSmartCache<T>(options: SmartCacheConfig<T>): SmartCache<T>;
+/**
+ * Create a prompt cache with sensible defaults
+ */
+declare function createPromptCache<T>(onRefresh: (promptName: string) => Promise<T>, ttl?: number): SmartCache<T>;
+
+/**
+ * Annotations Client
+ *
+ * Human feedback and corrections on traces and spans.
+ */
+
+/**
+ * Annotations API Client
+ *
+ * @example
+ * ```typescript
+ * import { AnnotationsClient } from '@kyte/sdk';
+ *
+ * const annotations = new AnnotationsClient();
+ *
+ * // Create a correction annotation
+ * await annotations.create({
+ *   traceId: 'trace_123',
+ *   type: 'correction',
+ *   value: 'The correct answer should be 42',
+ *   annotatorId: 'user@example.com'
+ * });
+ *
+ * // List all annotations for a trace
+ * const items = await annotations.list({ traceId: 'trace_123' });
+ * ```
+ */
+declare class AnnotationsClient {
+    private baseUrl;
+    private apiKey;
+    constructor();
+    /**
+     * Create a new annotation
+     */
+    create(request: CreateAnnotationRequest): Promise<Annotation>;
+    /**
+     * Get annotation by ID
+     */
+    get(annotationId: string): Promise<Annotation>;
+    /**
+     * List annotations
+     */
+    list(filters?: {
+        traceId?: string;
+        spanId?: string;
+        type?: AnnotationType;
+        annotatorId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        annotations: Annotation[];
+        total: number;
+    }>;
+    /**
+     * Update an annotation
+     */
+    update(annotationId: string, updates: Partial<Pick<Annotation, 'value' | 'comment' | 'metadata'>>): Promise<Annotation>;
+    /**
+     * Delete an annotation
+     */
+    delete(annotationId: string): Promise<void>;
+    /**
+     * Add a correction to a trace
+     */
+    addCorrection(traceId: string, correction: string, options?: {
+        spanId?: string;
+        annotatorId?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Annotation>;
+    /**
+     * Approve a trace/span
+     */
+    approve(traceId: string, options?: {
+        spanId?: string;
+        comment?: string;
+        annotatorId?: string;
+    }): Promise<Annotation>;
+    /**
+     * Reject a trace/span
+     */
+    reject(traceId: string, reason: string, options?: {
+        spanId?: string;
+        annotatorId?: string;
+    }): Promise<Annotation>;
+    /**
+     * Add a comment to a trace
+     */
+    addComment(traceId: string, comment: string, options?: {
+        spanId?: string;
+        annotatorId?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Annotation>;
+    /**
+     * Add a label to a trace
+     */
+    addLabel(traceId: string, label: string, options?: {
+        spanId?: string;
+        annotatorId?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Annotation>;
+    /**
+     * Add a numeric score annotation
+     */
+    addScore(traceId: string, score: number, options?: {
+        spanId?: string;
+        comment?: string;
+        annotatorId?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Annotation>;
+    /**
+     * Add thumbs up/down annotation
+     */
+    addThumbs(traceId: string, thumbs: 'up' | 'down', options?: {
+        spanId?: string;
+        comment?: string;
+        annotatorId?: string;
+    }): Promise<Annotation>;
+    /**
+     * Get annotation statistics for a trace
+     */
+    getStats(traceId: string): Promise<{
+        total: number;
+        byType: Record<AnnotationType, number>;
+        approvalRate: number | null;
+        averageScore: number | null;
+    }>;
+}
+/**
+ * Create an annotations client
+ */
+declare function createAnnotationsClient(): AnnotationsClient;
+
+/**
+ * Feedback Client
+ *
+ * Structured feedback collection with rating scales, categories, and analytics.
+ */
+
+/**
+ * Feedback API Client
+ *
+ * @example
+ * ```typescript
+ * import { FeedbackClient } from '@kyte/sdk';
+ *
+ * const feedback = new FeedbackClient();
+ *
+ * // Simple thumbs up/down
+ * await feedback.thumbsUp('trace_123', { userId: 'user_456' });
+ *
+ * // Detailed rating
+ * await feedback.rating('trace_123', 4, {
+ *   scale: [1, 5],
+ *   comment: 'Good response but could be more detailed',
+ *   userId: 'user_456'
+ * });
+ *
+ * // Get feedback stats
+ * const stats = await feedback.getStats({ traceIds: ['trace_123'] });
+ * ```
+ */
+declare class FeedbackClient {
+    private baseUrl;
+    private apiKey;
+    constructor();
+    /**
+     * Create feedback
+     */
+    create(request: CreateFeedbackRequest): Promise<Feedback>;
+    /**
+     * Get feedback by ID
+     */
+    get(feedbackId: string): Promise<Feedback>;
+    /**
+     * List feedback
+     */
+    list(filters?: {
+        traceId?: string;
+        spanId?: string;
+        type?: FeedbackType;
+        userId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        feedback: Feedback[];
+        total: number;
+    }>;
+    /**
+     * Delete feedback
+     */
+    delete(feedbackId: string): Promise<void>;
+    /**
+     * Add thumbs up feedback
+     */
+    thumbsUp(traceId: string, options?: {
+        spanId?: string;
+        comment?: string;
+        userId?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Feedback>;
+    /**
+     * Add thumbs down feedback
+     */
+    thumbsDown(traceId: string, options?: {
+        spanId?: string;
+        comment?: string;
+        userId?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Feedback>;
+    /**
+     * Add rating feedback
+     */
+    rating(traceId: string, value: number, options?: {
+        spanId?: string;
+        scale?: [number, number];
+        comment?: string;
+        userId?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Feedback>;
+    /**
+     * Add categorical feedback
+     */
+    categorical(traceId: string, category: string, options?: {
+        spanId?: string;
+        categories?: string[];
+        comment?: string;
+        userId?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Feedback>;
+    /**
+     * Add text feedback
+     */
+    text(traceId: string, text: string, options?: {
+        spanId?: string;
+        userId?: string;
+        metadata?: Record<string, any>;
+    }): Promise<Feedback>;
+    /**
+     * Get feedback statistics
+     */
+    getStats(filters: {
+        traceIds?: string[];
+        spanIds?: string[];
+        userId?: string;
+        startDate?: Date;
+        endDate?: Date;
+        groupBy?: 'day' | 'week' | 'month';
+    }): Promise<FeedbackStats>;
+    /**
+     * Calculate local statistics from feedback list
+     */
+    calculateStats(feedbackList: Feedback[]): FeedbackStats;
+}
+/**
+ * Create a feedback client
+ */
+declare function createFeedbackClient(): FeedbackClient;
+/**
+ * Feedback Collector - Higher-level abstraction for collecting feedback
+ *
+ * @example
+ * ```typescript
+ * const collector = new FeedbackCollector({
+ *   traceId: 'trace_123',
+ *   userId: 'user_456'
+ * });
+ *
+ * // Collect feedback at end of conversation
+ * await collector.collectRating(4, 'Good response!');
+ * ```
+ */
+declare class FeedbackCollector {
+    private client;
+    private traceId;
+    private spanId?;
+    private userId?;
+    private sessionId?;
+    constructor(options: {
+        traceId: string;
+        spanId?: string;
+        userId?: string;
+        sessionId?: string;
+    });
+    collectThumbsUp(comment?: string): Promise<Feedback>;
+    collectThumbsDown(comment?: string): Promise<Feedback>;
+    collectRating(value: number, comment?: string): Promise<Feedback>;
+    collectCategory(category: string, comment?: string): Promise<Feedback>;
+    collectText(text: string): Promise<Feedback>;
+}
+/**
+ * Create a feedback collector
+ */
+declare function createFeedbackCollector(options: {
+    traceId: string;
+    spanId?: string;
+    userId?: string;
+    sessionId?: string;
+}): FeedbackCollector;
+
+/**
+ * Media Handling
+ *
+ * Base64 extraction, SHA256 deduplication, and media upload.
+ * Inspired by Langfuse's media handling capabilities.
+ */
+
+/**
+ * Media Manager for handling multimodal content
+ *
+ * @example
+ * ```typescript
+ * import { MediaManager } from '@kyte/sdk';
+ *
+ * const media = new MediaManager();
+ *
+ * // Process messages with images
+ * const processed = await media.processMessages(messages);
+ *
+ * // Upload media with deduplication
+ * const ref = await media.upload(base64Data, 'image/png');
+ * ```
+ */
+declare class MediaManager {
+    private baseUrl;
+    private apiKey;
+    private uploadedHashes;
+    constructor();
+    /**
+     * Process messages and extract media
+     */
+    processMessages(messages: any[]): Promise<ProcessedMedia>;
+    /**
+     * Process a single message
+     */
+    private processMessage;
+    /**
+     * Process a data URL (data:image/png;base64,...)
+     */
+    private processBase64Url;
+    /**
+     * Process Anthropic-style base64 source
+     */
+    private processBase64Source;
+    /**
+     * Upload media with deduplication
+     */
+    upload(base64Data: string, mimeType: string): Promise<MediaReference>;
+    /**
+     * Calculate SHA256 hash of base64 data
+     */
+    private calculateHash;
+    /**
+     * Get media by ID
+     */
+    get(mediaId: string): Promise<MediaReference | null>;
+    /**
+     * Resolve media references in an object
+     */
+    resolveReferences(obj: any, options?: {
+        mode?: 'url' | 'base64DataUri';
+        maxTraversalDepth?: number;
+    }): Promise<any>;
+    /**
+     * Recursively traverse and resolve media references
+     */
+    private traverseAndResolve;
+    /**
+     * Convert URL to data URI
+     */
+    private urlToDataUri;
+    /**
+     * Clear the hash cache
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        totalBytes: number;
+    };
+}
+/**
+ * Create a media manager
+ */
+declare function createMediaManager(): MediaManager;
+/**
+ * Extract base64 data from a data URL
+ */
+declare function extractBase64FromDataUrl(dataUrl: string): {
+    mimeType: string;
+    data: string;
+} | null;
+/**
+ * Create a data URL from base64 data
+ */
+declare function createDataUrl(base64Data: string, mimeType: string): string;
+/**
+ * Check if a string is a valid data URL
+ */
+declare function isDataUrl(str: string): boolean;
+/**
+ * Get file extension from MIME type
+ */
+declare function mimeToExtension(mimeType: string): string;
+
+/**
+ * UUID v7 Implementation
+ * Time-ordered UUIDs for better database indexing
+ */
+/**
+ * Generate a UUID v7 (time-ordered)
+ */
+declare function uuidv7(): string;
+/**
+ * Validate if a string is a valid UUID v7
+ */
+declare function isValidUuidv7(uuid: string): boolean;
+/**
+ * Extract timestamp from UUID v7
+ */
+declare function extractTimestamp(uuid: string): number;
+/**
+ * Convert UUID v7 to Date
+ */
+declare function uuidv7ToDate(uuid: string): Date;
+/**
+ * Compare two UUID v7s by timestamp
+ */
+declare function compareUuidv7(a: string, b: string): number;
+/**
+ * Generate batch of monotonically increasing UUID v7s
+ */
+declare function generateBatchUuidv7(count: number): string[];
+/**
+ * Create UUID v7 with specific timestamp
+ */
+declare function uuidv7WithTimestamp(timestamp: number): string;
+/**
+ * Get age of UUID v7 in milliseconds
+ */
+declare function getUuidv7Age(uuid: string): number;
+
+declare function parseModelString(modelString: string): {
+    provider: string;
+    model: string;
+};
+interface ProviderAdapter {
+    chat(params: {
+        model: string;
+        messages: Array<{
+            role: string;
+            content: string;
+            tool_call_id?: string;
+            tool_calls?: any[];
+        }>;
+        tools?: any[];
+        settings?: ModelSettings;
+        outputSchema?: any;
+    }): Promise<{
+        content: string;
+        toolCalls?: ToolCall[];
+        usage: {
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens: number;
+        };
+        finishReason: 'stop' | 'tool_calls' | 'length' | 'error';
+    }>;
+}
+declare class Runner {
+    private adapters;
+    registerAdapter(provider: string, adapter: ProviderAdapter): void;
+    getAdapter(provider: string): ProviderAdapter | undefined;
+    run<TContext, TOutput>(params: {
+        model: string;
+        systemPrompt?: string;
+        prompt: string;
+        tools?: ToolDefinition[];
+        outputType?: any;
+        modelSettings?: ModelSettings;
+        deps?: TContext;
+        messageHistory?: Message[];
+        inputGuardrails?: InputGuardrail[];
+        outputGuardrails?: OutputGuardrail[];
+        maxRetries?: number;
+        maxTurns?: number;
+        onToolCall?: (name: string, args: Record<string, unknown>) => void;
+        onToolResult?: (name: string, result: unknown) => void;
+    }): Promise<AgentResult<TOutput>>;
+}
+
+declare class Agent<TContext = unknown, TOutput = string> {
+    readonly name: string;
+    readonly model: string;
+    private _systemPrompt?;
+    private _tools;
+    private _outputType?;
+    private _modelSettings?;
+    private _inputGuardrails;
+    private _outputGuardrails;
+    private _maxRetries;
+    private _maxTurns;
+    private _instructionsFn?;
+    private _resultValidatorFn?;
+    private _runner;
+    constructor(config: AgentConfig<TContext, TOutput>);
+    get tools(): ToolDefinition[];
+    get hasInstructions(): boolean;
+    get hasResultValidator(): boolean;
+    addTool(toolDef: ToolDefinition): void;
+    setInstructions(fn: (ctx: RunContext<TContext>) => string | Promise<string>): void;
+    setResultValidator(fn: (ctx: RunContext<TContext>, result: TOutput) => TOutput | Promise<TOutput>): void;
+    setRunner(runner: Runner): void;
+    run(prompt: string, options?: RunOptions<TContext>): Promise<AgentResult<TOutput>>;
+    runStream(prompt: string, options?: RunOptions<TContext>): AsyncIterable<StreamChunk>;
+    clone(): Agent<TContext, TOutput>;
+    asTool(config: {
+        description: string;
+    }): ToolDefinition;
+}
+
+interface AgentResultOptions<T> {
+    data: T;
+    usage: UsageInfo;
+    messages: Message[];
+    traceId: string;
+    durationMs: number;
+    toolCalls: number;
+    retries: number;
+}
+declare class AgentResultImpl<T = string> implements AgentResult<T> {
+    data: T;
+    usage: UsageInfo;
+    messages: Message[];
+    traceId: string;
+    durationMs: number;
+    toolCalls: number;
+    retries: number;
+    constructor(options: AgentResultOptions<T>);
+    allMessages(): Message[];
+    withToolReturnContent(): Message[];
+}
+
+interface RunContextOptions<T> {
+    deps: T;
+    model: string;
+    traceId: string;
+    spanId: string;
+    messages?: Message[];
+    retryCount?: number;
+    maxRetries?: number;
+}
+declare class RunContextImpl<T = unknown> implements RunContext<T> {
+    deps: T;
+    model: string;
+    messages: Message[];
+    traceId: string;
+    spanId: string;
+    retryCount: number;
+    maxRetries: number;
+    constructor(options: RunContextOptions<T>);
+    get isLastAttempt(): boolean;
+    addMessage(msg: Message): void;
+    addUserMessage(content: string): void;
+    addAssistantMessage(content: string): void;
+    getMessagesForApi(): ApiMessage[];
+    withRetry(): RunContext<T>;
+}
+
+declare class ExecutionCycle {
+    currentPhase: string;
+    private thinkDurationMs;
+    private actDurationMs;
+    private observeDurationMs;
+    private cycleCount;
+    think<T>(fn: (phase: PhaseContext) => Promise<T>): Promise<T>;
+    act<T>(fn: (phase: PhaseContext) => Promise<T>): Promise<T>;
+    observe<T>(fn: (phase: PhaseContext) => Promise<T>): Promise<T>;
+    getMetrics(): CycleMetrics;
+}
+
+declare class GoalTracker {
+    goal: string;
+    private expectedSteps;
+    private completedSteps;
+    private deviations;
+    private startTime;
+    private nextExpectedIndex;
+    setPlan(goal: string, expectedSteps: string[]): void;
+    markStepComplete(stepName: string): void;
+    getMetrics(): PlanMetrics;
+}
+
+declare class LoopDetector {
+    private similarityThreshold;
+    private maxConsecutiveRepeats;
+    private action;
+    constructor(config?: LoopDetectorConfig);
+    checkState(_messages: Message[], toolCalls: ToolCall[]): LoopDetectionResult;
+    /**
+     * Build non-overlapping sequences of the given window size from the tool calls.
+     */
+    private buildSequences;
+    /**
+     * Convert a set of tool calls into a feature set of tool names and argument keys
+     * for Jaccard similarity comparison.
+     */
+    private toolCallsToFeatureSet;
+    /**
+     * Compute Jaccard similarity between two feature sets.
+     * J(A, B) = |A intersection B| / |A union B|
+     */
+    private computeJaccardSimilarity;
+}
+
+/**
+ * Context passed to the drift detector for comparison.
+ */
+interface DriftCheckInput {
+    /** The expected conversation context (e.g., system prompt, goal description, or reference messages). */
+    expectedContext: string | Message[];
+    /** The actual conversation context (e.g., recent messages or current output). */
+    actualContext: string | Message[];
+}
+/**
+ * Lightweight drift detection engine.
+ *
+ * Supports four drift detection strategies: topic, behavior, quality, and coherence.
+ * Each detector produces a score between 0 and 1, where higher values indicate
+ * greater drift from the expected context.
+ */
+declare class DriftDetector {
+    private readonly detectors;
+    private readonly thresholds;
+    constructor(config: DriftDetectorConfig);
+    /**
+     * Checks for drift between expected and actual context.
+     *
+     * Runs all configured detectors and returns the result of the first one
+     * whose score exceeds its threshold. If no detector triggers, returns
+     * a no-drift result with the highest observed score.
+     */
+    checkDrift(input: DriftCheckInput): Promise<DriftResult>;
+    private runDetector;
+    private detectTopicDrift;
+    private detectBehaviorDrift;
+    private detectQualityDrift;
+    private detectCoherenceDrift;
+}
+
+declare function inputGuardrail(config: {
+    name: string;
+    execute: (input: string, context: GuardrailContext) => Promise<GuardrailResult>;
+}): InputGuardrail;
+declare function outputGuardrail(config: {
+    name: string;
+    execute: (output: unknown, context: GuardrailContext) => Promise<GuardrailResult>;
+}): OutputGuardrail;
+
+declare class EvaluationClient {
+    private apiUrl;
+    private apiKey;
+    constructor(config: {
+        apiUrl: string;
+        apiKey: string;
+    });
+    addScore(score: EvaluationScore): Promise<void>;
+    addScores(scores: EvaluationScore[]): Promise<void>;
+}
+
+declare class LLMJudge {
+    private config;
+    private runner;
+    constructor(config: JudgeConfig);
+    setAdapter(provider: string, adapter: ProviderAdapter): void;
+    evaluate(params: {
+        input: string;
+        output: string;
+        context?: string;
+        reference?: string;
+    }): Promise<JudgeResult>;
+}
+
+declare class SignalReporter {
+    private apiUrl;
+    private apiKey;
+    private queue;
+    private flushTimer;
+    private batchSize;
+    private flushInterval;
+    constructor(config: {
+        apiUrl: string;
+        apiKey: string;
+        batchSize?: number;
+        flushInterval?: number;
+    });
+    emit(request: EmitSignalRequest): Promise<Signal>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Reliability Metrics - Aggregate plan, cycle, loop, and drift metrics
+ * into a single reliability score.
+ *
+ * @packageDocumentation
+ */
+
+interface ReliabilityMetrics {
+    planMetrics?: PlanMetrics;
+    cycleMetrics?: CycleMetrics;
+    loopMetrics?: LoopDetectionResult;
+    driftMetrics?: DriftResult;
+    overallScore: number;
+}
+declare class MetricsAggregator {
+    private _planMetrics?;
+    private _cycleMetrics?;
+    private _loopMetrics?;
+    private _driftMetrics?;
+    setPlanMetrics(metrics: PlanMetrics): void;
+    setCycleMetrics(metrics: CycleMetrics): void;
+    setLoopMetrics(metrics: LoopDetectionResult): void;
+    setDriftMetrics(metrics: DriftResult): void;
+    getMetrics(): ReliabilityMetrics;
+    reset(): void;
+}
+
+/**
+ * Prompt Management - Versioned prompt template registration and rendering.
+ *
+ * @packageDocumentation
+ */
+interface PromptTemplate {
+    name: string;
+    template: string;
+    variables: string[];
+    version: number;
+    createdAt: string;
+}
+declare class PromptManager {
+    private templates;
+    register(name: string, template: string, variables: string[]): PromptTemplate;
+    render(name: string, values: Record<string, string>, version?: number): string;
+    getVersion(name: string, version?: number): PromptTemplate;
+    list(): string[];
+}
+
+/**
+ * Remediation Engine - Real-time signal handling and automated remediation.
+ *
+ * Connects to the backend via WebSocket, receives signals, and dispatches
+ * them to registered remediation handlers.
+ *
+ * @packageDocumentation
+ */
+
+interface RemediationEngineConfig {
+    url: string;
+    token: string;
+}
+interface RetryConfig {
+    maxRetries: number;
+    backoffMs: number;
+}
+interface FallbackConfig {
+    fallbackModel: string;
+}
+declare class RemediationEngine {
+    private readonly config;
+    private ws;
+    private handlers;
+    private actionListeners;
+    constructor(config: RemediationEngineConfig);
+    connect(): Promise<void>;
+    disconnect(): void;
+    onSignal(type: SignalType, handler: RemediationHandler): void;
+    /**
+     * Register a listener that is called whenever a remediation action is
+     * emitted after a signal is processed.
+     */
+    onAction(listener: (action: RemediationAction, signal: Signal) => void): void;
+    static retry(config: RetryConfig): RemediationHandler;
+    static fallback(config: FallbackConfig): RemediationHandler;
+    static contextReset(): RemediationHandler;
+    static goalReinjection(goal: string): RemediationHandler;
+    static checkpointRestore(checkpointId: string): RemediationHandler;
+    private handleMessage;
+    private dispatch;
+    private emitAction;
+}
+
+/**
+ * Local Rules Engine - Evaluate guardrail rules against a runtime context.
+ *
+ * @packageDocumentation
+ */
+
+interface Rule {
+    name: string;
+    condition: (ctx: RuleContext) => boolean;
+    action: GuardrailAction;
+    message: string;
+}
+interface RuleContext {
+    input?: string;
+    output?: string;
+    toolCalls?: Array<{
+        name: string;
+        arguments: Record<string, unknown>;
+    }>;
+    durationMs?: number;
+    tokenCount?: number;
+    metadata?: Record<string, unknown>;
+}
+interface RuleResult {
+    ruleName: string;
+    triggered: boolean;
+    action: GuardrailAction;
+    message: string;
+}
+declare class RulesEngine {
+    private rules;
+    addRule(rule: Rule): void;
+    removeRule(name: string): void;
+    evaluate(context: RuleContext): RuleResult[];
+    evaluateAll(context: RuleContext): RuleResult[];
+}
+
+interface DiagnosticSignal {
+    description: string;
+    sentiment: 'POSITIVE' | 'NEGATIVE' | 'NEUTRAL';
+}
+interface DiagnosticsConfig {
+    signals: Record<string, DiagnosticSignal>;
+}
+declare function createSelfDiagnosticsTool(config: DiagnosticsConfig): {
+    forOpenAI(): {
+        type: "function";
+        function: {
+            name: string;
+            description: string;
+            parameters: Record<string, any>;
+        };
+    };
+    forAnthropic(): {
+        name: string;
+        description: string;
+        input_schema: Record<string, any>;
+    };
+    forVercelAI(): {
+        description: string;
+        parameters: any;
+        execute: (params: any) => Promise<any>;
+    };
+    execute: (params: {
+        signal_name: string;
+        details?: string;
+    }) => Promise<{
+        error: string;
+        signal_name?: undefined;
+        description?: undefined;
+        sentiment?: undefined;
+        details?: undefined;
+        timestamp?: undefined;
+    } | {
+        signal_name: string;
+        description: string;
+        sentiment: "POSITIVE" | "NEGATIVE" | "NEUTRAL";
+        details: string | undefined;
+        timestamp: string;
+        error?: undefined;
+    }>;
+    signals: Record<string, DiagnosticSignal>;
+};
+
+declare class IntegrationRegistryImpl {
+    private integrations;
+    private patchedSet;
+    register(info: IntegrationInfo): void;
+    get(name: string): IntegrationInfo | undefined;
+    getAll(): IntegrationInfo[];
+    markPatched(name: string): void;
+    isPatched(name: string): boolean;
+    patch(...names: string[]): Promise<void>;
+    patchAll(): Promise<void>;
+}
+declare const IntegrationRegistry: IntegrationRegistryImpl;
+
+/**
+ * Kyte SDK for TypeScript/JavaScript
+ *
+ * Automatic tracing and monitoring for AI applications.
+ *
+ * @packageDocumentation
+ */
+
+declare const VERSION = "1.1.0";
+
+export { type ActiveSpan, Agent, type AgentConfig, AgentExecutionError, type AgentResult, AgentResultImpl, AigieCallbackHandler, AigieClient, type AigieConfig, AigieError, type Annotation, type AnnotationType, AnnotationsClient, type AnthropicToolSchema, type ApiMessage, type AutoInstrumentConfig, BehaviorDriftDetected, type CacheEntry, ConfigurationError, ContextDriftDetected, type CostDetails, type CreateAnnotationRequest, type CreateFeedbackRequest, type CustomInstrumentation, type CycleMetrics, type Deviation, DriftDetector, type DriftDetectorConfig, DriftError, type DriftResult, type DriftType, type EmitSignalRequest, EvaluationClient, type EvaluationScore, ExecutionCycle, type Feedback, FeedbackClient, FeedbackCollector, type FeedbackStats, type FeedbackType, GoalTracker, GuardrailAction, type GuardrailContext, GuardrailError, type GuardrailResult, type InputGuardrail, type IntegrationInfo, IntegrationRegistry, InterceptionError, type JudgeConfig, type JudgeResult, AigieCallbackHandler as KyteCallbackHandler, AigieClient as KyteClient, type AigieConfig as KyteConfig, LLMJudge, LoopDetectedError, type LoopDetectionResult, LoopDetector, type LoopDetectorConfig, MODEL_PRICING, MediaManager, type MediaReference, type Message, MetricsAggregator, type ModelPricing, ModelRetry, type ModelSettings, type OpenAIToolSchema, type OutputGuardrail, type PhaseContext, type PlanMetrics, type ProcessedMedia, PromptManager, type PromptTemplate, type ProviderAdapter, ProviderError, type ReliabilityMetrics, type RemediationAction, RemediationEngine, RemediationError, RemediationFailed, type RemediationHandler, RemediationRejected, RetryExhausted, type Rule, type RuleContext, type RuleResult, RulesEngine, type RunContext, RunContextImpl, type RunOptions, Runner, type Score, type ScoreType, type Signal, SignalReporter, SignalSeverity, SignalType, SmartCache, type SmartCacheConfig, type Span, type SpanBuilder, type SpanContext, type SpanOptions, type SpanType, type SpanUpdateData, type StreamChunk, TimeoutError, type TokenUsage, type ToolCall, type ToolCallHandle, type ToolCallResult, type ToolConfig, type ToolDefinition, ToolExecutionError, TopicDriftDetected, type Trace, type TraceContext, type TraceOptions, type TraceStatus, type TraceableConfig, TracingError, type UsageDetails, type UsageInfo, VERSION, ValidationError, type WrapperOptions, autoInstrument, calculateCost, compareUuidv7, createAigieHandler, createAnnotationsClient, createDataUrl, createFeedbackClient, createFeedbackCollector, createAigieHandler as createKyteHandler, createMediaManager, createPromptCache, createSelfDiagnosticsTool, createSmartCache, createTracingProxy, disableAutoInstrument, extractBase64FromDataUrl, extractTimestamp, formatCost, generateBatchUuidv7, getAigie, getKyte, getModelPricing, getModelsForProvider, getSupportedProviders, getUuidv7Age, initAigie, initKyte, inputGuardrail, isDataUrl, isModelSupported, isValidUuidv7, mimeToExtension, observe, outputGuardrail, parseModelString, startToolCall, tool, toolPlain, trace, traceable, tracedFetch, trackToolCall, uuidv7, uuidv7ToDate, uuidv7WithTimestamp, withTracing, wrapAnthropic, wrapOpenAI };