Customer Energy Advisor
Outcome
Help a utility customer understand a surprising bill and act on it by explaining usage drivers, tariff mechanics, and eligible programs in plain language, with confirmation before any tariff switch or program enrollment.
| Portfolio attribute | Value |
|---|---|
| Primary persona | Utility customer |
| Primary aggregate | CustomerEnergyAccount |
| Cosmos DB containers | 3 |
| Grounding data | usage, tariffs, bills, programs, weather |
| 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 | Response cycle time | 8-15% reduction | (baseline median response minutes - assisted median response minutes) / baseline median response minutes * 100 |
| Quality or risk | Evidence discovery time | 10-20% reduction | (baseline median evidence-search minutes - assisted median evidence-search minutes) / baseline median evidence-search minutes * 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: Usage, tariffs, bills, programs, and weather support faster preparation of grounded customer guidance.
Pilot guardrail: Require human review for billing, tariff, program, or customer-specific exceptions.
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 response cycle time and evidence discovery time 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. Ask why the bill changed | Utility customer | Question in the self-service app or IVR → Classified billing or usage intent | Policy controlled |
| 2. Decompose the bill into drivers | Usage analytics agent | Bill line items and interval usage summaries → Driver attribution such as weather, rate change, or usage shift | Policy controlled |
| 3. Explain tariff mechanics in plain language | Energy advisor | Active tariff definition and time-of-use breakdown → Cited explanation with the customer's own numbers | Policy controlled |
| 4. Match eligible programs and alternatives | Eligibility agent | Premise, usage profile, and program criteria → Ranked tariff and program options with projected savings | Policy controlled |
| 5. Confirm tariff switch or enrollment | Customer | Proposed tariff change or program enrollment → Submitted change request with confirmation record | Human required |
Technical architecture

Cosmos DB data model
| Container | Hierarchical partition key | Documents | Search paths |
|---|---|---|---|
customerEnergyAccounts | /tenantId, /serviceAccountId | CustomerEnergyAccount, IntervalUsageSummary, BillStatement | Operational fields only |
tariffCatalog | /tenantId, /serviceClassCode | TariffDefinition | /tariffSummaryVectorEmbedding, /tariffSummaryVector |
efficiencyProgramCatalog | /tenantId, /programSegmentCode | EfficiencyProgram | /programDescriptionVectorEmbedding, /programDescriptionVector |
Query contract
| Query | Container | Scope | Purpose |
|---|---|---|---|
| Bill explanation context | customerEnergyAccounts | single-partition | Read the bill and the matching usage summaries for the period in one partition query. |
| Peak usage day detection | customerEnergyAccounts | single-partition | Identify the days that drove the on-peak charges in the billing period. |
| Eligible program matching | efficiencyProgramCatalog | single-partition | Knowledge-container query against efficiencyProgramCatalog (partition-aligned to /tenantId + /programSegmentCode): return active programmes whose eligibility criteria the premise and usage profile satisfy; the catalogue is partitioned by customer segment so the read touches one partition. |
| Tariff comparison set | tariffCatalog | single-partition | Knowledge-container query against tariffCatalog (partition-aligned to /tenantId + /serviceClassCode): load the candidate rate schedules valid for the customer's service class for savings modelling, as a single partition read of that service class. |
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/energy-utilities/customer-energy-advisor
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