monora-ai 2.0.0 → 2.1.3

package/dist/sinks/https.js

@@ -52,6 +52,7 @@ const circuit_breaker_1 = require("../circuit_breaker");
 const verify_1 = require("../verify");
 const telemetry_1 = require("../telemetry");
 const logger_1 = require("../logger");
+const dataResidency_1 = require("../dataResidency");
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -73,6 +74,7 @@ class HttpRetryQueue {
         const filepath = path.join(this.queueDir, filename);
         const payload = {
             created_at: new Date().toISOString(),
+            attempts: 0,
             events,
         };
         fs.writeFileSync(filepath, JSON.stringify(payload));
@@ -103,8 +105,9 @@ class HttpRetryQueue {
                 try {
                     await sendFunc(events);
                 }
-                catch {
-                    return;
+                catch (error) {
+                    this.handleSendFailure(filepath, payload, error);
+                    continue;
                 }
                 this.removeFile(filepath);
             }
@@ -119,7 +122,9 @@ class HttpRetryQueue {
         try {
             entries = fs
                 .readdirSync(this.queueDir)
-                .filter((entry) => entry.endsWith('.json') && entry !== HttpRetryQueue.STATS_FILENAME);
+                .filter((entry) => entry.endsWith('.json') &&
+                entry !== HttpRetryQueue.STATS_FILENAME &&
+                !entry.endsWith(HttpRetryQueue.DEAD_LETTER_SUFFIX));
         }
         catch {
             return [];
@@ -135,12 +140,58 @@ class HttpRetryQueue {
             // Best-effort cleanup
         }
     }
+    handleSendFailure(filepath, payload, error) {
+        const attempts = this.getAttempts(payload);
+        const nextAttempts = attempts + 1;
+        payload.attempts = nextAttempts;
+        payload.updated_at = new Date().toISOString();
+        logger_1.logger.warning('HTTP retry queue send failed: %s', error);
+        if (nextAttempts >= HttpRetryQueue.MAX_ATTEMPTS) {
+            logger_1.logger.warning('HTTP retry queue max attempts reached (%d); moving batch to dead letter.', nextAttempts);
+            this.moveToDeadLetter(filepath, payload);
+            return;
+        }
+        this.requeueFile(filepath, payload);
+    }
+    getAttempts(payload) {
+        const attempts = Number(payload.attempts);
+        return Number.isFinite(attempts) && attempts >= 0 ? attempts : 0;
+    }
+    requeueFile(filepath, payload) {
+        const tmpPath = `${filepath}.tmp`;
+        try {
+            fs.writeFileSync(tmpPath, JSON.stringify(payload));
+            fs.renameSync(tmpPath, filepath);
+        }
+        catch (error) {
+            logger_1.logger.warning('Failed to requeue HTTP retry batch: %s', error);
+            try {
+                if (fs.existsSync(tmpPath)) {
+                    fs.unlinkSync(tmpPath);
+                }
+            }
+            catch {
+                return;
+            }
+        }
+    }
+    moveToDeadLetter(filepath, payload) {
+        const baseName = this.nextFilename().replace(/\.json$/, '');
+        const deadPath = path.join(this.queueDir, `${baseName}${HttpRetryQueue.DEAD_LETTER_SUFFIX}`);
+        try {
+            fs.writeFileSync(deadPath, JSON.stringify(payload));
+            this.removeFile(filepath);
+        }
+        catch (error) {
+            logger_1.logger.warning('Failed to move HTTP retry batch to dead letter: %s', error);
+        }
+    }
     pruneIfNeeded() {
         if (this.maxItems <= 0) {
             return;
         }
         const files = this.listFiles();
-        if (files.length < this.maxItems) {
+        if (files.length <= this.maxItems - 1) {
             return;
         }
         const excess = files.length - this.maxItems + 1;
@@ -233,8 +284,18 @@ class HttpRetryQueue {
     }
 }
 HttpRetryQueue.STATS_FILENAME = '.monora_retry_queue_stats.json';
+HttpRetryQueue.DEAD_LETTER_SUFFIX = '.dead.json';
+HttpRetryQueue.MAX_ATTEMPTS = 5;
 class HttpSink {
     constructor(endpoint, headers, options) {
+        // Enforce data residency before accepting the endpoint
+        const residencyConfig = options?.dataResidency || {};
+        if (residencyConfig.residency) {
+            this.dataResidencyResult = (0, dataResidency_1.enforceDataResidency)(endpoint, residencyConfig.residency, residencyConfig.action || 'warn');
+        }
+        else {
+            this.dataResidencyResult = null;
+        }
         this.endpoint = endpoint;
         this.headers = headers;
         this.batchSize = options?.batchSize || 50;
@@ -243,8 +304,13 @@ class HttpSink {
         this.backoffBaseSec = options?.backoffBaseSec || 0.5;
         this.buffer = [];
         this.retryIntervalMs = 5000;
-        this.idempotencyEnabled = true;
-        this.idempotencyHeader = 'Idempotency-Key';
+        const idempotencyConfig = options?.idempotency;
+        this.idempotencyEnabled = idempotencyConfig?.enabled ?? true;
+        const headerValue = idempotencyConfig?.header ?? idempotencyConfig?.headerName;
+        this.idempotencyHeader =
+            headerValue && headerValue.trim().length > 0
+                ? headerValue.trim()
+                : 'Idempotency-Key';
         this.flushing = false;
         // Initialize circuit breaker
         const cbConfig = options?.circuitBreaker || {};
@@ -273,14 +339,6 @@ class HttpSink {
                 this.retryTimer.unref();
             }
         }
-        const idempotencyConfig = options?.idempotency || {};
-        if (idempotencyConfig.enabled === false) {
-            this.idempotencyEnabled = false;
-        }
-        const headerName = idempotencyConfig.headerName;
-        if (headerName && headerName.trim().length > 0) {
-            this.idempotencyHeader = headerName.trim();
-        }
     }
     emit(events) {
         this.buffer.push(...events);
@@ -306,8 +364,10 @@ class HttpSink {
         try {
             await this.drainRetryQueue();
             while (this.buffer.length > 0) {
-                const batch = this.buffer;
-                this.buffer = [];
+                const batch = this.buffer.splice(0);
+                if (batch.length === 0) {
+                    break;
+                }
                 try {
                     await this.sendPayload(batch);
                 }

package/dist/sinks/stdout.d.ts

@@ -4,6 +4,7 @@
 import { Sink } from './base';
 export declare class StdoutSink implements Sink {
     private format;
+    private quiet;
     constructor(format?: 'json' | 'pretty');
     emit(events: Array<Record<string, any>>): void;
     flush(): void;

package/dist/sinks/stdout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stdout.d.ts","sourceRoot":"","sources":["../../src/sinks/stdout.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAE9B,qBAAa,UAAW,YAAW,IAAI;IACrC,OAAO,CAAC,MAAM,CAAoB;gBAEtB,MAAM,GAAE,MAAM,GAAG,QAAiB;IAI9C,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI;IAkB9C,KAAK,IAAI,IAAI;IAIb,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"stdout.d.ts","sourceRoot":"","sources":["../../src/sinks/stdout.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAE9B,qBAAa,UAAW,YAAW,IAAI;IACrC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,KAAK,CAAU;gBAEX,MAAM,GAAE,MAAM,GAAG,QAAmB;IAKhD,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI;IAqB9C,KAAK,IAAI,IAAI;IAIb,KAAK,IAAI,IAAI;CAGd"}

package/dist/sinks/stdout.js

@@ -6,10 +6,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.StdoutSink = void 0;
 const util_1 = require("util");
 class StdoutSink {
-    constructor(format = 'json') {
+    constructor(format = 'pretty') {
         this.format = format;
+        this.quiet = isQuietMode();
     }
     emit(events) {
+        if (this.quiet) {
+            return;
+        }
         for (const event of events) {
             try {
                 const payload = this.format === 'pretty'
@@ -32,3 +36,10 @@ class StdoutSink {
     }
 }
 exports.StdoutSink = StdoutSink;
+function isQuietMode() {
+    const raw = String(process.env.MONORA_QUIET || '').trim().toLowerCase();
+    if (!raw) {
+        return false;
+    }
+    return ['1', 'true', 'yes', 'on'].includes(raw);
+}

package/dist/spec.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Monora Schema Specification Types
+ *
+ * Provides typed schema definitions for AI model monitoring with
+ * field specifications, PII detection, and compliance configuration.
+ */
+/** Field data types for schema definition */
+export type FieldType = 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+/** Types of PII that can be detected in fields */
+export type PIIType = 'email' | 'phone' | 'ssn' | 'credit_card' | 'name' | 'address' | 'ip_address' | 'date_of_birth' | 'custom';
+/** Field role in the AI system */
+export type FieldRole = 'input' | 'output' | 'metadata' | 'identifier';
+/**
+ * Specification for a single field in the schema.
+ */
+export interface FieldSpec {
+    /** Field name (supports dot notation for nested fields) */
+    name: string;
+    /** Data type of the field */
+    dataType: FieldType;
+    /** Whether the field is required */
+    required?: boolean;
+    /** Whether the field can be null */
+    nullable?: boolean;
+    /** Human-readable description */
+    description?: string;
+    /** Type of PII contained, if any */
+    piiType?: PIIType;
+    /** Regex pattern for redacting PII */
+    redactionPattern?: string;
+    /** Minimum value for numeric fields */
+    minValue?: number;
+    /** Maximum value for numeric fields */
+    maxValue?: number;
+    /** Regex pattern for string validation */
+    pattern?: string;
+    /** Role of the field (input/output/metadata/identifier) */
+    role?: FieldRole;
+}
+/**
+ * Create a FieldSpec with defaults applied.
+ */
+export declare function createFieldSpec(name: string, dataType: FieldType, options?: Partial<Omit<FieldSpec, 'name' | 'dataType'>>): FieldSpec;
+/**
+ * Convert FieldSpec to JSON Schema property definition.
+ */
+export declare function fieldSpecToJsonSchema(spec: FieldSpec): Record<string, any>;
+/**
+ * Convert FieldSpec to a redaction rule for data handling.
+ */
+export declare function fieldSpecToRedactionRule(spec: FieldSpec): Record<string, any> | null;
+/**
+ * Enrichment configuration for compliance features.
+ */
+export interface EnrichmentConfig {
+    /** Enable bias detection */
+    biasDetection?: boolean;
+    /** Enable risk tracking */
+    riskTracking?: boolean;
+    /** Enable human oversight */
+    humanOversight?: boolean;
+    /** Enable data redaction */
+    dataRedaction?: boolean;
+    /** Enable identity tracking */
+    identityTracking?: boolean;
+    /** Enable cost tracking */
+    costTracking?: boolean;
+    /** Enable immutability/hash chain */
+    immutability?: boolean;
+    /** Enable event signing */
+    signing?: boolean;
+    /** Enable data governance */
+    dataGovernance?: boolean;
+    /** Enable lifecycle tracking */
+    lifecycleTracking?: boolean;
+    /** Enable data residency enforcement */
+    dataResidency?: boolean;
+}
+/**
+ * Create default EnrichmentConfig.
+ */
+export declare function createEnrichmentConfig(options?: Partial<EnrichmentConfig>): EnrichmentConfig;
+/**
+ * Get enrichment configuration for a specific compliance framework.
+ */
+export declare function enrichmentConfigForFramework(framework: string): EnrichmentConfig;
+/**
+ * Merge two enrichment configurations (union of enabled features).
+ */
+export declare function mergeEnrichmentConfigs(base: EnrichmentConfig, other: EnrichmentConfig): EnrichmentConfig;
+/**
+ * MonoraSpec - Complete schema specification for an AI model.
+ */
+export interface MonoraSpec {
+    /** Input fields (prompts, queries, etc.) */
+    inputs: FieldSpec[];
+    /** Output fields (responses, completions, etc.) */
+    outputs: FieldSpec[];
+    /** Metadata fields (timestamps, service info, etc.) */
+    metadata?: FieldSpec[];
+    /** Identifier fields (trace_id, event_id, etc.) */
+    identifiers?: FieldSpec[];
+    /** Enrichment configuration */
+    enrichments?: EnrichmentConfig;
+    /** Compliance frameworks to target */
+    complianceTargets?: string[];
+    /** Model/application name */
+    modelName?: string;
+    /** Model version */
+    modelVersion?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Event timestamp field name */
+    eventTimestampField?: string;
+}
+/**
+ * Create a MonoraSpec with defaults applied.
+ */
+export declare function createMonoraSpec(options: {
+    inputs: FieldSpec[];
+    outputs: FieldSpec[];
+    metadata?: FieldSpec[];
+    identifiers?: FieldSpec[];
+    enrichments?: EnrichmentConfig;
+    complianceTargets?: string[];
+    modelName?: string;
+    modelVersion?: string;
+    description?: string;
+    eventTimestampField?: string;
+}): MonoraSpec;
+/**
+ * Get all fields from a MonoraSpec.
+ */
+export declare function getAllFields(spec: MonoraSpec): FieldSpec[];
+/**
+ * Get fields with PII from a MonoraSpec.
+ */
+export declare function getPiiFields(spec: MonoraSpec): FieldSpec[];
+/**
+ * Convert MonoraSpec to schema contract format for onboarding validation.
+ */
+export declare function specToSchemaContract(spec: MonoraSpec): Record<string, any>;
+/**
+ * Convert MonoraSpec to Monora configuration format.
+ */
+export declare function specToConfig(spec: MonoraSpec): Record<string, any>;
+/**
+ * Create MonoraSpec from a schema contract.
+ */
+export declare function specFromSchemaContract(contract: Record<string, any>): MonoraSpec;
+/**
+ * Convert MonoraSpec to dictionary representation.
+ */
+export declare function specToDict(spec: MonoraSpec): Record<string, any>;
+/**
+ * Create MonoraSpec from dictionary representation.
+ */
+export declare function specFromDict(data: Record<string, any>): MonoraSpec;
+//# sourceMappingURL=spec.d.ts.map

package/dist/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,6CAA6C;AAC7C,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEzF,kDAAkD;AAClD,MAAM,MAAM,OAAO,GACf,OAAO,GACP,OAAO,GACP,KAAK,GACL,aAAa,GACb,MAAM,GACN,SAAS,GACT,YAAY,GACZ,eAAe,GACf,QAAQ,CAAC;AAEb,kCAAkC;AAClC,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,QAAQ,EAAE,SAAS,CAAC;IACpB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sCAAsC;IACtC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,SAAS,EACnB,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAAC,CAAM,GAC1D,SAAS,CAcX;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAsB1E;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAsBpF;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,6BAA6B;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,4BAA4B;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+BAA+B;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,2BAA2B;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qCAAqC;IACrC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6BAA6B;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gCAAgC;IAChC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,wCAAwC;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAyDD;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,OAAO,CAAC,gBAAgB,CAAM,GACtC,gBAAgB,CAclB;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAIhF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,gBAAgB,GACtB,gBAAgB,CAclB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,mDAAmD;IACnD,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;IACvB,mDAAmD;IACnD,WAAW,CAAC,EAAE,SAAS,EAAE,CAAC;IAC1B,+BAA+B;IAC/B,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,sCAAsC;IACtC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IACxC,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,GAAG,UAAU,CAab;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,EAAE,CAO1D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,EAAE,CAE1D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAgC1E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAwElE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,UAAU,CAkChF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAahE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,UAAU,CAalE"}