@ai2070/l0/dist/types/l0.d.ts

L0: The Missing Reliability Substrate for AI

import type { GuardrailRule, GuardrailViolation } from "./guardrails";
import type { BackoffStrategy, RetryReason } from "./retry";
import { ErrorCategory } from "./retry";
import type { L0Event as L0ObservabilityEvent } from "./observability";
export interface CheckpointValidationResult {
    skipContinuation: boolean;
    violations: GuardrailViolation[];
    driftDetected: boolean;
    driftTypes: string[];
}
export type L0ContentType = "text" | "image" | "audio" | "video" | "file" | "json" | "binary";
export interface L0DataPayload {
    contentType: L0ContentType;
    mimeType?: string;
    base64?: string;
    url?: string;
    bytes?: Uint8Array;
    json?: unknown;
    metadata?: {
        width?: number;
        height?: number;
        duration?: number;
        size?: number;
        filename?: string;
        seed?: number;
        model?: string;
        [key: string]: unknown;
    };
}
export interface L0Progress {
    percent?: number;
    step?: number;
    totalSteps?: number;
    message?: string;
    eta?: number;
}
export interface L0Event {
    type: "token" | "message" | "data" | "progress" | "error" | "complete";
    value?: string;
    role?: string;
    data?: L0DataPayload;
    progress?: L0Progress;
    error?: Error;
    reason?: ErrorCategory;
    timestamp?: number;
    usage?: {
        input_tokens?: number;
        output_tokens?: number;
        cost?: number;
        [key: string]: unknown;
    };
}
export interface L0Options<TOutput = unknown> {
    __outputType?: TOutput;
    stream: () => Promise<any> | any;
    context?: Record<string, unknown>;
    fallbackStreams?: Array<() => Promise<any> | any>;
    guardrails?: GuardrailRule[];
    retry?: RetryOptions;
    timeout?: {
        initialToken?: number;
        interToken?: number;
    };
    signal?: AbortSignal;
    monitoring?: {
        enabled?: boolean;
        sampleRate?: number;
        includeNetworkDetails?: boolean;
        includeTimings?: boolean;
        metadata?: Record<string, any>;
    };
    checkIntervals?: {
        guardrails?: number;
        drift?: number;
        checkpoint?: number;
    };
    detectDrift?: boolean;
    detectZeroTokens?: boolean;
    continueFromLastKnownGoodToken?: boolean;
    buildContinuationPrompt?: (checkpoint: string) => string;
    deduplicateContinuation?: boolean;
    deduplicationOptions?: {
        minOverlap?: number;
        maxOverlap?: number;
        caseSensitive?: boolean;
        normalizeWhitespace?: boolean;
    };
    onStart?: (attempt: number, isRetry: boolean, isFallback: boolean) => void;
    onComplete?: (state: L0State) => void;
    onError?: (error: Error, willRetry: boolean, willFallback: boolean) => void;
    onEvent?: (event: L0Event | L0ObservabilityEvent) => void;
    onViolation?: (violation: GuardrailViolation) => void;
    onRetry?: (attempt: number, reason: string) => void;
    onFallback?: (index: number, reason: string) => void;
    onResume?: (checkpoint: string, tokenCount: number) => void;
    onCheckpoint?: (checkpoint: string, tokenCount: number) => void;
    onTimeout?: (type: "initial" | "inter", elapsedMs: number) => void;
    onAbort?: (tokenCount: number, contentLength: number) => void;
    onDrift?: (types: string[], confidence?: number) => void;
    onToolCall?: (toolName: string, toolCallId: string, args: Record<string, unknown>) => void;
    interceptors?: L0Interceptor[];
    adapter?: L0Adapter | string;
    adapterOptions?: unknown;
}
export interface L0Adapter<StreamType = unknown, Options = unknown> {
    name: string;
    detect?(input: unknown): input is StreamType;
    wrap(stream: StreamType, options?: Options): AsyncGenerator<L0Event>;
}
export interface L0Interceptor {
    name?: string;
    before?: (options: L0Options) => L0Options | Promise<L0Options>;
    after?: (result: L0Result) => L0Result | Promise<L0Result>;
    onError?: (error: Error, options: L0Options) => void | Promise<void>;
}
export interface L0Result<TOutput = unknown> {
    __outputType?: TOutput;
    stream: AsyncIterable<L0Event>;
    text?: string;
    state: L0State;
    errors: Error[];
    telemetry?: L0Telemetry;
    abort: () => void;
}
export interface L0State {
    content: string;
    checkpoint: string;
    tokenCount: number;
    modelRetryCount: number;
    networkRetryCount: number;
    fallbackIndex: number;
    violations: GuardrailViolation[];
    driftDetected: boolean;
    completed: boolean;
    firstTokenAt?: number;
    lastTokenAt?: number;
    duration?: number;
    networkErrors: CategorizedNetworkError[];
    resumed: boolean;
    resumePoint?: string;
    resumeFrom?: number;
    dataOutputs: L0DataPayload[];
    lastProgress?: L0Progress;
    toolCallStartTimes?: Map<string, number>;
    toolCallNames?: Map<string, string>;
}
export interface L0Telemetry {
    sessionId: string;
    startTime: number;
    endTime?: number;
    duration?: number;
    metrics: {
        timeToFirstToken?: number;
        avgInterTokenTime?: number;
        tokensPerSecond?: number;
        totalTokens: number;
        totalRetries: number;
        networkRetryCount: number;
        modelRetryCount: number;
    };
    network: {
        errorCount: number;
        errorsByType: Record<string, number>;
        errors?: Array<{
            type: string;
            message: string;
            timestamp: number;
            retried: boolean;
            delay?: number;
        }>;
    };
    guardrails?: {
        violationCount: number;
        violationsByRule: Record<string, number>;
        violationsByRuleAndSeverity: Record<string, {
            warning: number;
            error: number;
            fatal: number;
        }>;
        violationsBySeverity: {
            warning: number;
            error: number;
            fatal: number;
        };
    };
    drift?: {
        detected: boolean;
        types: string[];
    };
    continuation?: {
        enabled: boolean;
        used: boolean;
        checkpointContent?: string;
        checkpointLength?: number;
        continuationCount?: number;
    };
    metadata?: Record<string, any>;
}
export interface CategorizedNetworkError {
    type: string;
    message: string;
    timestamp: number;
    retried: boolean;
    delay?: number;
    attempt?: number;
}
export interface RetryOptions {
    attempts?: number;
    maxRetries?: number;
    backoff?: BackoffStrategy;
    baseDelay?: number;
    maxDelay?: number;
    retryOn?: RetryReason[];
    errorTypeDelays?: {
        connectionDropped?: number;
        fetchError?: number;
        econnreset?: number;
        econnrefused?: number;
        sseAborted?: number;
        noBytes?: number;
        partialChunks?: number;
        runtimeKilled?: number;
        backgroundThrottle?: number;
        dnsError?: number;
        timeout?: number;
        unknown?: number;
    };
    calculateDelay?: (context: {
        attempt: number;
        totalAttempts: number;
        category: ErrorCategory;
        reason: string;
        error: Error;
        defaultDelay: number;
    }) => number | undefined;
    shouldRetry?: (error: Error, state: L0State, attempt: number, category: ErrorCategory) => Promise<boolean>;
}
export declare const minimalGuardrails: GuardrailRule[];
export declare const recommendedGuardrails: GuardrailRule[];
export declare const strictGuardrails: GuardrailRule[];
export declare const minimalRetry: RetryOptions;
export declare const recommendedRetry: RetryOptions;
export declare const strictRetry: RetryOptions;
export declare const exponentialRetry: RetryOptions;
//# sourceMappingURL=l0.d.ts.map