AI Services Integration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The AI Services Integration in Comply-Quick serves as a critical layer for transforming technical compliance data into human-readable narratives. Its primary purpose is to provide business owners and developers with plain-language summaries of complex events, such as regulatory changes or website scan results. By abstracting raw technical diffs and scanner findings, the AI service ensures that users can make informed decisions regarding their compliance posture without requiring a legal background.
The integration is architected to be resilient, utilizing a deterministic fallback system. This ensures that the core pipelines—namely the Autopilot Regeneration Pipeline and the Compliance Scanner Pipeline—remain functional even if the live AI provider (such as OpenAI) is unavailable or if API keys are missing.
Sources: src/lib/autopilot/pipeline.ts:1-12, src/lib/scanner/pipeline.ts:1-6
Architecture and Components
AI Client Interface
The system interacts with AI providers through a unified AiClient interface. This interface defines the contract for completion requests, allowing the application to distinguish between a "live" AI client and a "deterministic" mock client used during testing or as a fail-safe.
The following sequence diagram illustrates how a pipeline component interacts with the AI client to generate a summary:
The system prioritizes live AI responses but strictly enforces a deterministic fallback to prevent pipeline failures.
Sources: src/lib/autopilot/pipeline.ts:68-96, src/tests/autopilot.test.ts:98-112
Integration Pipelines
AI services are integrated into two primary workflows:
- Autopilot Regeneration: When a regulation changes, the
buildRegenerationProposalfunction uses AI to explain why a project's compliance package was updated and what specific sections were affected. - Compliance Scanner: After a site crawl, the
runScanfunction uses AI to summarize the biggest compliance risks and identify the most important next steps for the business owner.
Sources: src/lib/autopilot/pipeline.ts:79-114, src/lib/scanner/pipeline.ts:38-66
Data Flow and Logic
Prompt Engineering
The system uses structured prompt builders to ensure consistency in AI outputs. These builders combine technical metadata (frameworks, regions, detected tools) with human-readable change notes or findings.
| Component | Input Data | System Instruction |
|---|---|---|
| Autopilot | Project name, Framework, Change notes, Document diff | "You are a compliance analyst. Be precise, neutral... Output plain prose only." |
| Scanner | URL, Compliance score, Detected tools, Findings | "Write a concise plain-language summary... what the biggest compliance risks are." |
Sources: src/lib/autopilot/pipeline.ts:43-55, src/lib/scanner/pipeline.ts:19-30
Deterministic Fallbacks
To ensure reliability, the system implements hard-coded fallback functions. These functions generate a basic summary using the same metadata provided to the AI, ensuring the user still receives actionable information even without a live LLM.
/** Deterministic summary used when the AI client is unavailable. */
function fallbackSummary(regulation: RegulationContext, diff: DocumentDiff): string {
const sections = [...diff.changedSections, ...diff.addedSections];
const detail = sections.length > 0 ? ` Affected sections: ${sections.slice(0, 6).join(", ")}.` : "";
return (
`${regulation.name} (${regulation.region}) changed, so we regenerated a proposed update to this project's ` +
`compliance package (+${diff.addedLines}/-${diff.removedLines} lines).${detail} Review and approve to apply it.`
);
}
Sources: src/lib/autopilot/pipeline.ts:58-65, src/lib/scanner/pipeline.ts:32-36
UI Integration
AI-generated insights are surfaced in the Command Center dashboard. Specifically, the IntelligencePanel and AutopilotPanel (referenced in CommandCenterView.tsx) display the proactive monitoring results and regulatory alerts that are processed through the AI integration layer.
The diagram shows the flow of technical triggers through pipelines into the final UI summary.
Sources: src/app/dashboard/home/CommandCenterView.tsx:186-218, src/lib/scanner/pipeline.ts:1-10
Testing and Verification
The AI integration is verified using a DeterministicAiClient in test suites. This ensures that the logic for selecting between live and fallback summaries works correctly across different environmental configurations.
- Missing API Keys: The system is tested to ensure it returns the deterministic fallback when
OPENAI_API_KEYis not set. - Error Handling: Tests confirm that if a live AI client throws an error (e.g., rate limiting), the pipeline falls back gracefully to the deterministic summary rather than crashing.
Sources: src/tests/autopilot.test.ts:98-132, src/tests/scanner.test.ts:145-165
Conclusion
The AI Services Integration in Comply-Quick is a robust, fail-safe system designed to bridge the gap between technical compliance audits and user understanding. By utilizing structured prompting and a strict fallback architecture, the project maintains high availability for its intelligence features while providing professional, neutral, and actionable compliance summaries.