# Home Energy Sentinel

## What it is

Home Energy Sentinel is a small Alexa+ simulated experience for preparing
safer time-of-use energy plans. It demonstrates a conversational agent that
can read state and propose an action while a human retains final authority.

## Why it matters

Energy plans combine changing tariffs, device deadlines, and a household power
limit. A useful proposal can become unsafe when the underlying tariff or home
state changes. This project makes that boundary visible instead of silently
applying an outdated decision.

## Demo

The local one-screen demo shows:

1. a conversational read of the synthetic home state;
2. a proposed overnight schedule with `HUMAN APPROVAL REQUIRED`;
3. explicit human **Approve** or **Reject** actions;
4. before/after evidence and an audit event;
5. `STALE_PROPOSAL` when the synthetic tariff changes; and
6. a fresh proposal after rereading the new state.

## How it works

The deterministic policy finds a cheap overnight window and schedules the
water heater and EV sequentially without exceeding 7 kW. The agent first reads
the state, then creates a pending proposal. Proposal creation never mutates the
active plan.

## Human approval boundary

The agent client has an `agent` role and cannot approve a proposal. A separate
`human` client must call `approve_energy_plan`. The server rejects approval from
the agent role, and the UI keeps the approval buttons separate from the agent
conversation.

## Stale decisions

Every proposal stores the tariff, consumption, and active-plan fingerprints it
was based on. If any of them changes, approval returns `STALE_PROPOSAL` and the
canonical plan remains unchanged. Repeating an already applied approval is
idempotent and does not create a duplicate event.

## Architecture

- `src/server.js` — local MCP Streamable HTTP server and role checks.
- `src/client.js` — minimal MCP client used by the harness and UI.
- `src/contracts.js` — typed tool definitions and schemas.
- `src/domain.js` — synthetic state, proposals, approvals, and audit events.
- `src/policy.js` — deterministic schedule validation and planning policy.
- `conversation/` — conversational policy harness using the real MCP server.
- `ui/` — local web simulation using the same MCP server.
- `test/` — protocol, domain, conversation, and UI tests.
- `evidence/` — reproducible transcripts, results, and demo materials.

## Run locally

Requirements: Node.js 22 or later. The project has no external runtime
dependencies and does not require an account or cloud service.

```text
npm run demo-ui
```

Open `http://127.0.0.1:8788`.

The CLI/conversation alternatives are:

```text
npm start
npm run demo
node conversation/demo.js
```

## Run tests

```text
npm test
```

Expected result: 12 tests passed, 0 failed.

## Synthetic data disclosure

All tariffs, device identifiers, schedules, consumption values, and audit
events are synthetic fixtures. No real tariff provider, meter, customer
account, or smart-home device is connected. The project makes no claim of real
energy savings.

## Alexa+ simulation disclosure

This repository uses the Alexa+ simulated-experience path permitted by the
hackathon. The MCP server itself is real and implements MCP 2025-11-25 over
Streamable HTTP, but the demo does not claim to be connected to Alexa+ or an
Alexa device. The agent is a deterministic policy harness, not an LLM.

## Limitations

There is no live Alexa+ account, OAuth integration, remote deployment,
authentication service, persistence, multi-user support, real device control,
or production tariff integration.

## License

MIT — see [LICENSE](LICENSE).