Skip to main content
ENE-02 · Energy & Utilities

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 attributeValue
Primary personaUtility customer
Primary aggregateCustomerEnergyAccount
Cosmos DB containers3
Grounding datausage, tariffs, bills, programs, weather
Development estimateUSD 60-220 monthly dev estimate
Runtime optionsPython FastAPI and C# ASP.NET Core

Productivity hypothesis​

These measures reflect the workflow, evidence, decision boundary, and industry risk for this use case.

Impact typeMeasureConservative internal assumptionCustomer measurement
ProductivityResponse cycle time8-15% reduction(baseline median response minutes - assisted median response minutes) / baseline median response minutes * 100
Quality or riskEvidence discovery time10-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​

  1. Baseline the current workflow with representative users and tasks.
  2. Run the accelerator on the same task mix with human review retained.
  3. Measure response cycle time and evidence discovery time with the documented formulas.
  4. 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​

Domain workflow

StageActorInput → outputApproval
1. Ask why the bill changedUtility customerQuestion in the self-service app or IVR → Classified billing or usage intentPolicy controlled
2. Decompose the bill into driversUsage analytics agentBill line items and interval usage summaries → Driver attribution such as weather, rate change, or usage shiftPolicy controlled
3. Explain tariff mechanics in plain languageEnergy advisorActive tariff definition and time-of-use breakdown → Cited explanation with the customer's own numbersPolicy controlled
4. Match eligible programs and alternativesEligibility agentPremise, usage profile, and program criteria → Ranked tariff and program options with projected savingsPolicy controlled
5. Confirm tariff switch or enrollmentCustomerProposed tariff change or program enrollment → Submitted change request with confirmation recordHuman required

Technical architecture​

Technical architecture

Cosmos DB data model​

ContainerHierarchical partition keyDocumentsSearch paths
customerEnergyAccounts/tenantId, /serviceAccountIdCustomerEnergyAccount, IntervalUsageSummary, BillStatementOperational fields only
tariffCatalog/tenantId, /serviceClassCodeTariffDefinition/tariffSummaryVectorEmbedding, /tariffSummaryVector
efficiencyProgramCatalog/tenantId, /programSegmentCodeEfficiencyProgram/programDescriptionVectorEmbedding, /programDescriptionVector

Query contract​

QueryContainerScopePurpose
Bill explanation contextcustomerEnergyAccountssingle-partitionRead the bill and the matching usage summaries for the period in one partition query.
Peak usage day detectioncustomerEnergyAccountssingle-partitionIdentify the days that drove the on-peak charges in the billing period.
Eligible program matchingefficiencyProgramCatalogsingle-partitionKnowledge-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 settariffCatalogsingle-partitionKnowledge-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​

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​

Return to all accelerators