PMS Agent

Role

The PMS Agent is a Phase 1 specialist responsible for the Planned Maintenance System. It retrieves maintenance history from PostgreSQL, calculates overdue status against Alfa Laval service intervals, and returns a structured maintenance report — ready for the IOT Manager’s cross-referencing step.

Note

The PMS Agent answers the question: “Is this alert caused by missed or overdue maintenance?” It provides the maintenance context that turns a sensor anomaly into an actionable finding.

---

Component Mapping

When the IOT Manager dispatches a PMS task for a flagged parameter, the agent maps that parameter to the relevant physical components:

Flagged Parameter	Components Investigated
UV_INTENSITY	LAMP, QUARTZ-SLEEVE, UVR-UNIT, CIP
FILTER_DP	FILTER, FILTER-ELEMENT, BACKWASH-MOTOR
FLOW_RATE	PUMP, VALVE, FLOW-SENSOR

Tip

A single alert parameter can map to multiple components. For example, a UV_INTENSITY drop could be caused by a failing lamp, a fouled quartz sleeve, a degraded UVR unit, or a missed CIP cycle. The PMS Agent investigates all of them.

---

Per-Component Process

For each component identified in the mapping above, the PMS Agent runs the following sequence:

1. Last Service Lookup

   Query bwts_maintenance_log for the most recent service record matching this component type. Extract the service date, work description, and technician notes.

2. Current Runtime

   Calculate the elapsed hours or days since the last service. For hour-based components (e.g., UV lamps), use the runtime counter from bwts_iot_telemetry. For calendar-based components (e.g., quartz sleeves), use the date difference.

3. Overdue Check

   Compare the current runtime against the Alfa Laval maintenance schedule. Classify the component using the overdue classification system.

4. Next Service Due

   Calculate when the next service is due based on the last service date and the scheduled interval. Flag if the next service falls within the current operating session.

5. Service History — Last 3 Records

   Retrieve the three most recent service records for this component. Look for patterns: shortening intervals between services (accelerating wear), repeated issues, or incomplete repairs.

6. Contextual Link to Alert

   Assess whether the component’s maintenance status could explain the current alert. For example: “UV lamp has 3,247 runtime hours against a 3,000-hour service interval — 352 hours overdue. This is consistent with the observed UV intensity decline.”

---

Overdue Classification

The PMS Agent classifies every component into one of four statuses:

Status	Criteria
OVERDUE	Runtime or calendar age exceeds the scheduled service interval
DUE SOON	Within 10% of the scheduled interval (e.g., lamp at 2,700+ hours of a 3,000-hour interval)
OK	Well within the scheduled interval — no maintenance concern
NO RECORD	No service history found in the database for this component. Cannot determine status.

Caution

NO RECORD does not mean OK. A missing maintenance record could indicate that the component has never been serviced, that records were not migrated, or that the component was replaced without logging. Always flag NO RECORD components in the report — they represent a data gap that requires human follow-up.

---

Maintenance Schedule

Service intervals from the Alfa Laval BWTS equipment manual:

Component	Interval	Basis	Notes
UV Lamp	3,000 hours	Runtime	Replace when intensity drops below rated output or at 3,000h, whichever comes first
Quartz Sleeve	90 days	Calendar	Clean or replace. Fouling accelerates in high-turbidity waters
CIP (Clean-In-Place)	30 days	Calendar	Chemical cleaning cycle for the UV chamber and flow path
Filter Element	6 months	Calendar	Replace or deep-clean. Check differential pressure trend for early clogging
Backwash Motor	12 months	Calendar	Inspect bearings, seals, and electrical connections
Flow Sensor	12 months	Calendar	Calibration check. Drift can cause false flow-rate alerts
UVR Unit	12 months	Calendar	Full unit inspection — electronics, wiring, sensor calibration
Pump Seals	6 months	Calendar	Inspect for leaks. Replace if wear marks visible
Valve Actuators	12 months	Calendar	Function test all valves. Check response time against spec

Note

These intervals are manufacturer recommendations. Vessel operators may adjust intervals based on operating conditions (e.g., shorter CIP cycles in high-sediment ports). The PMS Agent uses the standard intervals unless overridden by a vessel-specific configuration.

---

Output Format

Every PMS Agent response follows the PMS REPORT structure:

Report Sections

Section	Content
Per-Component Status	One block per investigated component: last service, runtime, overdue classification, next service due, service history (last 3)
Summary	Overall maintenance posture — how many components are OVERDUE, DUE SOON, OK, or NO RECORD
Maintenance Gaps	Components with NO RECORD status or suspiciously long gaps between services
Data Gaps	Missing or incomplete records, tables that could not be queried, known data-quality issues

Example Snippet

=== PMS REPORT ===

COMPONENT: UV LAMP
  Last Service: 2026-03-12 (replaced — 4x UV lamps)
  Runtime Since Service: 3,247 hours
  Scheduled Interval: 3,000 hours
  Status: OVERDUE (247 hours past interval)
  Next Service Due: Was due at 3,000h — currently 247h overdue
  Service History:
    1. 2026-03-12 — Full lamp replacement (4x)
    2. 2025-11-08 — Lamp 3 replaced (single failure)
    3. 2025-06-20 — Full lamp replacement (4x)
  Link to Alert: UV lamp is 247 hours past the 3,000-hour
    service interval. Consistent with the observed 27% decline
    in UV intensity.

COMPONENT: QUARTZ SLEEVE
  Last Service: 2026-04-15 (cleaned)
  Days Since Service: 36 days
  Scheduled Interval: 90 days
  Status: OK (40% through interval)
  Next Service Due: 2026-07-14
  Link to Alert: Quartz sleeve recently serviced.
    Unlikely contributor to current UV intensity decline.

SUMMARY
  OVERDUE: 1 (UV Lamp)
  DUE SOON: 0
  OK: 3 (Quartz Sleeve, UVR Unit, CIP)
  NO RECORD: 0

---

Tools

graph LR
    PMS["PMS Agent"] --> DQ["db_query.py\nPMS query templates"]
    DQ --> PG[("PostgreSQL")]

    subgraph "Tables"
        T1["bwts_maintenance_log\nNo vessel_id column"]
        T2["bwts_iot_predictions\ncamelCase — needs double-quotes"]
        T3["bwts_iot_telemetry\nRuntime counters"]
    end

    PG --- T1
    PG --- T2
    PG --- T3

    style PMS fill:#1a1a2e,stroke:#e94560,stroke-width:3px,color:#fff
    style DQ fill:#16213e,stroke:#0f3460,stroke-width:2px,color:#fff
    style PG fill:#0d1b2a,stroke:#1b9aaa,stroke-width:2px,color:#fff
    style T1 fill:#0d1b2a,stroke:#1b9aaa,stroke-width:1px,color:#fff
    style T2 fill:#0d1b2a,stroke:#1b9aaa,stroke-width:1px,color:#fff
    style T3 fill:#0d1b2a,stroke:#1b9aaa,stroke-width:1px,color:#fff

Template	Purpose
last_service	Retrieve the most recent service record for a given component type
current_runtime	Calculate hours or days since the last service event
service_history	Retrieve the last N service records for a component (default: 3)
overdue_components	List all components where runtime or calendar age exceeds the scheduled interval
component_by_equipment	List all components associated with a given equipment tag

Caution

The bwts_maintenance_log table has NO vessel_id column. Do not include vessel_id in WHERE clauses — the query will fail silently and return zero rows. Filter by equipment tag instead.

Caution

The bwts_iot_predictions table uses camelCase column names. PostgreSQL folds unquoted identifiers to lowercase, so you must use double-quotes around column names (e.g., "predictedValue", "confidenceScore"). Unquoted queries will return column does not exist errors.

---

What It Does NOT Do

No Scheduling Recommendations

Reports maintenance status (overdue, due soon, OK) but never recommends when to schedule the next service. Scheduling decisions belong to the fleet manager.

No Sensor Analysis

Does not analyse sensor trends, detect anomalies, or interpret telemetry data. That is the Data Analysis Agent’s responsibility. Uses telemetry tables only for runtime counters.

No Manual Search

Equipment manual lookups, documented-cause searches, and troubleshooting guides are the Manual Agent’s domain.

No Report Generation or Email

Writes its findings to the task system. Never generates client-facing reports, HTML documents, or sends emails. All external communication flows through the Report Agent.