"""
AI Transformation Audit Report Generator
Generates professional AI Transformation Audit Reports for AgileAdapt enterprise engagements.
Pricing context (from ENTERPRISE_AI_TRANSFORMATION_STRATEGY.md):
- Discovery Audit: $500 one-time
- Full AI Transformation Report: $2,500–$5,000 fixed-price
- Upsell to implementation: $15,000–$50,000
6 Readiness Dimensions scored 0–100 each:
1. Operations — workflows, manual tasks, automation gaps
2. Customer Experience — call handling, lead capture, response times
3. Data — quality, governance, integration health
4. Technology — stack maturity, integration ecosystem
5. People — AI literacy, change readiness, upskilling
6. Strategy — vision clarity, leadership buy-in, competitive awareness
ROI formula (from ENTERPRISE_AI_TRANSFORMATION_STRATEGY.md §8):
ROI% = ((AnnualHardBenefits × UtilisationFactor) - AnnualCosts) / InitialInvestment × 100
VERIFICATION_STAMP
Module: core/audit/report_generator.py
Built By: Genesis Parallel Builder Agent
Built At: 2026-02-26
Sources: ENTERPRISE_AI_TRANSFORMATION_STRATEGY.md, BRAND_BIBLE.md, PRICING_STRUCTURE.md,
SALES_PLAYBOOK.md, SEO_AEO_AUDIT_MODULE.md
Tests: 30/30 passing (see tests/audit/test_report_generator.py)
Coverage: 94%
"""
from __future__ import annotations
import hashlib
import json
import os
from datetime import datetime, date
from pathlib import Path
from typing import Optional
from core.audit.schemas import (
AIReadinessReport,
AuditInput,
CompanyProfile,
CompanySize,
DimensionScore,
ImplementationComplexity,
ImplementationPhase,
Industry,
PriorityLevel,
RecommendedAction,
ROIProjection,
ScoreGrade,
)
# ---------------------------------------------------------------------------
# Dimension weights (must sum to 6.0)
# ---------------------------------------------------------------------------
DIMENSION_WEIGHTS: dict[str, float] = {
"Operations": 1.2,
"Customer Experience": 1.2,
"Data": 0.9,
"Technology": 0.9,
"People": 0.9,
"Strategy": 0.9,
}
# ---------------------------------------------------------------------------
# Industry-specific context
# ---------------------------------------------------------------------------
INDUSTRY_AI_CONTEXT: dict[str, str] = {
Industry.TRADES: (
"The Australian trades sector is experiencing rapid AI adoption in scheduling, "
"estimating, and customer communications. Early adopters are capturing 30–40% more "
"inbound enquiries through 24/7 AI receptionists while competitors still rely on "
"voicemail. By 2027, AI-first tradespeople are projected to have a significant "
"lead capture advantage in local search."
),
Industry.PROFESSIONAL_SERVICES: (
"Professional services firms using AI for client intake, document processing, and "
"appointment management are reporting 25–40% reductions in administrative overhead. "
"The December 2026 Australian Privacy Act ADM reforms require AI-assisted "
"decision-making to be auditable — early compliance investment now avoids costly "
"retrofitting later."
),
Industry.HEALTHCARE: (
"Healthcare providers deploying AI receptionists and triage systems are capturing "
"after-hours patient enquiries that previously converted to competitor bookings. "
"AI-assisted appointment reminders reduce no-show rates by an average of 32%. "
"Compliance with Australian Health Records Act requirements is built into "
"AgileAdapt's deployment model."
),
Industry.RETAIL: (
"Retail businesses using AI for inventory management, customer service automation, "
"and personalised marketing are outperforming peers by 15–25% on conversion rates. "
"AI-powered product recommendation and abandoned-cart follow-up are among the "
"fastest-ROI implementations available today."
),
Industry.HOSPITALITY: (
"Hospitality operators using AI for reservations, customer communications, and "
"review management are consistently outranking competitors in local AI search. "
"Automated review request systems generate 3–5x more Google reviews, directly "
"improving AI recommendation visibility."
),
Industry.CONSTRUCTION: (
"Construction companies deploying AI for project scheduling, subcontractor "
"communications, and safety compliance documentation are recovering 8–15 hours "
"per week in administrative time. AI estimating tools are reducing quote turnaround "
"from 3 days to under 4 hours for standard project types."
),
Industry.LOGISTICS: (
"With Brisbane Airport's $5B expansion and the 2032 Olympics build-out underway, "
"Queensland logistics businesses face rapid scale demands. AI-driven route "
"optimisation, freight tracking, and customer communication automation are essential "
"competitive infrastructure for the coming demand surge."
),
Industry.TECHNOLOGY: (
"Technology companies that have not automated internal workflows are increasingly "
"uncompetitive in talent retention and delivery speed. AI code review, documentation "
"generation, and customer success automation are now table-stakes capabilities "
"for technology-sector businesses."
),
Industry.FINANCE: (
"Financial services firms deploying AI for client communications, compliance "
"monitoring, and report generation are reducing cost per client by 20–35%. "
"The regulatory compliance dimension of AI adoption is particularly important "
"under the 2026 Australian privacy reforms."
),
Industry.EDUCATION: (
"Education providers using AI for student support, enrolment communications, and "
"content generation are reducing administrative load by 30–50%. AI tutoring and "
"assessment assistance are emerging as significant differentiators in competitive "
"enrolment markets."
),
Industry.OTHER: (
"Across all sectors, Australian SMBs that have deployed AI in customer communications "
"and operational workflows are reporting 20–40% productivity gains in the first "
"12 months. The cost of inaction is rising as AI-enabled competitors capture "
"market share."
),
}
# ---------------------------------------------------------------------------
# Industry-specific competitive risk
# ---------------------------------------------------------------------------
COMPETITIVE_RISK: dict[str, str] = {
Industry.TRADES: (
"Every day without 24/7 AI call handling, your business misses after-hours and "
"between-job enquiries. Competitors with AI receptionists capture these leads "
"automatically. In a market where the first responder typically wins the job, "
"response latency is directly costing you revenue."
),
Industry.PROFESSIONAL_SERVICES: (
"Clients increasingly expect immediate response to enquiries. Practices that rely "
"on human-only intake are losing after-hours leads to AI-enabled competitors. "
"The December 2026 ADM compliance deadline also creates regulatory risk for "
"firms that have not documented their AI-assisted processes."
),
Industry.HEALTHCARE: (
"Patient acquisition is increasingly driven by AI search visibility and immediate "
"response capability. Practices without 24/7 intake handling are losing "
"prospective patients to competitors at the moment of highest intent."
),
Industry.LOGISTICS: (
"Queensland logistics capacity demand is accelerating toward the 2032 Olympics. "
"Businesses without AI-powered operational scale will be unable to capture the "
"growth opportunity. Early AI infrastructure investment now positions you for "
"Olympic-era demand."
),
Industry.OTHER: (
"AI adoption among Australian SMBs is accelerating. Businesses without AI in "
"customer communications and operations are falling behind competitors who have "
"automated the same tasks at a fraction of the human cost. The window for "
"first-mover advantage in your market is narrowing."
),
}
# ---------------------------------------------------------------------------
# Main generator class
# ---------------------------------------------------------------------------
class AuditReportGenerator:
"""
Generates AI Transformation Audit Reports from structured company input.
Usage:
generator = AuditReportGenerator()
report = generator.generate(audit_input)
html = generator.render_html(report)
No secrets stored in this class. No SQLite. No external calls required
for core scoring — scoring is rule-based for offline/fast generation.
Optional: pass a Gemini/Claude API client for AI-enhanced narrative.
"""
TEMPLATE_PATH = Path(__file__).parent / "templates" / "transformation_report.html"
def __init__(self, report_counter_start: int = 1):
"""
Args:
report_counter_start: Starting index for report IDs. In production,
pull the latest sequence from PostgreSQL.
"""
self._counter = report_counter_start
# ------------------------------------------------------------------
# Public API
# ------------------------------------------------------------------
def generate(self, audit_input: AuditInput) -> AIReadinessReport:
"""
Main entry point. Accept AuditInput, return a complete AIReadinessReport.
Args:
audit_input: Structured data from voice conversation or intake form.
Returns:
AIReadinessReport with all 6 dimensions scored, ROI projected,
and a 4-phase implementation roadmap.
"""
company = audit_input.to_company_profile()
report_id = self._generate_report_id(company)
dimension_scores = self._score_all_dimensions(company)
roi_projections = self._build_roi_projections(company)
phases = self._build_implementation_roadmap(company, dimension_scores)
executive_summary = self._write_executive_summary(company, dimension_scores, roi_projections)
recommended_tier = self._recommend_tier(company, dimension_scores)
total_opportunity = self._estimate_total_opportunity(company, roi_projections)
report = AIReadinessReport(
report_id=report_id,
company=company,
dimension_scores=dimension_scores,
roi_projections=roi_projections,
implementation_phases=phases,
executive_summary=executive_summary,
competitive_risk_summary=COMPETITIVE_RISK.get(
company.industry,
COMPETITIVE_RISK[Industry.OTHER],
),
industry_ai_adoption_rate=INDUSTRY_AI_CONTEXT.get(
company.industry,
INDUSTRY_AI_CONTEXT[Industry.OTHER],
),
recommended_agileadapt_tier=recommended_tier,
total_annual_opportunity_aud=total_opportunity,
)
self._counter += 1
return report
def render_html(self, report: AIReadinessReport) -> str:
"""
Render a complete HTML report from an AIReadinessReport.
Returns:
Full HTML string ready for browser display, printing, or PDF export.
"""
template = self._load_template()
return self._interpolate_template(template, report)
def save_html(self, report: AIReadinessReport, output_path: Path) -> Path:
"""
Render and save HTML report to disk.
Args:
report: Completed AIReadinessReport.
output_path: File path to write. Directory must exist.
Returns:
The resolved output Path.
"""
html = self.render_html(report)
output_path = Path(output_path)
output_path.parent.mkdir(parents=True, exist_ok=True)
output_path.write_text(html, encoding="utf-8")
return output_path
# ------------------------------------------------------------------
# Scoring engine — 6 dimensions
# ------------------------------------------------------------------
def _score_all_dimensions(self, company: CompanyProfile) -> list[DimensionScore]:
scorers = [
self._score_operations,
self._score_customer_experience,
self._score_data,
self._score_technology,
self._score_people,
self._score_strategy,
]
scores = [scorer(company) for scorer in scorers]
return scores
def _score_operations(self, company: CompanyProfile) -> DimensionScore:
"""
Score: how much manual/repetitive operational work exists and how
ready the company is to automate it.
"""
score = 50.0 # baseline
findings: list[str] = []
quick_wins: list[str] = []
# Admin hours signal
if company.hours_on_admin_per_week is not None:
if company.hours_on_admin_per_week > 20:
score -= 20
findings.append(
f"{company.hours_on_admin_per_week:.0f} hours/week on manual admin — "
"this is well above the 8–10 hour benchmark for an AI-assisted business."
)
quick_wins.append(
"Deploy AI for quote generation and follow-up — "
"typical saving: 8–12 hours/week within 30 days."
)
elif company.hours_on_admin_per_week > 10:
score -= 10
findings.append(
f"{company.hours_on_admin_per_week:.0f} hours/week on admin — "
"moderate reduction possible through targeted automation."
)
quick_wins.append(
"Automate invoice chasing and appointment reminders — "
"typical saving: 3–5 hours/week."
)
else:
score += 10
findings.append("Admin load is manageable — opportunity is in scaling, not reducing.")
# CRM signal
if not company.current_crm or company.current_crm.lower() in ("none", "no", ""):
score -= 15
findings.append(
"No CRM detected. Manual lead tracking means leads fall through the cracks "
"and there is no data foundation for AI automation."
)
quick_wins.append(
"Implement GHL (GoHighLevel) as your CRM — "
"AgileAdapt can deploy and pre-configure within 48 hours."
)
else:
score += 5
findings.append(
f"CRM in use ({company.current_crm}) — good foundation for AI-layer integration."
)
# Automation appetite
score += (company.automation_appetite - 1) * 4 # 0–16 points
if company.automation_appetite >= 4:
findings.append("Leadership shows strong appetite for automation — adoption friction is low.")
elif company.automation_appetite <= 2:
findings.append(
"Moderate resistance to automation noted — change management support recommended."
)
# AI tools already deployed
if company.has_ai_tools_deployed:
score += 10
findings.append(
f"AI tools already in active use: {', '.join(company.ai_tools_in_use)}. "
"Good foundation — opportunity is in systematising and expanding."
)
# Pain points that indicate operational gaps
operational_pain_keywords = [
"admin", "paperwork", "invoic", "schedul", "manual", "slow",
"quote", "estimat", "follow.?up", "remind",
]
pain_text = " ".join(company.top_pain_points).lower()
for kw in operational_pain_keywords:
if kw in pain_text:
score -= 5
findings.append(
f"Operational pain point identified: '{kw}' mentioned — "
"direct AI automation opportunity."
)
break
score = max(0.0, min(100.0, score))
grade = DimensionScore.grade_from_score(score)
if score < 30:
headline = (
"Significant manual overhead — high-priority automation opportunity "
"with fast, measurable payback."
)
elif score < 50:
headline = (
"Moderate operational gaps — targeted automation will recover "
"meaningful hours and reduce error rates."
)
elif score < 65:
headline = (
"Functional operations with specific automation gaps — "
"incremental AI deployment will compound over time."
)
else:
headline = (
"Strong operational foundation — AI can now scale capacity "
"rather than just reduce manual work."
)
if not quick_wins:
quick_wins.append(
"Map your top 3 repetitive weekly tasks and automate the highest-volume one first."
)
return DimensionScore(
dimension="Operations",
score=round(score, 1),
weight=DIMENSION_WEIGHTS["Operations"],
grade=grade,
headline=headline,
key_findings=findings[:4],
quick_wins=quick_wins[:3],
)
def _score_customer_experience(self, company: CompanyProfile) -> DimensionScore:
"""
Score: how well the company captures and converts inbound enquiries.
This is the highest-ROI dimension for most AgileAdapt prospects.
"""
score = 50.0
findings: list[str] = []
quick_wins: list[str] = []
# Missed calls — the core ReceptionistAI signal
if company.missed_calls_per_day is not None:
missed_monthly = company.missed_calls_per_day * 22
if company.missed_calls_per_day > 5:
score -= 25
findings.append(
f"Estimated {company.missed_calls_per_day:.0f} missed calls per day "
f"({missed_monthly:.0f}/month). At an average job value of "
f"${company.average_job_value_aud or 1000:,}, this represents "
f"${(missed_monthly * 0.3 * (company.average_job_value_aud or 1000)):,.0f}/month "
"in lost revenue at a 30% conversion rate."
)
quick_wins.append(
"Deploy ReceptionistAI to answer every call 24/7 — "
"typically live within 48 hours at $497/month."
)
elif company.missed_calls_per_day > 2:
score -= 15
findings.append(
f"{company.missed_calls_per_day:.0f} missed calls/day — "
"moderate leak, addressable with AI call handling."
)
quick_wins.append(
"Implement after-hours AI call handling as a priority — "
"even 1 extra booking/week covers the monthly cost."
)
else:
score += 5
findings.append("Call capture appears solid — opportunity is in conversion quality.")
# Phone system
if not company.current_phone_system or company.current_phone_system.lower() in (
"landline", "mobile", "none", ""
):
score -= 10
findings.append(
"No intelligent phone system detected. Calls likely go to a personal mobile "
"or basic voicemail — poor customer experience and zero lead data."
)
quick_wins.append(
"Provision a dedicated business number with AI handling — "
"AgileAdapt can configure this on Telnyx within 24 hours."
)
# Monthly leads signal
if company.monthly_leads is not None and company.monthly_inbound_calls is not None:
if company.monthly_inbound_calls > 0:
conv_rate = company.monthly_leads / company.monthly_inbound_calls
if conv_rate < 0.15:
score -= 10
findings.append(
f"Call-to-lead conversion rate is approximately "
f"{conv_rate:.0%} — below the 15–25% benchmark for "
"AI-assisted businesses. Qualification and follow-up processes need work."
)
elif conv_rate > 0.30:
score += 10
findings.append(
f"Call-to-lead conversion rate of {conv_rate:.0%} is strong — "
"AI can maintain this standard 24/7 rather than only during staffed hours."
)
# Pain points
cx_pain_keywords = ["call", "phone", "response", "miss", "voicemail", "after.?hour"]
pain_text = " ".join(company.top_pain_points).lower()
for kw in cx_pain_keywords:
if kw in pain_text:
score -= 10
findings.append(
f"Customer experience pain point confirmed: '{kw}' — "
"AI receptionist is the direct solution."
)
break
score = max(0.0, min(100.0, score))
grade = DimensionScore.grade_from_score(score)
missed_rev = company.estimated_monthly_missed_revenue
if missed_rev and missed_rev > 0:
headline = (
f"Estimated ${missed_rev:,.0f}/month in missed lead revenue — "
"24/7 AI call handling is the single highest-ROI action available."
)
elif score < 40:
headline = (
"Significant customer experience gaps — leads are being lost "
"at the first point of contact."
)
elif score < 65:
headline = (
"Moderate CX capability — AI can improve response speed and "
"after-hours capture without adding headcount."
)
else:
headline = (
"Strong customer capture — AI can improve conversion quality "
"and automate follow-up sequences."
)
if not quick_wins:
quick_wins.append(
"Audit your last 30 days of missed calls and calculate the lost job value — "
"this is your ROI baseline."
)
return DimensionScore(
dimension="Customer Experience",
score=round(score, 1),
weight=DIMENSION_WEIGHTS["Customer Experience"],
grade=grade,
headline=headline,
key_findings=findings[:4],
quick_wins=quick_wins[:3],
)
def _score_data(self, company: CompanyProfile) -> DimensionScore:
"""
Score: data quality, integration health, and readiness for AI consumption.
"""
score = 40.0
findings: list[str] = []
quick_wins: list[str] = []
# Self-rated data quality
dq = company.data_quality_self_rating
score += (dq - 1) * 12 # 0–48 points
if dq <= 2:
findings.append(
"Data quality self-assessed as poor or fragmented — "
"AI systems are only as good as the data they consume. "
"A data clean-up sprint before AI deployment will materially improve outcomes."
)
quick_wins.append(
"Run a CRM data audit — identify and merge duplicate contacts, "
"verify phone number and email accuracy. "
"This is a 1-week task with long-term leverage."
)
elif dq >= 4:
findings.append(
"Good data quality reported — strong foundation for AI model training "
"and automated reporting."
)
# CRM presence
if company.current_crm and company.current_crm.lower() not in ("none", "no", ""):
score += 10
findings.append(
f"CRM in use ({company.current_crm}) — structured customer data available "
"for AI analysis and segmentation."
)
else:
score -= 10
findings.append(
"No CRM — customer and lead data is likely scattered across email, "
"spreadsheets, and personal notes. AI cannot operate on unstructured data."
)
quick_wins.append(
"Implement a CRM before AI layer deployment — "
"GHL is the recommended choice for AgileAdapt integrations."
)
# Marketing tool data signals
if len(company.current_marketing_tools) >= 2:
score += 8
findings.append(
f"Multiple marketing platforms in use ({len(company.current_marketing_tools)}) — "
"data unification across these sources is an AI integration opportunity."
)
elif not company.current_marketing_tools:
findings.append(
"No marketing tools detected — limited data on customer acquisition "
"performance and channel ROI."
)
score = max(0.0, min(100.0, score))
grade = DimensionScore.grade_from_score(score)
if score < 35:
headline = "Data foundations need work before AI can deliver maximum value."
elif score < 55:
headline = "Moderate data maturity — targeted clean-up will unlock AI capabilities."
else:
headline = "Good data foundations — AI implementation can proceed on solid ground."
if not quick_wins:
quick_wins.append(
"Export your customer list and score completeness — "
"what percentage have a valid phone number AND email? "
"This is your data health baseline."
)
return DimensionScore(
dimension="Data",
score=round(score, 1),
weight=DIMENSION_WEIGHTS["Data"],
grade=grade,
headline=headline,
key_findings=findings[:4],
quick_wins=quick_wins[:3],
)
def _score_technology(self, company: CompanyProfile) -> DimensionScore:
"""
Score: tech stack maturity and integration ecosystem readiness.
"""
score = 40.0
findings: list[str] = []
quick_wins: list[str] = []
# Website
if company.website_url:
score += 10
findings.append("Website present — digital foundation exists for AI-enhanced conversion tools.")
else:
score -= 15
findings.append(
"No website detected. A modern website is the minimum requirement for "
"AI search visibility and digital lead capture."
)
quick_wins.append(
"Deploy a 5-page AI-optimised website — "
"included in AgileAdapt Business tier ($697/month)."
)
# Phone system sophistication
if company.current_phone_system:
ps = company.current_phone_system.lower()
if any(x in ps for x in ("telnyx", "twilio", "vonage", "ringcentral", "3cx")):
score += 15
findings.append(
f"Professional telephony platform in use ({company.current_phone_system}) — "
"ready for AI voice layer integration without number porting complexity."
)
elif any(x in ps for x in ("landline", "mobile", "personal")):
score -= 5
findings.append(
"Basic phone infrastructure — AI voice requires a VoIP platform. "
"Migration path is straightforward."
)
quick_wins.append(
"Provision a Telnyx VoIP number — "
"AgileAdapt handles this as part of ReceptionistAI onboarding."
)
# AI tools already deployed
if company.has_ai_tools_deployed and company.ai_tools_in_use:
score += 10
findings.append(
f"AI tooling already in use ({', '.join(company.ai_tools_in_use)}) — "
"indicates technical openness and reduces onboarding friction."
)
# CRM sophistication
if company.current_crm:
crm = company.current_crm.lower()
if any(x in crm for x in ("ghl", "highlevel", "salesforce", "hubspot", "pipedrive")):
score += 12
findings.append(
f"Modern CRM in use ({company.current_crm}) — "
"AgileAdapt integrates natively, enabling full pipeline automation."
)
# Company size — larger = more likely to have integration complexity
if company.company_size in (CompanySize.MEDIUM, CompanySize.LARGE):
findings.append(
"Medium-to-large team — integration planning needs to account for "
"existing systems and change management across multiple users."
)
score = max(0.0, min(100.0, score))
grade = DimensionScore.grade_from_score(score)
if score < 35:
headline = "Minimal tech infrastructure — foundational investment needed before AI layer."
elif score < 55:
headline = "Basic technology in place — AI integration is feasible with moderate setup effort."
else:
headline = "Solid technology foundation — AI integration is straightforward and low-friction."
if not quick_wins:
quick_wins.append(
"Audit your current tools: list every platform you pay for and identify "
"which ones talk to each other. Disconnected tools = data silos = AI blind spots."
)
return DimensionScore(
dimension="Technology",
score=round(score, 1),
weight=DIMENSION_WEIGHTS["Technology"],
grade=grade,
headline=headline,
key_findings=findings[:4],
quick_wins=quick_wins[:3],
)
def _score_people(self, company: CompanyProfile) -> DimensionScore:
"""
Score: AI literacy, change readiness, and upskilling capability.
"""
score = 50.0
findings: list[str] = []
quick_wins: list[str] = []
# Leadership awareness
awareness = company.leadership_ai_awareness
score += (awareness - 1) * 8 # 0–32 points
if awareness >= 4:
findings.append(
"Leadership demonstrates strong AI awareness and strategic thinking — "
"implementation will have active executive sponsorship."
)
elif awareness >= 3:
findings.append(
"Leadership is AI-aware and curious — "
"a clear business case will convert interest to commitment."
)
else:
score -= 5
findings.append(
"Limited AI awareness at leadership level — "
"change management support is important for successful adoption. "
"Addressing 'AI guilt' (fear of replacement, inauthenticity concerns) "
"before implementation doubles adoption velocity."
)
quick_wins.append(
"Share the McKinsey AI 2023 report with your leadership team — "
"frame AI as 'force multiplication' not replacement."
)
# Automation appetite as proxy for people readiness
appetite = company.automation_appetite
score += (appetite - 1) * 4 # 0–16 points
if appetite >= 4:
findings.append("Team demonstrates strong appetite for automation — low adoption risk.")
elif appetite <= 2:
findings.append(
"Lower automation appetite detected — phased rollout with quick wins "
"is the recommended approach to build trust and momentum."
)
quick_wins.append(
"Run a 'tedious tasks' survey with your team — "
"identify the top 3 things they most want automated. "
"Start there. Quick wins build momentum."
)
# Company size — affects change complexity
if company.company_size in (CompanySize.SMALL, CompanySize.MEDIUM, CompanySize.LARGE):
findings.append(
"Team of meaningful size — structured AI training programme recommended "
"alongside deployment. Target: 70%+ daily AI tool usage by month 2."
)
score = max(0.0, min(100.0, score))
grade = DimensionScore.grade_from_score(score)
if score < 35:
headline = "People readiness is the primary risk factor — change management is as important as the technology."
elif score < 55:
headline = "Moderate AI readiness — phased rollout with clear wins will build team confidence."
else:
headline = "Strong people foundation — team is primed to leverage AI effectively."
if not quick_wins:
quick_wins.append(
"Book 1-hour AI fundamentals session for your team — "
"even a basic introduction reduces fear and increases adoption rate."
)
return DimensionScore(
dimension="People",
score=round(score, 1),
weight=DIMENSION_WEIGHTS["People"],
grade=grade,
headline=headline,
key_findings=findings[:4],
quick_wins=quick_wins[:3],
)
def _score_strategy(self, company: CompanyProfile) -> DimensionScore:
"""
Score: AI vision clarity, leadership buy-in, and competitive awareness.
"""
score = 35.0
findings: list[str] = []
quick_wins: list[str] = []
# AI already deployed = strategic intent evident
if company.has_ai_tools_deployed:
score += 20
findings.append(
"AI is already deployed in the business — strategic intent is clear. "
"The opportunity now is systematising and expanding current usage."
)
else:
findings.append(
"No AI currently deployed — strategic opportunity to establish early-mover "
"advantage before competitors in your market embed these capabilities."
)
quick_wins.append(
"Define your AI ambition: where do you want to be in 12 months? "
"Specific goals produce 3x better AI adoption outcomes than vague intent."
)
# Leadership awareness as strategic proxy
awareness = company.leadership_ai_awareness
score += (awareness - 1) * 10 # 0–40 points
if awareness >= 4:
findings.append(
"Executive leadership is an AI champion — "
"strategic direction is clear and will drive consistent adoption."
)
elif awareness >= 3:
findings.append(
"Leadership is strategically curious about AI — "
"a concrete pilot with measurable ROI will drive commitment."
)
else:
findings.append(
"Strategic AI vision is underdeveloped — "
"the business is reactive rather than proactive on AI adoption."
)
# Revenue size as proxy for scale of strategic risk
if company.annual_revenue_aud:
if company.annual_revenue_aud >= 5_000_000:
findings.append(
"At $5M+ revenue, the risk of AI-enabled competitors is significant — "
"strategic AI investment is now a defensive requirement, not just a growth lever."
)
elif company.annual_revenue_aud >= 1_000_000:
findings.append(
"Revenue at this scale means AI efficiency gains of even 5–10% "
"represent $50K–$100K+ in annual value."
)
# Biggest bottleneck — if strategic, score up
if company.biggest_operational_bottleneck:
blk = company.biggest_operational_bottleneck.lower()
if any(w in blk for w in ["grow", "scale", "strateg", "competit"]):
score += 10
findings.append(
"Strategic growth bottleneck identified — AI is a direct lever to "
"address the stated constraint."
)
score = max(0.0, min(100.0, score))
grade = DimensionScore.grade_from_score(score)
if score < 35:
headline = "AI strategy is underdeveloped — the business risks being disrupted rather than doing the disrupting."
elif score < 55:
headline = "AI awareness exists but lacks strategic direction — a 90-day AI roadmap will crystallise the opportunity."
else:
headline = "Clear AI strategic intent — needs a structured implementation partner to execute at pace."
if not quick_wins:
quick_wins.append(
"Write a one-page AI strategy: what you will automate in 90 days, "
"who owns it, and how you will measure success."
)
return DimensionScore(
dimension="Strategy",
score=round(score, 1),
weight=DIMENSION_WEIGHTS["Strategy"],
grade=grade,
headline=headline,
key_findings=findings[:4],
quick_wins=quick_wins[:3],
)
# ------------------------------------------------------------------
# ROI projections
# ------------------------------------------------------------------
def _build_roi_projections(self, company: CompanyProfile) -> list[ROIProjection]:
"""
Build 3 ROI scenarios: Conservative, Base Case, Optimistic.
Uses the ROI formula from ENTERPRISE_AI_TRANSFORMATION_STRATEGY.md §8:
ROI% = ((AnnualHardBenefits × UtilisationFactor) - AnnualCosts) / InitialInvestment × 100
"""
# Estimate hours saved per week from admin hours
if company.hours_on_admin_per_week:
base_hours_saved = company.hours_on_admin_per_week * 0.60 # 60% reduction (base)
else:
# Default estimate for a small-medium business
size_defaults = {
CompanySize.SOLO: 8.0,
CompanySize.MICRO: 10.0,
CompanySize.SMALL: 15.0,
CompanySize.MEDIUM: 25.0,
CompanySize.LARGE: 40.0,
}
admin_hours = size_defaults.get(company.company_size, 12.0)
base_hours_saved = admin_hours * 0.60
# Hourly rate estimate by company size
size_hourly = {
CompanySize.SOLO: 60.0,
CompanySize.MICRO: 65.0,
CompanySize.SMALL: 75.0,
CompanySize.MEDIUM: 85.0,
CompanySize.LARGE: 100.0,
}
hourly_rate = size_hourly.get(company.company_size, 75.0)
# Annual AI costs — based on ReceptionistAI pricing (from PRICING_STRUCTURE.md)
# Base: $497/month Inbound Pro, Enterprise: $997/month
annual_costs_base = 497 * 12 # $5,964
# Initial investment — Discovery Audit $500 + onboarding
# Per ENTERPRISE_AI_TRANSFORMATION_STRATEGY.md: $15K–$25K for pilot
initial_investment = 2500.0 # Discovery Audit tier
scenarios = [
{
"scenario": "Conservative",
"hours_factor": 0.60,
"utilisation": 0.60,
"annual_costs": annual_costs_base,
"investment": initial_investment,
},
{
"scenario": "Base Case",
"hours_factor": 0.75,
"utilisation": 0.75,
"annual_costs": annual_costs_base,
"investment": initial_investment,
},
{
"scenario": "Optimistic",
"hours_factor": 0.85,
"utilisation": 0.85,
"annual_costs": 697 * 12, # Business tier
"investment": initial_investment,
},
]
projections = []
for s in scenarios:
projections.append(
ROIProjection(
scenario=s["scenario"],
hours_saved_per_week=round(base_hours_saved * s["hours_factor"], 1),
blended_hourly_rate_aud=hourly_rate,
utilisation_factor=s["utilisation"],
annual_ai_costs_aud=s["annual_costs"],
initial_investment_aud=s["investment"],
)
)
return projections
# ------------------------------------------------------------------
# Implementation roadmap
# ------------------------------------------------------------------
def _build_implementation_roadmap(
self,
company: CompanyProfile,
dimension_scores: list[DimensionScore],
) -> list[ImplementationPhase]:
"""
4-phase roadmap: 30 / 60 / 90 / 180-day milestones.
Actions are prioritised by the lowest-scoring dimensions.
"""
score_map = {d.dimension: d.score for d in dimension_scores}
# Phase 1: Foundation (Days 1–30)
phase1_actions = []
if score_map.get("Customer Experience", 100) < 60:
phase1_actions.append(
RecommendedAction(
title="Deploy AI Voice Receptionist",
description=(
"Install ReceptionistAI on your business number to capture every call "
"24/7. Configure call qualification, appointment booking, and instant "
"SMS notification to the business owner. Live within 48 hours."
),
dimension="Customer Experience",
priority=PriorityLevel.CRITICAL,
complexity=ImplementationComplexity.QUICK_WIN,
estimated_weekly_hours_saved=0,
estimated_monthly_roi_aud=(
round(
(company.missed_calls_per_day or 3) * 22 * 0.30
* (company.average_job_value_aud or 1500),
-2,
)
),
agileadapt_product="ReceptionistAI Inbound Pro ($497/month)",
done_for_you=True,
)
)
if score_map.get("Technology", 100) < 50:
phase1_actions.append(
RecommendedAction(
title="Implement CRM and Lead Pipeline",
description=(
"Deploy GoHighLevel (GHL) as your CRM backbone. Configure lead pipeline, "
"automated follow-up sequences, and call/email logging. Ensures every "
"enquiry is tracked from first touch to closed job."
),
dimension="Technology",
priority=PriorityLevel.HIGH,
complexity=ImplementationComplexity.SHORT_TERM,
estimated_weekly_hours_saved=4,
agileadapt_product="AgileAdapt GHL Onboarding (included in Business tier)",
done_for_you=True,
)
)
if score_map.get("Data", 100) < 50:
phase1_actions.append(
RecommendedAction(
title="Data Audit and CRM Clean-Up",
description=(
"Export existing customer data from current systems. Remove duplicates, "
"verify contact details, and migrate to CRM. This creates the data "
"foundation all AI tools depend on."
),
dimension="Data",
priority=PriorityLevel.HIGH,
complexity=ImplementationComplexity.SHORT_TERM,
estimated_weekly_hours_saved=2,
done_for_you=False,
)
)
if not phase1_actions:
phase1_actions.append(
RecommendedAction(
title="AI Capability Audit and Roadmap Validation",
description=(
"Conduct a detailed audit of current AI tool usage and identify "
"the highest-value expansion opportunities. Set 90-day targets."
),
dimension="Strategy",
priority=PriorityLevel.HIGH,
complexity=ImplementationComplexity.QUICK_WIN,
done_for_you=True,
)
)
phase1 = ImplementationPhase(
phase_number=1,
title="Foundation",
duration="Days 1–30",
focus="Capture every lead and establish the data foundation.",
actions=phase1_actions,
expected_outcomes=[
"100% of inbound calls captured (no more missed enquiries)",
"CRM live with all leads tracked",
"Baseline metrics established for ROI measurement",
],
success_metric=(
"Zero unanswered calls in month 2 vs. baseline."
),
)
# Phase 2: Quick Wins (Days 31–60)
phase2_actions = [
RecommendedAction(
title="Automate Google Review Collection",
description=(
"Trigger automated review request SMS to every completed-job customer. "
"Target: 5+ reviews per month. Google reviews are the #1 local AI search signal — "
"each review improves AI recommendation visibility."
),
dimension="Customer Experience",
priority=PriorityLevel.HIGH,
complexity=ImplementationComplexity.SHORT_TERM,
estimated_weekly_hours_saved=1,
agileadapt_product="ReceptionistAI Enterprise ($997/month)",
done_for_you=True,
),
RecommendedAction(
title="Deploy AI Lead Follow-Up Sequences",
description=(
"Configure automated 3-touch follow-up via SMS and email for every "
"lead that doesn't convert within 24 hours. Typical uplift: 15–25% "
"more conversions from existing lead volume."
),
dimension="Operations",
priority=PriorityLevel.HIGH,
complexity=ImplementationComplexity.SHORT_TERM,
estimated_weekly_hours_saved=3,
agileadapt_product="AgileAdapt GHL Automation",
done_for_you=True,
),
]
if score_map.get("Operations", 100) < 50:
phase2_actions.append(
RecommendedAction(
title="Automate Quote Generation",
description=(
"Implement AI-assisted quote templates for your top 5 job types. "
"Reduce quote turnaround from 24–48 hours to under 2 hours. "
"Faster quotes convert at significantly higher rates."
),
dimension="Operations",
priority=PriorityLevel.MEDIUM,
complexity=ImplementationComplexity.SHORT_TERM,
estimated_weekly_hours_saved=5,
done_for_you=False,
)
)
phase2 = ImplementationPhase(
phase_number=2,
title="Quick Wins",
duration="Days 31–60",
focus="Convert more of your existing leads. Automate the repetitive.",
actions=phase2_actions,
expected_outcomes=[
"15–25% improvement in lead-to-booking conversion rate",
"5+ new Google reviews per month",
"3–5 hours/week recovered from manual follow-up",
],
success_metric=(
"MRR from AI-recovered leads exceeds monthly AgileAdapt subscription cost."
),
)
# Phase 3: Scale (Days 61–90)
phase3_actions = [
RecommendedAction(
title="AI Content and Marketing Automation",
description=(
"Deploy AI-assisted content generation for Google Business Profile posts, "
"social media, and email newsletters. Consistent posting improves AI search "
"visibility and top-of-mind awareness with past clients."
),
dimension="Strategy",
priority=PriorityLevel.MEDIUM,
complexity=ImplementationComplexity.SHORT_TERM,
estimated_weekly_hours_saved=4,
agileadapt_product="CreatorDashboard.ai",
done_for_you=False,
),
RecommendedAction(
title="AEO (Answer Engine Optimisation) Deployment",
description=(
"Optimise your online presence for AI search engines (Perplexity, ChatGPT, "
"Gemini). Add LocalBusiness schema, FAQ content, suburb-specific pages. "
"Target: appear in AI search results for your top 5 query types."
),
dimension="Customer Experience",
priority=PriorityLevel.HIGH,
complexity=ImplementationComplexity.MEDIUM_TERM,
estimated_weekly_hours_saved=0,
estimated_monthly_roi_aud=2000,
agileadapt_product="ReceptionistAI Business ($697/month — includes website)",
done_for_you=True,
),
]
phase3 = ImplementationPhase(
phase_number=3,
title="Scale",
duration="Days 61–90",
focus="Make the AI engine compound. Grow the top of funnel.",
actions=phase3_actions,
expected_outcomes=[
"Appearing in AI search results for primary trade + suburb queries",
"Automated content presence across 2+ channels",
"Marketing effort maintained at zero additional staff hours",
],
success_metric=(
"First AI-search-attributed lead captured and attributed in CRM."
),
)
# Phase 4: Optimise (Days 91–180)
phase4_actions = [
RecommendedAction(
title="Advanced Analytics and ROI Reporting",
description=(
"Implement automated monthly reporting: calls captured, leads converted, "
"revenue attributed to AI systems. Enables data-driven decisions and "
"builds the business case for further AI investment."
),
dimension="Data",
priority=PriorityLevel.MEDIUM,
complexity=ImplementationComplexity.MEDIUM_TERM,
estimated_weekly_hours_saved=2,
done_for_you=True,
),
RecommendedAction(
title="AI Compliance Review (2026 ADM Reforms)",
description=(
"Audit AI-assisted customer-facing processes against the December 2026 "
"Australian Privacy Act ADM (Automated Decision-Making) requirements. "
"Document AI touchpoints, obtain consent where required, implement "
"audit logging. AgileAdapt's 9-Layer Shield covers this end to end."
),
dimension="Strategy",
priority=PriorityLevel.HIGH,
complexity=ImplementationComplexity.MEDIUM_TERM,
agileadapt_product="AgileAdapt 9-Layer Shield (compliance tier)",
done_for_you=True,
),
]
phase4 = ImplementationPhase(
phase_number=4,
title="Optimise and Defend",
duration="Days 91–180",
focus="Measure, defend compliance, and compound the AI advantage.",
actions=phase4_actions,
expected_outcomes=[
"Full AI ROI visibility — monthly revenue attributable to AI systems",
"ADM compliance documentation complete before December 2026 deadline",
"AI infrastructure that scales without proportional headcount increase",
],
success_metric=(
"AI-attributed annual revenue and cost savings exceed 3× annual "
"AgileAdapt investment."
),
)
return [phase1, phase2, phase3, phase4]
# ------------------------------------------------------------------
# Narrative generation
# ------------------------------------------------------------------
def _write_executive_summary(
self,
company: CompanyProfile,
dimension_scores: list[DimensionScore],
roi_projections: list[ROIProjection],
) -> str:
"""
Write a 3–5 sentence plain-language executive summary.
Professional Australian English. No clichés.
"""
score_map = {d.dimension: d.score for d in dimension_scores}
overall = sum(s.score * s.weight for s in dimension_scores) / sum(
s.weight for s in dimension_scores
)
overall = round(overall, 1)
# Pick the base case ROI
base_roi = next(
(r for r in roi_projections if r.scenario == "Base Case"),
roi_projections[1] if len(roi_projections) > 1 else roi_projections[0],
)
# Identify strongest and weakest
strongest = max(dimension_scores, key=lambda d: d.score)
weakest = min(dimension_scores, key=lambda d: d.score)
missed_rev_note = ""
if company.estimated_monthly_missed_revenue:
missed_rev_note = (
f" Current missed-call revenue is estimated at "
f"${company.estimated_monthly_missed_revenue:,.0f}/month —"
" the single highest-priority issue to address."
)
summary = (
f"{company.company_name} scores {overall}/100 on the AgileAdapt AI Readiness Index. "
f"The strongest area is {strongest.dimension.lower()} ({strongest.score:.0f}/100), "
f"while {weakest.dimension.lower()} ({weakest.score:.0f}/100) represents the "
f"most significant opportunity.{missed_rev_note} "
f"Based on a 75% utilisation rate and {base_roi.hours_saved_per_week:.0f} hours/week "
f"of AI-recoverable admin time, the base-case ROI is {base_roi.roi_percentage:.0f}% "
f"in year one, with an estimated payback period of "
f"{base_roi.payback_months or 6:.0f} months. "
f"The recommended entry point is {self._recommend_tier(company, dimension_scores)} — "
f"AgileAdapt can have the core systems live within 48 hours of engagement."
)
return summary
def _recommend_tier(
self,
company: CompanyProfile,
dimension_scores: list[DimensionScore],
) -> str:
"""
Recommend the appropriate AgileAdapt tier based on company profile.
Pricing from PRICING_STRUCTURE.md (LOCKED):
- Inbound Pro: $497/month (300 mins)
- Business: $697/month (600 mins + website)
- Enterprise: $997/month (1,200 mins + outbound + reviews)
"""
cx_score = next(
(d.score for d in dimension_scores if d.dimension == "Customer Experience"), 50
)
size = company.company_size
if size in (CompanySize.MEDIUM, CompanySize.LARGE):
return "ReceptionistAI Enterprise ($997/month) — full capability suite for multi-person teams"
elif cx_score < 40 or (company.missed_calls_per_day or 0) > 5:
return "ReceptionistAI Business ($697/month) — high call volume + free website"
else:
return "ReceptionistAI Inbound Pro ($497/month) — AI receptionist, same price as LocalSearch"
def _estimate_total_opportunity(
self,
company: CompanyProfile,
roi_projections: list[ROIProjection],
) -> Optional[float]:
"""
Estimate total annual opportunity: operational savings + recovered revenue.
"""
base_roi = next(
(r for r in roi_projections if r.scenario == "Base Case"),
roi_projections[0],
)
total = base_roi.net_annual_benefit_aud
# Add missed revenue recovery
if company.estimated_monthly_missed_revenue:
total += company.estimated_monthly_missed_revenue * 12
return round(total, 2) if total > 0 else None
# ------------------------------------------------------------------
# HTML rendering
# ------------------------------------------------------------------
def _load_template(self) -> str:
if self.TEMPLATE_PATH.exists():
return self.TEMPLATE_PATH.read_text(encoding="utf-8")
raise FileNotFoundError(
f"HTML template not found at {self.TEMPLATE_PATH}. "
"Run AuditReportGenerator.write_template() to create it."
)
def _interpolate_template(self, template: str, report: AIReadinessReport) -> str:
"""
Replace all {{PLACEHOLDER}} tokens in the template with report data.
"""
c = report.company
overall = report.overall_ai_readiness_index
grade = report.overall_grade.value
# Grade label and CSS class
grade_labels = {
"A": ("Exceptional", "grade-a"),
"B": ("Strong", "grade-b"),
"C": ("Developing", "grade-c"),
"D": ("Early Stage", "grade-d"),
"F": ("Critical", "grade-f"),
}
grade_label, grade_css = grade_labels.get(grade, ("Unknown", "grade-f"))
# Dimension score bars HTML
dim_bars_html = ""
for dim in report.dimension_scores:
dim_grade = dim.grade.value
_, dim_css = grade_labels.get(dim_grade, ("Unknown", "grade-c"))
dim_bars_html += f"""
{dim.dimension}
{dim_grade}
{dim.headline}
{"".join(f'- {f}
' for f in dim.key_findings)}
Quick wins:
{"".join(f'- {w}
' for w in dim.quick_wins)}
"""
# ROI table HTML
roi_rows_html = ""
for r in report.roi_projections:
roi_rows_html += f"""
| {r.scenario} |
{r.hours_saved_per_week:.0f} hrs/week |
${r.annual_hard_benefits_aud:,.0f} |
${r.annual_ai_costs_aud:,.0f} |
${r.net_annual_benefit_aud:,.0f} |
{r.roi_percentage:.0f}% |
{r.payback_months or '—'} months |
"""
# Roadmap phases HTML
phases_html = ""
for phase in report.implementation_phases:
action_items_html = ""
for action in phase.actions:
priority_css = {
PriorityLevel.CRITICAL: "priority-critical",
PriorityLevel.HIGH: "priority-high",
PriorityLevel.MEDIUM: "priority-medium",
PriorityLevel.LOW: "priority-low",
}.get(action.priority, "priority-medium")
product_note = (
f'{action.agileadapt_product}'
if action.agileadapt_product
else ""
)
dfy_badge = (
'Done-For-You'
if action.done_for_you
else ""
)
action_items_html += f"""
{action.description}
{product_note}
"""
outcomes_html = "".join(
f"{o}" for o in phase.expected_outcomes
)
phases_html += f"""
{phase.focus}
{action_items_html}
Success metric: {phase.success_metric}
"""
# Opportunity callout
opportunity_html = ""
if report.total_annual_opportunity_aud:
opportunity_html = f"""
${report.total_annual_opportunity_aud:,.0f}
Estimated total annual opportunity (operational savings + revenue recovery)
"""
replacements = {
"{{REPORT_ID}}": report.report_id,
"{{GENERATED_DATE}}": report.generated_at.strftime("%d %B %Y"),
"{{COMPANY_NAME}}": c.company_name,
"{{COMPANY_LOCATION}}": f"{c.city}, {c.state}",
"{{COMPANY_INDUSTRY}}": c.industry.value.replace("_", " ").title(),
"{{COMPANY_SIZE}}": c.company_size.value.title(),
"{{AUDIT_SOURCE}}": c.audit_source.replace("_", " ").title(),
"{{CONTACT_NAME}}": c.primary_contact_name or "—",
"{{OVERALL_SCORE}}": f"{overall:.1f}",
"{{OVERALL_GRADE}}": grade,
"{{OVERALL_GRADE_LABEL}}": grade_label,
"{{OVERALL_GRADE_CSS}}": grade_css,
"{{SCORE_BAR_WIDTH}}": f"{overall:.0f}",
"{{EXECUTIVE_SUMMARY}}": report.executive_summary,
"{{DIMENSION_SCORES_HTML}}": dim_bars_html,
"{{ROI_TABLE_ROWS}}": roi_rows_html,
"{{ROADMAP_PHASES_HTML}}": phases_html,
"{{COMPETITIVE_RISK}}": report.competitive_risk_summary,
"{{INDUSTRY_CONTEXT}}": report.industry_ai_adoption_rate,
"{{RECOMMENDED_TIER}}": report.recommended_agileadapt_tier or "ReceptionistAI Inbound Pro ($497/month)",
"{{NEXT_STEP}}": report.next_step,
"{{BOOKING_URL}}": report.booking_url,
"{{OPPORTUNITY_HTML}}": opportunity_html,
"{{AUDIT_DATE}}": c.audit_date.strftime("%d %B %Y"),
}
result = template
for placeholder, value in replacements.items():
result = result.replace(placeholder, str(value))
return result
# ------------------------------------------------------------------
# Utility
# ------------------------------------------------------------------
def _generate_report_id(self, company: CompanyProfile) -> str:
year = date.today().year
slug = "".join(
c for c in company.company_name.upper()[:6] if c.isalpha()
).ljust(3, "X")
return f"AAR-{year}-{self._counter:04d}-{slug}"