@complior/engine 0.9.0

package/src/domain/documents/worker-notification-generator.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from 'vitest';
+import { generateWorkerNotification } from './worker-notification-generator.js';
+import { createMockPassport } from '../../test-helpers/factories.js';
+
+const TEMPLATE = `# Template 4: Worker Notification of High-Risk AI Use
+
+**Obligation:** eu-ai-act-OBL-012
+**Article:** Article 26(7)
+**For:** Deployers (employers)
+**Format:** DOCX / PDF / Email
+
+## Document Structure:
+
+### 1. Header
+- From: [Company Name, HR Department / Management]
+- To: [Workers / Works Council / Union Representative]
+- Date: [Date]
+- Subject: Notification of High-Risk AI System Deployment per EU AI Act Article 26(7)
+
+### 2. Notification Body
+
+Dear [Workers / Works Council],
+
+In accordance with Article 26(7) of the EU Artificial Intelligence Act (Regulation (EU) 2024/1689), we hereby inform you that [Company Name] intends to deploy the following high-risk AI system(s) in the workplace:
+
+**AI System Details:**
+- System name: [Name]
+- Provider: [Provider name]
+- Purpose: [What the system does in plain language]
+- Deployment date: [Planned date]
+- Affected roles/departments: [List]
+
+**How the system works:**
+[Plain language description: what data it processes, what decisions/recommendations it makes, how it affects workers]
+
+**Your rights:**
+- Human oversight: All AI-assisted decisions are reviewed by [named person/role] before implementation
+- You have the right to request an explanation of any AI-influenced decision affecting you (Article 86)
+- You may lodge a complaint with [internal contact] or with the national market surveillance authority
+- Your personal data is processed in accordance with GDPR — see our privacy notice [link/reference]
+
+**Contact:**
+For questions or concerns about this AI system, please contact: [Name, Title, Email, Phone]
+
+Signed: [Management representative name and title]
+
+### 3. Acknowledgment
+- [ ] I acknowledge receipt of this notification
+- Employee name: _________________
+- Date: _________________
+- Signature: _________________
+`;
+
+describe('generateWorkerNotification', () => {
+  it('pre-fills system name from manifest', () => {
+    const result = generateWorkerNotification({ manifest: createMockPassport(), template: TEMPLATE });
+    expect(result.markdown).toContain('System name: Test Agent');
+    expect(result.prefilledFields).toContain('System name');
+  });
+
+  it('pre-fills provider from manifest', () => {
+    const result = generateWorkerNotification({ manifest: createMockPassport(), template: TEMPLATE });
+    expect(result.markdown).toContain('Provider: OpenAI');
+    expect(result.prefilledFields).toContain('Provider');
+  });
+
+  it('pre-fills purpose/description from manifest', () => {
+    const result = generateWorkerNotification({ manifest: createMockPassport(), template: TEMPLATE });
+    expect(result.markdown).toContain('Purpose: An AI agent for testing compliance');
+    expect(result.prefilledFields).toContain('Purpose');
+  });
+
+  it('pre-fills company name from owner.team when not provided', () => {
+    const result = generateWorkerNotification({ manifest: createMockPassport(), template: TEMPLATE });
+    expect(result.markdown).toContain('Acme Corp, HR Department / Management');
+    expect(result.markdown).toContain('Acme Corp intends to deploy');
+    expect(result.prefilledFields).toContain('Company Name');
+  });
+
+  it('uses explicit companyName over manifest.owner.team', () => {
+    const result = generateWorkerNotification({
+      manifest: createMockPassport(),
+      template: TEMPLATE,
+      companyName: 'Custom Inc',
+    });
+    expect(result.markdown).toContain('Custom Inc, HR Department / Management');
+    expect(result.markdown).toContain('Custom Inc intends to deploy');
+    expect(result.markdown).not.toContain('Acme Corp');
+  });
+
+  it('pre-fills human oversight from responsible_person', () => {
+    const result = generateWorkerNotification({ manifest: createMockPassport(), template: TEMPLATE });
+    expect(result.markdown).toContain('reviewed by Jane Doe before');
+    expect(result.prefilledFields).toContain('Human oversight person');
+  });
+
+  it('fills contact info when provided', () => {
+    const result = generateWorkerNotification({
+      manifest: createMockPassport(),
+      template: TEMPLATE,
+      contactName: 'John Smith',
+      contactEmail: 'john@acme.com',
+      contactPhone: '+1-555-0100',
+    });
+    expect(result.markdown).toContain('John Smith, john@acme.com, +1-555-0100');
+    expect(result.prefilledFields).toContain('Contact details');
+    expect(result.prefilledFields).toContain('Internal contact');
+  });
+
+  it('leaves manual fields as placeholders', () => {
+    const result = generateWorkerNotification({ manifest: createMockPassport(), template: TEMPLATE });
+    expect(result.manualFields).toContain('Worker impact description');
+    expect(result.manualFields).toContain('Management signature');
+    expect(result.manualFields).toContain('Employee acknowledgment');
+    expect(result.manualFields).toContain('Privacy notice reference');
+  });
+
+  it('fills deployment date when provided', () => {
+    const result = generateWorkerNotification({
+      manifest: createMockPassport(),
+      template: TEMPLATE,
+      deploymentDate: '2026-04-01',
+    });
+    expect(result.markdown).toContain('Deployment date: 2026-04-01');
+    expect(result.prefilledFields).toContain('Deployment date');
+    expect(result.manualFields).not.toContain('Deployment date');
+  });
+
+  it('returns correct prefilledFields/manualFields counts', () => {
+    const result = generateWorkerNotification({ manifest: createMockPassport(), template: TEMPLATE });
+    // Auto-filled: Company Name, Date, System name, Provider, Purpose, Human oversight person
+    expect(result.prefilledFields.length).toBeGreaterThanOrEqual(6);
+    // Manual: Deployment date, Affected roles, System description, Worker impact, Internal contact,
+    //         Contact details, Management signature, Recipients, Employee acknowledgment, Privacy notice
+    expect(result.manualFields.length).toBeGreaterThanOrEqual(8);
+  });
+
+  it('returns frozen result', () => {
+    const result = generateWorkerNotification({ manifest: createMockPassport(), template: TEMPLATE });
+    expect(Object.isFrozen(result)).toBe(true);
+    expect(Object.isFrozen(result.prefilledFields)).toBe(true);
+    expect(Object.isFrozen(result.manualFields)).toBe(true);
+  });
+
+  it('fills affected roles when provided', () => {
+    const result = generateWorkerNotification({
+      manifest: createMockPassport(),
+      template: TEMPLATE,
+      affectedRoles: 'Customer Support, Sales',
+    });
+    expect(result.markdown).toContain('Affected roles/departments: Customer Support, Sales');
+    expect(result.prefilledFields).toContain('Affected roles');
+    expect(result.manualFields).not.toContain('Affected roles');
+  });
+
+  it('fills date with current ISO date', () => {
+    const result = generateWorkerNotification({ manifest: createMockPassport(), template: TEMPLATE });
+    const today = new Date().toISOString().slice(0, 10);
+    expect(result.markdown).toContain(`Date: ${today}`);
+    expect(result.prefilledFields).toContain('Date');
+  });
+});

package/src/domain/documents/worker-notification-generator.ts

@@ -0,0 +1,141 @@
+import type { AgentPassport } from '../../types/passport.types.js';
+
+// --- Types ---
+
+export interface WorkerNotificationInput {
+  readonly manifest: AgentPassport;
+  readonly template: string;
+  readonly companyName?: string;
+  readonly contactName?: string;
+  readonly contactEmail?: string;
+  readonly contactPhone?: string;
+  readonly deploymentDate?: string;
+  readonly affectedRoles?: string;
+  readonly impactDescription?: string;
+}
+
+export interface WorkerNotificationResult {
+  readonly markdown: string;
+  readonly prefilledFields: readonly string[];
+  readonly manualFields: readonly string[];
+}
+
+// --- Helpers ---
+
+const deriveOversightPerson = (manifest: AgentPassport): string | undefined => {
+  if (manifest.owner.responsible_person) return manifest.owner.responsible_person;
+  if (manifest.autonomy_level === 'L1' || manifest.autonomy_level === 'L2') {
+    return 'the designated human supervisor';
+  }
+  return undefined;
+};
+
+const buildContactLine = (name?: string, email?: string, phone?: string): string | undefined => {
+  const parts = [name, email, phone].filter(Boolean);
+  return parts.length > 0 ? parts.join(', ') : undefined;
+};
+
+// --- Generator ---
+
+export const generateWorkerNotification = (input: WorkerNotificationInput): WorkerNotificationResult => {
+  const { manifest, template, companyName, contactName, contactEmail, contactPhone, deploymentDate, affectedRoles, impactDescription } = input;
+  const prefilledFields: string[] = [];
+  const manualFields: string[] = [];
+
+  let markdown = template;
+  const today = new Date().toISOString().slice(0, 10);
+
+  // 1. Company Name — use input or fall back to manifest.owner.team
+  const company = companyName ?? manifest.owner.team;
+  if (company) {
+    markdown = markdown.replaceAll('[Company Name, HR Department / Management]', `${company}, HR Department / Management`);
+    markdown = markdown.replaceAll('[Company Name]', company);
+    prefilledFields.push('Company Name');
+  } else {
+    manualFields.push('Company Name');
+  }
+
+  // 2. Date header
+  markdown = markdown.replaceAll('[Date]', today);
+  prefilledFields.push('Date');
+
+  // 3. System name
+  markdown = markdown.replace('System name: [Name]', `System name: ${manifest.display_name}`);
+  prefilledFields.push('System name');
+
+  // 4. Provider
+  markdown = markdown.replace('[Provider name]', manifest.model.provider);
+  prefilledFields.push('Provider');
+
+  // 5. Purpose / description
+  markdown = markdown.replace('[What the system does in plain language]', manifest.description);
+  prefilledFields.push('Purpose');
+
+  // 6. Deployment date
+  if (deploymentDate) {
+    markdown = markdown.replace('[Planned date]', deploymentDate);
+    prefilledFields.push('Deployment date');
+  } else {
+    manualFields.push('Deployment date');
+  }
+
+  // 7. Affected roles
+  if (affectedRoles) {
+    markdown = markdown.replace('Affected roles/departments: [List]', `Affected roles/departments: ${affectedRoles}`);
+    prefilledFields.push('Affected roles');
+  } else {
+    manualFields.push('Affected roles');
+  }
+
+  // 8. How the system works (impact description)
+  if (impactDescription) {
+    markdown = markdown.replace(
+      '[Plain language description: what data it processes, what decisions/recommendations it makes, how it affects workers]',
+      impactDescription,
+    );
+    prefilledFields.push('System description');
+  } else {
+    manualFields.push('System description (how it works)');
+  }
+
+  // 9. How it affects you — always manual (deployment-specific)
+  manualFields.push('Worker impact description');
+
+  // 10. Human oversight person
+  const oversightPerson = deriveOversightPerson(manifest);
+  if (oversightPerson) {
+    markdown = markdown.replace('[named person/role]', oversightPerson);
+    prefilledFields.push('Human oversight person');
+  } else {
+    manualFields.push('Human oversight person');
+  }
+
+  // 11. Internal contact for complaints
+  if (contactName) {
+    markdown = markdown.replace('[internal contact]', contactName);
+    prefilledFields.push('Internal contact');
+  } else {
+    manualFields.push('Internal contact');
+  }
+
+  // 12. Contact details block
+  const contactLine = buildContactLine(contactName, contactEmail, contactPhone);
+  if (contactLine) {
+    markdown = markdown.replace('[Name, Title, Email, Phone]', contactLine);
+    prefilledFields.push('Contact details');
+  } else {
+    manualFields.push('Contact details');
+  }
+
+  // 13-16. Always-manual fields
+  manualFields.push('Management signature');
+  manualFields.push('Recipients');
+  manualFields.push('Employee acknowledgment');
+  manualFields.push('Privacy notice reference');
+
+  return Object.freeze({
+    markdown,
+    prefilledFields: Object.freeze([...prefilledFields]),
+    manualFields: Object.freeze([...manualFields]),
+  });
+};

package/src/domain/eval/adapters/adapter-port.ts

@@ -0,0 +1,94 @@
+/**
+ * TargetAdapter port — interface for sending probes to external AI endpoints.
+ *
+ * Adapters translate generic probes into vendor-specific HTTP requests.
+ * The eval system never imports concrete adapters directly; everything
+ * goes through this contract.
+ */
+
+export interface TargetResponse {
+  readonly text: string;
+  readonly status: number;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly latencyMs: number;
+  readonly raw?: unknown;
+}
+
+export interface ProbeOptions {
+  readonly systemPrompt?: string;
+  readonly temperature?: number;
+  readonly maxTokens?: number;
+  readonly timeout?: number;
+}
+
+export interface TargetAdapter {
+  /** Send a single-turn probe. */
+  readonly send: (probe: string, options?: ProbeOptions) => Promise<TargetResponse>;
+  /** Send a multi-turn probe (main + follow-up). */
+  readonly sendMultiTurn: (probes: readonly string[], options?: ProbeOptions) => Promise<readonly TargetResponse[]>;
+  /** Check if the target is reachable. */
+  readonly checkHealth: () => Promise<boolean>;
+  /** Human-readable adapter name (e.g. "openai", "ollama"). */
+  readonly name: string;
+}
+
+// ── Error & resilience helpers ──────────────────────────────────
+
+/** Error with HTTP status code for retry logic. */
+export class AdapterError extends Error {
+  constructor(readonly statusCode: number, message: string) {
+    super(message);
+    this.name = 'AdapterError';
+  }
+  get retryable(): boolean {
+    return this.statusCode === 429 || this.statusCode >= 500;
+  }
+}
+
+/**
+ * Safely parse JSON from a fetch Response.
+ * Throws AdapterError with descriptive message for non-JSON or error responses.
+ */
+export const safeJsonParse = async (res: Response): Promise<Record<string, unknown>> => {
+  if (!res.ok) {
+    // Try JSON error body first, fall back to text snippet
+    try {
+      const body = await res.json() as Record<string, unknown>;
+      const msg = body && typeof body === 'object' && 'error' in body
+        ? JSON.stringify(body.error)
+        : JSON.stringify(body);
+      throw new AdapterError(res.status, `API error ${res.status}: ${msg}`);
+    } catch (e) {
+      if (e instanceof AdapterError) throw e;
+      // json() failed — response is HTML or other non-JSON
+      throw new AdapterError(res.status, `API error ${res.status}: non-JSON response`);
+    }
+  }
+
+  // 2xx — parse as JSON
+  try {
+    return await res.json() as Record<string, unknown>;
+  } catch {
+    throw new AdapterError(res.status, `Non-JSON response body from ${res.status} response`);
+  }
+};
+
+/**
+ * Retry a function on retryable AdapterErrors (429, 5xx).
+ * Exponential backoff: 1s, 2s (default). Max 2 retries.
+ */
+export const withRetry = async <T>(
+  fn: () => Promise<T>,
+  maxRetries = 2,
+  baseDelayMs = 1000,
+): Promise<T> => {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (attempt >= maxRetries || !(err instanceof AdapterError) || !err.retryable) throw err;
+      const delay = baseDelayMs * Math.pow(2, attempt);
+      await new Promise((r) => setTimeout(r, delay));
+    }
+  }
+};