# ChillClock

**A food-cooling coach that estimates cooling deadlines, suggests practical next steps, and records decisions in a local hash-linked audit trail.**

ChillClock is a prototype for commercial kitchens, caterers, and food-service teams. It uses two temperature readings from the same food batch to estimate whether the batch may reach key cooling temperatures on time.

> **Safety note:** ChillClock is a decision-support prototype, not a food-safety determination. Its estimates can be wrong. Always measure food with a suitable thermometer and follow your approved procedures and applicable local food-safety requirements. The app never certifies food as safe.

## What it does

- **Cooling-time estimates:** A two-point Newton-cooling model estimates when a batch may reach 70°F and 41°F, assuming a stable ambient temperature and broadly consistent cooling conditions.
- **Deadline indicators:** Estimates are compared with prototype reference targets of 120 minutes for the first stage and 360 minutes total. These are examples for coaching, not a determination of which rules apply to your operation.
- **Context-aware suggestions:** Optional batch name, food depth, cover or ventilation status, and cooling method help produce a deterministic action plan. Suggestions may include using shallower pans, appropriate ventilation while protecting food from contamination, an ice-water bath with stirring, rapid-cooling equipment, and rechecking with a thermometer. These are practical suggestions; follow applicable mandatory requirements and approved procedures.
- **Direct and MCP predictions:** Use the dashboard's **Predict directly** path or **Run via MCP** to call the `predict_cooling` tool on the local MCP server.
- **MCP tools:** The server provides `predict_cooling` and `get_cooling_guidance` over the Model Context Protocol.
- **Audit trail:** Prediction and corrective-action events are stored in a local JSON Lines ledger and linked with SHA-256 hashes. The verifier checks the chain across both event types.
- **Quick demo:** Example readings let you try the workflow without waiting for a full cooling cycle.

Coaching is rule-based. ChillClock does not call AWS Bedrock or another hosted AI model at runtime. It is not an Alexa skill, voice assistant, or public hosted service.

## Run locally

Requirements: Node.js 20 or newer and npm.

From the repository root, install dependencies:

```sh
npm install
```

Start the dashboard and API:

```sh
npm run dev
```

Open <http://localhost:3000> and keep this terminal running. The dashboard server defaults to port 3000; set `PORT` to change it.

To use **Run via MCP**, open a second terminal in the project folder and start the MCP server:

```sh
npm run mcp
```

The MCP server listens on `127.0.0.1:3001` by default. Set `MCP_PORT` to use another port. Keep both servers running while using the MCP path. If the MCP server is unavailable, the dashboard will explain how to start it.

You can copy `.env.example` to `.env` to configure the ports. The app loads `.env` automatically.

## Quick demo

1. In the dashboard, choose **Load example A** or enter two readings from the same batch.
2. Enter the elapsed time and any known batch context, such as food depth and cooling method.
3. Choose **Predict directly** and review the estimated times, prototype deadline indicators, and action plan.
4. Choose **Run via MCP** to make the same prediction through the actual MCP `predict_cooling` tool.
5. Use a **Log action** button to add a selected action to the audit chain, then choose **Verify and view recent records** to check the recent entries.

## How estimates work

The engine estimates a cooling curve from two temperature readings and a known time interval using a simplified Newton-cooling model. It assumes broadly stable food and ambient conditions. Food composition, depth, container shape, stirring, airflow, refrigeration, and changes in cooling method can all make real cooling differ from the estimate.

The displayed **reading interval heuristic** is based only on the time between readings. Low, medium, or high is not a statistically validated confidence estimate and does not describe the probability that a prediction is accurate. If the model flags a potential missed target, physically recheck the batch and follow your operation's corrective procedure.

The 120-minute first-stage and 360-minute total values are prototype reference targets. Follow the requirements that apply to your location and operation.

## Audit trail limitations

Audit events are written to `data/ledger.jsonl`; the data directory is ignored by Git. The verifier checks whether the stored entries form an intact SHA-256 hash chain. This can reveal many unexpected changes, but the trail is **tamper-evident, not tamper-proof**. It is local to the running app and is not a replacement for regulated recordkeeping or an independently secured audit service.

## HTTP API

The dashboard server exposes:

- `GET /api/health` — basic server health.
- `POST /api/predict` — accepts `startTempF`, `currentTempF`, `elapsedMinutes`, and optional `ambientTempF`; returns an estimate and saves a prediction event.
- `POST /api/predict/mcp` — accepts the same readings plus optional batch context; calls the MCP `predict_cooling` tool and saves the result.
- `POST /api/actions` — validates a selected action and optional batch context, then appends a `corrective_action` event to the hash chain.
- `GET /api/log` — verifies the complete ledger and returns up to ten recent entries.

Example direct prediction request:

```sh
curl -X POST http://localhost:3000/api/predict \
  -H "Content-Type: application/json" \
  -d '{"startTempF":135,"currentTempF":100,"elapsedMinutes":45,"ambientTempF":37}'
```

The example output is an estimate, not a food-safety recommendation.

## Development

```sh
npm run typecheck
npm test
npx tsx apps/server/src/mcp-smoke.ts
```

The MCP smoke test requires the MCP server to be running in another terminal. The project uses TypeScript, Node.js, Express, the Model Context Protocol TypeScript SDK, and Vitest.

## Project structure

```text
apps/server/       Dashboard, HTTP API, and MCP server
packages/engine/   Cooling estimate and supporting logic
```

## License

MIT. See [LICENSE](LICENSE).