Skip to content
NBS Workshop

Casefile Agent

Role

The Casefile Agent is the historical analyst of the BWTS IOT pipeline. When the IOT Manager dispatches a Phase 1 investigation, this agent searches past incidents, fleet-wide patterns, and resolution histories to find precedents. Its output tells the Manager whether this problem has been seen before, how it was resolved, and whether the fix actually worked.

Investigation Process

graph TB
    START["Receive Investigation\nTask from IOT Manager"] --> S1


    subgraph "Search Strategy"
        direction TB
        S1["Same-Vessel\nHistory"]
        S2["Fleet-Wide\nPattern Search"]
        S3["Resolution\nEffectiveness"]
        S4["Contextual\nSimilarities"]


        S1 --> S2 --> S3 --> S4
    end


    S4 --> REPORT["Compile\nCASEFILE REPORT"]


    style START fill:#1a1a2e,stroke:#0f3460,stroke-width:2px,color:#fff
    style S1 fill:#0d1b2a,stroke:#1b9aaa,stroke-width:2px,color:#fff
    style S2 fill:#0d1b2a,stroke:#1b9aaa,stroke-width:2px,color:#fff
    style S3 fill:#0d1b2a,stroke:#1b9aaa,stroke-width:2px,color:#fff
    style S4 fill:#0d1b2a,stroke:#1b9aaa,stroke-width:2px,color:#fff
    style REPORT fill:#1a1a2e,stroke:#e94560,stroke-width:3px,color:#fff

  1. Same-Vessel History

    Search for past alerts and investigations on the same vessel and equipment tag. This is the highest-relevance search — identical hardware in identical operating conditions. Look for the same alarm code, the same parameter, and any related alarms that co-occurred.

  2. Fleet-Wide Pattern Search

    Expand the search to all vessels in the fleet with matching equipment types. Look for the same alarm code or symptom appearing on sister vessels. Fleet-wide patterns often indicate systemic issues — firmware bugs, batch defects, or environmental factors affecting multiple installations.

  3. Resolution Effectiveness

    For every matching past incident found in Steps 1 and 2, check whether the resolution actually worked. Did the same alarm recur within days or weeks? Was the fix a permanent resolution or a temporary workaround? This step prevents the pipeline from recommending fixes that have already been tried and failed.

  4. Contextual Similarities

    Search for incidents that share contextual factors even if the alarm code differs. Relevant context includes: operating mode at time of alert (Treatment, CIP, Standby), time since last CIP cycle, seasonal/geographic conditions (tropical waters, cold climate ports), and vessel operational profile (tanker vs. bulk carrier, short vs. long voyages).

Data Sources

Completed Alert Tasks

LifeOSAI Issue Search

Searches past completed investigation tasks using the ?q= parameter. Each completed task contains the original alert, the IOT Manager’s synthesis, confirmed causes, and the resolution applied. This is the richest source of structured investigation history.

PARA Memory Graph

Knowledge Graph

The PARA memory system stores distilled knowledge from past investigations as atomic YAML facts — equipment quirks, recurring patterns, known failure modes, and lessons learned. These facts persist across sessions and capture institutional knowledge that may not be fully recorded in task history.

IOT Events Database

bwts_iot_events Table

Raw event log in PostgreSQL containing timestamped records of all BWTS alerts, state changes, and operator actions. Used for statistical analysis — how many times has this alarm fired? What is the mean time between occurrences? Is the frequency increasing?

Output Format

Every Casefile Agent response follows the CASEFILE REPORT structure.

SectionContent
Same-Vessel HistoryPast incidents on the same vessel/equipment — alarm codes, dates, causes found, resolutions applied
Fleet-Wide MatchesSame or similar incidents across other vessels in the fleet — equipment tags, dates, commonalities
Resolution EffectivenessFor each past resolution: did it hold? Did the alarm recur? Time-to-recurrence if applicable
Similar IncidentsContextually similar incidents (different alarm, but similar conditions or failure mode)
SummaryKey findings distilled into bullet points — what the history tells us about this new alert
Data GapsWhat could not be determined — missing records, incomplete resolutions, vessels with no history

Tools

graph LR
    CF["Casefile\nAgent"] --> LOS["LifeOSAI\nIssue Search\n?q= parameter"]
    CF --> PARA["PARA Memory\nFiles\nKnowledge graph"]
    CF --> DB["db_query.py\nbwts_iot_events"]


    LOS --> TASKS[("Completed\nTasks")]
    PARA --> YAML[("YAML\nFacts")]
    DB --> PG[("PostgreSQL")]


    style CF fill:#1a1a2e,stroke:#e94560,stroke-width:3px,color:#fff
    style LOS fill:#16213e,stroke:#0f3460,stroke-width:2px,color:#fff
    style PARA fill:#16213e,stroke:#0f3460,stroke-width:2px,color:#fff
    style DB fill:#16213e,stroke:#0f3460,stroke-width:2px,color:#fff
    style TASKS fill:#0d1b2a,stroke:#1b9aaa,stroke-width:1px,color:#fff
    style YAML fill:#0d1b2a,stroke:#1b9aaa,stroke-width:1px,color:#fff
    style PG fill:#0d1b2a,stroke:#1b9aaa,stroke-width:1px,color:#fff
ToolPurpose
LifeOSAI Issue SearchSearch completed investigation tasks using the ?q= query parameter. Returns past alerts, confirmed causes, and applied resolutions.
PARA Memory FilesQuery the knowledge graph for distilled facts — equipment quirks, recurring patterns, lessons learned. Persists across sessions.
db_query.pyRun SQL queries against the bwts_iot_events table in PostgreSQL. Used for statistical analysis — alert frequency, recurrence intervals, event clustering.

What It Does NOT Do

No Sensor Analysis

Never queries telemetry tables, never analyses trends, never interprets sensor values. Live and historical sensor data is the Data Analysis Agent’s domain.

No Maintenance Checks

Never accesses maintenance schedules, planned work orders, or service records. Maintenance data belongs to the PMS Agent.

No Manual Search

Never searches equipment manuals, troubleshooting guides, or manufacturer documentation. That is the Manual Agent’s responsibility.

No Report Generation

Never creates client-facing reports, never sends emails, never formats HTML output. Report creation and distribution is the Report Agent’s job.