@complior/engine 0.9.0

package/src/domain/documents/document-generator.ts

@@ -0,0 +1,239 @@
+import type { AgentPassport } from '../../types/passport.types.js';
+import { deriveOversightDescription } from './passport-helpers.js';
+import {
+  ALL_DOC_TYPES as _ALL_DOC_TYPES,
+  TEMPLATE_FILE_MAP as _TEMPLATE_FILE_MAP,
+  DOC_ID_PREFIX_MAP,
+  DOC_ID_PATTERN_MAP,
+  type DocType as _DocType,
+} from '../../data/template-registry.js';
+
+// --- Types (re-exported from template-registry — single source of truth) ---
+
+export const ALL_DOC_TYPES = _ALL_DOC_TYPES;
+export type DocType = _DocType;
+export const TEMPLATE_FILE_MAP = _TEMPLATE_FILE_MAP;
+
+export interface DocGeneratorInput {
+  readonly manifest: AgentPassport;
+  readonly template: string;
+  readonly docType: DocType;
+  readonly organization?: string;
+}
+
+export interface DocResult {
+  readonly markdown: string;
+  readonly docType: DocType;
+  readonly prefilledFields: readonly string[];
+  readonly manualFields: readonly string[];
+}
+
+// --- Helpers ---
+
+const generateDocId = (prefix: string): string => {
+  const year = new Date().getFullYear();
+  const seq = String(Math.floor(Math.random() * 999) + 1).padStart(3, '0');
+  return `${prefix}-${year}-${seq}`;
+};
+
+// --- Generator ---
+
+export const generateDocument = (input: DocGeneratorInput): DocResult => {
+  const { manifest, template, docType, organization } = input;
+  const prefilledFields: string[] = [];
+  const manualFields: string[] = [];
+
+  let markdown = template;
+  const today = new Date().toISOString().slice(0, 10);
+
+  // --- Common placeholders (shared across all templates) ---
+
+  // Company Name / Organization
+  const orgName = organization ?? manifest.owner?.team;
+  if (orgName) {
+    markdown = markdown.replaceAll('[Company Name]', orgName);
+    markdown = markdown.replaceAll('[Organization]', orgName);
+    prefilledFields.push('Company Name');
+  } else {
+    manualFields.push('Company Name');
+  }
+
+  // Date
+  markdown = markdown.replaceAll('[Date]', today);
+  prefilledFields.push('Date');
+
+  // AI System Name
+  markdown = markdown.replaceAll('[AI System Name]', manifest.display_name);
+  prefilledFields.push('AI System Name');
+
+  // Provider
+  const provider = manifest.model?.provider ?? '';
+  if (provider) {
+    markdown = markdown.replaceAll('[Provider name]', provider);
+    markdown = markdown.replaceAll('[Provider]', provider);
+    prefilledFields.push('Provider');
+  } else {
+    manualFields.push('Provider');
+  }
+
+  // Version
+  markdown = markdown.replaceAll('[X.Y]', manifest.version);
+  prefilledFields.push('Version');
+
+  // Description
+  markdown = markdown.replaceAll('[Description]', manifest.description);
+  prefilledFields.push('Description');
+
+  // Risk class
+  const riskClass = manifest.compliance?.eu_ai_act?.risk_class ?? '';
+  if (riskClass) {
+    markdown = markdown.replaceAll('[Risk Class]', riskClass);
+    prefilledFields.push('Risk Class');
+  } else {
+    manualFields.push('Risk Class');
+  }
+
+  // Human Oversight Description
+  const oversightDesc = deriveOversightDescription(manifest);
+  markdown = markdown.replaceAll(
+    '[Human Oversight Description]',
+    oversightDesc,
+  );
+
+  // Autonomy Level
+  markdown = markdown.replaceAll('[Autonomy Level]', manifest.autonomy_level);
+
+  // Model ID
+  const modelId = manifest.model?.model_id ?? '';
+  if (modelId) {
+    markdown = markdown.replaceAll('[Model ID]', modelId);
+  }
+
+  // Document ID (type-specific prefix)
+  const idPattern = DOC_ID_PATTERN_MAP[docType];
+  const idPrefix = DOC_ID_PREFIX_MAP[docType];
+  if (idPattern && idPrefix && markdown.includes(idPattern)) {
+    const docId = generateDocId(idPrefix);
+    markdown = markdown.replace(idPattern, docId);
+    prefilledFields.push('Document ID');
+  }
+
+  // [Name, Title] — always manual
+  if (markdown.includes('[Name, Title]')) {
+    manualFields.push('Approved By (Name, Title)');
+  }
+
+  // --- Type-specific handling ---
+
+  switch (docType) {
+    case 'ai-literacy':
+      manualFields.push('Training levels configuration');
+      manualFields.push('AI systems in scope table');
+      manualFields.push('Training schedule');
+      manualFields.push('Sign-off signatures');
+      break;
+
+    case 'art5-screening':
+      manualFields.push('Prohibited practice details');
+      manualFields.push('Risk assessment');
+      manualFields.push('Decision and justification');
+      break;
+
+    case 'technical-documentation':
+      manualFields.push('System architecture details');
+      manualFields.push('Training data characteristics');
+      manualFields.push('Performance metrics');
+      manualFields.push('Monitoring measures');
+      break;
+
+    case 'incident-report':
+      manualFields.push('Incident description');
+      manualFields.push('Root cause analysis');
+      manualFields.push('Corrective actions');
+      manualFields.push('Market surveillance authority');
+      break;
+
+    case 'declaration-of-conformity':
+      manualFields.push('Harmonised standards used');
+      manualFields.push('Notified body details');
+      manualFields.push('Conformity assessment procedure');
+      manualFields.push('Signatory');
+      break;
+
+    case 'monitoring-policy':
+      manualFields.push('AI systems in scope table');
+      manualFields.push('Human oversight assignments');
+      manualFields.push('Log retention schedule');
+      manualFields.push('Review frequency');
+      break;
+
+    case 'fria':
+      manualFields.push('Affected groups identification');
+      manualFields.push('Rights impact severity assessment');
+      manualFields.push('Mitigation measures');
+      manualFields.push('Stakeholder consultation records');
+      break;
+
+    case 'worker-notification':
+      manualFields.push('Affected worker groups');
+      manualFields.push('AI system capabilities description');
+      manualFields.push('Worker rights and escalation');
+      manualFields.push('Notification timeline');
+      break;
+
+    case 'risk-management':
+      manualFields.push('Known risks identification');
+      manualFields.push('Misuse scenarios');
+      manualFields.push('Residual risk assessment');
+      manualFields.push('Test results and methodology');
+      manualFields.push('Mitigation measures');
+      break;
+
+    case 'data-governance':
+      manualFields.push('Data sources and origins');
+      manualFields.push('Collection and preparation methods');
+      manualFields.push('Quality metrics and targets');
+      manualFields.push('Bias analysis');
+      manualFields.push('Representativeness assessment');
+      break;
+
+    case 'qms':
+      manualFields.push('Compliance strategy');
+      manualFields.push('Design control procedures');
+      manualFields.push('Testing procedures');
+      manualFields.push('Roles and responsibilities');
+      manualFields.push('Change management');
+      break;
+
+    case 'instructions-for-use':
+      manualFields.push('Intended purpose details');
+      manualFields.push('Performance metrics and benchmarks');
+      manualFields.push('Known limitations');
+      manualFields.push('Human oversight procedures');
+      manualFields.push('Input data specifications');
+      break;
+
+    case 'gpai-transparency':
+      manualFields.push('Training data sources');
+      manualFields.push('Benchmark results');
+      manualFields.push('Safety evaluations');
+      manualFields.push('Copyright compliance policy');
+      manualFields.push('Energy consumption data');
+      break;
+
+    case 'gpai-systemic-risk':
+      manualFields.push('Adversarial testing results');
+      manualFields.push('Systemic risk assessment');
+      manualFields.push('Incident tracking procedures');
+      manualFields.push('Cybersecurity measures');
+      break;
+  }
+
+  return Object.freeze({
+    markdown,
+    docType,
+    prefilledFields: Object.freeze([...prefilledFields]),
+    manualFields: Object.freeze([...manualFields]),
+  });
+};
+

package/src/domain/documents/index.ts

@@ -0,0 +1,9 @@
+export { detectWeakSections, buildL2Feedback, enrichDocumentWithAI } from './ai-enricher.js';
+export type { AiEnrichInput, AiEnrichedResult } from './ai-enricher.js';
+export { generateDocument, ALL_DOC_TYPES, TEMPLATE_FILE_MAP } from './document-generator.js';
+export type { DocType, DocGeneratorInput, DocResult } from './document-generator.js';
+export { deriveOversightDescription } from './passport-helpers.js';
+export { generatePolicy } from './policy-generator.js';
+export type { PolicyGeneratorInput, PolicyResult } from './policy-generator.js';
+export { generateWorkerNotification } from './worker-notification-generator.js';
+export type { WorkerNotificationInput, WorkerNotificationResult } from './worker-notification-generator.js';

package/src/domain/documents/passport-helpers.ts

@@ -0,0 +1,25 @@
+import type { AgentPassport } from '../../types/passport.types.js';
+
+/** Derive human-readable oversight description from passport autonomy data. */
+export const deriveOversightDescription = (manifest: AgentPassport): string => {
+  const parts: string[] = [];
+  const level = manifest.autonomy_level;
+
+  if (level === 'L1' || level === 'L2') {
+    parts.push('System operates under direct human supervision.');
+  } else if (level === 'L3') {
+    parts.push('System operates semi-autonomously with human oversight checkpoints.');
+  } else {
+    parts.push('System operates autonomously; enhanced oversight measures required.');
+  }
+
+  if (manifest.constraints.human_approval_required.length > 0) {
+    parts.push(`Human approval required for: ${manifest.constraints.human_approval_required.join(', ')}.`);
+  }
+
+  if (manifest.autonomy_evidence.human_approval_gates > 0) {
+    parts.push(`${manifest.autonomy_evidence.human_approval_gates} human approval gate(s) detected in code.`);
+  }
+
+  return parts.join(' ');
+};

package/src/domain/documents/policy-generator.test.ts

@@ -0,0 +1,252 @@
+import { describe, it, expect } from 'vitest';
+import { generatePolicy } from './policy-generator.js';
+import { createMockPassport } from '../../test-helpers/factories.js';
+import type { IndustryId } from '../../data/industry-patterns.js';
+
+const HR_TEMPLATE = `# AI Usage Policy — HR / Employment
+
+| Field | Value |
+|-------|-------|
+| Organization | [Organization] |
+| Date | [Date] |
+| Version | [Version] |
+| AI System Name | [AI System Name] |
+| Risk Class | [Risk Class] |
+
+## 3. AI System Description
+
+- System name: [AI System Name]
+- Description: [Description]
+- Provider: [Provider]
+- Model ID: [Model ID]
+- Autonomy level: [Autonomy Level]
+
+## 6. Human Oversight
+
+- Autonomy level: [Autonomy Level]
+- [Human Oversight Description]
+
+## 14. Approval and Sign-off
+
+| Policy Owner | [Approver Name] | [Date] |
+`;
+
+const FINANCE_TEMPLATE = `# AI Usage Policy — Finance / Credit
+
+| Risk Class | [Risk Class] |
+| AI System Name | [AI System Name] |
+| Date | [Date] |
+
+## 4. Risk Classification
+
+This AI system is classified as **[Risk Class]** under the EU AI Act.
+
+## 14. Approval and Sign-off
+
+| Policy Owner | [Approver Name] | [Date] |
+`;
+
+const HEALTHCARE_TEMPLATE = `# AI Usage Policy — Healthcare / Medical
+
+| AI System Name | [AI System Name] |
+| Autonomy level | [Autonomy Level] |
+
+## 6. Human Oversight
+
+- Autonomy level: [Autonomy Level]
+- [Human Oversight Description]
+`;
+
+const EDUCATION_TEMPLATE = `# AI Usage Policy — Education / Academic
+
+| AI System Name | [AI System Name] |
+| Provider | [Provider] |
+| Model ID | [Model ID] |
+| Version | [Version] |
+`;
+
+const LEGAL_TEMPLATE = `# AI Usage Policy — Legal / Justice
+
+| AI System Name | [AI System Name] |
+| Organization | [Organization] |
+| Date | [Date] |
+
+## 14. Approval and Sign-off
+
+| Policy Owner | [Approver Name] | [Date] |
+`;
+
+describe('generatePolicy', () => {
+  it('pre-fills system name and organization for HR template', () => {
+    const manifest = createMockPassport({
+      display_name: 'HR Screening Bot',
+      owner: { team: 'TalentCo', contact: 'hr@talent.co', responsible_person: 'Alice' },
+    });
+
+    const result = generatePolicy({
+      manifest,
+      template: HR_TEMPLATE,
+      industry: 'hr',
+      organization: 'TalentCo HR',
+    });
+
+    expect(result.markdown).toContain('HR Screening Bot');
+    expect(result.markdown).toContain('TalentCo HR');
+    expect(result.markdown).not.toContain('[AI System Name]');
+    expect(result.markdown).not.toContain('[Organization]');
+    expect(result.prefilledFields).toContain('AI System Name');
+    expect(result.prefilledFields).toContain('Organization');
+    expect(result.industry).toBe('hr');
+  });
+
+  it('pre-fills risk class for finance template', () => {
+    const manifest = createMockPassport({
+      compliance: {
+        eu_ai_act: {
+          risk_class: 'high',
+          applicable_articles: ['Art. 6'],
+          deployer_obligations_met: [],
+          deployer_obligations_pending: [],
+        },
+        complior_score: 65,
+        last_scan: '2026-01-01',
+      },
+    });
+
+    const result = generatePolicy({
+      manifest,
+      template: FINANCE_TEMPLATE,
+      industry: 'finance',
+    });
+
+    expect(result.markdown).toContain('**high**');
+    expect(result.markdown).not.toContain('[Risk Class]');
+    expect(result.prefilledFields).toContain('Risk Class');
+  });
+
+  it('pre-fills autonomy and oversight for healthcare template', () => {
+    const manifest = createMockPassport({
+      autonomy_level: 'L3',
+      autonomy_evidence: {
+        human_approval_gates: 2,
+        unsupervised_actions: 1,
+        no_logging_actions: 0,
+        auto_rated: true,
+      },
+      constraints: {
+        rate_limits: { max_actions_per_minute: 60 },
+        budget: { max_cost_per_session_usd: 10 },
+        human_approval_required: ['prescribe'],
+        prohibited_actions: [],
+      },
+    });
+
+    const result = generatePolicy({
+      manifest,
+      template: HEALTHCARE_TEMPLATE,
+      industry: 'healthcare',
+    });
+
+    expect(result.markdown).toContain('L3');
+    expect(result.markdown).toContain('semi-autonomously');
+    expect(result.markdown).toContain('Human approval required for: prescribe');
+    expect(result.markdown).toContain('2 human approval gate(s)');
+    expect(result.prefilledFields).toContain('Autonomy Level');
+    expect(result.prefilledFields).toContain('Human Oversight Description');
+  });
+
+  it('pre-fills provider info for education template', () => {
+    const manifest = createMockPassport({
+      model: { provider: 'Anthropic', model_id: 'claude-3', deployment: 'cloud', data_residency: 'EU' },
+      version: '2.1.0',
+    });
+
+    const result = generatePolicy({
+      manifest,
+      template: EDUCATION_TEMPLATE,
+      industry: 'education',
+    });
+
+    expect(result.markdown).toContain('Anthropic');
+    expect(result.markdown).toContain('claude-3');
+    expect(result.markdown).toContain('2.1.0');
+    expect(result.prefilledFields).toContain('Provider');
+    expect(result.prefilledFields).toContain('Model ID');
+    expect(result.prefilledFields).toContain('Version');
+  });
+
+  it('tracks manual fields for legal template when approver not provided', () => {
+    const manifest = createMockPassport();
+
+    const result = generatePolicy({
+      manifest,
+      template: LEGAL_TEMPLATE,
+      industry: 'legal',
+    });
+
+    expect(result.manualFields).toContain('Approver Name');
+    expect(result.markdown).toContain('[Approver Name]');
+  });
+
+  it('returns frozen result', () => {
+    const manifest = createMockPassport();
+
+    const result = generatePolicy({
+      manifest,
+      template: HR_TEMPLATE,
+      industry: 'hr',
+    });
+
+    expect(Object.isFrozen(result)).toBe(true);
+    expect(Object.isFrozen(result.prefilledFields)).toBe(true);
+    expect(Object.isFrozen(result.manualFields)).toBe(true);
+  });
+
+  it('custom organization overrides passport owner.team', () => {
+    const manifest = createMockPassport({
+      owner: { team: 'Default Corp', contact: 'info@default.com', responsible_person: 'Bob' },
+    });
+
+    const result = generatePolicy({
+      manifest,
+      template: HR_TEMPLATE,
+      industry: 'hr',
+      organization: 'Custom Org Ltd',
+    });
+
+    expect(result.markdown).toContain('Custom Org Ltd');
+    expect(result.markdown).not.toContain('Default Corp');
+    expect(result.prefilledFields).toContain('Organization');
+  });
+
+  it('falls back to passport owner.team when no organization provided', () => {
+    const manifest = createMockPassport({
+      owner: { team: 'Fallback Inc', contact: 'info@fallback.com', responsible_person: 'Carol' },
+    });
+
+    const result = generatePolicy({
+      manifest,
+      template: HR_TEMPLATE,
+      industry: 'hr',
+    });
+
+    expect(result.markdown).toContain('Fallback Inc');
+    expect(result.prefilledFields).toContain('Organization');
+  });
+
+  it('pre-fills approver when provided', () => {
+    const manifest = createMockPassport();
+
+    const result = generatePolicy({
+      manifest,
+      template: HR_TEMPLATE,
+      industry: 'hr',
+      approver: 'Jane Smith, CLO',
+    });
+
+    expect(result.markdown).toContain('Jane Smith, CLO');
+    expect(result.markdown).not.toContain('[Approver Name]');
+    expect(result.prefilledFields).toContain('Approver');
+    expect(result.manualFields).not.toContain('Approver Name');
+  });
+});

package/src/domain/documents/policy-generator.ts

@@ -0,0 +1,94 @@
+import type { AgentPassport } from '../../types/passport.types.js';
+import type { IndustryId } from '../../data/industry-patterns.js';
+import { deriveOversightDescription } from './passport-helpers.js';
+
+// --- Types ---
+
+export interface PolicyGeneratorInput {
+  readonly manifest: AgentPassport;
+  readonly template: string;
+  readonly industry: IndustryId;
+  readonly organization?: string;
+  readonly approver?: string;
+}
+
+export interface PolicyResult {
+  readonly markdown: string;
+  readonly industry: IndustryId;
+  readonly prefilledFields: readonly string[];
+  readonly manualFields: readonly string[];
+}
+
+// --- Generator ---
+
+export const generatePolicy = (input: PolicyGeneratorInput): PolicyResult => {
+  const { manifest, template, industry, organization, approver } = input;
+  const prefilledFields: string[] = [];
+  const manualFields: string[] = [];
+
+  let markdown = template;
+  const today = new Date().toISOString().slice(0, 10);
+
+  // 1. Document Header table fields
+  markdown = markdown.replaceAll('[AI System Name]', manifest.display_name);
+  prefilledFields.push('AI System Name');
+
+  markdown = markdown.replaceAll('[Date]', today);
+  prefilledFields.push('Date');
+
+  markdown = markdown.replaceAll('[Version]', manifest.version);
+  prefilledFields.push('Version');
+
+  const orgName = organization ?? manifest.owner.team;
+  if (orgName) {
+    markdown = markdown.replaceAll('[Organization]', orgName);
+    prefilledFields.push('Organization');
+  } else {
+    manualFields.push('Organization');
+  }
+
+  const riskClass = manifest.compliance?.eu_ai_act?.risk_class ?? '';
+  if (riskClass) {
+    markdown = markdown.replaceAll('[Risk Class]', riskClass);
+    prefilledFields.push('Risk Class');
+  } else {
+    manualFields.push('Risk Class');
+  }
+
+  // 2. AI System Description section
+  markdown = markdown.replaceAll('[Description]', manifest.description);
+  prefilledFields.push('Description');
+
+  markdown = markdown.replaceAll('[Provider]', manifest.model.provider);
+  prefilledFields.push('Provider');
+
+  markdown = markdown.replaceAll('[Model ID]', manifest.model.model_id);
+  prefilledFields.push('Model ID');
+
+  markdown = markdown.replaceAll('[Autonomy Level]', manifest.autonomy_level);
+  prefilledFields.push('Autonomy Level');
+
+  // 3. Human Oversight description
+  const oversightDesc = deriveOversightDescription(manifest);
+  markdown = markdown.replaceAll('[Human Oversight Description]', oversightDesc);
+  prefilledFields.push('Human Oversight Description');
+
+  // 4. Approver
+  if (approver) {
+    markdown = markdown.replaceAll('[Approver Name]', approver);
+    prefilledFields.push('Approver');
+  } else {
+    manualFields.push('Approver Name');
+  }
+
+  // 5. Common manual fields (present in all templates)
+  manualFields.push('DPO sign-off');
+  manualFields.push('Additional role sign-offs');
+
+  return Object.freeze({
+    markdown,
+    industry,
+    prefilledFields: Object.freeze([...prefilledFields]),
+    manualFields: Object.freeze([...manualFields]),
+  });
+};