Report & Email Agent

Role

The Report Agent is the final delivery step in the BWTS IOT pipeline. It receives the fully compiled investigation context from the IOT Manager — root causes, confidence ratings, evidence from all specialists, and remediation procedures — and transforms it into a formatted HTML report delivered via email. It performs no analysis, no synthesis, and no data queries.

Note

The Report Agent is a formatting and delivery agent. By the time it receives a task, all intellectual work is complete. Its job is to present findings clearly and get them into the right inbox — nothing more.

---

How It Works

1. Validate Inputs

   The Report Agent receives a task containing the report_request_v1 payload from the IOT Manager. It validates that all required fields are present: alert metadata, data findings, PMS findings, casefile findings, confirmed causes with confidence ratings, remediation procedures, and urgency classification.

   If any required field is missing or malformed, the agent fails the task immediately with a descriptive error — it never attempts to generate a partial report.

2. Write Context JSON

   The validated payload is written to a structured JSON file in the agent’s working directory. This file serves as the input for report_builder.py and is preserved for logging and debugging purposes.

   shared/IOT-manager/report-agent/{alert_ids}_{timestamp}_context.json

3. Run report_builder.py validate

   The agent invokes report_builder.py in validate mode to perform schema-level checks on the context JSON before attempting to build:

   python report_builder.py validate --input context.json

   This catches structural issues (missing nested fields, type mismatches) before the build step, producing clear error messages rather than malformed HTML.

4. Run report_builder.py build

   Once validation passes, the agent invokes report_builder.py in build mode to generate the HTML report:

   python report_builder.py build --input context.json --output report.html

   The builder applies urgency-based colour coding, formats tables, and embeds all evidence into a self-contained HTML document.

5. Compose Plain-Text Email Body

   The agent writes a concise plain-text email body summarising the key findings. This ensures the report is readable even in email clients that strip or block HTML attachments. The plain-text body includes:

   • Vessel name and equipment tag
   • Urgency classification
   • Top root cause with confidence level
   • A note that the full HTML report is attached

6. Send via gmail_send.py

   The agent invokes gmail_send.py to deliver the email with the HTML report attached:

   python gmail_send.py send \
     --to "ops-team@your-domain.example" \
     --from "alerts@your-domain.example" \
     --subject "[BWTS REPORT] {SEVERITY} — {Parameter} — {Vessel} — {Date}" \
     --body body.txt \
     --attachment report.html

7. Confirm Delivery

   After gmail_send.py returns success, the agent marks its task as complete and posts a confirmation comment to the parent task. The IOT Manager uses this confirmation to close the investigation loop.

---

Report Structure

The HTML report is divided into three main sections, each serving a distinct purpose for the engineering team reviewing the alert.

Alert Summary

A table of all alerts included in the investigation, providing immediate context.

Column	Description
Alert ID	Unique alert instance identifier
Equipment Tag	BWTS equipment identifier (e.g., BWTS-UV-003)
Parameter	Sensor parameter in violation (e.g., uv_intensity)
Current Value	Latest sensor reading at time of alert
Threshold	Configured threshold that was breached
Triggered At	ISO 8601 timestamp of alert trigger
Severity	CRITICAL, WARNING, or INFO

Diagnosis

Root causes identified during synthesis, ranked by confidence. Each entry includes:

Column	Description
Root Cause	Description of the identified cause
Confidence	HIGH, MEDIUM, or LOW with colour indicator
Supporting Evidence	Bullet list of evidence from each specialist agent
Data Trend	Summary of relevant sensor trend from the Data Agent
Maintenance Status	Related maintenance findings from the PMS Agent
Historical Precedent	Past incidents from the Casefile Agent, if any

Recommended Actions

Remediation procedures grouped by urgency tier. Each action includes:

Column	Description
Action	Step-by-step procedure from the Manual Agent
Urgency	IMMEDIATE, SHORT-TERM, or MONITOR
Manual Reference	Section and page number in the PureBallast 3.1 manual
Safety Warnings	Verbatim safety warnings from the manual (if any)
Required Tools/Spares	Tools and parts needed for the procedure

---

Urgency Colour Coding

The HTML report applies a colour-coded banner at the top based on the urgency classification determined by the IOT Manager.

Urgency	Banner Colour	Meaning
IMMEDIATE	Red (#dc2626)	Action required before next BWTS operation. Compliance breach or safety risk.
SHORT-TERM	Amber (#f59e0b)	Address at next port call. Degradation trending or maintenance due.
MONITOR	Blue (#3b82f6)	Watch and log. Minor deviation or early warning signal.

Tip

The urgency classification is determined by the IOT Manager, not the Report Agent. The Report Agent only applies the corresponding visual styling — it never changes or overrides the urgency.

---

Email Format

Field	Value
From	alerts@your-domain.example
To	ops-team@your-domain.example
Subject	[BWTS REPORT] {SEVERITY} — {Parameter} — {Vessel} — {Date}
Body	Plain-text summary of key findings
Attachment	report.html — full formatted report

The [BWTS REPORT] subject prefix is mandatory

The Alert Monitor uses email subject patterns to identify incoming alerts. Without the [BWTS REPORT] prefix, the outgoing report email could be picked up as a new alert by the Alert Monitor, creating an infinite investigation loop. This prefix is explicitly excluded from the Alert Monitor’s matching rules.

Safety warnings must be included VERBATIM

The Report Agent must never paraphrase, summarise, or omit safety warnings extracted from the PureBallast 3.1 manual. These warnings carry regulatory and liability significance. If a safety warning is present in the report_request_v1 payload, it must appear word-for-word in the final report.

---

What It Does NOT Do

No Analysis

Never interprets sensor data, never identifies trends, never correlates parameters. All analysis is completed before the Report Agent is invoked.

No Synthesis

Never cross-references findings, never assigns confidence ratings, never determines root causes. That is the IOT Manager’s exclusive responsibility.

No Data Queries

Never connects to PostgreSQL, never calls the Dashboard API, never queries equipment manuals. Works solely from the compiled payload it receives.

Note

The Report Agent’s strict boundary ensures a clean separation between investigation and delivery. If the report is wrong, the problem is upstream in synthesis — never in the Report Agent’s formatting logic.

---

Tools

Tool	Script	Purpose
Report Builder	report_builder.py validate	Validate the context JSON against the report_request_v1 schema before building
Report Builder	report_builder.py build	Generate the formatted HTML report from validated context
Email Sender	gmail_send.py send	Deliver the report email with HTML attachment via SMTP

Caution

The Report Agent uses gmail_send.py for email delivery — NOT the Gmail MCP tool. The gmail_send.py script handles SMTP authentication, attachment encoding, and delivery confirmation in a single call. Using the Gmail MCP tool would bypass the established logging and error-handling patterns.