Container Visibility & Exception Handling Agent

Real-time-style tracking with predictive delay detection — flags detention risk 48 hours before it becomes a costly problem, instead of finding out when the shipper calls.

What it does

• Tracks simulated vessel position history and container status
• Compares vessel progress against expected transit time per route
• Detects delays and classifies severity (low / medium / high / critical)
• Estimates detention risk and cost impact
• Generates alerts with advance-warning windows and recommended mitigation
• Produces a daily operations brief a dispatcher can act on in minutes

Quick start

pip install -r requirements.txt

# Generate fresh synthetic sample data (optional, sample data is included)
python data/generate_sample_data.py

# Run without an API key — pure deterministic pipeline
python visibility_agent.py --offline \
    --vessels data/vessels.csv --containers data/containers.csv --routes data/routes.csv

# Run with Claude orchestrating the pipeline + writing the operations brief
export ANTHROPIC_API_KEY=sk-...
python visibility_agent.py \
    --vessels data/vessels.csv --containers data/containers.csv --routes data/routes.csv

Open demo.html directly in a browser for the buyer-facing dashboard — severity-ranked alert queue, filterable, mobile-responsive, with a mitigation-action modal (expedite request / shipper notification drafts with a human-verification gate). Static demo data mirrors the agent's real --offline output; in production the rows array is replaced by the agent's JSON report.

Example output

===== CONTAINER VISIBILITY BRIEF =====
Date: 2026-01-20
Tracking: 33 containers

🔴 ALERTS (7):
CONT001 (Vessel V001): Vessel Maersk Madrid delayed 94h on Shanghai→Los Angeles route
→ Detention risk in 0h if not mitigated
→ Expedite drayage to next available slot (Act within 24 hours)
→ Est. $300 expedite cost vs. $250+ detention

🟡 WATCHLIST (10):
CONT006: Vessel CMA CGM Jacques Saade delayed 13h on Singapore→Los Angeles route
...

SUMMARY: Tracking 33 containers. 7 high-priority alert(s): CONT001 —
Detention risk in 0h if not mitigated. 16 containers on schedule.

Architecture

CSV data (vessels, containers, routes)
        │
        ▼
tools/data_loader.py       → typed load functions
        │
        ▼
tools/delay_detection.py   → delay detection + detention impact estimate
tools/alerts.py            → alert + mitigation generation
        │
        ▼
tools/reporting.py         → daily brief + prioritized alert list
        │
        ▼
visibility_agent.py        → Claude tool-use loop wraps the pipeline
                              and writes the dispatcher-facing brief

Detention logic: each route defines free_days_before_detention (the grace period before demurrage/detention starts accruing). A vessel's delay_hours is compared against that trigger; alerts fire once a container is within a 48-hour advance-warning window of hitting it — not just when it's already too late.

Data schema

vessels.csv: vessel_id, vessel_name, current_port, destination, sailed_date, expected_arrival, actual_arrival, delay_hours

containers.csv: container_id, vessel_id, shipper, origin_port, destination_port, current_status

routes.csv: origin, destination, expected_transit_days, peak_season_delay_days, free_days_before_detention

All sample data is synthetic — generated by data/generate_sample_data.py, simulating several days of realistic vessel position history. No real customer or employer data is used anywhere in this repository.

Running the tests

The deterministic core has a full pytest suite (23 tests) covering the detention-window boundary math, severity classification, route free-day overrides, alert/mitigation generation, malformed-input handling, and an end-to-end run pinned to the sample data's known-good numbers (33 tracked, 17 alerts: 4 critical / 3 high / 10 medium).

pip install pytest   # dev-only dependency, not needed at runtime
python -m pytest tests/ -v

Malformed input (missing columns, empty files, non-numeric fields) produces a located, human-readable error and exit code 2 — never a raw traceback.

Tech

Python 3.11+, Anthropic Claude API (tool use), stdlib only for the core pipeline. demo.html is a zero-dependency static file.

Possible extensions

• Swap simulated vessel data for a real AIS feed (e.g. MarineTraffic API)
• APScheduler for recurring daily runs
• Wire demo.html to a live JSON endpoint via fetch()
• SMS/Slack push for critical-severity alerts

---

Part of a 3-agent portfolio for AI-powered logistics automation. See also: Import VIP Desk Agent and Carrier Scorecard Agent.