AuditReportGenerator
Audit Report Generator
Auto-generate structured GxP/regulatory audit reports from assessment data.
The Business Problem
Audit report writing is one of the most time-consuming and error-prone tasks in regulated industries. A typical GMP or ISO audit generates dozens of observations that must be:
- Classified by severity (Critical / Major / Minor / Observation)
- Linked to specific regulatory requirements and standards
- Supported by evidence and risk impact statements
- Assembled into a structured, signed-off audit report document
- Connected to a CAPA (Corrective and Preventive Action) tracking system
Manual report writing routinely takes 3–5 days per audit. In large organisations running 20–50 audits per year, this represents hundreds of person-hours of high-value QA/RA time. Reports vary in quality and completeness between auditors, and CAPA follow-through suffers from poor visibility.
Audit Report Generator (ARG) solves this. It ingests structured assessment data — audit scope, findings, evidence, CAPA plans — and auto-generates complete, print-ready audit reports with AI-written narrative sections, compliance scoring, risk matrices, and CAPA tracking dashboards.
What This Program Does
ARG is a domain-specific report automation platform built for regulated environments:
- Pharmaceutical and Biotech (FDA 21 CFR Part 211 / 820, EU GMP)
- Medical Device (ISO 13485:2016)
- Quality Management Systems (ISO 9001:2015)
- Supply Chain / API Suppliers (ICH Q7, ICH Q10)
Core Capabilities
| Feature | Description |
|---|---|
| Report Generation | Auto-generates 9-section audit reports from structured assessment data |
| Compliance Scoring | Weighted severity score (0–100%) across Critical / Major / Minor / Observation |
| Executive Summary | AI-written narrative tailored to finding pattern and audit type |
| Finding Classification | Cluster by area, severity, regulatory reference — risk matrix view |
| CAPA Tracking | Real-time status monitoring with overdue detection and closure rate analytics |
| Historical Audit Register | Full audit register with filtering by type, status, facility |
| REST API | Full JSON API for integration with QMS or LIMS systems |
| Print-Ready Reports | Report view with CSS print styling — save to PDF from browser |
Architecture
AuditReportGenerator/
├── data/
│ ├── ontology.py # Audit types, severities, standards, areas, CAPA statuses
│ └── mock_corpus.py # 10 audits, 47 findings, 22 CAPAs (GMP/ISO/Supplier)
├── engine/
│ ├── finding_classifier.py # Risk scoring, clustering, compliance score, priority ordering
│ ├── summary_engine.py # Auto-generates narrative sections (executive summary, etc.)
│ ├── capa_tracker.py # CAPA status assessment, overdue detection, closure analytics
│ └── report_generator.py # Orchestration — assembles full AuditReport dataclass
├── auditreport/
│ ├── model.py # SQLite persistence (4 tables: audits, findings, CAPAs, reports)
│ ├── app.py # Flask factory — browser routes + REST API
│ ├── seed.py # Seeds DB from mock corpus on first run
│ └── templates/ # 6 dark-theme Jinja2 templates
│ ├── base.html
│ ├── dashboard.html # Stats tiles + compliance chart + recent activity
│ ├── audits.html # Full audit register with filters
│ ├── audit_detail.html # Single audit — findings by severity + CAPA table
│ ├── report.html # Full 9-section generated report (print-ready)
│ ├── findings.html # All findings with severity/area filter
│ └── capa.html # CAPA tracker with effectiveness ratings
├── tests/ # 151 tests, 0 failures
│ ├── test_finding_classifier.py
│ ├── test_summary_engine.py
│ ├── test_capa_tracker.py
│ ├── test_report_generator.py
│ └── test_model.py
├── run.py
└── requirements.txt
Engine Modules
FindingClassifier
Classifies and scores audit findings.
from engine.finding_classifier import FindingClassifier
clf = FindingClassifier()
score = clf.compliance_score(findings) # 0–100 weighted score
rating = clf.compliance_rating(score) # "excellent"|"satisfactory"|"acceptable"|"marginal"|"unsatisfactory"
matrix = clf.risk_matrix(findings) # area → severity → count
clusters = clf.cluster_by_severity(findings) # {"Critical": [...], "Major": [...], ...}
ordered = clf.priority_order(findings) # sorted Critical → Observation
repeats = clf.repeat_findings(current, prior) # recurring finding detection
Compliance score formula:
score = 100 - Σ(severity_weight × finding_count)
Severity weights: Critical = 8.0, Major = 4.0, Minor = 1.5, Observation = 0.5
SummaryEngine
Auto-generates all narrative report sections.
from engine.summary_engine import SummaryEngine
eng = SummaryEngine()
summary = eng.executive_summary(audit, findings, capas) # multi-paragraph executive narrative
scope = eng.scope_statement(audit) # formal scope paragraph
method = eng.methodology_statement(audit) # methodology paragraph
obs = eng.key_observations(findings) # top-priority bullet observations
recs = eng.recommendations(findings, capas) # actionable recommendations list
concl = eng.conclusion(audit, findings, score) # formal conclusion paragraph
ctx = eng.regulatory_context(standard, findings) # regulatory mapping paragraph
CapaTracker
Tracks and assesses CAPA status.
from engine.capa_tracker import CapaTracker
tracker = CapaTracker()
statuses = tracker.assess_all(capas) # list[CapaStatus] with effectiveness_rating
overdue = tracker.overdue_capas(capas) # CAPAs past due date, not yet closed
rate = tracker.closure_rate(capas) # % closed
summary = tracker.capa_summary(capas) # {total, open, in_progress, completed, verified, overdue_count}
Effectiveness ratings: complete, on_track, at_risk, overdue, unstarted
ReportGenerator
Orchestrates full report assembly.
from engine.report_generator import ReportGenerator
gen = ReportGenerator()
report = gen.generate(audit, findings, capas) # → AuditReport dataclass
reports = gen.batch_generate(audits, all_findings, all_capas)
Mock Data
10 audits across a simulated multi-site pharmaceutical organisation:
| Audit ID | Type | Facility | Standard |
|---|---|---|---|
| AUD-2024-001 | GMP Internal | Philadelphia Manufacturing Plant | 21 CFR Part 211 |
| AUD-2024-002 | ISO 13485 | Baltimore Quality Site | ISO 13485:2016 |
| AUD-2024-003 | Supplier Qualification | ChemSource API Supplier | ICH Q7 |
| AUD-2024-004 | Regulatory Readiness | San Diego Sterile Fill Facility | 21 CFR Part 820 |
| AUD-2024-005 | GMP Internal | Chicago Bioprocessing Centre | 21 CFR Part 211 |
| AUD-2024-006 | GMP Internal | Houston Fill-Finish Plant | 21 CFR Part 211 |
| AUD-2024-007 | Supplier Qualification | Analytical Contract Lab Partners | ICH Q7 |
| AUD-2024-008 | GMP Internal | Boston Cell Therapy Site | 21 CFR Part 211 |
| AUD-2024-009 | CAPA Effectiveness | Philadelphia Manufacturing Plant | ICH Q10 |
| AUD-2024-010 | EU GMP | Baltimore Quality Site | EudraLex Vol 4 / Annex 16 |
47 Findings including real-world GMP deficiencies:
- Environmental monitoring action limit exceedances (aseptic suite)
- Sterility testing performed outside ISO 5 environment
- Batch release without QP authorization (EU GMP Annex 16)
- Supplier cold chain temperature monitoring gap (68-hour blackout)
- Water system revalidation 4 months overdue
- OOS investigation extended beyond 30-day target without management approval
- Reference standards expired — used for batch release testing
22 CAPAs with full root cause, corrective/preventive action narratives, and due date tracking.
API Reference
Browser Routes
| Route | Description |
|---|---|
GET / |
Dashboard — compliance chart, overdue CAPAs, recent findings |
GET /audits |
Full audit register with type/status filters |
GET /audit/<id> |
Audit detail — findings by severity, compliance score, CAPAs |
GET /audit/<id>/report |
Full 9-section generated report (print-ready) |
POST /audit/<id>/generate |
Generate/refresh report for audit |
GET /findings |
All findings with severity/area filters |
GET /capa |
CAPA tracker with overdue detection and effectiveness ratings |
POST /run_analysis |
Re-run full analysis for all audits |
REST API
# Audits
curl http://localhost:5107/api/v1/audits
curl "http://localhost:5107/api/v1/audits?type=GMP+Internal"
curl http://localhost:5107/api/v1/audit/AUD-2024-001
# Findings
curl http://localhost:5107/api/v1/findings
curl "http://localhost:5107/api/v1/findings?severity=Critical"
curl "http://localhost:5107/api/v1/findings?audit_id=AUD-2024-001"
# Reports
curl http://localhost:5107/api/v1/report/AUD-2024-001
curl -X POST http://localhost:5107/api/v1/report/AUD-2024-001/generate
# CAPAs
curl http://localhost:5107/api/v1/capas
curl "http://localhost:5107/api/v1/capas?status=Open"
# Stats
curl http://localhost:5107/api/v1/stats
curl -X POST http://localhost:5107/api/v1/run_analysis
Quick Start
git clone https://github.com/timjm25/AuditReportGenerator.git
cd AuditReportGenerator
pip install -r requirements.txt
python run.py
# → http://localhost:5107
The database seeds automatically on first request. No setup required.
Run tests:
python3 -m pytest tests/ -q
# 151 passed
Report Structure
Each auto-generated audit report contains 9 sections:
- Title Page — Audit ID, type, facility, auditor, compliance score, status
- Executive Summary — AI-written multi-paragraph narrative
- Audit Scope — Formal scope statement + areas audited
- Methodology — Audit approach and assessment techniques
- Regulatory Context — Standard reference + finding distribution
- Detailed Findings — Critical → Major → Minor → Observations with evidence and risk
- Key Observations — Priority-ordered bullet summary
- CAPA Summary — Status tiles + CAPA table with corrective action summaries
- Recommendations — Actionable next steps based on finding patterns
- Conclusion — Formal verdict + sign-off section
Reports include @media print CSS — use browser Print → Save as PDF to export.
Compliance Coverage
| Standard | Coverage |
|---|---|
| 21 CFR Part 211 | Manufacturing, QC, EM, Documentation, Training, CAPA, Equipment |
| 21 CFR Part 820 | Device design, process validation, complaints, CAPA |
| ISO 13485:2016 | QMS, management review, internal audit, CAPA, risk management |
| ISO 9001:2015 | Customer focus, process approach, improvement |
| ICH Q7 | API manufacturing, supplier qualification, laboratory controls |
| ICH Q10 | Pharmaceutical quality system, CAPA effectiveness |
| EudraLex Vol 4 | EU GMP, Annex 16 QP release, batch record requirements |
License
MIT License — free to use, modify, and distribute.
Built for pharmaceutical, biotech, and medical device organisations seeking to automate GxP audit reporting and CAPA management.