monora-ai 2.1.0 → 2.1.3

package/dist/impact-assessment.d.ts

@@ -0,0 +1,350 @@
+/**
+ * AI Impact Assessment for ISO 42001 A.5 compliance.
+ *
+ * This module provides AI Impact Assessment (AIIA) management supporting
+ * ISO 42001 controls A.5.2 (process), A.5.3 (documentation), A.5.4 (individual
+ * impacts), and A.5.5 (societal impacts).
+ *
+ * Cross-SDK Parity:
+ *   Both Python and Node.js SDKs provide identical impact assessment APIs:
+ *   - createImpactAssessment() / create_impact_assessment()
+ *   - addImpactRecord() / add_impact_record()
+ *   - addMitigation() / add_mitigation()
+ *   - submitForApproval() / submit_for_approval()
+ *   - recordApproval() / record_approval()
+ *   - finalizeAssessment() / finalize_assessment()
+ */
+import { MonoraConfig } from './config';
+export type Likelihood = 'rare' | 'unlikely' | 'possible' | 'likely' | 'certain';
+export type Severity = 'minimal' | 'minor' | 'moderate' | 'major' | 'catastrophic';
+export type ImpactCategory = 'fairness' | 'privacy' | 'safety' | 'autonomy' | 'economic' | 'environmental';
+export type AssessmentStatus = 'draft' | 'review' | 'approved' | 'archived';
+export type MitigationEffectiveness = 'partial' | 'substantial' | 'complete';
+export type MitigationStatus = 'planned' | 'in_progress' | 'implemented' | 'verified';
+export type ImpactType = 'individual' | 'societal';
+/**
+ * A single impact assessment record (individual or societal).
+ */
+export interface ImpactRecord {
+    /** Unique identifier for this impact record */
+    impactId: string;
+    /** Impact category */
+    category: ImpactCategory;
+    /** Detailed description of the potential impact */
+    description: string;
+    /** Probability of occurrence */
+    likelihood: Likelihood;
+    /** Severity if the impact occurs */
+    severity: Severity;
+    /** Computed risk score (likelihood * severity, 1-25) */
+    riskScore: number;
+    /** Groups or individuals who may be affected */
+    affectedParties: string[];
+    /** Whether this is an individual or societal impact */
+    impactType: ImpactType;
+}
+/**
+ * Convert impact record to dictionary for serialization.
+ */
+export declare function impactRecordToDict(record: ImpactRecord): Record<string, any>;
+/**
+ * A risk mitigation measure.
+ */
+export interface Mitigation {
+    /** Unique identifier */
+    mitigationId: string;
+    /** Category of risk being mitigated */
+    riskCategory: string;
+    /** Description of the mitigation measure */
+    description: string;
+    /** Expected effectiveness of the mitigation */
+    effectiveness: MitigationEffectiveness;
+    /** Current implementation status */
+    implementationStatus: MitigationStatus;
+    /** Person/team responsible for implementation */
+    owner: string;
+    /** List of impact_ids this mitigation addresses */
+    targetImpacts: string[];
+}
+/**
+ * Convert mitigation to dictionary for serialization.
+ */
+export declare function mitigationToDict(mitigation: Mitigation): Record<string, any>;
+/**
+ * An approval sign-off on the assessment.
+ */
+export interface Approval {
+    /** Role of the approver (ai_governance, legal, ethics_board) */
+    approverRole: string;
+    /** Name of the person approving */
+    approverName: string;
+    /** Timestamp of approval */
+    approvedAt: string;
+    /** Optional approval comments */
+    comments?: string;
+}
+/**
+ * Convert approval to dictionary for serialization.
+ */
+export declare function approvalToDict(approval: Approval): Record<string, any>;
+/**
+ * Complete AI Impact Assessment (AIIA) for ISO 42001 A.5.
+ */
+export interface AIImpactAssessment {
+    /** Unique identifier for this assessment */
+    assessmentId: string;
+    /** ID of the AI system being assessed */
+    systemId: string;
+    /** Date assessment was created */
+    assessmentDate: string;
+    /** Person conducting the assessment */
+    assessor: string;
+    /** Version of this assessment */
+    version: string;
+    /** Current status */
+    status: AssessmentStatus;
+    /** Purpose of the AI system */
+    intendedPurpose: string;
+    /** Context in which the system will be deployed */
+    deploymentContext: string;
+    /** Groups that may be affected by the system */
+    affectedGroups: string[];
+    /** List of individual impact assessments (A.5.4) */
+    individualImpacts: ImpactRecord[];
+    /** List of societal impact assessments (A.5.5) */
+    societalImpacts: ImpactRecord[];
+    /** Mitigation measures for identified risks */
+    riskMitigations: Mitigation[];
+    /** Risks remaining after mitigation */
+    residualRisks: string[];
+    /** Sign-offs from required approvers */
+    approvals: Approval[];
+    /** Timestamp of creation */
+    createdAt: string;
+    /** Timestamp of last update */
+    updatedAt: string;
+}
+/**
+ * Convert assessment to dictionary for serialization.
+ */
+export declare function assessmentToDict(assessment: AIImpactAssessment): Record<string, any>;
+/**
+ * Calculate risk score from likelihood and severity.
+ *
+ * Uses a 5x5 risk matrix where score = likelihood_weight * severity_weight.
+ *
+ * @param likelihood - Probability of occurrence
+ * @param severity - Severity if impact occurs
+ * @returns Risk score from 1 (rare/minimal) to 25 (certain/catastrophic)
+ */
+export declare function calculateRiskScore(likelihood: Likelihood, severity: Severity): number;
+/**
+ * Options for creating an impact assessment.
+ */
+export interface CreateImpactAssessmentOptions {
+    /** ID of the AI system being assessed */
+    systemId: string;
+    /** Person conducting the assessment */
+    assessor: string;
+    /** Purpose of the AI system */
+    intendedPurpose: string;
+    /** Context of deployment */
+    deploymentContext: string;
+    /** Groups that may be affected */
+    affectedGroups?: string[];
+    /** Assessment version */
+    version?: string;
+    /** Optional config */
+    config?: MonoraConfig;
+}
+/**
+ * Create a new AI Impact Assessment.
+ *
+ * @param options - Assessment creation options
+ * @returns A new AIImpactAssessment in draft status
+ *
+ * @example
+ * ```typescript
+ * const assessment = createImpactAssessment({
+ *   systemId: 'chatbot-v2',
+ *   assessor: 'Jane Doe',
+ *   intendedPurpose: 'Customer support automation',
+ *   deploymentContext: 'Web and mobile applications',
+ *   affectedGroups: ['customers', 'support_staff']
+ * });
+ * ```
+ */
+export declare function createImpactAssessment(options: CreateImpactAssessmentOptions): AIImpactAssessment;
+/**
+ * Options for adding an impact record.
+ */
+export interface AddImpactRecordOptions {
+    /** ID of the assessment to update */
+    assessmentId: string;
+    /** Impact category */
+    category: ImpactCategory;
+    /** Description of the potential impact */
+    description: string;
+    /** Probability of occurrence */
+    likelihood: Likelihood;
+    /** Severity if impact occurs */
+    severity: Severity;
+    /** Groups/individuals affected */
+    affectedParties?: string[];
+    /** Whether individual or societal impact */
+    impactType?: ImpactType;
+}
+/**
+ * Add an impact record to an assessment.
+ *
+ * @param options - Impact record options
+ * @returns The created ImpactRecord
+ * @throws Error if assessment not found or not in draft status
+ */
+export declare function addImpactRecord(options: AddImpactRecordOptions): ImpactRecord;
+/**
+ * Options for adding a mitigation.
+ */
+export interface AddMitigationOptions {
+    /** ID of the assessment to update */
+    assessmentId: string;
+    /** Category of risk being mitigated */
+    riskCategory: string;
+    /** Description of the mitigation measure */
+    description: string;
+    /** Expected effectiveness */
+    effectiveness: MitigationEffectiveness;
+    /** Current implementation status */
+    implementationStatus: MitigationStatus;
+    /** Person/team responsible */
+    owner: string;
+    /** List of impact_ids this addresses */
+    targetImpacts?: string[];
+}
+/**
+ * Add a risk mitigation to an assessment.
+ *
+ * @param options - Mitigation options
+ * @returns The created Mitigation
+ * @throws Error if assessment not found or not in draft status
+ */
+export declare function addMitigation(options: AddMitigationOptions): Mitigation;
+/**
+ * Add a residual risk to an assessment.
+ *
+ * @param assessmentId - ID of the assessment to update
+ * @param riskDescription - Description of the residual risk
+ * @throws Error if assessment not found or not in draft status
+ */
+export declare function addResidualRisk(assessmentId: string, riskDescription: string): void;
+/**
+ * Validate that an assessment has all required fields.
+ *
+ * @param assessment - The assessment to validate
+ * @returns List of validation errors (empty if valid)
+ */
+export declare function validateAssessmentCompleteness(assessment: AIImpactAssessment): string[];
+/**
+ * Submit an assessment for approval review.
+ *
+ * Changes status from 'draft' to 'review'.
+ *
+ * @param assessmentId - ID of the assessment to submit
+ * @returns The updated assessment
+ * @throws Error if assessment not found or not in draft status
+ */
+export declare function submitForApproval(assessmentId: string): AIImpactAssessment;
+/**
+ * Options for recording an approval.
+ */
+export interface RecordApprovalOptions {
+    /** ID of the assessment */
+    assessmentId: string;
+    /** Role of the approver */
+    approverRole: string;
+    /** Name of the person approving */
+    approverName: string;
+    /** Optional comments */
+    comments?: string;
+}
+/**
+ * Record an approval sign-off on an assessment.
+ *
+ * @param options - Approval options
+ * @returns The created Approval
+ * @throws Error if assessment not found or not in review status
+ */
+export declare function recordApproval(options: RecordApprovalOptions): Approval;
+/**
+ * Finalize an assessment, marking it as approved.
+ *
+ * Validates that all required approvals are present.
+ *
+ * @param assessmentId - ID of the assessment to finalize
+ * @param config - Optional config for required approvals
+ * @returns The finalized assessment
+ * @throws Error if assessment not found, not in review, or missing approvals
+ */
+export declare function finalizeAssessment(assessmentId: string, config?: MonoraConfig): AIImpactAssessment;
+/**
+ * Archive an approved assessment.
+ *
+ * @param assessmentId - ID of the assessment to archive
+ * @returns The archived assessment
+ * @throws Error if assessment not found or not approved
+ */
+export declare function archiveAssessment(assessmentId: string): AIImpactAssessment;
+/**
+ * Get an assessment by ID.
+ *
+ * @param assessmentId - ID of the assessment
+ * @returns The assessment if found, undefined otherwise
+ */
+export declare function getAssessment(assessmentId: string): AIImpactAssessment | undefined;
+/**
+ * Get all assessments for a system.
+ *
+ * @param systemId - ID of the AI system
+ * @returns List of assessments for the system
+ */
+export declare function getAssessmentsForSystem(systemId: string): AIImpactAssessment[];
+/**
+ * Get all registered assessments.
+ *
+ * @returns List of all assessments
+ */
+export declare function getAllAssessments(): AIImpactAssessment[];
+/**
+ * Clear all assessments from the registry.
+ */
+export declare function clearAssessments(): void;
+/**
+ * Get a summary of an assessment for reporting.
+ *
+ * @param assessmentId - ID of the assessment
+ * @returns Summary dict with key metrics
+ */
+export declare function getAssessmentSummary(assessmentId: string): Record<string, any>;
+/**
+ * Get aggregate report of all impact assessments.
+ *
+ * @param config - Optional config
+ * @returns Report dict for compliance reporting
+ */
+export declare function getImpactAssessmentReport(config?: MonoraConfig): Record<string, any>;
+/**
+ * Check if a system has approved impact assessment for production.
+ *
+ * @param systemId - ID of the AI system
+ * @param config - Optional config
+ * @returns Object with readiness status and details
+ */
+export declare function checkProductionReadiness(systemId: string, config?: MonoraConfig): Record<string, any>;
+/**
+ * Emit the current state of an assessment as an event.
+ *
+ * @param assessmentId - ID of the assessment to emit
+ * @param config - Optional config
+ */
+export declare function emitImpactAssessment(assessmentId: string, config?: MonoraConfig): void;
+//# sourceMappingURL=impact-assessment.d.ts.map

package/dist/impact-assessment.d.ts.map

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