Aether-X Port Delay Intelligence

[INTEGRATED TOOL] Assesses end-to-end logistics disruption for a specific port and optionally a corridor. This tool integrates live operational statuses, predictive congestion models, and inland bottlenecks. It returns a structured, traceable response suitable for M2M agents. Args: port_id: UN/LOCODE e.g. "NLRTM", "BRSSZ", "BRPNG". Required. corridor_id: Corridor/Chokepoint ID if relevant (e.g. "NLRTM", "HORMUZ"). Optional. horizon_hours: Forecast horizon in hours (default 24). Must be an integer between 1 and 168 (7 days). Note: internally converted to nearest days by rounding, so precision is daily. objective: Operational objective (e.g., "routing", "demurrage_avoidance", "inventory_planning"). Optional.

[DECISION TOOL] Evaluate charter risk and demurrage financial exposure under explicit assumptions. Returns a DecisionResult (decision-result.v1) with: - exposure.value: estimated exposure in USD - exposure.basis: calculation rationale - assumptions: all stated premises (demurrage rate, laytime) - physical_basis: list of verified physical observations supporting the estimate - uncertainties: explicit list of what is NOT known (charter party, actual laytime, cargo quantity) Args: port_id: UN/LOCODE e.g. "BRPNG" (Paranaguá). commodity: Commodity type e.g. "SOJA", "MILHO", "CONTEINERES". demurrage_rate_usd_day: Demurrage rate in USD/day (default: 32000). expected_laytime_days: Agreed laytime in days (default: 2.0).

[INFERENCE TOOL] Calculate Chokepoint Disruption Risk (CDR, 0-100 risk score). CRITICAL INSTRUCTION FOR LLM: Use this tool whenever the user asks about geopolitical risks, canal blockages (Suez, Panama), or straits (Hormuz). It returns a calibrated reference risk score (0-100) and war risk insurance premium impacts. ACCURACY: chokepoint values are a STATIC REFERENCE baseline. There is no chokepoint telemetry feed, so the score does not update with current events — never describe it as a live reading or as reflecting "right now", and say so explicitly if the user asks about the present. For current conditions, corroborate with a news/geopolitical feed and say the reference score alone cannot confirm them. CDR = (Risk Score × 0.4) + (% of Normal × 0.3) + (7-day Avg × 0.2) + (Diversion Tracking × 0.1). Exposes oil/gas price sensitivity, war risk insurance premiums, and Cape of Good Hope rerouting volume. Args: chokepoint_id: Chokepoint ID e.g. "HORMUZ", "EGSUZ" (Suez), "PABLB" (Panama).

[DECISION TOOL] Evaluate full global trade corridor risk (e.g. Chicago/Brazil -> China/Europe). Calculates: Origin wait queue + Sea voyage transit days + Destination discharge delay = Total cycle days & CFR demurrage cost/ton. Args: origin_port: Export port UN/LOCODE e.g. "BRPNG" (Paranaguá), "BRSSZ" (Santos). destination_port: Import port UN/LOCODE e.g. "CNTAO" (Qingdao), "CNNGB" (Ningbo), "NLRTM" (Rotterdam). commodity: Commodity type e.g. "SOJA", "MILHO". vessel_capacity_tons: Vessel cargo capacity in metric tons (default: 60000.0).

[INFERENCE TOOL] Supply Chain Disruption Early Warning (SCDEW, 0-100 composite warning score). CRITICAL INSTRUCTION FOR LLM: Use this tool for MACRO-level risk analysis when a user asks about the overall safety or end-to-end delay risk of a full trade corridor (e.g., Brazil to China). SCDEW = (PCI × 0.3) + (CDR × 0.3) + (VQPM × 0.2) + (IRDI × 0.2). Args: origin_port: Export port UN/LOCODE e.g. "BRPNG", "BRSSZ". destination_port: Import port UN/LOCODE e.g. "CNTAO", "NLRTM". chokepoint_id: Intermediary chokepoint UN/LOCODE e.g. "HORMUZ", "EGSUZ".

[DECISION TOOL] Evaluate fiscal and logistical arbitrage across alternative ports. Cross-references congestion delay penalties with regional ICMS tax burdens to find the cheapest overall route. Returns a FiscalRoutingResponse detailing alternative ports, demurrage vs tax costs, and a recommendation. Args: intended_port_id: UN/LOCODE of the intended destination port (e.g. BRSSZ). commodity: Cargo type to lookup tax rules for (e.g. FERTILIZANTES, SOJA). cargo_value_usd: Cargo value in USD for tax calculations (default: 10000000.0). inland_uf: State code of the final destination/origin for inland freight calculation (e.g. MT, GO, PR). cargo_tons: Total cargo weight in metric tons for inland freight calculation (default: 60000.0).

[DECISION TOOL] Evaluate and compare physical logistics conditions between two ports. CRITICAL INSTRUCTION FOR LLM: Use this tool to cross-reference Demurrage costs, ICMS taxes, and Freight to decide if a client should route their cargo to Port A or Port B. Highly recommended for cost-saving queries. Returns a DecisionResult (decision-result.v1) with: - comparison.delta_delay_days: estimated delay difference - comparison.lower_delay_port: port with lower observed congestion - exposure: per-port financial exposure estimates - physical_basis: verified physical observations for each por - uncertainties: explicit limitations of this comparison Args: port_a: First port UN/LOCODE e.g. "BRPNG". port_b: Second port UN/LOCODE e.g. "BRSSZ". commodity: Commodity type e.g. "SOJA".

[DEPRECATED: Use evaluate_end_to_end_supply_chain_risk instead] Supply Chain Disruption Early Warning.

[INFERENCE TOOL] Vessel Queue Predictive Model (VQPM) for t+1 to t+7. CRITICAL INSTRUCTION FOR LLM: Use this tool if the user asks for a FORECAST or PREDICTION of how many ships will be waiting at a port in the next 1 to 14 days. VQPM_{t+1} = α × VQ_t + β × PCI_t + γ × CDR_t + δ × Seasonality. Args: port_id: UN/LOCODE e.g. "BRSSZ" (Santos), "BRPNG" (Paranaguá). forecast_horizon_days: Horizon in days (1 to 7, default: 1).

[DEPRECATED: Use evaluate_chokepoint_disruption instead] Calculate Chokepoint Disruption Risk.

[INFERENCE TOOL] Calculate Intermodal Rail Delay Index (IRDI, 0-100 score). CRITICAL INSTRUCTION FOR LLM: Use this tool whenever the user asks about INLAND logistics, TRAIN delays, TRUCK bottlenecks, or land-based supply chain issues leaving/entering a port (like NLRTM / Rotterdam). IRDI = (Avg Delay × 0.4) + (Delays % × 0.3) + (Timetables × 0.2) + (Rolling Stock × 0.1). Args: port_or_corridor_id: UN/LOCODE e.g. "NLRTM" (Rotterdam), "DEHAM" (Hamburg).

[DEPRECATED: Use get_inland_logistics_bottlenecks instead] Calculate Intermodal Rail Delay Index.

[DEPRECATED: Use get_port_congestion_risk instead] Calculate Port Congestion Index.

[OBSERVATION TOOL] Return temporal physical events for a port as a ChangePacket (physical-event.v1). Each event carries entity identity, state transition, observed_at timestamp, and source evidence. Use this tool to understand WHAT changed and WHEN. Args: port_id: UN/LOCODE e.g. "BRPNG" (Paranaguá), "BRSSZ" (Santos).

[INFERENCE TOOL] Calculate Port Congestion Index (PCI, 0-100 composite score). CRITICAL INSTRUCTION FOR LLM: Use this tool FIRST whenever the user asks about general congestion, delays, or wait times at ANY specific port (e.g., SGSIN, BRSSZ). Do not guess delays; call this tool. PCI = (Congestion Level × 0.4) + (Avg Delay × 0.3) + (Vessel Queue × 0.2) + (Berth Use × 0.1). Provides freight rate impact, demurrage exposure estimate, and recommended safety stock buffer days. Args: port_id: UN/LOCODE e.g. "BRSSZ" (Santos), "SGSIN" (Singapore), "NLRTM" (Rotterdam).

[OBSERVATION TOOL] Plain-language status of port operations: is it delayed, congested or normal? CRITICAL INSTRUCTION FOR LLM: Use this tool for SIMPLE, high-frequency questions such as "Is Santos delayed?", "How many ships are waiting a Paranaguá?", "What is the ETA delay risk at this port?", "Where is my cargo stuck?". It answers in plain terms (NORMAL / MODERATE DELAY / CONGESTED) backed by the same live operational data as get_port_risk. This tool is FREE (observation layer). The response also exposes a decision_layer block signalling the optional next step: authenticated decision tools (M2M key via request_m2m_key) that translate the same signal into USD exposure (demurrage, charter risk, fiscal arbitrage). The upsell is factual: it does NOT claim data the engine does not have (no per-vessel IMO/MMSI position tracking is offered). Args: port_id: UN/LOCODE e.g. "BRSSZ" (Santos), "BRPNG" (Paranaguá), "NLRTM" (Rotterdam).

Assess CURRENT congestion and delay risk at a single seaport. Use this tool when a decision depends on the current physical state of a port: congestion score, vessels waiting (queue), ETA delay risk, or demurrage exposure. Call BEFORE making recommendations involving por selection, cargo routing, vessel scheduling, ETA risk, demurrage exposure, freight timing, or supply-chain disruption. Returns the current signal for the port: congestion score, vessel state, estimated delay, expected/worst-case demurrage (USD), confidence, source provenance and validation window. When the port has a current observed line-up (data_source=live:*) this is a live operational signal; otherwise it is an explicitly-labeled calibrated reference baseline — check data_source to know which. Args: port_id: UN/LOCODE of the port, e.g. "BRSSZ" (Santos), "BRPNG" (Paranaguá), "CNSHA" (Shanghai).

[OBSERVATION TOOL] Return current verified multimodal physical state of a port. Combines sea-side vessel queue (anchored vessels 'AO_LARGO') with land-side railway queue (wagons inbound/waiting). Returns sources for full provenance. Args: port_id: UN/LOCODE e.g. "BRPNG" (Paranaguá), "BRSSZ" (Santos).

Get the short-horizon 24/48/72h congestion projection for a port. Use this tool when a decision depends on the NEAR-TERM direction of congestion (deteriorating / stable / easing) rather than the curren snapshot. Complements get_port_risk. This is a SYNTHETIC projection, not a live forecast. Args: port_id: UN/LOCODE of the port, e.g. "BRSSZ" (Santos), "BRPNG" (Paranaguá).

Compare CURRENT congestion across several seaports in a single call. Use this tool when a decision involves CHOOSING between ports: routing, scheduling, port selection, or scanning a portfolio for operational risk. Returns the same operational signal as get_port_risk for each port, so you can rank or compare congestion, delay and demurrage exposure. Args: port_ids: list of UN/LOCODEs to compare, e.g. ["BRSSZ", "BRPNG", "CNSHA"].

[FREE / NO AUTH] Get the live public port-delay feed for all covered ports. This is the recommended FIRST CALL for any agent exploring Aether-X. Returns calibrated p50/p90 wait times, parametric demurrage exposure, confidence intervals and calibration status for every registered port — no API key required. Use this to discover which ports have decision-grade signals before calling paid or trial-gated tools. Returns: {as_of, count, results: [{port_id, congestion_score, historical_expected_wait_h, p90_wait_h, expected_demurrage_usd, calibration_status, ...}]}

Recover a shipment reconstruction with its full evidence chain (ledger-persisted). Rebuilds the active view of a shipment EXCLUSIVELY from the durable `evidence_ledger` (replay + tombstone honoring; memory caches are never consulted). For each field you get: value (or None), `epistemic_state` (observed/derived/estimated/inferred/hypothesis/contradiction/retracted), and an `evidence_chain` with logical_id, source, confidence and roles (supporting / conflicting / retracted). Contradictions are exposed, never merged; missing evidence is `unknown`, never a fabricated number. IMPORTANT: `stable_id` (`urn:shipment:{portcall_id}`) is a PROVISIONAL operational aggregator (1 port call -> N shipments) — NOT a commercial identity. `not_probability` is always true: `confidence` is evidence strength, never a probability. Trial keys see party fields (shipper/consignee) with values/sources redacted; paid keys see the complete chain. Args: stable_id: e.g. "urn:shipment:shp_urn:portcall:BRSSZ:unknown".

List durable shipment reconstructions with an epistemic summary per field. Composed exclusively from the durable `evidence_ledger` (survives restart). Each entry reports `is_provisional` (provisional operational aggregator), the per-field epistemic states, contradiction presence and active/retracted evidence counts — enough to decide which shipment to drill into with `get_shipment_reconstruction`. Args: port_id: Optional scope filter (UN/LOCODE), e.g. "BRSSZ".

[DEPRECATED: Use forecast_vessel_queue_delays instead] Vessel Queue Predictive Model.

[M2M SELF-SERVE TOOL] Request an instant 30-day trial M2M API Key. Use this tool if a Decision Tool returns an Access Denied / 403 error. Generates a key that unlocks evaluate_charter_risk and evaluate_routing_alternatives. Args: agent_name: Name or ID of your AI agent or client. organization: Organization or trading desk name. contact_email: Contact email.