Maintenance Troubleshooting Copilot
Outcome
Get a maintenance technician from a fault code to a verified repair by combining equipment history, sensor evidence, manuals, and prior successful fixes, with supervisor authorization before any safety-critical intervention.
| Portfolio attribute | Value |
|---|---|
| Primary persona | Maintenance technician |
| Primary aggregate | TroubleshootingSession |
| Cosmos DB containers | 2 |
| Grounding data | manuals, work orders, sensor events, fault codes |
| Development estimate | USD 60-220 monthly dev estimate |
| Runtime options | Python FastAPI and C# ASP.NET Core |
Productivity hypothesis
These measures reflect the workflow, evidence, decision boundary, and industry risk for this use case.
| Impact type | Measure | Conservative internal assumption | Customer measurement |
|---|---|---|---|
| Productivity | Fault evidence discovery time | 20-35% reduction | (baseline median fault-evidence search minutes - assisted median minutes) / baseline median minutes * 100 |
| Quality or risk | Repeated troubleshooting | 8-15% reduction | (baseline repeated troubleshooting-step rate - assisted rate) / baseline rate * 100 |
Important: Conservative internal pilot assumptions only; not public benchmarks, commitments, or expected customer results. Validate against a comparable baseline or matched control cohort with mandatory human review.
Rationale: PLC alarms, historian trends, OEM procedures, spares, and CMMS history support faster fault isolation.
Pilot guardrail: Require verified equipment state, evidence, safety procedures, and technician approval before action.
Customer validation plan
- Baseline the current workflow with representative users and tasks.
- Run the accelerator on the same task mix with human review retained.
- Measure fault evidence discovery time and repeated troubleshooting with the documented formulas.
- Replace internal assumptions with customer-observed results before a business case.
Why Azure Cosmos DB
This AI solution needs an operational data plane, not only a vector index:
- Hybrid vector and full-text retrieval combines semantic recall with exact identifiers, codes, names, and domain language.
- Hierarchical partition keys and metadata predicates keep tenant and domain boundaries in the normal query path.
- Operational JSON, source chunks, workflow and agent state, feedback, and audit records remain together for low-latency reads and governed writes.
- Change feed reacts to source and operational updates without polling.
- Autoscale throughput, configurable consistency, and multi-region distribution support variable demand and enterprise availability.
Domain workflow

| Stage | Actor | Input → output | Approval |
|---|---|---|---|
| 1. Report the fault at the machine | Maintenance technician | Fault code, symptom description, and asset tag scan → TroubleshootingSession bound to the asset | Policy controlled |
| 2. Correlate sensor and fault evidence | Diagnostic agent | Recent fault events and process signals → Evidence timeline for the failure window | Policy controlled |
| 3. Rank causes from history and manuals | Hypothesis agent | Evidence timeline, repair history, procedures → Ranked root-cause hypotheses with supporting fixes | Policy controlled |
| 4. Guide the repair step by step | Maintenance copilot | Selected hypothesis and applicable procedure → Cited step sequence with tools and safety precautions | Policy controlled |
| 5. Authorize safety-critical intervention | Maintenance supervisor | Proposed lockout, bypass, or parameter change → Authorized work with a signed permit record | Human required |
Technical architecture

Cosmos DB data model
| Container | Hierarchical partition key | Documents | Search paths |
|---|---|---|---|
troubleshootingSessions | /tenantId, /assetId | TroubleshootingSession, AssetProfile, FaultEvent, RepairHistoryRecord | /symptomVectorEmbedding, /rootCauseNarrativeVectorEmbedding, /symptomVector, /rootCauseNarrativeVector |
maintenanceProcedureLibrary | /tenantId, /procedureId | MaintenanceProcedure | /stepVectorEmbedding, /stepVector |
Query contract
| Query | Container | Scope | Purpose |
|---|---|---|---|
| Asset diagnostic context | troubleshootingSessions | single-partition | Load asset profile, recent faults, and repair history for the machine in one partition read. |
| Recurring fault pattern | troubleshootingSessions | single-partition | Detect the same fault code repeating on the asset within the reliability window. |
| Model-applicable procedure lookup | maintenanceProcedureLibrary | cross-partition-bounded | Knowledge-container query against maintenanceProcedureLibrary (bounded fan-out across the /tenantId + /procedureId partitions named by the shortlist): retrieve only the manual steps valid for this equipment model, over the procedure ids that the asset profile and fault signature shortlist. |
| Repeat-failure repairs | troubleshootingSessions | single-partition | Find past repairs on the asset where the fix did not hold, to avoid repeating them. |
Python and C# services route each document type to its declared container and hierarchical partition key. ETag-based writes protect mutable aggregates, while append-only records and bounded cross-partition queries preserve scale.
Azure deployment

Clone the source repository, authenticate with Azure, and run:
Set-Location accelerators/manufacturing/maintenance-troubleshooting-copilot
az login
./Deploy.ps1 -Runtime python -Location eastus2
Change python to csharp to deploy the .NET implementation.
Explore the implementation
- Launch signed-in demo
- Implementation article
- Domain data model
- Workflow and API contract
- Python application
- C# application
- Domain container Bicep
- Platform Bicep
- Cost and configuration
- Source repository