@digilogiclabs/platform-core 1.13.0 → 1.15.0

package/dist/IAI-D8wA_i8N.d.ts

@@ -0,0 +1,718 @@
+/**
+ * Cache abstraction interface
+ * Provides a vendor-agnostic way to interact with key-value caches
+ */
+interface ICacheOptions {
+    /** Time to live in seconds */
+    ttl?: number;
+    /** Cache key prefix */
+    prefix?: string;
+}
+interface ICache {
+    /**
+     * Get a value from cache
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Set a value in cache
+     */
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Delete a value from cache
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if key exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Delete all keys matching pattern
+     */
+    deletePattern(pattern: string): Promise<number>;
+    /**
+     * Get multiple values
+     */
+    mget<T = unknown>(keys: string[]): Promise<(T | null)[]>;
+    /**
+     * Set multiple values
+     */
+    mset<T = unknown>(entries: Array<{
+        key: string;
+        value: T;
+        ttl?: number;
+    }>): Promise<void>;
+    /**
+     * Increment a numeric value
+     */
+    incr(key: string, by?: number): Promise<number>;
+    /**
+     * Publish a message to a channel
+     */
+    publish(channel: string, message: string): Promise<void>;
+    /**
+     * Subscribe to a channel
+     */
+    subscribe(channel: string, callback: (message: string) => void): Promise<() => void>;
+    /**
+     * Check cache connectivity
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Close cache connection
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Logger Interface
+ * Standardizes logging across the platform
+ */
+/**
+ * Log levels in order of severity
+ */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Metadata that can be attached to log entries
+ */
+interface LogMeta {
+    /** Error object if logging an error */
+    error?: Error;
+    /** Duration in milliseconds (for timing operations) */
+    duration?: number;
+    /** Request ID for tracing */
+    requestId?: string;
+    /** User ID if applicable */
+    userId?: string;
+    /** Any additional key-value pairs */
+    [key: string]: unknown;
+}
+/**
+ * A structured log entry
+ */
+interface LogEntry {
+    /** Log level */
+    level: LogLevel;
+    /** Log message */
+    message: string;
+    /** When the log was created */
+    timestamp: Date;
+    /** Optional metadata */
+    meta?: LogMeta;
+    /** Logger context (e.g., service name) */
+    context?: Record<string, unknown>;
+}
+/**
+ * Logger interface for structured logging
+ */
+interface ILogger {
+    /**
+     * Log a debug message (for development/troubleshooting)
+     */
+    debug(message: string, meta?: LogMeta): void;
+    /**
+     * Log an informational message
+     */
+    info(message: string, meta?: LogMeta): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, meta?: LogMeta): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, meta?: LogMeta): void;
+    /**
+     * Create a child logger with additional context
+     * @param context Additional context to include in all logs from this child
+     */
+    child(context: Record<string, unknown>): ILogger;
+}
+/**
+ * Configuration options for loggers
+ */
+interface LoggerConfig {
+    /** Minimum level to log */
+    level?: LogLevel;
+    /** Whether to pretty print (for development) */
+    pretty?: boolean;
+    /** Service name to include in logs */
+    service?: string;
+    /** Environment name */
+    environment?: string;
+}
+/**
+ * Console logger implementation (for development)
+ */
+declare class ConsoleLogger implements ILogger {
+    private context;
+    private level;
+    private static levelPriority;
+    constructor(config?: LoggerConfig);
+    private shouldLog;
+    private log;
+    debug(message: string, meta?: LogMeta): void;
+    info(message: string, meta?: LogMeta): void;
+    warn(message: string, meta?: LogMeta): void;
+    error(message: string, meta?: LogMeta): void;
+    child(context: Record<string, unknown>): ILogger;
+}
+/**
+ * No-op logger for testing or when logging is disabled
+ */
+declare class NoopLogger implements ILogger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+    child(): ILogger;
+}
+
+/**
+ * Distributed Tracing Interface
+ *
+ * Provides vendor-agnostic distributed tracing for observability.
+ * Supports OpenTelemetry, Jaeger, Zipkin, and custom implementations.
+ */
+type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
+type SpanStatusCode = "unset" | "ok" | "error";
+interface SpanStatus {
+    code: SpanStatusCode;
+    message?: string;
+}
+interface SpanContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+    traceState?: string;
+}
+interface SpanOptions {
+    /** Type of span */
+    kind?: SpanKind;
+    /** Initial attributes */
+    attributes?: Record<string, string | number | boolean>;
+    /** Parent span (for manual context propagation) */
+    parent?: ISpan;
+    /** Links to other spans */
+    links?: SpanContext[];
+    /** Start time (defaults to now) */
+    startTime?: number;
+}
+interface SpanEvent {
+    name: string;
+    timestamp: number;
+    attributes?: Record<string, string | number | boolean>;
+}
+interface ISpan {
+    /** Span name */
+    readonly name: string;
+    /** Span context (trace ID, span ID) */
+    readonly context: SpanContext;
+    /** Whether the span is recording */
+    readonly isRecording: boolean;
+    /**
+     * Set a single attribute
+     */
+    setAttribute(key: string, value: string | number | boolean): this;
+    /**
+     * Set multiple attributes
+     */
+    setAttributes(attributes: Record<string, string | number | boolean>): this;
+    /**
+     * Add an event to the span
+     */
+    addEvent(name: string, attributes?: Record<string, string | number | boolean>): this;
+    /**
+     * Set the span status
+     */
+    setStatus(status: SpanStatus): this;
+    /**
+     * Record an exception
+     */
+    recordException(exception: Error, attributes?: Record<string, string | number | boolean>): this;
+    /**
+     * Update the span name
+     */
+    updateName(name: string): this;
+    /**
+     * End the span (required to export)
+     */
+    end(endTime?: number): void;
+}
+interface ITracing {
+    /**
+     * Create and start a new span
+     */
+    startSpan(name: string, options?: SpanOptions): ISpan;
+    /**
+     * Get the currently active span
+     */
+    getCurrentSpan(): ISpan | undefined;
+    /**
+     * Execute a function within a span context
+     */
+    withSpan<T>(name: string, fn: (span: ISpan) => T, options?: SpanOptions): T;
+    /**
+     * Execute an async function within a span context
+     */
+    withSpanAsync<T>(name: string, fn: (span: ISpan) => Promise<T>, options?: SpanOptions): Promise<T>;
+    /**
+     * Instrument a function with automatic span creation
+     */
+    instrument<TArgs extends unknown[], TReturn>(name: string, fn: (...args: TArgs) => TReturn, options?: SpanOptions): (...args: TArgs) => TReturn;
+    /**
+     * Instrument an async function with automatic span creation
+     */
+    instrumentAsync<TArgs extends unknown[], TReturn>(name: string, fn: (...args: TArgs) => Promise<TReturn>, options?: SpanOptions): (...args: TArgs) => Promise<TReturn>;
+    /**
+     * Extract trace context from headers (for incoming requests)
+     */
+    extractContext(headers: Record<string, string | string[] | undefined>): SpanContext | undefined;
+    /**
+     * Inject trace context into headers (for outgoing requests)
+     */
+    injectContext(headers: Record<string, string>): void;
+    /**
+     * Check if tracing is enabled and healthy
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Flush pending spans to the exporter
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown the tracer
+     */
+    close(): Promise<void>;
+}
+interface TracingConfig {
+    /** Enable tracing */
+    enabled: boolean;
+    /** Service name for traces */
+    serviceName: string;
+    /** Service version */
+    serviceVersion?: string;
+    /** Environment (dev, staging, production) */
+    environment?: string;
+    /** Sampling rate (0.0 to 1.0) */
+    sampleRate?: number;
+    /** Exporter type */
+    exporter?: "console" | "otlp" | "jaeger" | "zipkin" | "none";
+    /** Exporter endpoint */
+    endpoint?: string;
+    /** Additional resource attributes */
+    resourceAttributes?: Record<string, string>;
+    /** Propagation format */
+    propagation?: "w3c" | "b3" | "jaeger";
+}
+declare class MemorySpan implements ISpan {
+    readonly name: string;
+    readonly context: SpanContext;
+    readonly isRecording: boolean;
+    private _attributes;
+    private _events;
+    private _status;
+    private _endTime?;
+    private _startTime;
+    constructor(name: string, traceId: string, parentSpanId?: string);
+    private generateSpanId;
+    setAttribute(key: string, value: string | number | boolean): this;
+    setAttributes(attributes: Record<string, string | number | boolean>): this;
+    addEvent(name: string, attributes?: Record<string, string | number | boolean>): this;
+    setStatus(status: SpanStatus): this;
+    recordException(exception: Error, attributes?: Record<string, string | number | boolean>): this;
+    updateName(name: string): this;
+    end(endTime?: number): void;
+    getAttributes(): Record<string, string | number | boolean>;
+    getEvents(): SpanEvent[];
+    getStatus(): SpanStatus;
+    getDuration(): number | undefined;
+    isEnded(): boolean;
+}
+declare class MemoryTracing implements ITracing {
+    private spans;
+    private currentSpan;
+    private traceId;
+    constructor();
+    private generateTraceId;
+    startSpan(name: string, options?: SpanOptions): ISpan;
+    getCurrentSpan(): ISpan | undefined;
+    withSpan<T>(name: string, fn: (span: ISpan) => T, options?: SpanOptions): T;
+    withSpanAsync<T>(name: string, fn: (span: ISpan) => Promise<T>, options?: SpanOptions): Promise<T>;
+    instrument<TArgs extends unknown[], TReturn>(name: string, fn: (...args: TArgs) => TReturn, options?: SpanOptions): (...args: TArgs) => TReturn;
+    instrumentAsync<TArgs extends unknown[], TReturn>(name: string, fn: (...args: TArgs) => Promise<TReturn>, options?: SpanOptions): (...args: TArgs) => Promise<TReturn>;
+    extractContext(headers: Record<string, string | string[] | undefined>): SpanContext | undefined;
+    injectContext(headers: Record<string, string>): void;
+    healthCheck(): Promise<boolean>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    getSpans(): MemorySpan[];
+    getCompletedSpans(): MemorySpan[];
+    clear(): void;
+}
+declare class NoopTracing implements ITracing {
+    private noopSpan;
+    startSpan(): ISpan;
+    getCurrentSpan(): ISpan | undefined;
+    withSpan<T>(_name: string, fn: (span: ISpan) => T): T;
+    withSpanAsync<T>(_name: string, fn: (span: ISpan) => Promise<T>): Promise<T>;
+    instrument<TArgs extends unknown[], TReturn>(_name: string, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+    instrumentAsync<TArgs extends unknown[], TReturn>(_name: string, fn: (...args: TArgs) => Promise<TReturn>): (...args: TArgs) => Promise<TReturn>;
+    extractContext(): SpanContext | undefined;
+    injectContext(): void;
+    healthCheck(): Promise<boolean>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * IAI - Core AI abstraction interface for platform-core
+ *
+ * Provides a vendor-agnostic interface for AI operations including:
+ * - Text generation (chat, completion)
+ * - Embeddings generation
+ * - Model routing and fallback
+ * - Streaming support
+ * - Token usage tracking
+ */
+type AIProvider = "openai" | "anthropic" | "google" | "azure" | "bedrock" | "custom";
+type AIModelType = "chat" | "completion" | "embedding" | "image" | "audio" | "video";
+type AIRole = "system" | "user" | "assistant" | "function" | "tool";
+interface AIMessage {
+    role: AIRole;
+    content: string;
+    name?: string;
+    toolCallId?: string;
+    toolCalls?: AIToolCall[];
+}
+interface AIToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface AITool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+interface AIModelConfig {
+    /** Model identifier (e.g., 'gpt-4', 'claude-3-opus') */
+    modelId: string;
+    /** Provider for this model */
+    provider: AIProvider;
+    /** Model capabilities */
+    capabilities: AIModelType[];
+    /** Maximum context window in tokens */
+    maxContextTokens: number;
+    /** Maximum output tokens */
+    maxOutputTokens: number;
+    /** Cost per 1K input tokens in USD */
+    inputCostPer1K: number;
+    /** Cost per 1K output tokens in USD */
+    outputCostPer1K: number;
+    /** Supports streaming */
+    supportsStreaming: boolean;
+    /** Supports function/tool calling */
+    supportsTools: boolean;
+    /** Supports vision (image input) */
+    supportsVision: boolean;
+    /** Rate limits per minute */
+    rateLimits?: {
+        requestsPerMinute: number;
+        tokensPerMinute: number;
+    };
+    /** Custom endpoint for self-hosted models */
+    endpoint?: string;
+    /** Additional provider-specific config */
+    providerConfig?: Record<string, unknown>;
+}
+interface AIChatRequest {
+    messages: AIMessage[];
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    stop?: string | string[];
+    tools?: AITool[];
+    toolChoice?: "auto" | "none" | "required" | {
+        type: "function";
+        function: {
+            name: string;
+        };
+    };
+    stream?: boolean;
+    user?: string;
+    metadata?: Record<string, unknown>;
+}
+interface AICompletionRequest {
+    prompt: string;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    stop?: string | string[];
+    stream?: boolean;
+    user?: string;
+    metadata?: Record<string, unknown>;
+}
+interface AIEmbeddingRequest {
+    input: string | string[];
+    model?: string;
+    dimensions?: number;
+    user?: string;
+    metadata?: Record<string, unknown>;
+}
+interface AIChatResponse {
+    id: string;
+    model: string;
+    provider: AIProvider;
+    choices: AIChatChoice[];
+    usage: AIUsageInfo;
+    created: Date;
+    finishReason: AIFinishReason;
+}
+interface AIChatChoice {
+    index: number;
+    message: AIMessage;
+    finishReason: AIFinishReason;
+}
+type AIFinishReason = "stop" | "length" | "tool_calls" | "content_filter" | "error";
+interface AICompletionResponse {
+    id: string;
+    model: string;
+    provider: AIProvider;
+    text: string;
+    usage: AIUsageInfo;
+    created: Date;
+    finishReason: AIFinishReason;
+}
+interface AIEmbeddingResponse {
+    id: string;
+    model: string;
+    provider: AIProvider;
+    embeddings: number[][];
+    usage: AIUsageInfo;
+    created: Date;
+}
+interface AIUsageInfo {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    estimatedCostUsd: number;
+}
+interface AIStreamChunk {
+    id: string;
+    model: string;
+    provider: AIProvider;
+    delta: {
+        content?: string;
+        toolCalls?: AIToolCall[];
+        role?: AIRole;
+    };
+    finishReason?: AIFinishReason;
+    usage?: AIUsageInfo;
+}
+type AIStreamCallback = (chunk: AIStreamChunk) => void | Promise<void>;
+type RoutingStrategy = "priority" | "round-robin" | "least-latency" | "cost-optimized" | "random";
+interface AIRouterConfig {
+    /** Primary model to use */
+    primaryModel: string;
+    /** Fallback models in order of preference */
+    fallbackModels?: string[];
+    /** Routing strategy for load balancing */
+    strategy?: RoutingStrategy;
+    /** Maximum retries before failing */
+    maxRetries?: number;
+    /** Timeout in milliseconds */
+    timeoutMs?: number;
+    /** Enable automatic fallback on errors */
+    autoFallback?: boolean;
+    /** Cost budget per request in USD (for cost-optimized routing) */
+    costBudget?: number;
+    /** Custom routing function */
+    customRouter?: (request: AIChatRequest | AICompletionRequest) => string;
+}
+type AIErrorCode = "invalid_request" | "authentication_error" | "rate_limit_exceeded" | "quota_exceeded" | "model_not_found" | "context_length_exceeded" | "content_filter" | "server_error" | "timeout" | "network_error" | "provider_unavailable" | "unknown";
+interface AIError extends Error {
+    code: AIErrorCode;
+    provider?: AIProvider;
+    model?: string;
+    statusCode?: number;
+    retryable: boolean;
+    retryAfterMs?: number;
+}
+declare const AIErrorMessages: Record<AIErrorCode, string>;
+declare function createAIError(code: AIErrorCode, message?: string, options?: {
+    provider?: AIProvider;
+    model?: string;
+    statusCode?: number;
+    retryable?: boolean;
+    retryAfterMs?: number;
+    cause?: Error;
+}): AIError;
+declare function isAIError(error: unknown): error is AIError;
+interface AIConfig {
+    /** Default model for chat requests */
+    defaultChatModel?: string;
+    /** Default model for completion requests */
+    defaultCompletionModel?: string;
+    /** Default model for embedding requests */
+    defaultEmbeddingModel?: string;
+    /** Router configuration */
+    router?: AIRouterConfig;
+    /** Available model configurations */
+    models?: AIModelConfig[];
+    /** API keys for providers */
+    apiKeys?: Partial<Record<AIProvider, string>>;
+    /** Default timeout in milliseconds */
+    defaultTimeoutMs?: number;
+    /** Enable request/response logging */
+    enableLogging?: boolean;
+    /** Cache embeddings */
+    cacheEmbeddings?: boolean;
+    /** Embedding cache TTL in seconds */
+    embeddingCacheTtlSeconds?: number;
+}
+/**
+ * IAI - Core AI interface
+ *
+ * @example
+ * ```typescript
+ * const ai = platform.ai;
+ *
+ * // Chat completion
+ * const response = await ai.chat({
+ *   messages: [
+ *     { role: 'system', content: 'You are a helpful assistant.' },
+ *     { role: 'user', content: 'Hello!' }
+ *   ]
+ * });
+ *
+ * // Streaming chat
+ * for await (const chunk of ai.chatStream({
+ *   messages: [{ role: 'user', content: 'Tell me a story' }]
+ * })) {
+ *   process.stdout.write(chunk.delta.content || '');
+ * }
+ *
+ * // Embeddings
+ * const embeddings = await ai.embed({
+ *   input: ['Hello world', 'Goodbye world']
+ * });
+ * ```
+ */
+interface IAI {
+    /**
+     * Send a chat completion request
+     */
+    chat(request: AIChatRequest): Promise<AIChatResponse>;
+    /**
+     * Send a streaming chat completion request
+     */
+    chatStream(request: AIChatRequest): AsyncIterable<AIStreamChunk>;
+    /**
+     * Send a chat completion request with callback-based streaming
+     */
+    chatWithCallback(request: AIChatRequest, callback: AIStreamCallback): Promise<AIChatResponse>;
+    /**
+     * Send a text completion request
+     */
+    complete(request: AICompletionRequest): Promise<AICompletionResponse>;
+    /**
+     * Send a streaming completion request
+     */
+    completeStream(request: AICompletionRequest): AsyncIterable<AIStreamChunk>;
+    /**
+     * Generate embeddings for text
+     */
+    embed(request: AIEmbeddingRequest): Promise<AIEmbeddingResponse>;
+    /**
+     * Calculate similarity between two texts
+     */
+    similarity(text1: string, text2: string, model?: string): Promise<number>;
+    /**
+     * List available models
+     */
+    listModels(): Promise<AIModelConfig[]>;
+    /**
+     * Get model configuration
+     */
+    getModel(modelId: string): Promise<AIModelConfig | null>;
+    /**
+     * Check if a model supports a capability
+     */
+    supportsCapability(modelId: string, capability: AIModelType): Promise<boolean>;
+    /**
+     * Estimate tokens for text
+     */
+    estimateTokens(text: string, model?: string): Promise<number>;
+    /**
+     * Estimate cost for a request
+     */
+    estimateCost(request: AIChatRequest | AICompletionRequest | AIEmbeddingRequest): Promise<number>;
+    /**
+     * Check if AI service is healthy
+     */
+    healthCheck(): Promise<{
+        healthy: boolean;
+        providers: Record<AIProvider, {
+            available: boolean;
+            latencyMs?: number;
+            error?: string;
+        }>;
+    }>;
+}
+/**
+ * MemoryAI - In-memory implementation for testing
+ */
+declare class MemoryAI implements IAI {
+    private config;
+    private models;
+    private responses;
+    private embeddings;
+    private requestLog;
+    constructor(config?: AIConfig);
+    setResponse(key: string, response: AIChatResponse | AICompletionResponse): void;
+    setEmbedding(text: string, embedding: number[]): void;
+    getRequestLog(): Array<{
+        type: string;
+        request: unknown;
+        timestamp: Date;
+    }>;
+    clearRequestLog(): void;
+    chat(request: AIChatRequest): Promise<AIChatResponse>;
+    chatStream(request: AIChatRequest): AsyncIterable<AIStreamChunk>;
+    chatWithCallback(request: AIChatRequest, callback: AIStreamCallback): Promise<AIChatResponse>;
+    complete(request: AICompletionRequest): Promise<AICompletionResponse>;
+    completeStream(request: AICompletionRequest): AsyncIterable<AIStreamChunk>;
+    embed(request: AIEmbeddingRequest): Promise<AIEmbeddingResponse>;
+    similarity(text1: string, text2: string, model?: string): Promise<number>;
+    listModels(): Promise<AIModelConfig[]>;
+    getModel(modelId: string): Promise<AIModelConfig | null>;
+    supportsCapability(modelId: string, capability: AIModelType): Promise<boolean>;
+    estimateTokens(text: string, _model?: string): Promise<number>;
+    estimateCost(request: AIChatRequest | AICompletionRequest | AIEmbeddingRequest): Promise<number>;
+    healthCheck(): Promise<{
+        healthy: boolean;
+        providers: Record<AIProvider, {
+            available: boolean;
+            latencyMs?: number;
+            error?: string;
+        }>;
+    }>;
+    private estimateTokensSync;
+    private calculateCost;
+    private generateMockEmbedding;
+    private cosineSimilarity;
+}
+
+export { type AIConfig as A, type AIFinishReason as B, ConsoleLogger as C, type AIUsageInfo as D, type AIRouterConfig as E, type AIErrorCode as F, type AIError as G, MemoryTracing as H, type ICache as I, NoopTracing as J, type ISpan as K, type LogLevel as L, MemoryAI as M, NoopLogger as N, type SpanOptions as O, type SpanStatus as P, type SpanKind as Q, type RoutingStrategy as R, type SpanContext as S, type TracingConfig as T, type SpanStatusCode as U, type SpanEvent as V, type ILogger as a, type ITracing as b, type IAI as c, type AIChatRequest as d, type AIChatResponse as e, type AIStreamChunk as f, type AIStreamCallback as g, type AICompletionRequest as h, type AICompletionResponse as i, type AIEmbeddingRequest as j, type AIEmbeddingResponse as k, type AIModelConfig as l, type AIModelType as m, type AIProvider as n, type ICacheOptions as o, type LogMeta as p, type LogEntry as q, type LoggerConfig as r, createAIError as s, isAIError as t, AIErrorMessages as u, type AIRole as v, type AIMessage as w, type AIToolCall as x, type AITool as y, type AIChatChoice as z };