monora-ai 2.0.0 → 2.1.3

package/dist/oversight.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Human oversight tracking for EU AI Act Art.14 and ISO 42001 8.3 compliance.
+ *
+ * This module provides human review and override tracking for AI decisions,
+ * supporting EU AI Act Article 14 human oversight requirements and ISO 42001
+ * control 8.3.
+ *
+ * Cross-SDK Parity:
+ *   Both Python and Node.js SDKs provide identical human oversight APIs:
+ *   - recordHumanReview() / record_human_review()
+ *   - recordHumanOverride() / record_human_override()
+ *   - getPendingReviews() / get_pending_reviews()
+ */
+import { MonoraConfig } from './config';
+export type ReviewType = 'approval' | 'rejection' | 'modification' | 'escalation';
+export type ReviewDecision = 'approved' | 'rejected' | 'modified' | 'escalated' | 'pending';
+/**
+ * A human review of an AI decision.
+ */
+export interface HumanReview {
+    /** ID of the event being reviewed */
+    reviewedEventId: string;
+    /** ID of the human reviewer */
+    reviewerId: string;
+    /** Type of review action */
+    reviewType: ReviewType;
+    /** Review decision outcome */
+    decision: ReviewDecision;
+    /** Description of any modifications made */
+    modifications?: string;
+    /** Time taken to review in milliseconds */
+    reviewDurationMs?: number;
+    /** Additional notes from the reviewer */
+    reviewNotes?: string;
+    /** Flags indicating compliance concerns */
+    complianceFlags: string[];
+    /** When the review was completed */
+    timestamp: string;
+}
+/**
+ * Convert HumanReview to event body dictionary.
+ */
+export declare function reviewToEventBody(review: HumanReview): Record<string, any>;
+/**
+ * A human override of an AI output.
+ */
+export interface HumanOverride {
+    /** ID of the event being overridden */
+    overriddenEventId: string;
+    /** Reason for the override */
+    overrideReason: string;
+    /** Hash of the original AI output */
+    originalOutputHash?: string;
+    /** Hash of the corrected output */
+    correctedOutputHash?: string;
+    /** Authority level of the person overriding */
+    overrideAuthority?: string;
+    /** When the override was made */
+    timestamp: string;
+}
+/**
+ * Convert HumanOverride to event body dictionary.
+ */
+export declare function overrideToEventBody(override: HumanOverride): Record<string, any>;
+/**
+ * An event awaiting human review.
+ */
+export interface PendingReview {
+    /** Event ID */
+    eventId: string;
+    /** Trace ID */
+    traceId?: string;
+    /** Event type */
+    eventType: string;
+    /** Model used */
+    model?: string;
+    /** Risk level */
+    riskLevel?: string;
+    /** Unix timestamp when created */
+    createdAt: number;
+    /** Unix timestamp when it times out */
+    timeoutAt: number;
+}
+/**
+ * Storage abstraction for oversight review tracking.
+ */
+export interface ReviewStore {
+    addPendingReview(review: PendingReview): void;
+    removePendingReview(eventId: string): void;
+    listPendingReviews(): PendingReview[];
+    listTimedOutReviews(now: number): PendingReview[];
+    addCompletedReview(review: HumanReview): void;
+    listCompletedReviews(): HumanReview[];
+    addOverride(override: HumanOverride): void;
+    listOverrides(): HumanOverride[];
+    clear(): void;
+}
+/**
+ * In-memory store for oversight reviews.
+ *
+ * Note: This is single-instance only. For production/distributed use, supply
+ * a persistent store via setReviewStore (e.g., SqliteReviewStore or Redis).
+ */
+export declare class MemoryReviewStore implements ReviewStore {
+    private pendingReviews;
+    private completedReviews;
+    private overrides;
+    private completedTtlMs;
+    constructor(options?: {
+        completedTtlMs?: number;
+    });
+    addPendingReview(review: PendingReview): void;
+    removePendingReview(eventId: string): void;
+    listPendingReviews(): PendingReview[];
+    listTimedOutReviews(now: number): PendingReview[];
+    addCompletedReview(review: HumanReview): void;
+    listCompletedReviews(): HumanReview[];
+    addOverride(override: HumanOverride): void;
+    listOverrides(): HumanOverride[];
+    clear(): void;
+    private pruneCompletedReviews;
+}
+/**
+ * SQLite-backed persistent review store (requires better-sqlite3).
+ */
+export declare class SqliteReviewStore implements ReviewStore {
+    private db;
+    private completedTtlMs;
+    constructor(dbPath: string, options?: {
+        completedTtlMs?: number;
+    });
+    addPendingReview(review: PendingReview): void;
+    removePendingReview(eventId: string): void;
+    listPendingReviews(): PendingReview[];
+    listTimedOutReviews(now: number): PendingReview[];
+    addCompletedReview(review: HumanReview): void;
+    listCompletedReviews(): HumanReview[];
+    addOverride(override: HumanOverride): void;
+    listOverrides(): HumanOverride[];
+    clear(): void;
+    private pruneCompletedReviews;
+    private parseComplianceFlags;
+}
+export declare function setReviewStore(store: ReviewStore): void;
+/**
+ * Options for recording a human review.
+ */
+export interface RecordHumanReviewOptions {
+    /** Description of any modifications made */
+    modifications?: string;
+    /** Time taken to review in milliseconds */
+    reviewDurationMs?: number;
+    /** Additional reviewer notes */
+    notes?: string;
+    /** Flags indicating compliance concerns */
+    complianceFlags?: string[];
+    /** Optional config */
+    config?: MonoraConfig;
+}
+/**
+ * Record a human review of an AI decision.
+ *
+ * @param reviewedEventId - ID of the event being reviewed.
+ * @param reviewerId - ID of the human reviewer.
+ * @param reviewType - Type of review (approval, rejection, modification, escalation).
+ * @param decision - Review decision (approved, rejected, modified, escalated).
+ * @param options - Additional options.
+ * @returns The created HumanReview.
+ *
+ * @example
+ * ```typescript
+ * recordHumanReview(
+ *   'evt_123',
+ *   'usr_456',
+ *   'approval',
+ *   'approved',
+ *   { notes: 'Verified output accuracy' }
+ * );
+ * ```
+ */
+export declare function recordHumanReview(reviewedEventId: string, reviewerId: string, reviewType: ReviewType, decision: ReviewDecision, options?: RecordHumanReviewOptions): HumanReview;
+/**
+ * Options for recording a human override.
+ */
+export interface RecordHumanOverrideOptions {
+    /** The original AI output (will be hashed) */
+    originalOutput?: string;
+    /** The corrected output (will be hashed) */
+    correctedOutput?: string;
+    /** Authority level of the person overriding */
+    overrideAuthority?: string;
+    /** Optional config */
+    config?: MonoraConfig;
+}
+/**
+ * Record a human override of an AI output.
+ *
+ * @param overriddenEventId - ID of the event being overridden.
+ * @param overrideReason - Reason for the override.
+ * @param options - Additional options.
+ * @returns The created HumanOverride.
+ *
+ * @example
+ * ```typescript
+ * recordHumanOverride(
+ *   'evt_123',
+ *   'Incorrect recommendation',
+ *   { overrideAuthority: 'supervisor' }
+ * );
+ * ```
+ */
+export declare function recordHumanOverride(overriddenEventId: string, overrideReason: string, options?: RecordHumanOverrideOptions): HumanOverride;
+/**
+ * Options for requiring review.
+ */
+export interface RequireReviewOptions {
+    /** Trace ID of the event */
+    traceId?: string;
+    /** Type of event */
+    eventType?: string;
+    /** Model used */
+    model?: string;
+    /** Risk level */
+    riskLevel?: string;
+    /** Optional config */
+    config?: MonoraConfig;
+}
+/**
+ * Mark an event as requiring human review.
+ *
+ * @param eventId - ID of the event requiring review.
+ * @param options - Additional options.
+ * @returns The created PendingReview.
+ */
+export declare function requireReview(eventId: string, options?: RequireReviewOptions): PendingReview;
+/**
+ * Get all events pending human review.
+ */
+export declare function getPendingReviews(): PendingReview[];
+/**
+ * Get reviews that have timed out.
+ */
+export declare function getTimedOutReviews(): PendingReview[];
+/**
+ * Check if an event requires human review based on config.
+ *
+ * @param eventType - Type of event.
+ * @param model - Model used.
+ * @param riskLevel - Risk level of the event.
+ * @param config - Optional config.
+ * @returns True if review is required.
+ */
+export declare function checkReviewRequired(eventType: string, model?: string, riskLevel?: string, config?: MonoraConfig): boolean;
+/**
+ * Get summary of human oversight for reporting.
+ *
+ * @returns Summary dict for compliance reports.
+ */
+export declare function getOversightSummary(): Record<string, any>;
+/**
+ * Clear all oversight tracking data.
+ */
+export declare function clearOversightData(): void;
+//# sourceMappingURL=oversight.d.ts.map

package/dist/oversight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oversight.d.ts","sourceRoot":"","sources":["../src/oversight.ts"],"names":[],"mappings":"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"}