@omote/core 0.9.1 → 0.9.2

package/dist/ErrorCodes-AX3ADZri.d.mts

@@ -0,0 +1,266 @@
+/**
+ * Logging types for Omote SDK
+ *
+ * 6-level logging system with structured output:
+ * - error: Critical failures that prevent operation
+ * - warn: Recoverable issues or degraded performance
+ * - info: Key lifecycle events (model loaded, inference complete)
+ * - debug: Detailed operational info for development
+ * - trace: Fine-grained tracing for performance analysis
+ * - verbose: Extremely detailed output (tensor shapes, intermediate values)
+ */
+type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'verbose';
+/**
+ * Numeric priority for log levels (lower = more severe)
+ */
+declare const LOG_LEVEL_PRIORITY: Record<LogLevel, number>;
+/**
+ * Structured log entry
+ */
+interface LogEntry {
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Log level */
+    level: LogLevel;
+    /** Module name (e.g., 'LocalInference', 'ModelCache') */
+    module: string;
+    /** Human-readable message */
+    message: string;
+    /** Optional structured error code from ErrorCodes (e.g., 'OMOTE_INF_001') */
+    code?: string;
+    /** Optional structured data */
+    data?: Record<string, unknown>;
+    /** Optional error object */
+    error?: Error;
+    /** Trace ID from active telemetry span (log-to-span correlation) */
+    traceId?: string;
+    /** Span ID from active telemetry span (log-to-span correlation) */
+    spanId?: string;
+}
+/**
+ * Log output sink interface.
+ *
+ * **Portability contract**: Replace the default console sink to route logs to
+ * any backend — Node.js winston/pino, Unreal UE_LOG, Unity Debug.Log, or a
+ * remote telemetry service. Register via `configureLogging({ sink: mySink })`.
+ */
+interface LogSink {
+    (entry: LogEntry): void;
+}
+/**
+ * Log formatter interface
+ */
+interface LogFormatter {
+    (entry: LogEntry): string;
+}
+/**
+ * Global logging configuration
+ */
+interface LoggingConfig {
+    /** Minimum log level to output (default: 'info') */
+    level: LogLevel;
+    /** Enable/disable logging globally (default: true) */
+    enabled: boolean;
+    /** Output format: 'json' for structured, 'pretty' for human-readable */
+    format: 'json' | 'pretty';
+    /** Custom output sink (default: console) */
+    sink?: LogSink;
+    /** Include timestamps in output (default: true) */
+    timestamps?: boolean;
+    /** Include module name in output (default: true) */
+    includeModule?: boolean;
+}
+/**
+ * Logger interface for module-specific logging.
+ *
+ * **Portability contract**: All SDK modules depend only on this interface.
+ * To integrate with a non-browser runtime (Node.js, Unreal, Unity), either:
+ * 1. Use the built-in Logger with a custom `LogSink`, or
+ * 2. Provide your own `ILogger` implementation that bridges to the host
+ *    runtime's logging system (e.g., `console.log`, `UE_LOG`, `Debug.Log`).
+ */
+interface ILogger {
+    error(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    debug(message: string, data?: Record<string, unknown>): void;
+    trace(message: string, data?: Record<string, unknown>): void;
+    verbose(message: string, data?: Record<string, unknown>): void;
+    /** Create a child logger with a sub-module name */
+    child(subModule: string): ILogger;
+    /** Get the module name for this logger */
+    readonly module: string;
+}
+/**
+ * Default configuration
+ */
+declare const DEFAULT_LOGGING_CONFIG: LoggingConfig;
+
+/**
+ * Omote SDK Logger
+ *
+ * Unified logging system with:
+ * - 6 log levels (error, warn, info, debug, trace, verbose)
+ * - Structured JSON output for machine parsing
+ * - Pretty output for human readability
+ * - Module-based child loggers
+ * - Runtime configuration
+ * - Browser and Node.js compatible
+ */
+
+/**
+ * Configure global logging settings
+ */
+declare function configureLogging(config: Partial<LoggingConfig>): void;
+/**
+ * Get current logging configuration
+ */
+declare function getLoggingConfig(): LoggingConfig;
+/**
+ * Reset logging configuration to defaults
+ */
+declare function resetLoggingConfig(): void;
+/**
+ * Set log level at runtime
+ */
+declare function setLogLevel(level: LogLevel): void;
+/**
+ * Enable or disable logging
+ */
+declare function setLoggingEnabled(enabled: boolean): void;
+/**
+ * Create a logger for a specific module
+ *
+ * @param module - Module name (e.g., 'LocalInference', 'ModelCache')
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger('LocalInference');
+ * logger.info('Model loaded', { backend: 'webgpu', loadTimeMs: 1234 });
+ * ```
+ */
+declare function createLogger(module: string): ILogger;
+/**
+ * Clear logger cache (useful for testing)
+ */
+declare function clearLoggerCache(): void;
+/**
+ * No-op logger for when logging is completely disabled
+ */
+declare const noopLogger: ILogger;
+/**
+ * Get a no-op logger (for production builds that tree-shake logging)
+ */
+declare function getNoopLogger(): ILogger;
+
+/**
+ * Abstract monotonic clock for runtime-agnostic timing.
+ *
+ * **Portability contract**: To port the SDK to Node.js, Python, Unreal, or Unity,
+ * implement this interface with your runtime's high-resolution timer and call
+ * `configureClock()` at startup.
+ *
+ * @example Node.js
+ * ```typescript
+ * import { configureClock } from '@omote/core';
+ * configureClock({
+ *   now: () => Number(process.hrtime.bigint() / 1_000_000n),
+ *   timestamp: () => Date.now(),
+ * });
+ * ```
+ *
+ * @example Unreal Engine (via wasm-bindgen)
+ * ```typescript
+ * configureClock({
+ *   now: () => FPlatformTime.Seconds() * 1000,
+ *   timestamp: () => FDateTime.UtcNow().ToUnixTimestamp() * 1000,
+ * });
+ * ```
+ *
+ * @example Unity (via jslib bridge)
+ * ```typescript
+ * configureClock({
+ *   now: () => Time.realtimeSinceStartup * 1000,
+ *   timestamp: () => Date.now(),
+ * });
+ * ```
+ */
+interface Clock {
+    /** Monotonic high-resolution milliseconds (for durations, telemetry spans) */
+    now(): number;
+    /** Wall-clock milliseconds since epoch (for log timestamps) */
+    timestamp(): number;
+}
+declare const defaultClock: Clock;
+/** Replace the default browser clock with a custom implementation. */
+declare function configureClock(clock: Clock): void;
+/** Get the active clock instance. */
+declare function getClock(): Clock;
+
+/**
+ * Structured error codes for the Omote SDK.
+ *
+ * Codes follow the pattern `OMOTE_{CATEGORY}_{SEQ}` where:
+ * - **INF** = Inference (model loading, session, OOM)
+ * - **AUD** = Audio (AudioContext, scheduling, decoding)
+ * - **SPH** = Speech (VAD, ASR, microphone)
+ * - **TTS** = Text-to-Speech (synthesis, streaming, phonemizer)
+ * - **PIP** = Pipeline (state machine, abort)
+ * - **CAC** = Cache (IndexedDB quota, eviction, staleness)
+ * - **NET** = Network (fetch, timeout, WebSocket)
+ *
+ * Exported as a const object (not enum) for tree-shaking.
+ */
+declare const ErrorCodes: {
+    /** Model failed to load (file not found, corrupted, unsupported format) */
+    readonly INF_LOAD_FAILED: "OMOTE_INF_001";
+    /** ORT session poisoned after WebGPU device loss — must reload tab */
+    readonly INF_SESSION_POISON: "OMOTE_INF_002";
+    /** Inference exceeded timeout threshold */
+    readonly INF_TIMEOUT: "OMOTE_INF_003";
+    /** Out-of-memory during inference or model loading */
+    readonly INF_OOM: "OMOTE_INF_004";
+    /** WebGPU unavailable, fell back to WASM */
+    readonly INF_WEBGPU_FALLBACK: "OMOTE_INF_005";
+    /** Input tensor shape does not match model expectations */
+    readonly INF_SHAPE_MISMATCH: "OMOTE_INF_006";
+    /** AudioContext creation or resume failed */
+    readonly AUD_CONTEXT_FAILED: "OMOTE_AUD_001";
+    /** Gap detected in audio scheduling (buffer underrun) */
+    readonly AUD_SCHEDULE_GAP: "OMOTE_AUD_002";
+    /** Audio buffer decoding failed */
+    readonly AUD_DECODE_FAILED: "OMOTE_AUD_003";
+    /** Voice activity detection error */
+    readonly SPH_VAD_ERROR: "OMOTE_SPH_001";
+    /** Automatic speech recognition error */
+    readonly SPH_ASR_ERROR: "OMOTE_SPH_002";
+    /** Microphone access denied or unavailable */
+    readonly SPH_MIC_DENIED: "OMOTE_SPH_003";
+    /** TTS synthesis failed */
+    readonly TTS_SYNTH_FAILED: "OMOTE_TTS_001";
+    /** TTS streaming error (chunk delivery failure) */
+    readonly TTS_STREAM_ERROR: "OMOTE_TTS_002";
+    /** Phonemizer (eSpeak-NG WASM) ran out of memory */
+    readonly TTS_PHONEMIZER_OOM: "OMOTE_TTS_003";
+    /** Invalid state transition in pipeline state machine */
+    readonly PIP_STATE_ERROR: "OMOTE_PIP_001";
+    /** Pipeline operation aborted (user interrupt or signal) */
+    readonly PIP_ABORT: "OMOTE_PIP_002";
+    /** IndexedDB storage quota exceeded */
+    readonly CAC_QUOTA_EXCEEDED: "OMOTE_CAC_001";
+    /** Cache entry evicted (LRU or manual) */
+    readonly CAC_EVICTION: "OMOTE_CAC_002";
+    /** Cached model is stale (version mismatch) */
+    readonly CAC_STALE: "OMOTE_CAC_003";
+    /** HTTP fetch failed (model download, CDN) */
+    readonly NET_FETCH_FAILED: "OMOTE_NET_001";
+    /** Network request timed out */
+    readonly NET_TIMEOUT: "OMOTE_NET_002";
+    /** WebSocket connection error */
+    readonly NET_WEBSOCKET_ERROR: "OMOTE_NET_003";
+};
+/** Union type of all error code string values. */
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+export { type Clock as C, DEFAULT_LOGGING_CONFIG as D, type ErrorCode as E, type ILogger as I, type LogFormatter as L, ErrorCodes as a, LOG_LEVEL_PRIORITY as b, type LogEntry as c, type LogLevel as d, type LogSink as e, type LoggingConfig as f, clearLoggerCache as g, configureClock as h, configureLogging as i, createLogger as j, defaultClock as k, getClock as l, getLoggingConfig as m, getNoopLogger as n, noopLogger as o, setLoggingEnabled as p, resetLoggingConfig as r, setLogLevel as s };

package/dist/ErrorCodes-AX3ADZri.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Logging types for Omote SDK
+ *
+ * 6-level logging system with structured output:
+ * - error: Critical failures that prevent operation
+ * - warn: Recoverable issues or degraded performance
+ * - info: Key lifecycle events (model loaded, inference complete)
+ * - debug: Detailed operational info for development
+ * - trace: Fine-grained tracing for performance analysis
+ * - verbose: Extremely detailed output (tensor shapes, intermediate values)
+ */
+type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'verbose';
+/**
+ * Numeric priority for log levels (lower = more severe)
+ */
+declare const LOG_LEVEL_PRIORITY: Record<LogLevel, number>;
+/**
+ * Structured log entry
+ */
+interface LogEntry {
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Log level */
+    level: LogLevel;
+    /** Module name (e.g., 'LocalInference', 'ModelCache') */
+    module: string;
+    /** Human-readable message */
+    message: string;
+    /** Optional structured error code from ErrorCodes (e.g., 'OMOTE_INF_001') */
+    code?: string;
+    /** Optional structured data */
+    data?: Record<string, unknown>;
+    /** Optional error object */
+    error?: Error;
+    /** Trace ID from active telemetry span (log-to-span correlation) */
+    traceId?: string;
+    /** Span ID from active telemetry span (log-to-span correlation) */
+    spanId?: string;
+}
+/**
+ * Log output sink interface.
+ *
+ * **Portability contract**: Replace the default console sink to route logs to
+ * any backend — Node.js winston/pino, Unreal UE_LOG, Unity Debug.Log, or a
+ * remote telemetry service. Register via `configureLogging({ sink: mySink })`.
+ */
+interface LogSink {
+    (entry: LogEntry): void;
+}
+/**
+ * Log formatter interface
+ */
+interface LogFormatter {
+    (entry: LogEntry): string;
+}
+/**
+ * Global logging configuration
+ */
+interface LoggingConfig {
+    /** Minimum log level to output (default: 'info') */
+    level: LogLevel;
+    /** Enable/disable logging globally (default: true) */
+    enabled: boolean;
+    /** Output format: 'json' for structured, 'pretty' for human-readable */
+    format: 'json' | 'pretty';
+    /** Custom output sink (default: console) */
+    sink?: LogSink;
+    /** Include timestamps in output (default: true) */
+    timestamps?: boolean;
+    /** Include module name in output (default: true) */
+    includeModule?: boolean;
+}
+/**
+ * Logger interface for module-specific logging.
+ *
+ * **Portability contract**: All SDK modules depend only on this interface.
+ * To integrate with a non-browser runtime (Node.js, Unreal, Unity), either:
+ * 1. Use the built-in Logger with a custom `LogSink`, or
+ * 2. Provide your own `ILogger` implementation that bridges to the host
+ *    runtime's logging system (e.g., `console.log`, `UE_LOG`, `Debug.Log`).
+ */
+interface ILogger {
+    error(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    debug(message: string, data?: Record<string, unknown>): void;
+    trace(message: string, data?: Record<string, unknown>): void;
+    verbose(message: string, data?: Record<string, unknown>): void;
+    /** Create a child logger with a sub-module name */
+    child(subModule: string): ILogger;
+    /** Get the module name for this logger */
+    readonly module: string;
+}
+/**
+ * Default configuration
+ */
+declare const DEFAULT_LOGGING_CONFIG: LoggingConfig;
+
+/**
+ * Omote SDK Logger
+ *
+ * Unified logging system with:
+ * - 6 log levels (error, warn, info, debug, trace, verbose)
+ * - Structured JSON output for machine parsing
+ * - Pretty output for human readability
+ * - Module-based child loggers
+ * - Runtime configuration
+ * - Browser and Node.js compatible
+ */
+
+/**
+ * Configure global logging settings
+ */
+declare function configureLogging(config: Partial<LoggingConfig>): void;
+/**
+ * Get current logging configuration
+ */
+declare function getLoggingConfig(): LoggingConfig;
+/**
+ * Reset logging configuration to defaults
+ */
+declare function resetLoggingConfig(): void;
+/**
+ * Set log level at runtime
+ */
+declare function setLogLevel(level: LogLevel): void;
+/**
+ * Enable or disable logging
+ */
+declare function setLoggingEnabled(enabled: boolean): void;
+/**
+ * Create a logger for a specific module
+ *
+ * @param module - Module name (e.g., 'LocalInference', 'ModelCache')
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger('LocalInference');
+ * logger.info('Model loaded', { backend: 'webgpu', loadTimeMs: 1234 });
+ * ```
+ */
+declare function createLogger(module: string): ILogger;
+/**
+ * Clear logger cache (useful for testing)
+ */
+declare function clearLoggerCache(): void;
+/**
+ * No-op logger for when logging is completely disabled
+ */
+declare const noopLogger: ILogger;
+/**
+ * Get a no-op logger (for production builds that tree-shake logging)
+ */
+declare function getNoopLogger(): ILogger;
+
+/**
+ * Abstract monotonic clock for runtime-agnostic timing.
+ *
+ * **Portability contract**: To port the SDK to Node.js, Python, Unreal, or Unity,
+ * implement this interface with your runtime's high-resolution timer and call
+ * `configureClock()` at startup.
+ *
+ * @example Node.js
+ * ```typescript
+ * import { configureClock } from '@omote/core';
+ * configureClock({
+ *   now: () => Number(process.hrtime.bigint() / 1_000_000n),
+ *   timestamp: () => Date.now(),
+ * });
+ * ```
+ *
+ * @example Unreal Engine (via wasm-bindgen)
+ * ```typescript
+ * configureClock({
+ *   now: () => FPlatformTime.Seconds() * 1000,
+ *   timestamp: () => FDateTime.UtcNow().ToUnixTimestamp() * 1000,
+ * });
+ * ```
+ *
+ * @example Unity (via jslib bridge)
+ * ```typescript
+ * configureClock({
+ *   now: () => Time.realtimeSinceStartup * 1000,
+ *   timestamp: () => Date.now(),
+ * });
+ * ```
+ */
+interface Clock {
+    /** Monotonic high-resolution milliseconds (for durations, telemetry spans) */
+    now(): number;
+    /** Wall-clock milliseconds since epoch (for log timestamps) */
+    timestamp(): number;
+}
+declare const defaultClock: Clock;
+/** Replace the default browser clock with a custom implementation. */
+declare function configureClock(clock: Clock): void;
+/** Get the active clock instance. */
+declare function getClock(): Clock;
+
+/**
+ * Structured error codes for the Omote SDK.
+ *
+ * Codes follow the pattern `OMOTE_{CATEGORY}_{SEQ}` where:
+ * - **INF** = Inference (model loading, session, OOM)
+ * - **AUD** = Audio (AudioContext, scheduling, decoding)
+ * - **SPH** = Speech (VAD, ASR, microphone)
+ * - **TTS** = Text-to-Speech (synthesis, streaming, phonemizer)
+ * - **PIP** = Pipeline (state machine, abort)
+ * - **CAC** = Cache (IndexedDB quota, eviction, staleness)
+ * - **NET** = Network (fetch, timeout, WebSocket)
+ *
+ * Exported as a const object (not enum) for tree-shaking.
+ */
+declare const ErrorCodes: {
+    /** Model failed to load (file not found, corrupted, unsupported format) */
+    readonly INF_LOAD_FAILED: "OMOTE_INF_001";
+    /** ORT session poisoned after WebGPU device loss — must reload tab */
+    readonly INF_SESSION_POISON: "OMOTE_INF_002";
+    /** Inference exceeded timeout threshold */
+    readonly INF_TIMEOUT: "OMOTE_INF_003";
+    /** Out-of-memory during inference or model loading */
+    readonly INF_OOM: "OMOTE_INF_004";
+    /** WebGPU unavailable, fell back to WASM */
+    readonly INF_WEBGPU_FALLBACK: "OMOTE_INF_005";
+    /** Input tensor shape does not match model expectations */
+    readonly INF_SHAPE_MISMATCH: "OMOTE_INF_006";
+    /** AudioContext creation or resume failed */
+    readonly AUD_CONTEXT_FAILED: "OMOTE_AUD_001";
+    /** Gap detected in audio scheduling (buffer underrun) */
+    readonly AUD_SCHEDULE_GAP: "OMOTE_AUD_002";
+    /** Audio buffer decoding failed */
+    readonly AUD_DECODE_FAILED: "OMOTE_AUD_003";
+    /** Voice activity detection error */
+    readonly SPH_VAD_ERROR: "OMOTE_SPH_001";
+    /** Automatic speech recognition error */
+    readonly SPH_ASR_ERROR: "OMOTE_SPH_002";
+    /** Microphone access denied or unavailable */
+    readonly SPH_MIC_DENIED: "OMOTE_SPH_003";
+    /** TTS synthesis failed */
+    readonly TTS_SYNTH_FAILED: "OMOTE_TTS_001";
+    /** TTS streaming error (chunk delivery failure) */
+    readonly TTS_STREAM_ERROR: "OMOTE_TTS_002";
+    /** Phonemizer (eSpeak-NG WASM) ran out of memory */
+    readonly TTS_PHONEMIZER_OOM: "OMOTE_TTS_003";
+    /** Invalid state transition in pipeline state machine */
+    readonly PIP_STATE_ERROR: "OMOTE_PIP_001";
+    /** Pipeline operation aborted (user interrupt or signal) */
+    readonly PIP_ABORT: "OMOTE_PIP_002";
+    /** IndexedDB storage quota exceeded */
+    readonly CAC_QUOTA_EXCEEDED: "OMOTE_CAC_001";
+    /** Cache entry evicted (LRU or manual) */
+    readonly CAC_EVICTION: "OMOTE_CAC_002";
+    /** Cached model is stale (version mismatch) */
+    readonly CAC_STALE: "OMOTE_CAC_003";
+    /** HTTP fetch failed (model download, CDN) */
+    readonly NET_FETCH_FAILED: "OMOTE_NET_001";
+    /** Network request timed out */
+    readonly NET_TIMEOUT: "OMOTE_NET_002";
+    /** WebSocket connection error */
+    readonly NET_WEBSOCKET_ERROR: "OMOTE_NET_003";
+};
+/** Union type of all error code string values. */
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+export { type Clock as C, DEFAULT_LOGGING_CONFIG as D, type ErrorCode as E, type ILogger as I, type LogFormatter as L, ErrorCodes as a, LOG_LEVEL_PRIORITY as b, type LogEntry as c, type LogLevel as d, type LogSink as e, type LoggingConfig as f, clearLoggerCache as g, configureClock as h, configureLogging as i, createLogger as j, defaultClock as k, getClock as l, getLoggingConfig as m, getNoopLogger as n, noopLogger as o, setLoggingEnabled as p, resetLoggingConfig as r, setLogLevel as s };