Copilot instructions

1---
2applyTo: "**/ai-models/**, **/model-cards/**, **/bedrock/**, **/sagemaker/**"
3description: "EU AI Act risk classification, ISO 42001 controls, model card authoring, audit trail requirements, and AI acceptable use policy for enterprise AI systems."
4---
5 
6# AI Governance — Copilot Instructions
7 
8> Applied automatically when working with AI model code, model cards, Bedrock, or SageMaker files. Loaded alongside copilot-instructions.md.
9 
10---
11 
12## EU AI Act Risk Tier Classification
13 
14Before deploying any AI system, classify it using the following tier table. Record the classification in the system's model card.
15 
16| Tier | Definition | Examples | Controls Required |
17|------|-----------|---------|------------------|
18| **Unacceptable Risk** | Banned — must not be deployed | Real-time biometric surveillance in public spaces; social scoring systems; subliminal manipulation | Do not build |
19| **High Risk** | Directly affects fundamental rights or safety | Credit scoring, employment screening, medical diagnosis, law enforcement, educational assessment, critical infrastructure control | Full HITL, audit trail, bias evaluation, model card, ARB + AI governance approval |
20| **Limited Risk** | Transparency obligations only | Chatbots, content recommendation, synthetic media | Disclosure to users, hallucination controls, model card recommended |
21| **Minimal Risk** | No specific obligation | Spam filters, AI game NPCs, basic document search | Best practices; model card optional |
22 
23### High-Risk Classification Examples for This Organisation
24 
25| System | EU AI Act Article | Classification |
26|--------|------------------|---------------|
27| Credit risk model | Art. 6(2), Annex III §5 | High Risk |
28| HR candidate ranking | Art. 6(2), Annex III §4 | High Risk |
29| Clinical decision support | Art. 6(2), Annex III §6 | High Risk |
30| Automated underwriting | Art. 6(2), Annex III §5 | High Risk |
31| Customer service chatbot | Art. 50 | Limited Risk |
32| Fraud detection (alert only) | Art. 6(2), Annex III §6 | High Risk |
33 
34---
35 
36## Mandatory Model Card Sections
37 
38Every AI system deployed to production must have a model card at `docs/ai-models/{system-name}/MODEL-CARD.md`. Use this template:
39 
40```markdown
41# Model Card: {System Name}
42 
43Version: {semver}
44Date: YYYY-MM-DD
45Status: Draft | Reviewed | Approved
46Owner: {team name}
47EU AI Act Tier: Unacceptable | High | Limited | Minimal
48ISO 42001 Review Completed: Yes | No | N/A
49 
50## System Overview
51 
52One paragraph: what does this system do, what decisions does it influence or automate?
53 
54## Intended Use
55 
56- **Primary use case:** {specific description}
57- **Intended users:** {who operates or is subject to this system}
58- **Deployment context:** {production environment description}
59 
60## Out-of-Scope Use
61 
62- Do not use for {specific misuse scenario 1}
63- Do not use for {specific misuse scenario 2}
64- Not validated for use with {excluded population or context}
65 
66## Training Data
67 
68- **Dataset:** {name, version, or description}
69- **Date range:** {earliest — latest}
70- **Size:** {number of samples}
71- **Source:** {internal systems | licensed | public — specify licence}
72- **PII included:** Yes (anonymised via {method}) | No
73- **Known biases:** {list any known demographic or contextual biases in the training data}
74 
75## Evaluation Results
76 
77| Metric | Value | Dataset | Notes |
78|--------|-------|---------|-------|
79| Accuracy | 0.94 | held-out test set (n=10,000) | |
80| Precision | 0.91 | held-out test set | |
81| Recall | 0.88 | held-out test set | |
82| F1 | 0.895 | held-out test set | |
83| p99 Latency | 180ms | production load test | SageMaker ml.m5.xlarge |
84| Faithfulness (RAG) | 0.82 | RAGAS evaluation set | Minimum threshold: 0.7 |
85 
86## Fairness Evaluation
87 
88Evaluated using **Amazon SageMaker Clarify** — results at `docs/ai-models/{name}/clarify-report/`.
89 
90| Demographic Group | Metric | Value | Acceptable Threshold | Pass/Fail |
91|------------------|--------|-------|---------------------|-----------|
92| Gender (Male vs Female) | Disparate Impact | 0.95 | ≥ 0.80 | Pass |
93| Age (< 30 vs ≥ 30) | Statistical Parity Difference | 0.03 | ≤ 0.10 | Pass |
94 
95## Known Limitations
96 
97- {Limitation 1 — be specific, e.g., "Performance degrades for non-English text; BLEU score drops 40% for Spanish input"}
98- {Limitation 2}
99- {Limitation 3}
100 
101## Ethical Considerations
102 
103- {List any ethical risks identified and how they are mitigated}
104- Human review required for: {list decision types that must be reviewed by a human}
105 
106## EU AI Act Compliance
107 
108- Conformity Assessment: {Internal | Third-party notified body} — Reference: {document ID}
109- Technical Documentation: `docs/ai-models/{name}/technical-documentation/`
110- Register Entry: EU AI Act Registration Number {number} (for High Risk)
111 
112## Contact and Governance
113 
114- System Owner: {name, email}
115- AI Ethics Review: ai-governance@{company}.com
116- Report issues: {Jira project or email}
117- Review cadence: Quarterly (model performance) | Annually (full governance review)
118```
119 
120---
121 
122## ISO 42001 Controls — Required Before Production Deployment
123 
124ISO 42001 defines an AI Management System (AIMS). The following controls are required for all production AI systems in this organisation:
125 
126| Control | ISO 42001 Reference | Verification |
127|---------|-------------------|-------------|
128| AI policy documented and approved | §5.2 | Document at `docs/ai-governance/ai-policy.md` |
129| Risk assessment completed | §6.1.2 | `ai-risk-assessment.prompt.md` output stored |
130| Objectives and KPIs defined | §6.2 | In model card Evaluation Results section |
131| Roles and responsibilities assigned | §5.3 | Model card Contact section completed |
132| Data governance documented | §8.4 | Data lineage and consent documented |
133| Monitoring and measurement active | §9.1 | SageMaker Model Monitor configured |
134| Internal audit scheduled | §9.2 | Quarterly review in calendar |
135| Nonconformity and corrective action process | §10.1 | AI incident classification process followed |
136 
137---
138 
139## Audit Trail Requirements
140 
141All High-Risk AI systems must emit **immutable audit log records** for every inference. Log to a write-once store (e.g., AWS CloudTrail Lake, S3 with Object Lock).
142 
143### Required Fields per Inference Record
144 
145```json
146{
147  "event_type": "ai_inference",
148  "model_id": "arn:aws:bedrock:eu-west-1::foundation-model/anthropic.claude-3-sonnet-20240229-v1:0",
149  "model_version": "3-sonnet-20240229-v1:0",
150  "system_id": "credit-risk-scoring-v2",
151  "input_hash_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
152  "output_hash_sha256": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
153  "user_id": "usr_abc123",
154  "session_id": "sess_xyz789",
155  "timestamp": "2024-11-01T14:30:00.000Z",
156  "latency_ms": 142,
157  "cost_tokens": { "input": 512, "output": 128 },
158  "decision_outcome": "APPROVED | DECLINED | REFERRED",
159  "hitl_reviewed": false,
160  "hitl_reviewer_id": null,
161  "jurisdiction": "GB"
162}
163```
164 
165- Do **not** log raw input or output — log hashes only (PII protection)
166- Retention: minimum 5 years for High-Risk systems (EU AI Act Article 12)
167- Logs must be exportable for regulatory inspection within 24 hours of request
168 
169---
170 
171## Human-in-the-Loop (HITL) Requirements
172 
173| EU AI Act Tier | HITL Required | Mode |
174|---------------|--------------|------|
175| High Risk | Mandatory | Meaningful oversight — human can override every decision |
176| Limited Risk | Recommended | Escalation path available |
177| Minimal Risk | Not required | — |
178 
179### HITL Implementation Pattern
180 
181- High-Risk systems must present a **confidence score** alongside every automated decision
182- If `confidence < 0.85`, the system must **automatically route to human review**
183- The human reviewer must be provided with the model's explanation (SHAP values or equivalent)
184- Override decisions must be logged with reviewer ID and reasoning
185- HITL override rate must be reported in quarterly model performance reviews
186 
187---
188 
189## Hallucination and Groundedness Thresholds (RAG Systems)
190 
191| Metric | Tool | Minimum Threshold | Action if Below |
192|--------|------|------------------|----------------|
193| Faithfulness | RAGAS | 0.70 | Block deployment; retune retrieval |
194| Answer Relevancy | RAGAS | 0.75 | Review prompt template; expand context window |
195| Context Precision | RAGAS | 0.65 | Improve chunking strategy or embedding model |
196| Context Recall | RAGAS | 0.70 | Increase top-k retrieval; review document preprocessing |
197 
198Run RAGAS evaluation as part of ML CI pipeline before every model version promotion.
199 
200---
201 
202## Bias Evaluation — SageMaker Clarify
203 
204Required for all systems used in: credit decisions, employment screening, healthcare triage, insurance underwriting.
205 
206```python
207# SageMaker Clarify bias configuration
208from sagemaker import clarify
209 
210clarify_processor = clarify.SageMakerClarifyProcessor(
211    role=role,
212    instance_count=1,
213    instance_type="ml.m5.xlarge",
214    sagemaker_session=session
215)
216 
217bias_config = clarify.BiasConfig(
218    label_values_or_threshold=[1],          # positive outcome value
219    facet_name="gender",                     # protected attribute
220    facet_values_or_threshold=["F"],         # group to evaluate
221    group_name="age_band"                    # intersectional analysis
222)
223 
224# Acceptable thresholds — fail CI if exceeded
225# DI (Disparate Impact): must be >= 0.80 (i.e., minority group ≥ 80% of majority group outcome rate)
226# SPD (Statistical Parity Difference): must be <= ±0.10
227# FTR (False Positive Rate difference): must be <= 0.05 for credit/employment decisions
228```
229 
230---
231 
232## AI Acceptable Use Policy Template
233 
234Include in `docs/ai-governance/acceptable-use-policy.md`:
235 
236```markdown
237## Prohibited Uses
238 
239- Generating content that impersonates a real person without consent
240- Automated decision-making on loan/employment/housing applications without HITL for edge cases
241- Processing special category personal data (health, biometrics, religion) without explicit consent
242- Generating synthetic training data from production PII without anonymisation review
243 
244## Required Disclosures
245 
246- Users must be informed when interacting with an AI system (chatbots, automated emails, scoring systems)
247- AI-generated content presented externally must be labelled as AI-generated
248 
249## Incident Reporting
250 
251Report AI incidents (bias discovered, model drift, unexpected outputs) via the AI incident register at {Jira project}.
252```
253 
254---
255 
256## AI Incident Classification
257 
258| Class | Definition | Response |
259|-------|-----------|---------|
260| AI-P1 | Discriminatory outcome confirmed; regulatory breach | Disable system immediately; notify DPO; ARB within 24h |
261| AI-P2 | Model drift detected (PSI > 0.2); significant accuracy degradation | Page on-call ML engineer; retrain within 48h |
262| AI-P3 | Evaluation metric dropped below threshold; unexpected output pattern | ML team investigates next business day |
263| AI-P4 | Isolated unusual output; no systemic pattern | Log in model card Known Limitations; review at next quarterly |
264