VoltWise — Energy-Aware Physical Outcome Verification

Amazon Developer Hackathon Submission
Your smart home says it's ON. VoltWise checks if it actually happened.

Overview: The "Beyond ON" Problem

In contemporary smart-home platforms, commanding a device to turn on returns a simple acknowledgement: "Living room heater is ON". However, this acknowledgement answers only one question: did the device accept the radio command?

It does not prove that the expected physical or electrical response occurred:

• A heater can acknowledge ON while stuck in an idle standby draw (~7 W instead of ~1,500 W).

• A malfunctioning appliance can draw hazardous, abnormal current (~2,200 W exceeding safety thresholds).

• A household can experience unexplained bill spikes without transparent, non-hallucinatory attribution of which appliances contributed and what remained unattributed.

VoltWise bridges this gap. Built for an intelligent conversational assistant experience, VoltWise treats the command, the reported state, physical electrical observations, safety policy decisions, and verified outcomes as distinct, verifiable layers of evidence.

Related MCP server: alexa-plus

Real Architecture vs. Simulated Demonstration Boundaries

To ensure complete technical honesty and transparency for hackathon evaluation, VoltWise strictly delineates what is real software and what is a simulated test fixture:

┌────────────────────────────────────────────────────────────────────────┐
│                   SIMULATED JUDGING SURFACE (BROWSER)                  │
│  React 19 + TypeScript + Vite Interactive "Digital Home" & Chat UI     │
│  (Simulated Alexa-style conversational interaction; NOT native Alexa+) │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ HTTP POST /api/sim/chat
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   REAL FASTAPI SIMULATOR GATEWAY                       │
│  - Parses natural language intent (e.g. "Alexa, what's causing...")   │
│  - Deterministically selects matching tool and typed arguments         │
│  - Opens official MCP ClientSession over Streamable HTTP               │
│  - NO backdoor/direct application fallback if MCP is unavailable       │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Real MCP ClientSession
                                    │ Streamable HTTP (Port 8001 / /mcp)
                                    │ Protocol 2025-11-25
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                 REAL MODEL CONTEXT PROTOCOL (MCP) SERVER               │
│  Official Python SDK 2.3.0 Streamable HTTP Transport                  │
│  Full 9-Tool Registry (Verification, Diagnostics, Energy & Tariffs)    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Typed Function Calls
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                 REAL APPLICATION ENGINES & LOGIC                       │
│  - VerificationService: Compares expected vs observed electrical draw  │
│  - DiagnosticEngine: Classifies behavior (offline, standby, abnormal)  │
│  - SafetyEngine: Zero-retry cutoff if draw exceeds safe threshold      │
│  - EnergyUsageEngine & TariffEngine: Decimal slab & run-rate analytics │
│  - SQLiteEventRepository & TraceRepository: Full persisted audit trail │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Telemetry & State Polling
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│            SIMULATED ELECTRICAL TELEMETRY & APPLIANCE FIXTURES         │
│  - Deterministic resistive heater, AC, TV, fan, and light profiles     │
│  - Standby (7 W), operating (1,500 W), and high-draw (2,200 W) faults  │
│  - Deterministic 30-day billing cycle historical telemetry fixtures   │
└────────────────────────────────────────────────────────────────────────┘

What is 100% Real

1. Model Context Protocol (MCP) Server & Client: Built on the official Python mcp SDK (2.3.0). Exposes tools over standard stdio and real Streamable HTTP transports. The client negotiates protocol version 2025-11-25 over live network connections.

2. Simulator Gateway: The FastAPI backend communicates with the MCP server exclusively through the official mcp.client.session.ClientSession and streamable_http_client. There is zero in-process bypass or direct application fallback.

3. Verification & Diagnostic Engines: Full deterministic physics rules, range checks, transient peak detection, safe retry bounds, and safety stop orchestration.

4. Energy & Tariff Intelligence: Exact timestamp boundary comparisons, run-rate projections, non-hallucinatory attribution accounting (measuring vs estimating vs preserving unattributed kWh), and Decimal slab tariff math.

5. Audit Trails: Real SQLite database persistence for application events and MCP traces.

What is Simulated (Explicit Disclosures)

• Simulated Alexa-Style UI: The judge-facing browser UI simulates how an Alexa+ conversational agent would present this data. It is not a native Alexa+ deployment, Alexa Skill, or certified Amazon device package.

• Simulated Electrical Telemetry: Smart plugs, household meters, appliance states, and electrical wattages are deterministic software fixtures. There is no physical smart-plug hardware or physical IoT bench connected.

• Simulated Electrical Cutoff: The safety cutoff is an immediate software state change (0 W, state OFF, zero retries). It does not represent a certified physical circuit breaker, relay hardware, or UL/CE production electrical safety certification.

• Illustrative Tariff: The configured 300 kWh threshold slab tariff is an illustrative model for demonstration purposes, not live utility tariff data.

The 9 Actual MCP Tools

VoltWise exposes nine tools in a unified registry accessible via stdio and Streamable HTTP (/mcp):

Installation & Local Startup

Prerequisites

• Operating System: Windows 10/11 (with PowerShell 5.1+) or Linux / macOS

• Python: Version 3.12

• Node.js: Version 24 (requires Node 24.15 or later)

• Docker: Optional (for single-port container packaging)

Method A: One-Click Windows Launcher (Recommended)

1. Clone or extract the repository:

   cd VoltWise

2. Initialize Python virtual environment and frontend dependencies:

   py -3.12 -m venv .venv
   .\.venv\Scripts\python -m pip install -e ".[dev]"
   cd frontend
   npm.cmd ci
   cd ..

3. Run the automated launcher:

   .\start-voltwise.bat

   The launcher verifies port availability, starts the MCP Streamable HTTP server on port 8001, validates official client readiness across all tools, starts the FastAPI REST gateway on port 8000, starts the Vite frontend on port 5173, resets the demo state, and opens your default browser.

4. To stop all background demo processes cleanly:

   .\stop-voltwise.bat

Method B: Manual Multi-Terminal Startup

Terminal 1 — Real MCP Server (Port 8001)

$env:VOLTWISE_MCP_PORT = "8001"
.\.venv\Scripts\voltwise-mcp-http.exe

Terminal 2 — FastAPI REST API & Simulator Gateway (Port 8000)

$env:VOLTWISE_MCP_URL = "http://127.0.0.1:8001/mcp"
.\.venv\Scripts\voltwise-api.exe

Terminal 3 — Vite Frontend (Port 5173)

cd frontend
npm.cmd run dev

Open http://127.0.0.1:5173 in any modern web browser.

Method C: Single-Port Production Container (Docker)

VoltWise includes a self-contained multi-stage Dockerfile that packages the compiled React frontend, FastAPI backend, and MCP server into a single non-root container running on port 8080:

docker build -t voltwise .
docker run --rm -p 8080:8080 -v voltwise-data:/data voltwise

Open http://127.0.0.1:8080. Health check is available at /health, REST API at /api/..., and MCP at /mcp.

The Five Canonical Demo Scenarios

Use the Demo setup preset selector in the judge UI (or command the simulated assistant) to reproduce all 5 core demonstration flows:

Scenario 1: Heater Electrical Response Failure (NO_DRAW)

• Initial Setup: Select No draw fault preset (or click Reset demo).

• User Action: Type "Turn the heater on" or click the Turn on heater quick action.

• Observed Behavior:

  • The living room heater UI reports ON.

  • Electrical telemetry observation detects only ~7 W (idle standby power) instead of the nominal ~1,500 W.

  • VoltWise flags the failure: "Not verified: Living room heater acknowledged ON, but electrical draw is only 7 W".

  • The floorplan tile highlights the device in an unverified warning state.

Scenario 2: Diagnostic Telemetry & Technician Handoff Copy

• Initial Setup: Follows Scenario 1 while the heater is in the unverified state.

• User Action: Type "Check what's wrong with the heater" or click Diagnose heater.

• Observed Behavior:

  • VoltWise invokes the MCP power_run_diagnostic tool.

  • The diagnostic engine analyzes power history, identifies standby-only draw without mechanical heat generation, and classifies the root fault.

  • Generates clear, field-ready Technician Handoff Copy (component checks, element resistance, relay continuity) without human speculation.

Scenario 3: Bounded Recovery After Single Safe Retry (NO_DRAW_THEN_RECOVER)

• Initial Setup: Select Recovery demo preset in the Demo setup dropdown.

• User Action: Type "Check what's wrong with the heater".

• Observed Behavior:

  • Initial electrical verification fails at ~7 W.

  • Safety policy confirms the failure is non-hazardous and authorizes exactly one safe retry.

  • VoltWise cycles the simulated control and re-verifies electrical response.

  • Re-verification detects ~1,500 W normal operating draw.

  • Status updates to "Physically Verified: Living Room Heater is drawing 1,500 W", successfully recovering without human intervention.

Scenario 4: High-Draw Safety Cutoff (HIGH_DRAW)

• Initial Setup: Select High draw fault preset.

• User Action: Type "Turn the heater on".

• Observed Behavior:

  • Telemetry detects an unsafe surge to ~2,200 W (exceeding nominal 1,500 W and the 1,900 W safety ceiling).

  • Safety engine executes an immediate software safety cutoff:

    • Simulated power cut to 0 W.

    • Device forced to OFF.

    • Zero retries permitted by safety policy.

  • Display alerts the user with an urgent safety stoppage warning and preserves the triggering electrical evidence in the audit log.

Scenario 5: Conversational Natural-Language Energy Intelligence

• Initial Setup: Click Reset demo to restore the canonical NORMAL_CURRENT_CYCLE scenario.

• User Action: Type:

  "Alexa, what's causing my electricity usage to increase?"
  (Also accepts natural variants: "Why is my electricity bill going up?", "What's using more electricity?", "Why did my energy usage increase?")

• Observed Behavior:

  • Routed through MCP power_explain_usage_change.

  • Transparent accounting explains:

    • Current period usage: 142.0 kWh vs previous equivalent period: 118.0 kWh (+24.0 kWh / +20.34% increase).

    • Ranked primary contributor: Air Conditioner (+21 hours runtime = 15.75 kWh estimated contribution).

    • Other auxiliary loads: 3.60 kWh.

    • Unattributed consumption: 4.65 kWh (honestly reported as unexplained household variation rather than hallucinating fake appliance IDs).

Verification & Test Suites

VoltWise maintains thorough test coverage across backend engines, REST APIs, MCP transports, and frontend components.

Backend Validation (169 Tests Passing)

Run pytest from the repository root:

.\.venv\Scripts\python -m pytest

Tests cover: physical verification rules, safety engine cutoff triggers, one-retry boundary limits, tariff slab quantization, billing run-rate forecasting, MCP Streamable HTTP protocol negotiation (2025-11-25), and simulator gateway routing.

Frontend Validation (74 Tests Passing)

Run Vitest from the frontend/ directory:

cd frontend
npm.cmd test -- --run

Tests cover: judge UI interactions, appliance control, high-draw safety presentation, energy explanation cards, live MCP technical traces, and keyboard accessibility.

Production Build Validation

Verify TypeScript types and Vite production bundling:

cd frontend
npm.cmd run build

Configuration & Environment Variables

Default development settings operate out of the box on localhost without requiring any .env file. To customize, copy .env.example to .env or set environment variables:

Security & Privacy Hygiene

This release distribution is prepared for public GitHub publication:

• No private keys, API secrets, or passwords: Authentication tokens in .env.example are blank placeholders.

• No runtime databases committed: .db files are strictly excluded; the database directory is initialized automatically at startup.

• No machine-specific paths: All paths in scripts and configuration are relative to project root.

• Sanitized release tree: node_modules, .venv, .pytest_cache, temporary video artifacts, screen captures, and build caches are purged from the repository.

License

This project is licensed under the terms of the MIT License. See the LICENSE file for full details.